Adams 2020 FP1

Adams View Function Builder

User's Guide
Corporate Europe, Middle East, Africa
MSC Software Corporation MSC Software GmbH
4675 MacArthur Court, Suite 900 Am Moosfeld 13
Newport Beach, CA 92660 81829 Munich, Germany
Telephone: (714) 540-8900 Telephone: (49) 89 431 98 70
Toll Free Number: 1 855 672 7638 Email: [email protected]
Email: [email protected]

Japan Asia-Pacific
MSC Software Japan Ltd. MSC Software (S) Pte. Ltd.
Shinjuku First West 8F 100 Beach Road
23-7 Nishi Shinjuku #16-05 Shaw Tower
1-Chome, Shinjuku-Ku Singapore 189702
Tokyo 160-0023, JAPAN Telephone: 65-6272-0082
Telephone: (81) (3)-6911-1200 Email: [email protected]
Email: [email protected]

Worldwide Web
www.mscsoftware.com

Support
http://www.mscsoftware.com/Contents/Services/Technical-Support/Contact-Technical-Support.aspx

Disclaimer
This documentation, as well as the software described in it, is furnished under license and may be used only in accordance with the
terms of such license.
MSC Software Corporation reserves the right to make changes in specifications and other information contained in this document
without prior notice.
The concepts, methods, and examples presented in this text are for illustrative and educational purposes only, and are not intended
to be exhaustive or to apply to any particular engineering problem or design. MSC Software Corporation assumes no liability or
responsibility to any person or company for direct or indirect damages resulting from the use of any information contained herein.
User Documentation: Copyright © 2020 MSC Software Corporation. Printed in U.S.A. All Rights Reserved.
This notice shall be marked on any reproduction of this documentation, in whole or in part. Any reproduction or distribution of this
document, in whole or in part, without the prior written consent of MSC Software Corporation is prohibited.
This software may contain certain third-party software that is protected by copyright and licensed from MSC Software suppliers.
Additional terms and conditions and/or notices may apply for certain third party software. Such additional third party software terms
and conditions and/or notices may be set forth in documentation and/or at http://www.mscsoftware.com/thirdpartysoftware (or successor
website designated by MSC from time to time). Portions of this software are owned by Siemens Product Lifecycle Management, Inc.
© Copyright 2020
The MSC Software logo, MSC, MSC Adams, MD Adams, and Adams are trademarks or registered trademarks of MSC Software
Corporation in the United States and/or other countries. Hexagon and the Hexagon logo are trademarks or registered trademarks of
Hexagon AB and/or its subsidiaries. FLEXlm and FlexNet Publisher are trademarks or registered trademarks of Flexera Software.
Parasolid is a registered trademark of Siemens Product Lifecycle Management, Inc. All other trademarks are the property of their
respective owners.

ADAM:V2020FP1:Z:Z:Z:DC-FUNC
Documentation Feedback
At MSC Software, we strive to produce the highest quality documentation and welcome your feedback.
If you have comments or suggestions about our documentation, write to us at: documentation-
[email protected].
Please include the following information with your feedback:
 Document name
 Release/Version number
 Chapter/Section name
 Topic title (for Online Help)
 Brief description of the content (for example, incomplete/incorrect information, grammatical
errors, information that requires clarification or more details and so on).
 Your suggestions for correcting/improving documentation
You may also provide your feedback about MSC Software documentation by taking a short 5-minute
survey at: http://msc-documentation.questionpro.com.

Note: The above mentioned e-mail address is only for providing documentation specific
feedback. If you have any technical problems, issues, or queries, please contact Technical
Support.
 1
Learning Function Builder Basics

Using the Adams View Function Builder

The Adams View Function Builder is a versatile tool inside of Adams View, part of the Adams® 2020 FP1
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.

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
2 Adams View Function Builder
Learning Function Builder Basics

Category:
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.

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
Clearance Functions
Spline Functions
Force in Object Functions
Resultant Force Functions
Math Functions
Vector Functions
Data Element Access
User-Written Subroutine Invocation
Constants & Variables
FE part

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.
 3
Learning Function Builder Basics

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
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
4 Adams View Function Builder
Learning Function Builder Basics

 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:
variable create variable=my_radius real=40 units=length geometry
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:
 5
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 locations,
parameterizing values for geometry dimensions, and working with design variables. For more information on
expressions, see Expression Language Reference.
6 Adams View Function Builder
Learning Function Builder Basics

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, as shown below:
To access the expression mode from the Build menu:
1. Click the Design Exploration tab. From the Measures container, click the Computed Measure tool
.

or
 7
Learning Function Builder Basics

(Classic interface) 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.

8 Adams View Function Builder
Learning Function Builder Basics

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:

1. Click the Elements tab. From the Function container, click the Create a Function tool .

or
(Classic interface) From the Build menu, point to Function, and then select New.

The Function Builder appears as shown next.

 9
Learning Function Builder Basics

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
10 Adams View Function Builder
Learning Function Builder Basics

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

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

12 Adams View Function Builder
Learning Function Builder Basics

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.

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

1. Click the Elements tab. From the Function container, click the Create a Function tool .

or
(Classic interface) From the Build menu, point to Measure, point to Function, and then select New.

The Function Builder appears as shown next.

 13
Performing Operations in the Function Builder

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

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.
14 Adams View Function Builder
Performing Operations in the Function Builder

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
 Verifying Function Syntax
 Setting Measure Attributes
 Creating a Measure Strip Chart
 Getting Assistance
 Inserting Operators in Function Definitions
 Displaying System-Supplied Function Categories
 15
Performing Operations in the Function Builder

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.
 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.
 17
Performing Operations in the Function Builder

To evaluate a function:
1. Make sure there is a function in the function text area.
2. Select Evaluate.
Adams View displays the value of the function next to Function Value.

Note: Under the model object, there are both "ground" and "ground_part" fields. The latter
was added to determine the ground part of the given model at any given point in time
and provides a workaround for the issue of expressions returning the incorrect ground
part for a model when the name of the model's ground part is not "ground". It is
therefore recommended to use "ground_part" instead of "ground".

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.
2. Select Plot Limits.

A dialog box appears, prompting you for the values that you want to use.
18 Adams View Function Builder
Performing Operations in the Function Builder

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.

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.
 19
Performing Operations in the Function Builder

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.

To get assistance:
1. Select a function from the list of system-supplied functions.
2. Select Assist.
The Assist dialog box appears.
20 Adams View Function Builder
Performing Operations in the Function Builder

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
String Functions
Database Functions
Miscellaneous Functions
 21
Performing Operations in the Function Builder

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.

2. Select the desired function from the list.

The function name and arguments appear under the function list.
22 Adams View Function Builder
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:
 23
Expression Language Reference

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

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.
24 Adams View Function Builder
Expression Language Reference

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:
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
 25
Expression Language Reference

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 2 ⁄ 2 = 0.7071
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
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
26 Adams View Function Builder
Expression Language Reference

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)
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.
 27
Expression Language Reference

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.
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.
28 Adams View Function Builder
Expression Language Reference

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

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 at
marker_name.location[2] 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:
 29
Expression Language Reference

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"
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
30 Adams View Function Builder
Expression Language Reference

Indexed array: Alias:

alias location[1] loc_x
alias location[2] loc_y
alias location[3] loc_z

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
 31
Expression Language Reference

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

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 value
(either directly or indirectly), evaluation could continue endlessly. To avoid problems, Adams View only
resolves such expressions one level deep.
 33
Expression Language Reference

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.
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
34 Adams View Function Builder
Expression Language Reference

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 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:
 35
Expression Language Reference

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

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.
36 Adams View Function Builder
Expression Language Reference

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):
{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)
 37
Expression Language Reference

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:
 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
38 Adams View Function Builder
Expression Language Reference

Are stored as:

These parameter values: General math matrix 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 matrices 1xN matrices
(such as spline x values or 1 2 …
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.

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:
 39
Expression Language Reference

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.
Creating Matrix Expressions of Various Dimensions

Matrix
Adams matrix syntax: General math matrix 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:

Indexing in Adams
40 Adams View Function Builder
Expression Language Reference

Mathematical
Adams index 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

Mathematical
Adams index 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:
Extracting a Complete Row
 41
Expression Language Reference

Mathematical
Adams index 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 2 8 9
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:

Extracting a Complete Column
42 Adams View Function Builder
Expression Language Reference

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 x 8 9
2 matrix 5 6
{[8, 9], [5, 6]} [*,1] Elements in all rows, {8,5}
1st column of a 2 x 2 8 9
matrix 5 6
{[1,2,3], [4,5,6], Elements in all rows, {1,4,7}
[7,8,9]} [*,1] 1st column in a 3 x 3 1 2 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
3xN Matrix
 43
Expression Language Reference

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
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
44 Adams View Function Builder
Expression Language Reference

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:

0 1 2
2 ** {0,1,2} (2 ,2 ,2 ) = {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}
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.)
 45
Expression Language Reference

Expression: Result: Comments:

!{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}.

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
46 Adams View Function Builder
Expression Language Reference

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:
(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:
Simple Unit Labels and Their Minimal Abbreviations
 47
Expression Language Reference

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_
48 Adams View Function Builder
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
 49
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.
50 Adams View Function Builder
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.
 51
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.
52 Adams View Function Builder
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.
 53
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.
54 Adams View Function Builder
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.
 55
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.
56 Adams View Function Builder
Adams View Function Builder Glossary
 About Design-Time Functions 59
User-Written Functions

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))
60 Adams View Function Builder
User-Written 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:
 Writing Your Own Compiled Functions
 About Design-Time Functions 61
User-Written 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.
The following C prototypes define the functional interface to the array object:
62 Adams View Function Builder
User-Written Functions

#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 */
Dims[0] = Size;
Dims[1] = Size;
 About Design-Time Functions 63
System-Supplied Functions

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
The following table lists the names and definitions for the math functions:
64 Adams View Function Builder
System-Supplied 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.
TAN The tangent of an expression that represents a numerical value.
TANH The hyperbolic tangent of an expression that represents a numerical value.
 About Design-Time Functions 65
System-Supplied Functions

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.
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.
66 Adams View Function Builder
System-Supplied Functions

This function: Returns:

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.
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.
 About Design-Time Functions 67
System-Supplied Functions

This function: Returns:

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.
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.
68 Adams View Function Builder
System-Supplied Functions

This function: Returns:

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.
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.
 About Design-Time Functions 69
System-Supplied Functions

This function: Returns:

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.
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.
70 Adams View Function Builder
System-Supplied Functions

This function: Returns:

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.
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.
 About Design-Time Functions 71
System-Supplied Functions

This function: Returns:

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.
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.
72 Adams View Function Builder
System-Supplied Functions

This function: Returns:

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.

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:
 About Design-Time Functions 73
System-Supplied 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_STRINGS Returns the index into the array if the string is found, zero if not found.
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_WHITESPACE A string that is the result of removing all leading and trailing spaces
(blank spaces, tab spaces) from the input string.
STR_REPLACE_ALL Returns a string constructed by replacing all the occurrences of the sub
string in an input string with another 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.
74 Adams View Function Builder
System-Supplied 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.
 About Design-Time Functions 75
System-Supplied Functions

This function: Returns:

DB_DELETE_DEPENDENTS An array of objects that are dependents of the object you
specified.
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_DEPENDENTS_EXHAUSTIVE Lists a complete chain of dependents (of the specified type) for
a given object. That is immediate dependents, dependents of
dependents and so on.
DB_DESCENDANTS Returns the objects of a given type, activity, and number of
levels beneath the parent.
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_OBJ_FROM_NAME_TYPE Returns the object of a given name and type.
DB_OF_CLASS A 1 if an object is a member of a given class; returns a 0 if it is
not.
76 Adams View Function Builder
System-Supplied Functions

This function: Returns:

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_REFERENTS_EXHAUSTIVE Lists a complete chain of the objects (of the specified type)
referred to by a given object. That is immediate referents,
referents of referents and so on.
DB_SHORT_NAME Returns the shortest unique name for the given object.
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:
 About Design-Time Functions 77
System-Supplied Functions

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.
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_HIERARC A text string that is a unique database name, taking into account the
HY 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.
78 Adams View Function Builder
System-Supplied Functions

This function: Returns:

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.
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.
 About Design-Time Functions 79
System-Supplied Functions

This function: Returns:

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.
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:
80 Adams View Function Builder
Design-Time Function Descriptions

This function: Returns:

BACKUP_FILE A backup of a specified file.
COPY_FILES Copies a file to the specified location. Returns 1 if successful.
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.
GETCWD The current working directory as a character string.
GETENV Text string containing the value of the environment variable you
specified.
LOCAL_FILE_ NAME Returns the local name of a file when given a name that may contain the
directory specifications.
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.
REPLACE_DELIMITER This will replace delimiter in string path and returns replaced delimiter
string.
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:
 About Design-Time Functions 81
Design-Time Function Descriptions

 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
Design-Time Function Descriptions

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

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
Design-Time Function Descriptions

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.

 Functions: A - C 85
Design-Time Function Descriptions

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
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.
86 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: A - C 87
Design-Time Function Descriptions

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
Design-Time Function Descriptions

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.

 Functions: A - C 89
Design-Time Function Descriptions

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
Design-Time Function Descriptions

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.

 Functions: A - C 91
Design-Time Function Descriptions

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=(EVAL(ALERT2 (msg.self, "ERROR")))
Learn more about GUI functions.
92 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: A - C 93
Design-Time Function Descriptions

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
Design-Time Function Descriptions

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.

 Functions: A - C 95
Design-Time Function Descriptions

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
Design-Time Function Descriptions

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.

 Functions: A - C 97
Design-Time Function Descriptions

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
Design-Time Function Descriptions

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.
 Functions: A - C 99
Design-Time Function Descriptions

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
Design-Time Function Descriptions

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.
 Functions: A - C 101
Design-Time Function Descriptions

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
Design-Time Function Descriptions

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.

 Functions: A - C 103
Design-Time Function Descriptions

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
Design-Time Function Descriptions

Learn more about math functions.

 Functions: A - C 105
Design-Time Function Descriptions

AVIEW_EDIT_FILE
This function will invoke given file, open in notepad window for the user to edit as they see fit. Also this
function can be used to view status of the file. View/edit the specified configuration file, input file and so on.
The program used to open the file depends on the environment variable: 
MDI_AVIEW_TEXT_EDITOR
However its default value is: C:\Windows\notepad.exe

Format
AVIEW_EDIT_FILE (STRING)
AVIEW_EDIT_FILE( "P:\\work\\aview.cmd" )

Arguments

String Input full file path

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

Function Variable set variable = view_file_status int =

(eval(AVIEW_EDIT_FILE($f_input_file_name)))
Result It will open input file in a notepad window to edit or view. Return 1 on successful.
106 Adams View Function Builder
Design-Time Function Descriptions

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 2 ( – ẑ 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
 Functions: A - C 107
Design-Time Function Descriptions

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.
108 Adams View Function Builder
Design-Time Function Descriptions

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 2 ( ẑ 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
 Functions: A - C 109
Design-Time Function Descriptions

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.
110 Adams View Function Builder
Design-Time Function Descriptions

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 2 ( 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
 Functions: A - C 111
Design-Time Function Descriptions

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.
112 Adams View Function Builder
Design-Time Function Descriptions

BACKUP_FILE
Renames the specified file to a backup file. The name of the backup file on Linux 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 Linux) or foo.daq (on Windows):
var set var=bkup int=(eval(BACKUP_FILE("foo.dat")))
Learn more about system functions.
 Functions: A - C 113
Design-Time Function Descriptions

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.
114 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: A - C 115
Design-Time Function Descriptions

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.

116 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: A - C 117
Design-Time Function Descriptions

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.

118 Adams View Function Builder
Design-Time Function Descriptions

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
linearly- FREQARG
Fixed linear spacing per spaced logarithmically-
FREQARG: samples: spaced 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.
FREQSTART First frequency of requested range.
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.

Examples
The following example assumes that you have four Adams View matrices, ABCD, as follows:
 Functions: A - C 119
Design-Time Function Descriptions

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.
120 Adams View Function Builder
Design-Time Function Descriptions

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 &
linear_state_equation_name = .model_1.LSE &
 Functions: A - C 121
Design-Time Function Descriptions

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.
122 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: A - C 123
Design-Time Function Descriptions

freqStart Low frequency in the omega vector.

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.
124 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: A - C 125
Design-Time Function Descriptions

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.
126 Adams View Function Builder
Design-Time Function Descriptions

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
 Functions: A - C 127
Design-Time Function Descriptions

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.
128 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: A - C 129
Design-Time Function Descriptions

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.

130 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: A - C 131
Design-Time Function Descriptions

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.

132 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: A - C 133
Design-Time Function Descriptions

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.

134 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: A - C 135
Design-Time Function Descriptions

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.

136 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: A - C 137
Design-Time Function Descriptions

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.

138 Adams View Function Builder
Design-Time Function Descriptions

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.

COND
 Functions: A - C 139
Design-Time Function Descriptions

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.

140 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: A - C 141
Design-Time Function Descriptions

COPY_FILES
Copies a file to the specified location. Returns 1 if successful.

Format
COPY_FILES(String Source_File_Path, String Target_File_Path)

Argument

Source Character string containing the full-file name to be copy.

Target Character string containing the full-path where to copy.

Example
The following example illustrates the use of the COPY_FILES function:
COPY_FILES( "P:\\work\\aview.log" ,"D:\\Some_Dir" )
returns 1
Learn more about system functions.
142 Adams View Function Builder
Design-Time Function Descriptions

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.

COSH
Returns the hyperbolic cosine of an expression that represents a numerical value.
 Functions: A - C 143
Design-Time Function Descriptions

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.

144 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: A - C 145
Design-Time Function Descriptions

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}

Note: This design function do not exactly represent Solver CUBSPL. The interpolation follows
CUBIC method (closely matches) but extrapolation follows 'linear' of 'cubic' based on type of
spline specified (based on option extrapolate_linear=yes/no).

Learn more about matrix/array functions.

146 Adams View Function Builder
Design-Time Function Descriptions

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}

Note: This design function do not exactly represent Solver CUBSPL. The interpolation follows
CUBIC method (more closely matching with CSPLINE than this function) but extrapolation
follows 'linear' of 'cubic' based on type of spline specified (based on option
extrapolate_linear=yes/no).

Learn more about matrix/array functions.

 Functions: A - C 147
Design-Time Function Descriptions
148 Adams View Function Builder
Design-Time Function Descriptions

Functions: D - E
 Functions: D - E 149
Design-Time Function Descriptions

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.
150 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: D - E 151
Design-Time Function Descriptions

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.

152 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: D - E 153
Design-Time Function Descriptions

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.
154 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: D - E 155
Design-Time Function Descriptions

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.
156 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: D - E 157
Design-Time Function Descriptions

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.

158 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: D - E 159
Design-Time Function Descriptions

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.

160 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: D - E 161
Design-Time Function Descriptions

DB_DEPENDENTS_EXHAUSTIVE
Lists a complete chain of dependents (of the specified type) for a given object. That is immediate dependents,
dependents of dependents and so on.

Format
DB_DEPENDENTS_EXHAUSTIVE (Object Name, Object Type)

Arguments

Object Name Name of a database object.

Object Type Character string (see DB_TYPE).

Example
This function is a good way to interrogate parametric models to find all of the objects of a certain type in a
model that are somehow influenced by another object like a design variable. The following example lists
information about all marker objects that depend on the design variable DV_1 or that are further down the
dependency chain (dependents of the first-degree dependent, their dependents and so on). 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.
list_info entity entity_name =
(EVAL(DB_DEPENDENTS_EXHAUSTIVE(.model_1.DV_1.self,"marker")))
Learn more about database functions.
162 Adams View Function Builder
Design-Time Function Descriptions

DB_DESCENDANTS
Returns the objects of a given type, activity, and number of levels beneath the parent.

Format
DB_DESCENDANTS (Object Name, Object Type, Activity Flag, Levels)

Arguments

Object Name Name of the parent object under which to search.

Object Type Character string (see DB_TYPE).
Activity Flag Integer flag whose value determines which objects to return:
 -1 = return objects that are inactive, or are children of inactive models
 0 = return all objects regardless of activity
 1 = return all objects whose parent model is active. If the Object Type is
"model", only return active models.
 2 = return active objects whose parent model is also active
Levels Integer flag whose value determines which objects to return:
 0 = all objects (exhaustive search) below parent
 1 = immediate children of parent
 2 = one or two levels below parent

Example
The following function creates a variable that stores all design variables whose parent model is active and exist
within the first two levels below model_1:
variable create variable=variable_list &
object_value=(DB_DESCENDANTS (.model_1, "variable", 1, 2))
Learn more about database functions.
 Functions: D - E 163
Design-Time Function Descriptions

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.
164 Adams View Function Builder
Design-Time Function Descriptions

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
 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.
 Functions: D - E 165
Design-Time Function Descriptions

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.

166 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: D - E 167
Design-Time Function Descriptions

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.

168 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: D - E 169
Design-Time Function Descriptions

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.
170 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: D - E 171
Design-Time Function Descriptions

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.

172 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: D - E 173
Design-Time Function Descriptions

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.

174 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: D - E 175
Design-Time Function Descriptions

DB_OBJ_FROM_NAME_TYPE
Returns the object of a given name and type.

Format
DB_OBJ_FROM_NAME_TYPE (Parent Object, String Name, String Object Type)

Arguments

Object Parent object under which to search.

Name Name of Object to be search
Object Class Character string (see DB_TYPE).

Example
The following function will return Link_1 object:
DB_OBJ_FROM_NAME_TYPE(.MODEL_1.PART_2 , "LINK_1" , "geometry")
Learn more about database functions.
176 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: D - E 177
Design-Time Function Descriptions

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.
178 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: D - E 179
Design-Time Function Descriptions

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.

180 Adams View Function Builder
Design-Time Function Descriptions

DB_REFERENTS_EXHAUSTIVE
Lists a complete chain of the objects (of the specified type) referred to by a given object. That is immediate
referents, referents of referents and so on.

Format
DB_REFERENTS_EXHAUSTIVE (Object Name, Object Type)

Arguments

Object Name Name of a database object.

Object Type Character string (see DB_TYPE).

Example
This function is a good way to interrogate parametric models to find all of objects of a given type that
influence a certain object in the model. The following example stores the array of objects that are immediate
referents, referents of referents and so on of Marker_1, in the variable db06:
var set var = db06 obj=(eval(DB_REFERENTS_EXHAUSTIVE(Marker_1, "all")))

Learn more about database functions.

 Functions: D - E 181
Design-Time Function Descriptions

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.
182 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: D - E 183
Design-Time Function Descriptions

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.
184 Adams View Function Builder
Design-Time Function Descriptions

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 marker:

Learn more about database functions.

 Functions: D - E 185
Design-Time Function Descriptions

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.

186 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: D - E 187
Design-Time Function Descriptions

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.

188 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: D - E 189
Design-Time Function Descriptions

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.

190 Adams View Function Builder
Design-Time Function Descriptions

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
 Functions: D - E 191
Design-Time Function Descriptions

Learn more about modeling functions.

192 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: D - E 193
Design-Time Function Descriptions

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.

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.
194 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: D - E 195
Design-Time Function Descriptions

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.

196 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: D - E 197
Design-Time Function Descriptions

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.

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
198 Adams View Function Builder
Design-Time Function Descriptions

Learn more about modeling functions

 Functions: D - E 199
Design-Time Function Descriptions

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.

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
200 Adams View Function Builder
Design-Time Function Descriptions

Learn more about modeling functions

 Functions: D - E 201
Design-Time Function Descriptions

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.

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
202 Adams View Function Builder
Design-Time Function Descriptions

Learn more about modeling functions

 Functions: D - E 203
Design-Time Function Descriptions

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.

204 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: D - E 205
Design-Time Function Descriptions

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.

206 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: D - E 207
Design-Time Function Descriptions

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.

208 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: D - E 209
Design-Time Function Descriptions

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.

210 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: D - E 211
Design-Time Function Descriptions

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.

212 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: D - E 213
Design-Time Function Descriptions

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.

214 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: D - E 215
Design-Time Function Descriptions

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.

216 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: F - L 217
Design-Time Function Descriptions

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.

218 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: F - L 219
Design-Time Function Descriptions

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.
220 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: F - L 221
Design-Time Function Descriptions

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.
222 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: F - L 223
Design-Time Function Descriptions

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.
224 Adams View Function Builder
Design-Time Function Descriptions

Numerator Coefficients A set of numerator coefficients in the transfer function.

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)
 Functions: F - L 225
Design-Time Function Descriptions

Learn more about matrix/array functions.

226 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: F - L 227
Design-Time Function Descriptions

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.
228 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: F - L 229
Design-Time Function Descriptions

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.

230 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: F - L 231
Design-Time Function Descriptions

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.

232 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: F - L 233
Design-Time Function Descriptions

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.

234 Adams View Function Builder
Design-Time Function Descriptions

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

Note: GRIDDATA uses only linear interpolation method which is the MATLAB default.

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.
 Functions: F - L 235
Design-Time Function Descriptions

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.

236 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: F - L 237
Design-Time Function Descriptions

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.

238 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: F - L 239
Design-Time Function Descriptions

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.

240 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: F - L 241
Design-Time Function Descriptions

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.

242 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: F - L 243
Design-Time Function Descriptions

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.

244 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: F - L 245
Design-Time Function Descriptions

INTERP1
Similar to 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.
Note: Not all method options of the MATLAB function with same name are supported by
this function.

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.
246 Adams View Function Builder
Design-Time Function Descriptions

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)
Learn more about matrix/array functions.
 Functions: F - L 247
Design-Time Function Descriptions

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.
248 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: F - L 249
Design-Time Function Descriptions

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.

250 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: F - L 251
Design-Time Function Descriptions

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.

252 Adams View Function Builder
Design-Time Function Descriptions

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.

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
 Functions: F - L 253
Design-Time Function Descriptions

Note: The line between the coordinate system objects is not affected by the objects' orientations.

Learn more about location/orientation functions.

254 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: F - L 255
Design-Time Function Descriptions

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.

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
256 Adams View Function Builder
Design-Time Function Descriptions

Note: Assumes that the default for angular displacement units is degrees.

Learn more about location/orientation functions.

 Functions: F - L 257
Design-Time Function Descriptions

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.
258 Adams View Function Builder
Design-Time Function Descriptions

Learn more about location/orientation functions.

 Functions: F - L 259
Design-Time Function Descriptions

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.

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)
260 Adams View Function Builder
Design-Time Function Descriptions

Learn more about location/orientation functions.

 Functions: F - L 261
Design-Time Function Descriptions

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.

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
262 Adams View Function Builder
Design-Time Function Descriptions

Note: LOC_INLINE normalizes the transformed coordinates before returning them.

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
 Functions: F - L 263
Design-Time Function Descriptions

Learn more about location/orientation functions.

264 Adams View Function Builder
Design-Time Function Descriptions

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.

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)
 Functions: F - L 265
Design-Time Function Descriptions

Learn more about location/orientation functions.

266 Adams View Function Builder
Design-Time Function Descriptions

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.

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)
 Functions: F - L 267
Design-Time Function Descriptions

Learn more about location/orientation functions.

268 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: F - L 269
Design-Time Function Descriptions

Learn more about location/orientation functions.

270 Adams View Function Builder
Design-Time Function Descriptions

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).
 Functions: F - L 271
Design-Time Function Descriptions

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
272 Adams View Function Builder
Design-Time Function Descriptions

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
 Functions: F - L 273
Design-Time Function Descriptions

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.

274 Adams View Function Builder
Design-Time Function Descriptions

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.

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
 Functions: F - L 275
Design-Time Function Descriptions

Learn more about location/orientation functions.

276 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: F - L 277
Design-Time Function Descriptions

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.

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
278 Adams View Function Builder
Design-Time Function Descriptions

Learn more about location/orientation functions.

 Functions: F - L 279
Design-Time Function Descriptions

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

Learn more about location/orientation functions.

280 Adams View Function Builder
Design-Time Function Descriptions

Notes: Special care should be taken when using the LOC_RELATIVE_TO() function when it
involves nested expressions as arguments involving parameters of database entities such as
markers. 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. So any expression involving LOC_RELATIVE_TO which belongs to the
marker database entity will automatically return the location relative to the coordinate system
of the part that owns the marker. Consider the following example in which the node_id
parameter of a flexible body f1 is parameterized using the following expression:

(LOC_TO_FLEXBODY_NODEID(.mod1.f1, LOC_RELATIVE_TO({0.0, 0.0, 0.0},

.mod1.tst)))

If this expression is evaluated using the Function Builder, the results produced will be different
from the actual evaluation of the node_id expression in the database. This is because the
expression evaluation is always relative to the parent expression. In the case of the function
builder expression evaluation, there is no parent expression, hence the
LOC_RELATIVE_TO() function will return the global location whereas when the same
expression is evaluated in the database, the LOC_RELATIVE_TO() will return the location
relative to the flexible body f1 which is the parent of the node_id.

An alternative to LOC_RELATIVE_TO() in these situations would be to use LOC_LOC()

specifying 0 as the third argument as shown below:

(LOC_TO_FLEXBODY_NODEID(.mod1.f1, LOC_LOC({0.0, 0.0, 0.0}, .mod1.tst,0)))

In this case the location returned by LOC_LOC() will always be without any parent reference
frame and hence will return consistent values when evaluated using the function builder or in
the database.
 Functions: F - L 281
Design-Time Function Descriptions

LOC_SPHERICAL
Returns Cartesian coordinates (x, y, z) that are equivalent to spherical coordinates ( ρ , θ , φ ). In this case:
 x= ρ sin θ cos φ
 y= ρ sin θ sin φ
 z= ρ cos θ

Format
LOC_SPHERICAL (Rho, Theta, Phi)

Arguments

Rho The radius of the sphere.

Theta Counterclockwise rotation about y
Phi Counterclockwise rotation about z

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

Function LOC_SPHERICAL(10, 8D, 90D)

Result 9.9, 1.39, 0

Learn more about location/orientation functions.

282 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: F - L 283
Design-Time Function Descriptions

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
284 Adams View Function Builder
Design-Time Function Descriptions

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
 Functions: F - L 285
Design-Time Function Descriptions

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
286 Adams View Function Builder
Design-Time Function Descriptions

LOCAL_FILE_ NAME
Returns the local name of a file when given a name that may contain the directory specifications:
"/user/coop/source/dbase/file.dat" → "file.dat"

Format
LOCAL_FILE_NAME(full_file_name)

Argument

Full_file_name Character string containing the full-file name.

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

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.

288 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: M - P 289
Design-Time Function Descriptions

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.

290 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: M - P 291
Design-Time Function Descriptions

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.

292 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: M - P 293
Design-Time Function Descriptions

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 Enter the marker on which the vector quantity is projected. The default is the global
coordinate system.
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)

294 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: M - P 295
Design-Time Function Descriptions

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.

296 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: M - P 297
Design-Time Function Descriptions

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.

298 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: M - P 299
Design-Time Function Descriptions

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.

300 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: M - P 301
Design-Time Function Descriptions

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.
302 Adams View Function Builder
Design-Time Function Descriptions

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.
var set var=.nodes int=(eval(node_ids_closest_to(marker_1, link,
3, 0))) &
comments = "3 closest nodes to marker"
 Functions: M - P 303
Design-Time Function Descriptions

Learn more about GUI functions.

304 Adams View Function Builder
Design-Time Function Descriptions

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.
var set var=.nodes int=(eval(node_ids_in_volume(link, sphere)))
 Functions: M - P 305
Design-Time Function Descriptions

Learn more about GUI functions.

306 Adams View Function Builder
Design-Time Function Descriptions

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)))
 Functions: M - P 307
Design-Time Function Descriptions

Learn more about GUI functions.

308 Adams View Function Builder
Design-Time Function Descriptions

NODE_NODE_CLOSEST
Returns an integer node ID associated with a node of the flexible body, new_flex, closest to node
old_node_id, on the flexible body old_flex. If intpt is set to 1, only the interface nodes are considered.

Format
NODE_NODE_CLOSEST(old_flex, new_flex, old_node_id, intpt)

Arguments

old_flex The old flexible body.

new_flex The new flexible body.
old_node_id 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_id, 1)))
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.
 Functions: M - P 309
Design-Time Function Descriptions

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.
310 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: M - P 311
Design-Time Function Descriptions

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.

312 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: M - P 313
Design-Time Function Descriptions

OBJECTIVE_UNIT
Returns the unit string for a design objective.

Format
OBJECTIVE_UNIT (Objective)

Arguments

Objective The design objective whose unit string is required.

Examples
The following is an illustration of the OBJECTIVE_UNIT function:
var set var=obj_unit str=(eval(OBJECTIVE_UNIT(.MODEL_1.OBJECTIVE_1)))
314 Adams View Function Builder
Design-Time Function Descriptions

OBJECTIVE_VALUE
Returns the value of a design objective for a particular analysis.

Format
OBJECTIVE_VALUE (Objective, Analysis)

Arguments

Objective The design objective to be evaluated

Analysis The analysis for which the objective is to be evaluated

Examples
The following is an illustration of the OBJECTIVE_VALUE function:
var set var=obj_val real=(eval(OBJECTIVE_VALUE(.MODEL_1.OBJECTIVE_1,
.MODEL_1.Last_run)))
 Functions: M - P 315
Design-Time Function Descriptions

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.

316 Adams View Function Builder
Design-Time Function Descriptions

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.

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
 Functions: M - P 317
Design-Time Function Descriptions

Learn more about location/orientation functions.

318 Adams View Function Builder
Design-Time Function Descriptions

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
 Functions: M - P 319
Design-Time Function Descriptions

Learn more about location/orientation functions.

320 Adams View Function Builder
Design-Time Function Descriptions

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

In the following illustration, the ORI_ALL_AXES function returns a body-fixed 313 Euler sequence
describing an orientation, as specified:
 Functions: M - P 321
Design-Time Function Descriptions

Function ORI_ALL_AXES({{14,18,0},{10,14,0},{16,14,0}}, zx)

Result 315, 90, 0

Learn more about location/orientation functions.

322 Adams View Function Builder
Design-Time Function Descriptions

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
 Functions: M - P 323
Design-Time Function Descriptions

Note: The returned y axis is aligned with the line through marker_1 and marker_2.

Learn more about location/orientation functions.

324 Adams View Function Builder
Design-Time Function Descriptions

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
 Functions: M - P 325
Design-Time Function Descriptions

Learn more about location/orientation functions.

326 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: M - P 327
Design-Time Function Descriptions

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.

Example
In the following illustration, the ORI_IN_PLANE function returns an orientation of a plane whose z-axis is
defined from marker_1 (100.0, 100.0, 0.0) to marker_2 (300.0, 300.0, 0.0) and whose y-axis is in the plane
defined by marker_1, marker_2 and marker_3 (350.0, 100.0, 0.0):

Function ORI_IN_PLANE(marker_1, marker_2, marker_3, "z_zy")

Result 135, 90, 90
328 Adams View Function Builder
Design-Time Function Descriptions

Learn more about location/orientation functions.

 Functions: M - P 329
Design-Time Function Descriptions

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.

330 Adams View Function Builder
Design-Time Function Descriptions

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
 Functions: M - P 331
Design-Time Function Descriptions

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.

332 Adams View Function Builder
Design-Time Function Descriptions

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

In the following illustration, the ORI_ONE_AXIS function returns a body-fixed 313 Euler sequence:
 Functions: M - P 333
Design-Time Function Descriptions

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

Learn more about location/orientation functions.

334 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: M - P 335
Design-Time Function Descriptions

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
336 Adams View Function Builder
Design-Time Function Descriptions

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
 Functions: M - P 337
Design-Time Function Descriptions

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.
338 Adams View Function Builder
Design-Time Function Descriptions

Learn more about location/orientation functions.

 Functions: M - P 339
Design-Time Function Descriptions

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
340 Adams View Function Builder
Design-Time Function Descriptions

Learn more about location/orientation functions.

 Functions: M - P 341
Design-Time Function Descriptions

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))
342 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: M - P 343
Design-Time Function Descriptions

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.

344 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: M - P 345
Design-Time Function Descriptions

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.

346 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: M - P 347
Design-Time Function Descriptions

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.
348 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: M - P 349
Design-Time Function Descriptions

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.
350 Adams View Function Builder
Design-Time Function Descriptions

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}
 Functions: M - P 351
Design-Time Function Descriptions

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.

352 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: M - P 353
Design-Time Function Descriptions

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:
354 Adams View Function Builder
Design-Time Function Descriptions

Learn more about modeling functions.

 Functions: M - P 355
Design-Time Function Descriptions

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.

Note: If the Value is File or directory path, use below file separator
conventions:
• For Windows, use double backslash, for example:
C:\\Temp\\FilePath.txt
• For Linux, use single forward slash, for example:
./usr/Temp/FilePath.txt

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.

356 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: R - S 357
Design-Time Function Descriptions

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.

358 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: R - S 359
Design-Time Function Descriptions

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.
360 Adams View Function Builder
Design-Time Function Descriptions

READ_T_O_OPEN_FILE
Opens a TeimOrbit formatted file for reading. Returns 1 on success, and 0 if any errors occur.

Format
READ_T_O_OPEN_FILE (Filename)

Prerequisites
None

Arguments

Filename Name of TeimOrbit file to read

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

Function READ_T_O_OPEN_FILE(“<acar_shared>/springs.tbl/mdi_0001.spr”)
Result 1

Function READ_T_O_OPEN_FILE(“<acar_shared>/springs.tbl/mdi_0001_spr.xml”)
Result 0

Important: Filenames are case sensitive and parameters are not case sensitive.
 Functions: R - S 361
Design-Time Function Descriptions

READ_T_O_CLOSE_FILE
Closes a previously opened TeimOrbit file. Note that only one TO file can be read from at a time, and this
command will close the currently open file. Returns 1 on success, and 0 if any errors occur.

Format
READ_T_O_CLOSE_FILE ()

Prerequisites
READ_T_O_OPEN_FILE (Filename)

Arguments
None

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

Function READ_T_O_CLOSE_FILE()
Result 1

Important: Filenames are case sensitive and parameters are not case sensitive.
362 Adams View Function Builder
Design-Time Function Descriptions

READ_T_O_FIND_BLOCK
Searches the currently open TeimOrbit file for a named block, which can then be further processed. Returns
1 on success and 0 if any errors occur.

Format
READ_T_O_FIND_BLOCK (Block Name)

Prerequisites
READ_T_O_OPEN_FILE (Filename)

Arguments

Block Name Name of block to find in TeimOrbit file. In the TO file, a block is
a string separated by brackets, for example, [MDI_HEADER]. Not
case sensitive.

Examples
[The following assumes this file has already been opened (“<acar_shared>/springs.tbl/mdi_0001.spr”)]

Function READ_T_O_FIND_BLOCK (“SPRING_DATA”)

Result 1

Function READ_T_O_FIND_BLOCK (“FREE_LENGTH”)

Result 0

This call will fail because the subblock “FREE_LENGTH” is not a block.

Important: Filenames are case sensitive and parameters are not case sensitive.
 Functions: R - S 363
Design-Time Function Descriptions

READ_T_O_FIND_SUBBLOCK
Searches the current block within the currently open file for a named subblock, which can then be further
processed. Returns 1 on success and 0 if any errors occur.

Format
READ_T_O_FIND_SUBBLOCK (Subblock Name)

Prerequisites
READ_T_O_OPEN_FILE (Filename)
READ_T_O_FIND_BLOCK (Block Name)
Or
READ_T_O_NEXT_BLOCK ()

Arguments

Subblock Name Name of subblock to find in current block within currently open file.
In the TO file, a subblock is a string separated by parentheses, for
example, (Z_DATA). Not case sensitive.

Examples
[The following assumes this file has already been opened
(“<acar_shared>/powertrains.tbl/V12_engine_map.pwr”), and the “ENGINE” block has been selected.]

Function READ_T_O_FIND_SUBBLOCK (“XY_DATA”)

Result 1

Function READ_T_O_FIND_SUBBLOCK (“USER”)

Result 0

This call will fail because the subblock “USER” is not part of the currently selected block.

Important: Filenames are case sensitive and parameters are not case sensitive.
364 Adams View Function Builder
Design-Time Function Descriptions

READ_T_O_UNITS
Reads the units specified in the currently open TeimOrbit file into the specified string variable. The variable
contains strings for the units in this order: length, force, angle, mass, time. If the unit is not present in the
TO file, the current unit is returned. Function returns 1 on success and 0 if errors occur.

Format
READ_T_O_UNITS (Unit Variable)

Prerequisites
READ_T_O_OPEN_FILE (Filename)

Arguments

Variable String variable that will hold an array of unit strings read from
the currently open TeimOrbit file. Note that it is necessary to
pass the “self ” attribute to this function.

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

Function acar toolkit get_units variable=.mdi.units_temp

READ_T_O_UNITS( .mdi.units_temp.self )
Result 1

Important: Filenames are case sensitive and parameters are not case sensitive.
 Functions: R - S 365
Design-Time Function Descriptions

READ_T_O_CHECK_HEADER
Checks that the header in the currently open file has the specified type and version number. Returns 1 on
success and 0 if errors occur.

Format
READ_T_O_CHECK_HEADER (Type, Version)

Prerequisites
READ_T_O_OPEN_FILE (Filename)

Arguments

Type String denoting the expected type of TeimOrbit file to be read. Not case sensitive.
Version Real number denoting the expected version in the TeimOrbit file.

Examples
The following examples illustrates the use of the READ_T_O_CHECK_HEADER function:

Function READ_T_O_CHECK_HEADER(‘spr’, 4)

Result 1

Function READ_T_O_CHECK_HEADER(‘spring’, 4)

Result 0

Function READ_T_O_CHECK_HEADER(‘spr’, 1)
Result 0

Important: Filenames are case sensitive and parameters are not case sensitive.
366 Adams View Function Builder
Design-Time Function Descriptions

READ_T_O_INTEGER
Searches a specified block within the currently open file for an integer attribute. Returns the integer value of
the selected attribute, or 0 if the attribute is not found or other errors occur.

Format
READ_T_O_INTEGER (Block Name, Attribute)

Prerequisites
READ_T_O_OPEN_FILE (Filename)

Arguments

Block Name Name of block in which to search

Attribute Name of attribute within the specified block to retrieve the integer value.

Examples
[The following assumes this file has already been opened
(“<acar_shared>/driver_controls.tbl/constant_radius_cornering.dcf ”).]

Function READ_T_O_INTEGER(“EXPERIMENT”, “INITIAL_GEAR”)

Result 3

Function READ_T_O_INTEGER(“EXPERIMENT”, “INITIAL_SPEED”)

Result 16

This call returns the integer representing the “INITIAL_SPEED”. Note that in this case,
READ_T_O_REAL is a better choice.

Function READ_T_O_INTEGER(“EXPERIMENT”, “EXPERIMENT_NAME”)

Result 0

This call fails since ‘EXPERIMENT_NAME’ is a string.

Important: Filenames are case sensitive and parameters are not case sensitive.
 Functions: R - S 367
Design-Time Function Descriptions

READ_T_O_SUBBLOCK_INTEGER
Searches for an integer attribute contained in the specified subblock within the specified block. Returns the
integer value of the selected attribute, or 0 if the attribute is not found or other errors occur.

Format
READ_T_O_SUBBLOCK_INTEGER (Block Name, SubBlock Name, Attribute)

Prerequisites
READ_T_O_OPEN_FILE (Filename)

Arguments

Block Name Name of block in which to search

SubBlock Name Name of subblock within the specified block in which to search

Attribute Name of attribute within the specified subblock to retrieve the integer value.

Examples
[The following assumes this file has already been opened
(“<acar_shared>/driver_controls.tbl/constant_radius_cornering.dcf ”).]

Function READ_T_O_SUBBLOCK_INTEGER(“STEADY_STATE”, “GEAR”,

“CONTROL_VALUE”)
Result 3

Function READ_T_O_SUBBLOCK_INTEGER(“STEADY_STATE”, “GEAR”,

“CONTROL_TYPE”)
Result 0

This call will fail because “CONTROL_TYPE” is not an integer.

Important: Filenames are case sensitive and parameters are not case sensitive.
368 Adams View Function Builder
Design-Time Function Descriptions

READ_T_O_REAL
Searches a specified block within the currently open TeimOrbit file for a real number attribute. Returns the
real number value of the selected attribute, or 0 if the attribute is not found or other errors occur.

Format
READ_T_O_REAL (Block Name, Attribute)

Prerequisites
READ_T_O_OPEN_FILE (Filename)

Arguments

Block Name Name of block in which to search

Attribute Name of attribute within the specified block to retrieve the real number
value. Not case sensitive.

Examples
[The following assumes this file has already been opened
(“<acar_shared>/driver_controls.tbl/constant_radius_cornering.dcf ”).]

Function READ_T_O_REAL(“EXPERIMENT”, “INITIAL_SPEED”)

Result 16.666

Function READ_T_O_REAL(“EXPERIMENT”, “MINI_MANEUVERS”)

Result 0

This call will fail because “MINI_MANEUVERS” is not an attribute.

Important: Filenames are case sensitive and parameters are not case sensitive.
 Functions: R - S 369
Design-Time Function Descriptions

READ_T_O_REAL_ARRAY
Searches a specified block within the currently open TeimOrbit file for a number or array of numbers with
the specified attribute label. Returns the real number(s) of the selected attribute, or 0.0 if the attribute is not
found or other errors occur.

Format
READ_T_O_REAL_ARRAY (Block Name, Attribute)

Prerequisites
READ_T_O_OPEN_FILE (Filename)

Arguments

Block Name Name of block in which to search

Attribute Name of attribute within the specified block to retrieve the value(s).

Examples
[The following assumes this file has already been opened
(“<aride_shared>/general_bushing.tbl/gen_bus001.gbu”)]

Function READ_T_O_REAL_ARRAY(“BUSHING_PARAMETERS”,
“X_ALPHA”)
Result 0.57941891

Function READ_T_O_REAL_ARRAY(“BUSHING_PARAMETERS”,
“RX_ALPHA”)
Result 0.0

This call will fail because “RX_ALPHA” is not a valid attribute.

Important: Filenames are case sensitive and parameters are not case sensitive.
370 Adams View Function Builder
Design-Time Function Descriptions

READ_T_O_SUBBLOCK_REAL
Searches for a real number attribute contained in the specified block and subblock. Returns the real number
value of the selected attribute, or 0 if the attribute is not found or other errors occur.

Format
READ_T_O_SUBBLOCK_REAL (Block Name, SubBlock Name, Attribute)

Prerequisites
READ_T_O_OPEN_FILE (Filename)

Arguments

Block Name Name of block in which to search

SubBlock Name Name of subblock within the specified block in which to search

Attribute Name of attribute within the specified subblock to retrieve the real number
value.

Examples
[The following assumes this file has already been opened
(“<acar_shared>/driver_controls.tbl/constant_radius_cornering.dcf ”).]

Function READ_T_O_SUBBLOCK_REAL(“STEADY_STATE”,
“MACHINE_CONTROL”, “RADIUS”)
Result 80.0

Function READ_T_O_SUBBLOCK_REAL(“STEADY_STATE”,
“MACHINE_CONTROL”, “TURN_DIRECTION”)
Result 0.0

This call will fail because “TURN_DIRECTION” is not a real number.

Important: Filenames are case sensitive and parameters are not case sensitive.
 Functions: R - S 371
Design-Time Function Descriptions

READ_T_O_SUBBLOCK_REAL_ARRAY
Searches a specified subblock within the currently selected block within the open TeimOrbit file for a number
or array of numbers with the specified attribute label. Returns the real number(s) of the selected attribute, or
0.0 if the attribute is not found or other errors occur.

Format
READ_T_O_SUBBLOCK_REAL_ARRAY (Block Name, SubBlock Name, Attribute)

Prerequisites
READ_T_O_OPEN_FILE (Filename)

Arguments

Block Name Name of block in which the subblock resides

SubBlock Name Name of subblock in which to search
Attribute Name of attribute within the specified block to retrieve the value(s).

Example
[Suppose there is a subblock “BUSHING_A” within the “BUSHING_PARAMETERS” block]

Function READ_T_O_SUBBLOCK_REAL_ARRAY(“BUSHING_PARAMETERS”,
“BUSHING_1”, “X_ALPHA”)
Result 0.57941891

Important: Filenames are case sensitive and parameters are not case sensitive.
372 Adams View Function Builder
Design-Time Function Descriptions

READ_T_O_STRING
Searches a specified block within the currently open file for a string attribute. Returns the string value of the
selected attribute, or a null string if the attribute is not found or other errors occur.

Format
READ_T_O_STRING (Block Name, Attribute)

Prerequisites
READ_T_O_OPEN_FILE (Filename)

Arguments

Block Name Name of block in which to search

Attribute Name of attribute within the specified block to retrieve the string value.

Examples
[The following assumes this file has already been opened
(“<acar_shared>/driver_controls.tbl/constant_radius_cornering.dcf ”).]

Function READ_T_O_STRING(“EXPERIMENT”, “STATIC_SETUP”)

Result “STRAIGHT”

Function READ_T_O_STRING(“EXPERIMENT”, “INITIAL_GEAR”)

Result “”

This call will fail because “INITIAL_GEAR” is not a string value.

Important: Filenames are case sensitive and parameters are not case sensitive.
 Functions: R - S 373
Design-Time Function Descriptions

READ_T_O_SUBBLOCK_STRING
Searches for a string attribute contained in the specified block and subblock. Returns the string value of the
selected attribute, or a null string if the attribute is not found or other errors occur.

Format
READ_T_O_SUBBLOCK_STRING (Block Name, SubBlock Name, Attribute)

Prerequisites
READ_T_O_OPEN_FILE (Filename)

Arguments

Block Name Name of block in which to search

SubBlock Name Name of subblock within the specified block in which to search

Attribute Name of attribute within the specified subblock to retrieve the string value.

Examples
[The following assumes this file has already been opened
(“<acar_shared>/driver_controls.tbl/constant_radius_cornering.dcf ”)]

Function READ_T_O_SUBBLOCK_STRING (“STEADY_STATE”, “STEERING”,

“METHOD”)
Result “MACHINE”

Function READ_T_O_SUBBLOCK_STRING (“STEADY_STATE”, “GEAR”,

“CONTROL_VALUE”)
Result “”

This call will fail because “CONTROL_VALUE” is not a string.

Important: Filenames are case sensitive and parameters are not case sensitive.
374 Adams View Function Builder
Design-Time Function Descriptions

READ_T_O_TABLE_COLUMN
Searches a specified block within the currently open TeimOrbit file for column of real numbers with the
specified attribute label. Returns the one-dimensional array of real number values from the selected column,
or 0.0 if the attribute is not found or other errors occur.

Format
READ_T_O_TABLE_COLUMN (Block Name, Column)

Prerequisites
READ_T_O_OPEN_FILE (Filename)

Arguments

Block Name Name of block in which to search

Column Column header within the specified block to retrieve the one-dimensional array
of real number values.

Examples
[The following assumes this file has already been opened (“<acar_shared>/springs.tbl/mdi_0001.spr”)]

Function READ_T_O_TABLE_COLUMN (“CURVE”, “force”)

Result [-10750.0, -8000.0, …, 10750.0]

Function READ_T_O_TABLE_COLUMN (“CURVE”, “velocity”)

Result 0.0

This call will fail because “velocity” is not a column within the “CURVE” block.

Important: Filenames are case sensitive and parameters are not case sensitive.
 Functions: R - S 375
Design-Time Function Descriptions

READ_T_O_SUBBLOCK_TABLE_COLUMN
Searches a specified subblock block within selected block in the currently open TeimOrbit file for column of
real numbers with the specified attribute label. Returns the one-dimensional array of real number values from
the selected column, or 0.0 if the attribute is not found or other errors occur.

Format
READ_T_O_SUBBLOCK_TABLE_COLUMN (Block Name, SubBlock Name, Column)

Prerequisites
READ_T_O_OPEN_FILE (Filename)

Arguments

SubBlock Name Name of subblock in which to search

Block Name Name of block in which to search
Column Column header within the specified subblock to retrieve the one-dimensional array of
real number values.

Examples
[The following assumes this file has already been opened
(“<acar_shared>/powertrains.tbl/V12_engine_map.pwr”)]

Function READ_T_O_SUBBLOCK_TABLE_COLUMN (“ENGINE”, “XY_DATA”,

“engine_speed”)
Result [0.0,500.0,1000.0,…,7500.0]

Function READ_T_O_SUBBLOCK_TABLE_COLUMN (“ENGINE”, “XY_DATA”,

“throttle”)
Result 0.0

This call will fail because “throttle” is not within the “XY_DATA” subblock.

Important: Filenames are case sensitive and parameters are not case sensitive.
376 Adams View Function Builder
Design-Time Function Descriptions

READ_T_O_START_TABLE_READ
Searches the currently open TeimOrbit file for the specified table, and returns the first line of text from the
table. Returns an empty string if the table is not found or other errors occur.

Format
READ_T_O_START_TABLE_READ (Block Name)

Prerequisites
READ_T_O_OPEN_FILE (Filename)

Arguments

Block Name Name of block in which to read from

Examples
[The following assumes this file has already been opened (“<acar_shared>/springs.tbl/mdi_0001.spr”)]

Function READ_T_O_START_TABLE_READ(“CURVE”)
Result { disp force}

Function READ_T_O_START_TABLE_READ(“FREE_LENGTH”)
Result “”

Important: Filenames are case sensitive and parameters are not case sensitive.
 Functions: R - S 377
Design-Time Function Descriptions

READ_T_O_START_SUBBLOCK_TABLE_READ
Searches the currently open TeimOrbit file for the specified subblock contained within the selected block,
and returns the first line of text from the subblock table. Returns an empty string if the subblock is not found
or other errors occur.

Format
READ_T_O_START_SUBBLOCK_TABLE_READ (Block Name, SubBlock Name)

Prerequisites
READ_T_O_OPEN_FILE (Filename)

Arguments

Block Name Name of block in which to search

SubBlock Name Name of subblock in which to read from

Examples
[The following assumes this file has already been opened
(“<acar_shared>/powertrains.tbl/V12_engine_map.pwr”)]

Function READ_T_O_START_SUBBLOCK_TABLE_READ(“ENGINE”, “XY_DATA”)

Result {engine_speed <rpm> torque@throttle <torque>}

Function READ_T_O_START_SUBBLOCK_TABLE_READ (“ENGINE”, “throttle”)

Result “”

Important: Filenames are case sensitive and parameters are not case sensitive.
378 Adams View Function Builder
Design-Time Function Descriptions

READ_T_O_READ_TABLE_LINE
Reads next line in current block or subblock.

Format
READ_T_O_READ_TABLE_LINE ()

Prerequisites
READ_T_O_OPEN_FILE (Filename)
READ_T_O_START_TABLE_READ (Block Name)
or
READ_T_O_START_TABLE_SUBBLOCK_READ (Block Name, SubBlock Name)

Arguments
None

Examples
[The following assumes this file has already been opened (“<acar_shared>/springs.tbl/mdi_0001.spr”), and
read_t_o_start_table_read has been used to read the first line in the “CURVE” block.]

Function READ_T_O_READ_TABLE_LINE ()
Result “-110.0 -10750.0”

Note that the first time this is called after the READ_T_O_START_TABLE_READ will return the first
string in the block.

Important: Filenames are case sensitive and parameters are not case sensitive.
 Functions: R - S 379
Design-Time Function Descriptions

READ_T_O_NEXT_BLOCK
Moves to the next block in the currently open TeimOrbit file. Returns a string with the block type, or a null
string if there is no next block in the file.

Format
READ_T_O_NEXT_BLOCK ()

Prerequisites
READ_T_O_OPEN_FILE (Filename)

Arguments
None

Examples
[The following assumes this file has already been opened
(“<acar_shared>/driver_controls.tbl/constant_radius_cornering.dcf ”), and the previous read was in the
“EXPERIMENT” block]

Function READ_T_O_NEXT_BLOCK()
Result “STEADY_STATE”

If the function was issued again, a null string would be returned, since “STEADY_STATE” is the last block
in the file:

Function READ_T_O_NEXT_BLOCK()
Result “”

Important: Filenames are case sensitive and parameters are not case sensitive.
380 Adams View Function Builder
Design-Time Function Descriptions

READ_T_O_NEXT_ATTRIBUTE
Reads the next attribute in the file. Returns a null string if there are no more attributes in the file.

Format
READ_T_O_NEXT_ATTRIBUTE ()

Prerequisites
READ_T_O_OPEN_FILE (Filename)

Arguments
None

Examples
[The following assumes this file has already been opened
(“<acar_shared>/driver_controls.tbl/constant_radius_cornering.dcf ”), and the previous read was at the start
of the “STEADY_STATE” block]

Function READ_T_O_NEXT_ATTRIBUTE ()
Result ACTUATOR_TYPE = 'TORQUE'

Important: Filenames are case sensitive and parameters are not case sensitive.
 Functions: R - S 381
Design-Time Function Descriptions

READ_T_O_BLOCK_EXISTS
Searches a TeimOrbit file for existence of a specified block. Returns 1 if the block is found, otherwise 0.

Format
READ_T_O_BLOCK_EXISTS (Filename, Block Name)

Arguments

Filename TeimOrbit file to read

Block Name Block to search for in file.

Examples

Function READ_T_O_BLOCK_EXISTS(“<acar_shared>/springs.tbl/mdi_0001.spr”,
“CURVE”)
Result 1

Function READ_T_O_BLOCK_EXISTS(“<acar_shared>/springs.tbl/mdi_0001.spr”,
“FREE_LENGTH”)
Result 0

Important: Filenames are case sensitive and parameters are not case sensitive.
382 Adams View Function Builder
Design-Time Function Descriptions

READ_T_O_ATTRIBUTE_EXISTS
Searches a TeimOrbit file for existence of an attribute in a specified block or subblock. Returns 1 if the block
is found, otherwise 0.

Format
READ_T_O_ATTRIBUTE_EXISTS (Filename, Block Name, SubBlock Name, Attribute Name)

Arguments

Filename TeimOrbit file to read

Block Name Block to search for in file.
SubBlock Name SubBlock to search for in specified block. Pass a null string if no subblock is
selected.
Attribute Name Attribute to search for in specified subblock.

Examples

Function READ_T_O_ATTRIBUTE_EXISTS
(“<acar_shared>/springs.tbl/mdi_0001.spr”, “SPRING_DATA”, “”,
“FREE_LENGTH”)
Result 1

Function READ_T_O_ATTRIBUTE_EXISTS
(“<acar_shared>/springs.tbl/mdi_0001.spr”, “SPRING_DATA”,
“FREE_LENGTH”)
Result 0

Important: Filenames are case sensitive and parameters are not case sensitive.
 Functions: R - S 383
Design-Time Function Descriptions

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.

384 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: R - S 385
Design-Time Function Descriptions

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.

386 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: R - S 387
Design-Time Function Descriptions

REPLACE_DELIMITER
This will replace delimiter in string path and returns replaced delimiter string.

Format
REPLACE_DELIMITER("P:/work/tests/Test_1.log" )

Argument

Path String Full_Path (containing "/")

Example
The following example illustrates the use of the REPLACE_DELIMITER function:
REPLACE_DELIMITER ("P:/work/tests/Test_1.log")
Return "P:\work\tests\Test_1.log"
Learn more about system functions.
388 Adams View Function Builder
Design-Time Function Descriptions

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, 3, 1]}, {2.5,3.5}, "CUBIC", 200)

Result {0.015, 2.0, 3.0, 2.0, 1.0, 0.0}

Learn more about matrix/array functions.

 Functions: R - S 389
Design-Time Function Descriptions

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.

390 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: R - S 391
Design-Time Function Descriptions

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.
392 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: R - S 393
Design-Time Function Descriptions

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.
394 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: R - S 395
Design-Time Function Descriptions

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.

396 Adams View Function Builder
Design-Time Function Descriptions

RUN_PYTHON_CODE
Executes Python code. If successful, it returns a 1; otherwise returns 0.

Format
RUN_PYTHON_CODE(Python code as String)

Arguments

String A string containing the Python source code. It may contain multiple lines, separated by
'\n'.

Example
The following function will return 1:
RUN_PYTHON_CODE("sys.version")
 Functions: R - S 397
Design-Time Function Descriptions

RUN_PYTHON_FILE
Imports the input Python file. If successful, it returns a 1; otherwise, it returns 0.

Format
RUN_PYTHON_FILE(Path to python file)

Arguments

String Python file path as string.

Example
The following function will return 1:
RUN_PYTHON_FILE ("Test.py")
398 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: R - S 399
Design-Time Function Descriptions

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.
400 Adams View Function Builder
Design-Time Function Descriptions
 Functions: R - S 401
Design-Time Function Descriptions

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.
402 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: R - S 403
Design-Time Function Descriptions

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.
404 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: R - S 405
Design-Time Function Descriptions

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.
406 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: R - S 407
Design-Time Function Descriptions

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.
408 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: R - S 409
Design-Time Function Descriptions

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.

410 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: R - S 411
Design-Time Function Descriptions

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.

412 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: R - S 413
Design-Time Function Descriptions

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.

Return Codes

Return Value Return Code Description

0 NOERRS No errors
-101 INPERR Errors while opening ADAMS output files
-102 BADSIT Site security checking not successful
-105 ERINPT Errors while reading in ADAMS dataset
-117 ERVRFY Model did not pass verification phase
-118 ERMEMO Problem during memory initialization phase
-119 ERRVRS UCONFG Version mismatch
-120 ERRDIM UCONFG passes negative array dimensions
-121 ERRLCK Lockup detected
-122 BADMEM Problem allocating memory
-123 BADAMD Problem initiating AMD Command Parser
-124 ERRSML Simulation failure detected
-125 NOTCXX The Model is not compatible with the C++ solver
-998 TERMNT Current session terminated before completion
-997 INPTRM Session terminated before completion during input phase
-996 PRFLER Program Fault was encountered
-995 ERTERM Abnormal termination of Solver
-994 SNHALT Sensor Halt was imposed
414 Adams View Function Builder
Design-Time Function Descriptions

Return Value Return Code Description

-993 TRMRCR Recursion encountered when trying to terminate
-200 QUITFL Quit Solver, control goes back to the driver
100 BADCMD Erroneous command issued

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.
 Functions: R - S 415
Design-Time Function Descriptions

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.

416 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: R - S 417
Design-Time Function Descriptions

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.

418 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: R - S 419
Design-Time Function Descriptions

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.

420 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: R - S 421
Design-Time Function Descriptions

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.

422 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: R - S 423
Design-Time Function Descriptions

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.

424 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: R - S 425
Design-Time Function Descriptions

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.

426 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: R - S 427
Design-Time Function Descriptions

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.

428 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: R - S 429
Design-Time Function Descriptions

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.

430 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: R - S 431
Design-Time Function Descriptions

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.

432 Adams View Function Builder
Design-Time Function Descriptions

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. The ASCII table is used for this, see examples below.

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. Note that the string is not case senstive.

Function STR_COMPARE("adjective","adjective")
or
STR_COMPARE("ADJECTIVE","adjective")
or
STR_COMPARE("AdjEctIVe","adjective")
Result 0

The following function returns a positive number (corresponding to the difference in character order),
indicating that the second string comes before the first string in ASCII character order:

Function STR_COMPARE("verb","subject")
Result 3

The following function returns a negative number (corresponding to the difference in character order),
indicating that the second string comes after the first string in ASCII character order:

Function STR_COMPARE("varb","verb")
Result -4

Learn more about string functions.

 Functions: R - S 433
Design-Time Function Descriptions

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 integer) N
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
434 Adams View Function Builder
Design-Time Function Descriptions

%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
 Functions: R - S 435
Design-Time Function Descriptions

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.

436 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: R - S 437
Design-Time Function Descriptions

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.

438 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: R - S 439
Design-Time Function Descriptions

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.
440 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: R - S 441
Design-Time Function Descriptions

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.

442 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: R - S 443
Design-Time Function Descriptions

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.

444 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: R - S 445
Design-Time Function Descriptions

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.

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
446 Adams View Function Builder
Design-Time Function Descriptions

Function STR_MATCH("1?{800,888}?[2ABC][3DEF]*, "1-800-2357205)

Result 1

Learn more about string functions.

 Functions: R - S 447
Design-Time Function Descriptions

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 .

448 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: R - S 449
Design-Time Function Descriptions

STR_REPLACE_ALL
Returns a string constructed by replacing all the occurrences of the sub string in an input string with another
string

Format
STR_REPLACE_ALL (Destination String, Old Sub String, New Replace String)

Argument

Destination String Text string.

Old Sub String Text string to replace in destination string
New Replace String Text string to be replace with old sub string in destination string

Example
The following function returns string constructed by replacing all the occurrence of old sub string with new
string

Function str_replace_all("aabbccaaaeeffaaaa","aa","cba")
Result "cbabbcccbaaeeffcbacba"

Learn more about string functions.

450 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: R - S 451
Design-Time Function Descriptions

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.

452 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: R - S 453
Design-Time Function Descriptions

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.

454 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: R - S 455
Design-Time Function Descriptions

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.

456 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: T - Z 457
Design-Time Function Descriptions

Functions: T - Z
458 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: T - Z 459
Design-Time Function Descriptions

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.

460 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: T - Z 461
Design-Time Function Descriptions

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.

462 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: T - Z 463
Design-Time Function Descriptions

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.

464 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: T - Z 465
Design-Time Function Descriptions

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.

466 Adams View Function Builder
Design-Time Function Descriptions

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.

Return Codes

Return Value Return Code Description

0 NOERRS No errors
-101 INPERR Errors while opening ADAMS output files
-102 BADSIT Site security checking not successful
-105 ERINPT Errors while reading in ADAMS dataset
-117 ERVRFY Model did not pass verification phase
-118 ERMEMO Problem during memory initalization phase
-119 ERRVRS UCONFG Version mismatch
-120 ERRDIM UCONFG passes negative array dimensions
-121 ERRLCK Lockup detected
-122 BADMEM Problem allocating memory
-123 BADAMD Problem initiating AMD Command Parser
-124 ERRSML Simulation failure detected
-125 NOTCXX The Model is not compatible with the C++ solver
-998 TERMNT Current session terminated before completion
-997 INPTRM Session terminated before completion during input phase
 Functions: T - Z 467
Design-Time Function Descriptions

Return Value Return Code Description

-996 PRFLER Program Fault was encountered
-995 ERTERM Abnormal termination of Solver
-994 SNHALT Sensor Halt was imposed
-993 TRMRCR Recursion encountered when trying to terminate
-200 QUITFL Quit Solver, control goes back to the driver
100 BADCMD Erroneous command issued

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.
468 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: T - Z 469
Design-Time Function Descriptions

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.

470 Adams View Function Builder
Design-Time Function Descriptions

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

endFlag 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 CPU 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(1)))
variable set var=foo string=(eval(str_print("file read took "
//mycpu//"cpuseconds")))
Learn more about GUI functions.
 Functions: T - Z 471
Design-Time Function Descriptions

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

endFlag 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 CPU time since the last timer
started is returned.

Example
variable set variable=myelapse real=(eval(timer_elapsed(0)))
file command read file="mybigcmdfile.cmd"
var set var=foo string=(eval(str_print("File read took"
//timer_elapsed(1)//" seconds")))
Learn more about GUI functions.
472 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: T - Z 473
Design-Time Function Descriptions

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.
474 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: T - Z 475
Design-Time Function Descriptions

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.

476 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: T - Z 477
Design-Time Function Descriptions

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.

478 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: T - Z 479
Design-Time Function Descriptions

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.
480 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: T - Z 481
Design-Time Function Descriptions

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.

482 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: T - Z 483
Design-Time Function Descriptions

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.

484 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: T - Z 485
Design-Time Function Descriptions

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.

486 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: T - Z 487
Design-Time Function Descriptions

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.

488 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: T - Z 489
Design-Time Function Descriptions

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.

490 Adams View Function Builder
Design-Time Function Descriptions

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.
 Functions: T - Z 491
Design-Time Function Descriptions

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.

492 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: T - Z 493
Design-Time Function Descriptions

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.

494 Adams View Function Builder
Design-Time Function Descriptions

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.

 Functions: T - Z 495
Design-Time Function Descriptions

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.

496 Adams View Function Builder
Design-Time Function Descriptions

WRITE_T_O_OPEN_FILE
Open an TeimOrbit file for writing. Returns 1 on success and 0 if an error occurs.

Format
WRITE_T_O_OPEN_FILE (Filename, Append)

Prerequisites
None

Arguments

Filename TeimOrbit file to write.

Append 1 = append to current file, 0 = create new file

Example

Function WRITE_T_O_OPEN_FILE (“mdi_0001_new.spr”, 0)

Result 1

Important: Filenames are case sensitive and parameters are not case sensitive.
 Functions: T - Z 497
Design-Time Function Descriptions

WRITE_T_O_CLOSE_FILE
Close currently open TeimOrbit file. Returns 1 on success and 0 if an error occurs.

Format
WRITE_T_O_CLOSE_FILE ()

Prerequisites
WRITE_T_O_OPEN_FILE (Filename)

Arguments
None

Example

Function WRITE_T_O_CLOSE_FILE ()
Result 1

Important: Filenames are case sensitive and parameters are not case sensitive.
498 Adams View Function Builder
Design-Time Function Descriptions

WRITE_T_O_UNITS
Write units to file based on string variable containing an array of strings corresponding to the units, obtained
via a call to “get_units”. Return 1 on success and 0 if errors occur.

Format
WRITE_T_O_UNITS (Variable)

Prerequisites
WRITE_T_O_OPEN_FILE (Filename)

Arguments

Variable String variable containing an array of strings corresponding to the units length,
angle, force, mass and time. If there is no string at the corresponding index, no
unit is written to the file.

Example

Function acar toolkit get_units variable=.mdi.my_unit_var

WRITE_T_O_UNITS (.mdi.my_unit_var.self )
Result 1
Writes to file $--------------------------------------------UNITS
[UNITS]
LENGTH = 'mm'
ANGLE = 'degrees'
FORCE = 'newton'
MASS = 'kg'
TIME = 'second'

Important: Filenames are case sensitive and parameters are not case sensitive.
 Functions: T - Z 499
Design-Time Function Descriptions

WRITE_T_O_DATA_BLOCK
Write a block to the currently open file. Returns 1 on success and 0 if errors occur.

Format
WRITE_T_O_DATA_BLOCK (Block Name)

Prerequisites
WRITE_T_O_OPEN_FILE (Filename)

Arguments

Block Name Block to write to currently open file.

Example

Function WRITE_T_O_DATA_BLOCK (“CURVE”)

Result 1

Writes to file $----------------------------------------CURVE

[CURVE]

Important: Filenames are case sensitive and parameters are not case sensitive.
500 Adams View Function Builder
Design-Time Function Descriptions

WRITE_T_O_SUBBLOCK
Write subblock to currently selected block in the open file. Returns 1 on success and 0 if errors occur.

Format
WRITE_T_O_SUBBLOCK (SubBlock Name)

Prerequisites
WRITE_T_O_OPEN_FILE (Filename)
WRITE_T_O_DATA_BLOCK (Block Name)

Arguments

SubBlock Name Name of subblock to write to file.

Example

Function WRITE_T_O_SUBBLOCK (“Z_DATA”)

Result 1
Writes to file (Z_DATA)

Important: Filenames are case sensitive and parameters are not case sensitive.
 Functions: T - Z 501
Design-Time Function Descriptions

WRITE_T_O_INTEGER
Writes an attribute to the current block with the specified integer value. Returns 1 on success and 0 if errors
occur.

Format
WRITE_T_O_INTEGER (Attribute, Value)

Prerequisites
WRITE_T_O_OPEN_FILE (Filename)
WRITE_T_O_DATA_BLOCK (Block Name)

Arguments

Attribute Name of attribute to write

Value Integer value for specified attribute

Example

Function WRITE_T_O_INTEGER (“CONTROL_VALUE”, 4)

Result 1
Writes to file CONTROL_VALUE = 4

Important: Filenames are case sensitive and parameters are not case sensitive.
502 Adams View Function Builder
Design-Time Function Descriptions

WRITE_T_O_REAL
Writes an attribute to the current block with the specified real number value. Returns 1 on success and 0 if
errors occur.

Format
WRITE_T_O_REAL (Attribute, Value)

Prerequisites
WRITE_T_O_OPEN_FILE (Filename)
WRITE_T_O_DATA_BLOCK (Block Name)

Arguments

Attribute Name of attribute to write

Value Real number value for specified attribute

Examples

Function WRITE_T_O_INTEGER (“RADIUS”, 90.0)

Result 1

Writes to file RADIUS = 90.0

Function WRITE_T_O_INTEGER (“RADIUS”, “no”)

Result 0

Important: Filenames are case sensitive and parameters are not case sensitive.
 Functions: T - Z 503
Design-Time Function Descriptions

WRITE_T_O_REAL_ARRAY
Writes an array of real numbers to the currently open file with the specified attribute label. Returns 1 on
success and 0 if errors occur.

Format
WRITE_T_O_REAL_ARRAY (Array, Attribute)

Prerequisites
WRITE_T_O_OPEN_FILE (Filename)
WRITE_T_O_DATA_BLOCK (Block Name)

Arguments

Array Array of real values

Attribute Name of attribute to assign array to.

Examples

Function WRITE_T_O_REAL_ARRAY ({1,2,3,4,5}, “NEW_ARRAY”)

Result 1

Writes to file NEW_ARRAY = 1.0, 2.0, 3.0, 4.0, 5.0

Function WRITE_T_O_REAL_ARRAY ({‘a’,’b’,’c’,’d’,’e’}, “NEW_ARRAY”)

Result 0

Important: Filenames are case sensitive and parameters are not case sensitive.
504 Adams View Function Builder
Design-Time Function Descriptions

WRITE_T_O_PUSH_PRECISION
Sets the precision of the real numbers written to the currently open file. Returns 1.

Format
WRITE_T_O_PUSH_PRECISION (Precision)

Prerequisites
WRITE_T_O_OPEN_FILE (Filename)

Arguments

Precision Number of significant digits in real numbers written to file.

Example

Function WRITE_T_O_PUSH_PRECISION (3)

Result 1

Important: Filenames are case sensitive and parameters are not case sensitive.
 Functions: T - Z 505
Design-Time Function Descriptions

WRITE_T_O_POP_PRECISION
Sets the precision to the previous precision for the real numbers written to the currently opened file. Returns
1 on success, and 0 if there are errors.

Format
WRITE_T_O_POP_PRECISION ()

Prerequisites
WRITE_T_O_OPEN_FILE (Filename)

Arguments
None

Example

Function WRITE_T_O_POP_PRECISION ()
Result 1

Important: Filenames are case sensitive and parameters are not case sensitive.
506 Adams View Function Builder
Design-Time Function Descriptions

WRITE_T_O_STRING
Writes an attribute to the current block with the specified string value. Returns 1 on success and 0 if errors
occur.

Format
WRITE_T_O_STRING (Attribute, Value)

Prerequisites
WRITE_T_O_OPEN_FILE (Filename)
WRITE_T_O_DATA_BLOCK (Block Name)

Arguments

Attribute Name of attribute to write

Value String value for specified attribute

Examples

Function WRITE_T_O_STRING (“ACTUATOR_TYPE”, “TORQUE”)

Result 1
Writes to File ACTUATOR_TYPE = 'TORQUE'

Function WRITE_T_O_STRING (“ACTUATOR_TYPE”, 5)

Result 0

Important: Filenames are case sensitive and parameters are not case sensitive.
 Functions: T - Z 507
Design-Time Function Descriptions

WRITE_T_O_TABLE_HEADER
Writes a head to the currently selected block or subblock within the currently open file. Writes 1 on success
and 0 if errors occur.

Format
WRITE_T_O_TABLE_HEADER (Value)

Prerequisites
WRITE_T_O_OPEN_FILE (Filename)
WRITE_T_O_DATA_BLOCK (Block Name)

Arguments

Value Header text to write to the file.

Example

Function WRITE_T_O_TABLE_HEADER (“disp force”)

Result 1
Writes to File { disp force }

Important: Filenames are case sensitive and parameters are not case sensitive.
508 Adams View Function Builder
Design-Time Function Descriptions

WRITE_T_O_TABLE_REALS
Writes a single row of array values to the current table. Returns 1 on success and 0 if errors occur.

Format
WRITE_T_O_TABLE_REALS (Array)

Prerequisites
WRITE_T_O_OPEN_FILE (Filename)
WRITE_T_O_DATA_BLOCK (Block Name)

Arguments

Array Array of real number values to write to table.

Example

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

Result 1
Writes to file 1.0 2.0 3.0 4.0

Important: Filenames are case sensitive and parameters are not case sensitive.
 Functions: T - Z 509
Design-Time Function Descriptions

WRITE_I_N_TABLE_REALS
Writes multiple columns of real values to the current table. Returns 1 on success and 0 if errors occur.

Format
WRITE_I_N_ TABLE_REALS (Array, Value)

Prerequisites
WRITE_T_O_OPEN_FILE (Filename)
WRITE_T_O_DATA_BLOCK (Block Name)

Arguments

Array Array of real number values to write to table.

Value Number of rows in each column.

Example

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

Result 1
Writes to file 1.0 2.0

3.0 4.0

5.0 6.0

7.0 8.0

Important: Filenames are case sensitive and parameters are not case sensitive.
510 Adams View Function Builder
Design-Time Function Descriptions

WRITE_T_O_TABLE_LINE
Writes a line of text to the currently open file. Returns 1 on success and 0 if errors occur.

Format
WRITE_T_O_TABLE_LINE (Line)

Prerequisites
WRITE_T_O_OPEN_FILE (Filename)

Arguments

Line Text to write to file.

Example

Function WRITE_T_O_TABLE_LINE(“$---------STEADY_STATE”)

Result 1
Writes to file $---------STEADY_STATE

Important: Filenames are case sensitive and parameters are not case sensitive.
 Functions: T - Z 511
Design-Time Function Descriptions

WRITE_T_O_TABLE_STRING
Writes a quoted line of text to the currently open file. Returns 1 on success and 0 if errors occur.

Format
WRITE_T_O_TABLE_LINE (Line)

Prerequisites
WRITE_T_O_OPEN_FILE (Filename)

Arguments

Line Text to write to file.

Example

Function WRITE_T_O_TABLE_LINE (“Example of straight line acceleration

using machine controls”)
Result 1
Writes to file ‘Example of straight line acceleration using machine controls’

Important: Filenames are case sensitive and parameters are not case sensitive.
512 Adams View Function Builder
Design-Time Function Descriptions

WRITE_T_O_COMMENT
Writes a commented line of text to the currently open file. Returns 1 on success and 0 if errors occur.

Format
WRITE_T_O_COMMENT (Comment)

Prerequisites
WRITE_T_O_OPEN_FILE (Filename)

Arguments

Comment Text to write to file.

Example

Function WRITE_T_O_TABLE_LINE (“-------------MDI_HEADER”)

Result 1
Writes to file $-------------MDI_HEADER

Important: Filenames are case sensitive and parameters are not case sensitive.
 Functions: T - Z 513
Design-Time Function Descriptions

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:
514 Adams View Function Builder
Design-Time Function Descriptions

In Adams, PITCH is defined as the negative value of the second Body 321 rotation angle.
 Functions: T - Z 515
Design-Time Function Descriptions

There are always two equivalent sets of rotation angles that yield the same final rotation.
Learn more about modeling functions.
516 Adams View Function Builder
Design-Time Function Descriptions
 About Run-Time Functions 461
Run-Time Functions Categories

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.

Run-Time Functions Categories

The two major types of run-time functions are:
 System-Supplied Run-Time Functions
 User-Supplied Run-Time Functions

System-Supplied Run-Time Functions

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.
462 Adams View Function Builder
Run-Time Functions Categories

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

1. 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.
 About Run-Time Functions 463
Run-Time Functions Categories

This function: Returns:

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

2. 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:
464 Adams View Function Builder
Run-Time Functions Categories

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

3. 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:
 About Run-Time Functions 465
Run-Time Functions Categories

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

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

5. 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:
466 Adams View Function Builder
Run-Time Functions Categories

 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
 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.
 About Run-Time Functions 467
Run-Time Functions Categories

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

6. 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.
468 Adams View Function Builder
Run-Time Functions Categories

 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.
 Which force vector component you want to obtain.
Using a Force in Object Function
 About Run-Time Functions 469
Run-Time Functions Categories

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:

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
470 Adams View Function Builder
Run-Time Functions Categories

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.
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.
 About Run-Time Functions 471
Run-Time Functions Categories

Function: Returns:
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.

7. 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.
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.
472 Adams View Function Builder
Run-Time Functions Categories

8. 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.
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.
 About Run-Time Functions 473
Run-Time Functions Categories

Function: Does the following:

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

9. Vector Functions
Vector functions represent the class of functions that carry out vector operations. The following table lists the
names and definitions for the Vector functions available through the Function Builder:
474 Adams View Function Builder
Run-Time Functions Categories

Function: Returns:
Translational Displacement Vector (DXYZ) A translational displacement vector between two
coordinate system markers.
Unit vector along X (UVX) A unit vector in the X-axis direction of a coordinate system
marker resolved in the coordinate system of another marker
Unit vector along Y (UVY) A unit vector in the Y-axis direction of a coordinate system
marker resolved in the coordinate system of another marker
Unit vector along Z (UVZ) A unit vector in the Z-axis direction of a coordinate system
marker resolved in the coordinate system of another marker
Difference between acceleration vectors (ACCXYZ) Difference between the acceleration vectors of two
coordinate system markers resolved in the coordinate
system of another marker
Translational Force Vector (FXYZ) The net translational force vector acting on a coordinate
system marker expressed in the coordinate system of
another marker
Translational Torque Vector (TXYZ) The net translational torque vector acting on a coordinate
system marker expressed in the coordinate system of
another marker
Difference between translational velocity vectors Difference between the velocity vectors of two coordinate
(VXYZ) system markers resolved in the coordinate system of
another marker
Difference between angular velocity vectors (WXYZ) Difference between the angular velocity vectors of two
coordinate system markers resolved in the coordinate
system of another marker
Difference between angular acceleration vectors Difference between the angular acceleration vectors of two
(WDTXYZ) coordinate system markers resolved in the coordinate
system of another marker
Unit Vector (UV) The unit vector in the direction of an arbitrary vector
expression
Vector Transformation (TRANS) The transformed vector of an arbitrary vector expression
resolved between two coordinate system markers

10. 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:
 About Run-Time Functions 475
Run-Time Functions Categories

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.

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

12. 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.
476 Adams View Function Builder
Run-Time Functions Categories

User-Supplied Run-Time Functions

User-supplied run-time functions are parameterized runtime functions that are defined by the user that
contain an expression which is made up of a combination of design variables, system supplied functions,
design time expressions and constants.
User-supplied run-time functions consist of an expression whose evaluated form will be used by the solver at
the time of simulation.
You can create these functions via Adams View command language, using the "runtime_function create"
command. Alternatively, you can create them using the Function Builder in runtime mode. During creation
you must specify the text of the run-time function and optionally the parameter names. When you use these
functions, Adams substitutes the user parameters (if any) into the function text in place of the parameter
names.
For example:
runtime_function create &
runtime_function_name = runtime_func__1 &
text_of_expression = "-1.0*(DM(P1, P2)-400.0)-0.001*VR(P1, P2)" &
argument_names = "P1", "P2" &

In the example above, P1 and P2 are the formal arguments to the function runtime_func__1.
We can apply above function on sforce.
For Example:
force modify direct single_component_force &
single_component_force_name = .MODEL_1.SFORCE_1 &
function = "runtime_func__1(.MODEL_1.PART_2.MARKER_1,
.MODEL_1.PART_2.MARKER_2)"

One can also use an Adams ID instead of the full object name.
For Example:
force modify direct single_component_force &
single_component_force_name = .MODEL_1.SFORCE_1 &
function = "runtime_func__1(1,2)"

Expanded form
Adams expands the expression by replacing the arguments for the formal parameters before exporting to an
Adams Solver dataset (.adm file) or passing to Adams Solver from Adams View.
For Example:
Exporting an .adm file, the above runtime_func__1 applied to sforce_1 will be expand like so in the
.adm file:
FUNCTION = -1.0*(DM(1, 2)-400.0)-0.001*VR(1, 2)
Therefore, like other forms of design-time model parameterization, the parametrized version of the
expression can only be found in the Adams View representation of the model.
 About Run-Time Functions 477
Run-Time Functions Categories

UI
You can create user-written run-time functions using the function builder. The function builder launched
from two ways:
1. Main menu:
Tools → Function Builder → Runtime Mode
2. Ribbon based menu:

Ribbon menu → Elements Tab → Function container → Click icon

Function Builder for run-time functions

478 Adams View Function Builder
Run-Time Functions Descriptions

User-written run-time function in model browser

After creating run-time function, you can view it Model browser:
Elements → Functions

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.
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
 Functions: A - M 479
Run-Time Functions Descriptions

Functions: A - M
480 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: A - M 481
Run-Time Functions Descriptions

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 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 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.
482 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: A - M 483
Run-Time Functions Descriptions

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
dt2 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.
484 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: A - M 485
Run-Time Functions Descriptions

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
dt2 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.
486 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: A - M 487
Run-Time Functions Descriptions

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 d t2   dt2 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 RT 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 RF with respect to the Reference Frame, R.
dt 2

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.
ACCM(marker_T, marker_F, marker_R)
488 Adams View Function Builder
Run-Time Functions Descriptions

Learn more about acceleration functions.

 Functions: A - M 489
Run-Time Functions Descriptions

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.

490 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: A - M 491
Run-Time Functions Descriptions

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.
492 Adams View Function Builder
Run-Time Functions Descriptions

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 Variable (Required) Real variable that represents the first independent variable in
the spline.
Second Independent (Optional) Real variable that represents the second independent variable in
Variable 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
-2.0 -1.2
 Functions: A - M 493
Run-Time Functions Descriptions

Independent variable (x): Dependent variable (y):

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

494 Adams View Function Builder
Run-Time Functions Descriptions

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
 Functions: A - M 495
Run-Time Functions Descriptions

Learn more about displacement functions.

496 Adams View Function Builder
Run-Time Functions Descriptions

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
 Functions: A - M 497
Run-Time Functions Descriptions

Learn more about displacement functions.

498 Adams View Function Builder
Run-Time Functions Descriptions

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
 Functions: A - M 499
Run-Time Functions Descriptions

Learn more about displacement functions.

500 Adams View Function Builder
Run-Time Functions Descriptions

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) (R) d
d
WDTX = ωT – ω • x̂
dt dt F A
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
 ω is the time-derivative of ω F with respect to the Reference Frame, R.
dt F
 x̂ A is the unit vector along the x-axis of the About Marker, A.
 Functions: A - M 501
Run-Time Functions Descriptions

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.
502 Adams View Function Builder
Run-Time Functions Descriptions

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) (R) d
d
WDTY = ωT – ω • ŷ
dt dt F A
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
 ω is the time-derivative of ω F with respect to the Reference Frame, R.
dt F
 ŷ A is the unit vector along the y-axis of the About Marker, A.
 Functions: A - M 503
Run-Time Functions Descriptions

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.
504 Adams View Function Builder
Run-Time Functions Descriptions

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) (R) d
d
WDTZ = ωT – ω • ẑ
dt dt F A
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
 ω is the time-derivative of ω F with respect to the Reference Frame, R.
dt F
 ẑ A is the unit vector along the z-axis of the About Marker, A.
 Functions: A - M 505
Run-Time Functions Descriptions

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.
506 Adams View Function Builder
Run-Time Functions Descriptions

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 – ωF • ωT – ω
 dt dt   dt d t F
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

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.
 Functions: A - M 507
Run-Time Functions Descriptions

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
Run-Time Functions Descriptions

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.
 Functions: A - M 509
Run-Time Functions Descriptions

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
Run-Time Functions Descriptions

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.
 Functions: A - M 511
Run-Time Functions Descriptions

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
Run-Time Functions Descriptions

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.
 Functions: A - M 513
Run-Time Functions Descriptions

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
Run-Time Functions Descriptions

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.

 Functions: A - M 515
Run-Time Functions Descriptions

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))= π ⁄ 2 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(DY(marker_2, marker_3), DX(marker_2, marker_3))
Learn more about math functions.
516 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: A - M 517
Run-Time Functions Descriptions

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
Run-Time Functions Descriptions

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
 Functions: A - M 519
Run-Time Functions Descriptions

Learn more about displacement functions.

520 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: A - M 521
Run-Time Functions Descriptions

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
Run-Time Functions Descriptions

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:
 Functions: A - M 523
Run-Time Functions Descriptions

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
Run-Time Functions Descriptions

Learn more about displacement functions

 Functions: A - M 525
Run-Time Functions Descriptions

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
Run-Time Functions Descriptions

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.
 Functions: A - M 527
Run-Time Functions Descriptions

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.

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:
528 Adams View Function Builder
Run-Time Functions Descriptions

BEAM(.model_2.beam_1, 0, 4, 0)
Learn more about force in object functions.
 Functions: A - M 529
Run-Time Functions Descriptions

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.

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:
530 Adams View Function Builder
Run-Time Functions Descriptions

BUSH(.model_2.bushing_1, 0, 7, 0)
Learn more about force in object functions.
 Functions: A - M 531
Run-Time Functions Descriptions

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
Run-Time Functions Descriptions

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)

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.
 Functions: A - M 533
Run-Time Functions Descriptions

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.
534 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: A - M 535
Run-Time Functions Descriptions

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:
Motion = CUBSPL(TIME, 0, spline_1)
536 Adams View Function Builder
Run-Time Functions Descriptions

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.

 Functions: A - M 537
Run-Time Functions Descriptions

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
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.
538 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: A - M 539
Run-Time Functions Descriptions

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
VARIABLE/1, FU=DELAY(DIF(2), DIF(1)-3*DIF(2), 0.95)
DIF/1, FU=5*VARVAL(1)
540 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: A - M 541
Run-Time Functions Descriptions

Difference between acceleration vectors (ACCXYZ)

The ACCXYZ measure returns the difference between the acceleration vector of marker i and the acceleration
vector of marker j resolved in the coordinate system of marker k. All vector time derivatives are taken in the
reference frame of marker l.

Format
ACCXYZ(i[,j][,k][,l])

Arguments

Applied To Marker (i) The marker whose acceleration is being measured.

Applied From Marker (j) The marker with respect to which the acceleration is being measured. If j
is not specified, it defaults to the global origin. Specify j = 0 if you want to
use this default, then specify k or l.
Along Marker (k) The marker in whose coordinate system the acceleration vector is being
expressed. If not specified, k defaults to the global coordinate system.
Specify k = 0 if you want to use this default, then specify l.
Reference Frame (l) The reference frame in which the second time derivative of the
displacement vector is taken. Set l = 0 or omit the argument if you want
the time derivative to be taken in the global reference frame.

Extended Definition
Mathematically, ACCXYZ is calculated as follows:

where:
542 Adams View Function Builder
Run-Time Functions Descriptions

 R i is the displacement of marker i with respect to the global origin.

 R j is the displacement of marker j with respect to the global origin.

(l) 2
d-
 ------ denotes two time differentiations in the reference frame of the l marker.
2
dt
 ACCX is the Acceleration Along X (ACCX) measure.
 ACCY is the Acceleration Along Y (ACCY) measure.
 ACCZ is the Acceleration Along Z (ACCZ) measure.

 x̂ k is the unit vector along the x-axis of marker k.

 ŷ k is the unit vector along the y-axis of marker k.

 ẑ k is the unit vector along the z-axis of marker k.

Examples
Unlike VR, the Adams function expression language does not provide support for radial acceleration (or
separation acceleration), ACCR. The following variable shows how this quantity could be computed.
VARIABLE/1, FUNCTION = ACCXYZ(21,11) * UV(DXYZ(21,11))
 Functions: A - M 543
Run-Time Functions Descriptions

Difference between translational velocity vectors (VXYZ)

The VXYZ measure returns the difference between the velocity vector of marker i and the velocity vector of
marker j resolved in the coordinate system of marker k. All vector time derivatives are taken in the reference
frame of marker l.

Format
VXYZ(i[,j][,k][,l])

Arguments

Applied To Marker (i) The marker whose origin is being measured.

Applied From Marker (j) The marker with respect to which the velocity is being measured. If j is not
specified, it defaults to the global origin. Specify j = 0 if you want to use this
default and you need to specify k or l.
Along Marker (k) The marker in whose coordinate system the velocity vector is being expressed.
If not specified, k defaults to the global coordinate system. Specify k = 0 if you
want to use this default and you need to specify l.
Reference Frame (l) The reference frame in which the first-time derivative of the displacement
vector is taken. Set l = 0 or omit the argument if you want the time derivatives
to be taken in the global reference frame.

Extended Definition
Mathematically, VXYZ is calculated as follows:

where:

 R i is the displacement of marker i in ground.

544 Adams View Function Builder
Run-Time Functions Descriptions

 R j is the displacement of marker j in ground.

 VX is the Velocity Along X (VX) measure.
 VY is the Velocity Along Y (VY) measure.
 VZ is the Velocity Along Z (VZ) measure.

(l) d
 ----- denotes time differentiation in the reference frame of the l marker.
dt

Examples
This variable statement:
VARIABLE/1, FUNCTION = VXYZ(21,11) * UV(DXYZ(21,11))
computes the projection of the velocity vector of marker 21 from marker 11 on a unit vector along the line
of sight to marker 21 from marker 11. This quantity is also known as the radial velocity and can be written
more compactly as:
VARIABLE/1, FUNCTION = VR(21,11)
 Functions: A - M 545
Run-Time Functions Descriptions

Difference between angular velocity vectors (WXYZ)

The WXYZ measure returns the difference between the angular velocity vector of marker i and the angular
velocity vector of marker j resolved in the coordinate system of marker k.

Format
WXYZ(i[,j][,k])

Arguments

Applied To Marker (i) The marker whose velocity is being measured.

Applied From Marker (j) The marker with respect to which the angular velocity is being measured. If j
is not specified, it defaults to the global origin. Specify j = 0 if you want to use
this default, and then specify k.
About Marker (k) The marker in whose coordinate system the angular velocity vector is being
expressed. If not specified, k defaults to the global coordinate system.

Extended Definition
Mathematically, WXYZ is calculated as:

where:

 ω i is the angular velocity vector of marker i in ground.

 ω j is the angular velocity vector of marker j in ground.

 WX is the Angular Velocity About X (WX) measure.
 WY is the Angular Velocity About Y (WY) measure.
 WZ is the Angular Velocity About Z (WZ) measure.

 x̂ k is the unit vector along the x-axis of marker k.

546 Adams View Function Builder
Run-Time Functions Descriptions

 ŷ k is the unit vector along the y-axis of marker k.

 ẑ k is the unit vector along the z-axis of marker k.

Examples
A vector expression for angular velocity might be used directly in the definition of a vector torque element:
VTORQUE/3, I=310, JFLOAT=9911, RM=310,
, TXYZ = -6.*WXYZ(310,9900,310)
 Functions: A - M 547
Run-Time Functions Descriptions

Difference between angular acceleration vectors (WDTXYZ)

The WDTXYZ measure returns the difference between the angular acceleration vector of marker i and the
angular acceleration vector of marker j resolved in the coordinate system of marker k. All vector time
derivatives are taken in the reference frame of marker l.

Format
WDTXYZ(i[,j][,k][,l])

Arguments

Applied To Marker (i) The marker whose acceleration is being measured.

Applied From Marker (j) The marker with respect to which the angular acceleration is being
measured. If j is not specified, it defaults to the global origin. Specify j = 0
if you want to use this default, and then specify k or l.
Along Marker (k) The marker in whose coordinate system the angular acceleration vector is
being expressed. If not specified, k defaults to the global coordinate
system. Specify k = 0 if you want to use this default, and then specify l.
Reference Frame (l) The reference frame in which the first time derivative of the angular
velocity vector is taken. Set l = 0 or omit the argument if you want the time
derivative to be taken in the global reference frame.

Extended Definition
Mathematically, WDTXYZ is calculated as:

where:

 ω i is the angular velocity vector of marker i in ground.

 ω j is the angular velocity vector of marker j in ground.

548 Adams View Function Builder
Run-Time Functions Descriptions

(l) d-
 ---- denotes time differentiation in the reference frame of the l marker.
dt
 WDTX is the Angular Acceleration About X (WDTX) measure.
 WDTY is the Angular Acceleration About Y (WDTY) measure.
 WDTZ is the Angular Acceleration About Z (WDTZ) measure.

 xˆk is the unit vector along the x-axis of marker k.

 yˆk is the unit vector along the y-axis of marker k.

 zˆk is the unit vector along the z-axis of marker k.

Examples
A vector expression for angular acceleration might be used directly in the definition of a vector torque
element:
VTORQUE/3, I=310, JFLOAT=9911, RM=310,
, TXYZ = -6.*WDTXYZ(310,9900,310)
 Functions: A - M 549
Run-Time Functions Descriptions

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.
550 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: A - M 551
Run-Time Functions Descriptions

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.
552 Adams View Function Builder
Run-Time Functions Descriptions

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
 Functions: A - M 553
Run-Time Functions Descriptions

Learn more about displacement functions.

554 Adams View Function Builder
Run-Time Functions Descriptions

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
 Functions: A - M 555
Run-Time Functions Descriptions

Learn more about displacement functions.

556 Adams View Function Builder
Run-Time Functions Descriptions

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
 Functions: A - M 557
Run-Time Functions Descriptions

Learn more about displacement functions.

558 Adams View Function Builder
Run-Time Functions Descriptions

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
 Functions: A - M 559
Run-Time Functions Descriptions

Learn more about displacement functions.

560 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: A - M 561
Run-Time Functions Descriptions

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.
562 Adams View Function Builder
Run-Time Functions Descriptions

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.

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:
 Functions: A - M 563
Run-Time Functions Descriptions

FIELD(.model_1.field_11, 1, 5, 0)
Learn more about force in object functions.
564 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: A - M 565
Run-Time Functions Descriptions

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.
566 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: A - M 567
Run-Time Functions Descriptions

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.

568 Adams View Function Builder
Run-Time Functions Descriptions

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

 Functions: A - M 569
Run-Time Functions Descriptions

Learn more about constants and variables.

570 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: A - M 571
Run-Time Functions Descriptions

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.

572 Adams View Function Builder
Run-Time Functions Descriptions

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.
 spline id is the identifier of the spline that specifies the RPC III or DAC file input. Setting up a Spline
in Adams Durability.
 Functions: A - M 573
Run-Time Functions Descriptions

For more information on the INTERP function, see INTERP for Adams Solver (C++) or INTERP for
Adams Solver (FORTRAN).
574 Adams View Function Builder
Run-Time Functions Descriptions

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.

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)
 Functions: A - M 575
Run-Time Functions Descriptions

Learn more about force in object functions.

576 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: A - M 577
Run-Time Functions Descriptions

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.
578 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: A - M 579
Run-Time Functions Descriptions

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.
580 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: A - M 581
Run-Time Functions Descriptions

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.
582 Adams View Function Builder
Run-Time Functions Descriptions

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: MOD 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.

 Functions: A - M 583
Run-Time Functions Descriptions

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.
584 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: A - M 585
Run-Time Functions Descriptions

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.
586 Adams View Function Builder
Run-Time Functions Descriptions

Functions: N - Z
 Functions: N - Z 587
Run-Time Functions Descriptions

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
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.
588 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: N - Z 589
Run-Time Functions Descriptions

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 triggered;
Distance 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:
 q is the displacement variable
590 Adams View Function Builder
Run-Time Functions Descriptions

 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

 Functions: N - Z 591
Run-Time Functions Descriptions

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.
592 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: N - Z 593
Run-Time Functions Descriptions

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.
594 Adams View Function Builder
Run-Time Functions Descriptions

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.

 Functions: N - Z 595
Run-Time Functions Descriptions

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
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.
596 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: N - Z 597
Run-Time Functions Descriptions

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.
598 Adams View Function Builder
Run-Time Functions Descriptions

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.

 Functions: N - Z 599
Run-Time Functions Descriptions

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.
600 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: N - Z 601
Run-Time Functions Descriptions

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))
In the function:
602 Adams View Function Builder
Run-Time Functions Descriptions

 x = TIME
 x0 = 25 degrees
 ω = 1 cycle (360D)
 phi = 0
 a = PI
 b=5
Learn more about math functions.
 Functions: N - Z 603
Run-Time Functions Descriptions

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.
604 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: N - Z 605
Run-Time Functions Descriptions

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.
606 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: N - Z 607
Run-Time Functions Descriptions

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.
608 Adams View Function Builder
Run-Time Functions Descriptions

The magnitude and units calculated for the six force (Fx, Fy, Fz) and torque (Tx, Ty, Tz) components will
depend upon the expressions or subroutines you supply. These expressions are generally written in terms of
runtime functions displacements, velocities and rotation (velocity) angles by the use of functions like Distance
Along X (DX), Angle About X (AX), Velocity Along X (VX), Angular Velocity About X (WX), and so on.

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.
 Functions: N - Z 609
Run-Time Functions Descriptions

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. Note that this refers to forces defined by the Adams Solver SPRINGDAMPER
statement, not the force elements created in Adams View via the ribbon button termed “spring” and “torsion
spring”.

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.
610 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: N - Z 611
Run-Time Functions Descriptions

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.

612 Adams View Function Builder
Run-Time Functions Descriptions

STEP
Approximates the Heaviside step function with a cubic polynomial.

Notes: 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.
 Functions: N - Z 613
Run-Time Functions Descriptions

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.
614 Adams View Function Builder
Run-Time Functions Descriptions

STEP5
Provides approximations to the Heaviside step function with a quintic polynomial.

Notes: 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.
 Functions: N - Z 615
Run-Time Functions Descriptions

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
616 Adams View Function Builder
Run-Time Functions Descriptions

Learn more about resultant force functions.

 Functions: N - Z 617
Run-Time Functions Descriptions

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
618 Adams View Function Builder
Run-Time Functions Descriptions

Learn more about resultant force functions.

 Functions: N - Z 619
Run-Time Functions Descriptions

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:


 F T, 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
620 Adams View Function Builder
Run-Time Functions Descriptions

Learn more about resultant force functions.

 Functions: N - Z 621
Run-Time Functions Descriptions

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
622 Adams View Function Builder
Run-Time Functions Descriptions

Learn more about resultant force functions.

 Functions: N - Z 623
Run-Time Functions Descriptions

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:


 T T, 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
624 Adams View Function Builder
Run-Time Functions Descriptions

Learn more about resultant force functions.

 Functions: N - Z 625
Run-Time Functions Descriptions

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:


 T T, 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
626 Adams View Function Builder
Run-Time Functions Descriptions

Learn more about resultant force functions.

 Functions: N - Z 627
Run-Time Functions Descriptions

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
628 Adams View Function Builder
Run-Time Functions Descriptions

Learn more about resultant force functions.

 Functions: N - Z 629
Run-Time Functions Descriptions

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
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 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
630 Adams View Function Builder
Run-Time Functions Descriptions

Learn more about resultant force functions.

 Functions: N - Z 631
Run-Time Functions Descriptions

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)
For example:
SWEEP (x, a, x0, f0, x1, f1, dx)

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.

Note: Error message will be triggered if x 0 ≥ x1 .

Equation
Mathematically, SWEEP is calculated as follows:
632 Adams View Function Builder
Run-Time Functions Descriptions

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)
 Functions: N - Z 633
Run-Time Functions Descriptions

Learn more about math functions.

634 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: N - Z 635
Run-Time Functions Descriptions

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.
636 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: N - Z 637
Run-Time Functions Descriptions

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.
638 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: N - Z 639
Run-Time Functions Descriptions

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.
640 Adams View Function Builder
Run-Time Functions Descriptions

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.

 Functions: N - Z 641
Run-Time Functions Descriptions

Translational Displacement Vector (DXYZ)

The DXYZ measure returns the translational displacement vector from marker j to marker i as expressed in
the coordinate system of marker k.

Format
DXYZ(i[,j][,k])

Arguments

To Marker (i) The marker whose origin is being measured.

From Marker (j) The marker whose origin is the reference point for the displacement
calculation. Set j=0 if you want j to default to the global coordinate system
while still specifying k.
Reference Frame (k) The marker in whose coordinate system the displacement vector is being
expressed. If not specified, k defaults to the global coordinate system.

Extended Definition

where:

 R i is the displacement of marker i with respect to the global origin.

 R j is the displacement of marker j with respect to the global origin.

 DX is the Distance Along X (DX) measure.
 DY is the Distance Along Y (DY) measure.
 DZ is the Distance Along Z (DZ) measure.

 x̂ k is the unit vector along the x-axis of marker k.

 ŷ k is the unit vector along the y-axis of marker k.

642 Adams View Function Builder
Run-Time Functions Descriptions

 ẑ k is the unit vector along the z-axis of marker k.

Examples
The following statement:
VARIABLE/1, FUNCTION=MAG(DXYZ(21,11,32))
is equivalent to:
VARIABLE/1, FUNCTION=DM(21,11)
and because a magnitude is taken, the use of the coordinate system of marker 32 as an alternative to the
ground coordinate system is redundant (and wasteful).
 Functions: N - Z 643
Run-Time Functions Descriptions

Translational Force Vector (FXYZ)

The FXYZ measure returns the net translational force vector acting on marker i, represented in the coordinate
system of marker k. All force and constraint elements acting between markers i and j are included in the
calculation of the force. If j is not specified, FXYZ measures the sum of all force and constraint elements
acting on marker i. If k is not specified or if k=0, the force is represented in the GROUND coordinate system.
To specify k without specifying j, use j=0.

Format
FXYZ(i[,j][,k])

Arguments

Applied To Marker (i) An integer that specifies the identifier of the marker at which the
magnitude of the net force is to be calculated.
Applied From Marker (j) A second integer that specifies a marker identifier. All forces acting
between the [i,j] pair are to be included in the calculation. Set j = 0 or do
not specify if you are interested in all forces acting on marker i.
Along Marker (k) An integer that specifies the identifier of a marker (coordinate system) in
which the x-component of the force is to be returned. k defaults to the
global coordinate system when it is not specified.

Extended Definition
Mathematically, FXYZ is calculated as:

 FX 
 
FXYZ ( i, j, k ) =  FY 
 
 FZ 
where:
 FX is the Sum of Forces Along X (FX) measure.
 FY is the Sum of Forces Along Y (FY) measure.
 FZ is the Sum of Forces Along Z (FZ) measure.

Examples
Magnitude of torque at marker 5 due to all forces applied at marker 4.
VARIABLE/1, FUN=MAG(DXYZ(4,5)%FXYZ(4))
644 Adams View Function Builder
Run-Time Functions Descriptions

Translational Torque Vector (TXYZ)

The TXYZ measure returns the net translational torque vector acting on marker i, represented in the
coordinate system of marker k. All force and constraint elements acting between markers i and j are included
in the calculation of the torque. If j is not specified, TXYZ measures the sum of all force and constraint
elements acting on marker i. If k is not specified or if k=0, the torque is represented in the GROUND
coordinate system. To specify k without specifying j, use j=0.

Format
TXYZ(i[,j][,k])

Arguments

Applied To Marker (i) An integer that specifies the identifier of the marker at which the magnitude
of the net torque is to be calculated.
Applied From Marker (j) A second integer that specifies a marker identifier. All forces acting between
the [i,j] pair are to be included in the calculation. Set j = 0 or do not specify if
you are interested in all forces acting on marker i.
Along Marker (k) An integer that specifies the identifier of a marker (coordinate system) in
which the x-component of the torque is to be returned. k defaults to the global
coordinate system when it is not specified.

Extended Definition
Mathematically, TXYZ is calculated as:

 TX 
 
TXYZ ( i, j, k ) =  TY 
 
 TZ 
where:
 TX is the Sum of Torques About X (TX) measure.
 TY is the Sum of Torques About Y (TY) measure.
 TZ is the Sum of Torques About Z (TZ) measure.

Examples
The total torque on marker 5, resolved on the x-axis of marker 4.
VARIABLE/1, FUN=TXYZ(5)*UVX(4)
which is alternatively available as TX(5,0,4).
 Functions: N - Z 645
Run-Time Functions Descriptions

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 of
Displacement Value two-sided impact.
High Trigger for Higher value for independent variable at which to trigger the second side
Displacement Value 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 Distance over which to gradually turn on damping once impact is
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:
646 Adams View Function Builder
Run-Time Functions Descriptions

e ·
 K ( q 1 – q ) – Cq ⋅ STEP ( q, q 1 – d, 1, q 1, 0 ) if q < q 1 
 
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.

 Functions: N - Z 647
Run-Time Functions Descriptions

Unit vector along X (UVX)

The UVX measure returns the unit vector in the direction of the x axis of marker i, resolved in the coordinate
system of marker k.

Format
UVX(i[,k])

Arguments

Applied To Marker (i) The marker whose x-axis unit vector is being measured.
Reference Frame (k) The marker in whose coordinate system the unit vector is being expressed. If
k is not specified, k defaults to the global coordinate system.

Extended Definition
Mathematically, UVX is calculated as:

where:

 xˆi is the unit vector along the x-axis of marker i.

 xˆk is the unit vector along the x-axis of marker k.

 yˆk is the unit vector along the y-axis of marker k.

 zˆk is the unit vector along the z-axis of marker k.

Examples
VARIABLE/1, FUN=DXYZ(i,j)*UVX(k)
VARIABLE/2, FUN=DX(i,j,k)
648 Adams View Function Builder
Run-Time Functions Descriptions

Variables 1 and 2 are synonymous. They both produce the translational displacement between markers i and
j along the direction of the x-axis of marker k.
 Functions: N - Z 649
Run-Time Functions Descriptions

Unit vector along Y (UVY)

The UVY measure returns the unit vector in the direction of the y axis of marker i, resolved in the coordinate
system of marker k.

Format
UVY(i[,k])

Arguments

Applied To Marker (i) The marker whose y-axis unit vector is being measured.
Reference Frame (k) The marker in whose coordinate system the unit vector is being expressed. If
k is not specified, k defaults to the global coordinate system.

Extended Definition
Mathematically, UVY is calculated as:

where:

 ŷ i is the unit vector along the y-axis of marker i.

 x̂ i is the unit vector along the x-axis of marker k.

 ŷ k is the unit vector along the y-axis of marker k.

 ẑ k is the unit vector along the z-axis of marker k.

Examples
VARIABLE/1, FUN=DXYZ(i,j)*UVX(k)
VARIABLE/2, FUN=DX(i,j,k)
Variables 1 and 2 are synonymous. They both produce the translational displacement between markers i and
j along the direction of the x-axis of marker k.
650 Adams View Function Builder
Run-Time Functions Descriptions

Unit vector along Z (UVZ)

The UVZ measure returns the unit vector in the direction of the z axis of marker i, resolved in the coordinate
system of marker k.

Format
UVZ(i[,k])

Arguments

Applied To Marker (i) The marker whose z-axis unit vector is being measured.
Reference Frame (k) The marker in whose coordinate system the unit vector is being expressed. If
k is not specified, k defaults to the global coordinate system.

Extended Definition
Mathematically, UVZ is calculated as:

where:

 ẑ i is the unit vector along the z-axis of marker i.

 x̂ k is the unit vector along the x-axis of marker k.

 ŷ k is the unit vector along the y-axis of marker k.

 ẑ k is the unit vector along the z-axis of marker k.

Examples
VARIABLE/1, FUN=DXYZ(i,j)*UVZ(k)
VARIABLE/2, FUN=DZ(i,j,k)
Variables 1 and 2 are synonymous. They both produce the translational displacement between markers i and
j along the direction of the z-axis of marker k.
 Functions: N - Z 651
Run-Time Functions Descriptions

Unit Vector (UV)

The UV function returns the unit vector in the direction of an arbitrary vector function expression.

Format
UV(exp)

Arguments

Vector Expression (exp) An arbitrary vector function expression.

Extended Definition
Mathematically, UV is calculated as:

where is an arbitrary vector function expression.

Note that Adams Solver (C++) attempts to handle the singular case when the vector function expression is
the zero vector. For instance, the expression UV(DXYZ(i,j)) is problematic if markers i and j become
coincident. In this case, Adams Solver (C++) will reuse the last valid direction of the unit vector. It is
recommended that you avoid computing the unit vector in the direction of expressions that start with a zero
value or are persistently zero (such as velocity measurements during a static equilibrium analysis).

Examples
VARIABLE/1, FUN=VXYZ(i,j)*UV(DXYZ(i,j))
VARIABLE/2, FUN=VR(i,j)
Variables 1 and 2 are synonymous. They both compute the separation velocity of markers i and j: the
projection of the relative velocity vector on a unit vector in the direction of the position vector between the
markers.
652 Adams View Function Builder
Run-Time Functions Descriptions

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.
 Functions: N - Z 653
Run-Time Functions Descriptions

Vector Transformation (TRANS)

The TRANS function transforms an arbitrary vector function expression represented in the coordinate
system of marker j to the coordinate system of marker i.

Format
TRANS(exp,i[,j])

Arguments

Vector Expression (exp) An arbitrary vector function expression.

From Marker (i) The marker whose coordinate system the expression, exp, is to be represented.
Reference Frame (j) The marker in whose coordinate system the expression, exp, is specified. If not
specified, the expression, exp, is assumed to be specified in the global
coordinate system.

Examples
VFORCE/1, I=1, JFLOAT=2, RM=3, FXYZ=VXYZ(i,j,k)
VFORCE/2, I=1, JFLOAT=2, RM=3, FXYZ=TRANS(VXYZ(i,j),k)
VFORCE/3, I=1, JFLOAT=2, RM=3, FXYZ=TRANS(VXYZ(i,j,l),k,l)
Variables 1, 2 and 3 are synonymous. They all specify a vector force law that is equal to the velocity vector of
marker i with respect to marker j, represented in the coordinate system of marker k.
654 Adams View Function Builder
Run-Time Functions Descriptions

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.

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.
 Functions: N - Z 655
Run-Time Functions Descriptions

VR(marker_T, marker_F, marker_R)

Learn more about velocity functions.
656 Adams View Function Builder
Run-Time Functions Descriptions

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.

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.
 Functions: N - Z 657
Run-Time Functions Descriptions

VX(marker_T, marker_F, marker_A, marker_R)

Learn more about velocity functions.
658 Adams View Function Builder
Run-Time Functions Descriptions

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.

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.
 Functions: N - Z 659
Run-Time Functions Descriptions

VY(marker_T, marker_F, marker_A, marker_R)

Learn more about velocity functions.
660 Adams View Function Builder
Run-Time Functions Descriptions

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.

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.
 Functions: N - Z 661
Run-Time Functions Descriptions

VZ(marker_T, marker_F, marker_A, marker_R)

Learn more about velocity functions.
662 Adams View Function Builder
Run-Time Functions Descriptions

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.
 645
Adams Solver (C++)

Product-Specific Functions
When using a template-based or plugin product with Adams View, the Function Builder includes some
product-specific functions.

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

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
646 Adams View Function Builder
Template-Based Products

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

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
 649
Expression Example

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

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.

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.
650 Adams View Function Builder
Example - Building Functions for Motions

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.
7. The Simple Harmonic Function dialog box appears. Fill in the dialog box as shown next:
 651
Example - Parameterizing Values for Marker Locations

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.

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.
652 Adams View Function Builder
Example - Parameterizing Values for Marker Locations

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.