using adams/view function bld. - md adams 2010

1Using the Adams/View Function Builder

Using the Adams/View Function BuilderThe Adams/View Function Builder is a versatile tool inside of Adams/View, part of the MD Adams

2010® suite of software, that lets you write expressions, functions, and subroutines to define forces, measures, and motion in Adams products. You can create and modify functions and parameterize values for various entities.

This section provides references and procedures for writing expressions, functions, and subroutines using the Function Builder in Adams/View.

Adams/View Function BuilderLearning Function Builder Basics

2

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

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.

Category:

Math Functions

Location/Orientation Functions

Modeling Functions

Matrix/Array Functions

String Functions

Database Functions

Miscellaneous Functions

3Using the Adams/View Function BuilderLearning Function Builder Basics

Run-Time Functions

Run-time functions allow you to specify mathematical relationships between simulation states that directly define the behavior of your model. Adams updates the run-time functions only during a simulation.

The Function Builder gives you access to over one hundred run-time functions, that it categorizes based on their functionality. The following table lists the run-time functions categories:

Run-Time Function Categories

Besides the categories listed above, the Function Builder includes a category named All Functions. This category contains all the run-time functions, grouped by functionality.

For more information and examples for each run-time function, see Run-Time Function Descriptions.

Function Builder ModesThe 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

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

For this operation: Use this mode:

Building Expressions Expression

Creating or Modifying Computed Measures Expression


4

The following two sections introduce you to the Function Builder modes:

• Expression Mode

• Run-Time Mode

Expression Mode

In expression mode you can create expressions, which are the basis of all parameterization. Adams updates expressions when it detects that dependencies have been changed. Performing optimization and design studies can affect the dependencies for some expressions.

In addition to design-time functions, expressions can include the following elements:

• Design variables

• Operators

• Operands

• Database Access

For detailed information on expressions and their elements, see Expression Language Reference.

To learn more about the expression mode, see Working in Expression Mode.

Run-Time Mode

When working in run-time mode, the Function Builder allows you to combine run-time functions with a variety of elements to build functions. After you define the functions, Adams/Solver uses them during the simulation process.

The following sections introduce you to the run-time function elements.

• Design Variables

• Numerical Values

• Operators

Design Variables

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

Building Design-Time Functions Expression

Building Run-Time Functions Run-time

Creating or Modifying Function Measures Run-time

For this operation: Use this mode:


variable create variable=my_radius real=40 units=lengthgeometry modify shape cylinder &cylinder_name = .model_1.PART_1.CYLINDER_1 &radius = (my_radius)

For more information on design variables, see Expression Language Reference.

Numerical Values

In run-time mode you can use integers and real numbers. Adams doesn't support complex numbers at this time.

Operators

You can use the standard set of FORTRAN operators in the functions you create in run-time mode. The operators table below lists the operators Adams/View supports in this mode. The table lists the operators by precedence, with grouping being the highest precedence operator.

• Different from FORTRAN convention, when in run-time mode, the unary minus operator has precedence over the exponentiation operator, and exponentiation associates from left to right.

Operators

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

Accessing the Function BuilderYou 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:

This operator: Has this role:

( ) Grouping

- Unary minus = negation

** Exponentiation

/ Division

* Multiplication

+ Addition

- Subtraction


6

Accessing the Expression Mode for Basic Operations

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

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

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

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


locations, parameterizing values for geometry dimensions, and working with design variables. For more information on expressions, see Expression Language Reference.

To perform such operations, you can access the expression mode from the pop-up menus of boxes that can be parameterized.

To access the expression mode from a box:

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

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

2. Build your expression, and then select OK.

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

Creating or Modifying Computed Measures

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

To access the expression mode from the Build menu:


8

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

The Function Builder appears as shown next

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

Building Design-Time Functions

You can also use the expression mode when you want to build custom functions. To build functions, you can access the expression mode from the Build menu.

To access the expression mode from the Build menu:


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

The Function Builder appears as shown next.

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

Working in Run-Time ModeYou can access the run-time mode of the Function Builder in several ways, depending on the operation you want to perform. The Function Builder might look slightly different depending on the operation for which you intend to use it. For example, if you open the Function Builder to build function measures, it includes boxes for entering general attributes for the measure.

For information on run-time functions, functions you can use in run-time mode, see Run-Time Functions.

In run-time mode, you can perform two basic types of operations. In addition, you can set how Adams/View references database objects.

• Setting Default Database Object References

• Building Run-Time Functions

• Creating or Modifying Function Measures


10

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.


To access the run-time mode from a box:

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


2. Create a function, and then select OK.

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

Creating or Modifying Function Measures

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


12

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

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


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

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

Performing Operations in the Function BuilderThe Adams/View Function Builder lets you perform many operations to help you build functions and create and modify measures. The Function Builder Operations table below provides a quick overview of the Function Builder operations and the modes in which they are supported.

For an overview of the Function Builder, see Learning Function Builder Basics. For information on the Function Builder modes, see Accessing the Function Builder.

Function Builder Operations

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

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

Adams/View Function BuilderPerforming Operations in the Function Builder

14

• Verifying Function Syntax

• Setting Measure Attributes

• Creating a Measure Strip Chart

• Getting Assistance

• Inserting Operators in Function Definitions

• Displaying System-Supplied Function Categories

Getting Object Names and Data Dictionary

The following two sections explain how you can get an object's name and data dictionary:

• Getting Object Data

• Getting Data Owned by an Object

Getting Object Data

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

To get object data:

1. From the option menu located under the Getting Object Data label, select the desired object type.

2. Right-click the text box to the right of the object type you chose in Step 1, point to the object type name, and then select Browse to look for an object name.

To insert an object name into the function definition:

After you've specified the object name, you can insert it into the function definition.


• 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

To access the data dictionary:

1. Select Get Data Owned by Object.

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

Data Dictionary for Markers

2. Select an item from the data dictionary.

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

Evaluating Functions

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

To evaluate a function:

1. Make sure there is a function in the function text area.


2. Select Evaluate.

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

Plotting Using the Function Builder

Using the Function Builder, you can plot the values of some functions. The following two sections explain how to plot functions using the Function Builder.

Plotting Functions

Adams/View gives you the option to preview a plot of your function. You can use the plotting feature whenever your function evaluates to multiple values.

When in run-time mode, time is presumed to be the independent variable when plotting a function (for example, SIN(TIME)).

To plot a function:

1. Make sure you have a correct function in the function work area.

2. Select Plot.

Adams/View displays a plot of your results.

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.

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


18

2. Select Plot Limits.

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

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

Verifying Function Syntax

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

To verify function syntax:

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

2. Select Verify.

Setting Measure Attributes

When creating or modifying a computed or a function measure, you can set measure attributes to be used when plotting the measure for these three attributes categories:

• General - Specify the units and the legend text.

• Axis - Specify the text for the axis label, the axis type, as well as the lower and upper limit for the axis.

• Curve - Specify the curve color, thickness, line type, and symbol.


To set measure attributes:

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

Creating a Measure Strip Chart

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

To create a measure strip chart:

1. Create or modify the measure.

2. Select Create Strip Chart.

3. Select OK.

Adams/View displays a strip chart of your measure.

For more information on using strip charts, see Setting Up Strip Charts in Adams/View online help.

Getting Assistance

You can get assistance when working with system-supplied functions in either run-time or expression mode. The Assist dialog box lists all the arguments specific to the function for which you need assistance, and prompts you for argument values. Once you enter the argument values and close the Assist dialog box, Adams/View automatically inserts those values into the function work area.

When entering values in the Assist dialog box, do not enclose them in parenthesis, braces, or quotation marks. Adams/View automatically enters these as needed, before displaying expressions in the function work area.


20

To get assistance:

1. Select a function from the list of system-supplied functions.

2. Select Assist.

The Assist dialog box appears.

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

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.

Category:

Math Functions


Modeling Functions



Table 2. Run-Time Functions Categories

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.

String Functions

Database Functions


Category:


Velocity Functions


Contact Functions

Spline Functions



Math Functions

Data Element Access



Category:


22

2. Select the desired function from the list.

The function name and arguments appear under the function list.

23Using the Adams/View Function BuilderExpression Language Reference

Expression Language ReferenceThis 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/ViewYou use expressions in Adams/View in the expression mode of the Function Builder. Expressions are combinations of constants, operators, functions, and database object references, all enclosed in parentheses. In Adams/View you can use expressions to specify parameter values, such as locations of markers or functions of motions.

Adams/View uses expressions for two purposes:

• To compute values for you, such as when you are entering the radius of a cylinder and the value is not a simple number, but is the result of a mathematical computation. Instead of using a calculator to determine the actual number, you can enter the expression directly and let Adams/View perform the computation for you.

• To parameterize your model. Expressions can contain references to other data values in Adams/View. These expressions do not remain constant; Adams updates them each time the referenced data changes. Using expressions in this way allows you to make changes to one value and have this change propagate throughout your entire model. This is called parameterizing your model. If you are familiar with spreadsheets, this is identical to defining a cell as a function of another cell.

You construct Adams/View expressions during model building. When Adams/View reads an expression, it either evaluates it and stores the value in its database, or stores the expression itself.

Adams/View includes variable objects intended for use with expressions. When creating an Adams/View variable, you give it a name and a value. You can then include this variable, by name, in expressions; if you change the value of the variable, then Adams/View updates the expression. In fact, any design variable or other object that changes will cause any expression that used it to re-evaluate. This allows you to parameterize your model using design variables. You can use such a parameterized model to do design studies, design of experiments, and optimizations.

Learn more (Expression Example).

Adams/View Function BuilderExpression Language Reference

24

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

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:

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


Constant Value Examples

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

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

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

This constant: Has this value:

TRUE or YES or ON 1

FALSE or NO or OFF 0

PI = 3.1415

HALF_PI

THREE_HALVES_PI

TWO_PI

SIN45

SQRT2

RTOD

DTOR

VERSION [Adams Release Version #]

NONE see explanation below

2 1.5707=3 2 4.7122=

2 6.283= 4 sin 0.0137=

2 1.414=180 57.2974= 180 0.0174=


26

concatenates them into one: NONE // 2 forces the number 2 to become a character string, and NONE + "10" forces the string "10" to become the number 10.

The real power of the NONE constant is evident when it is used by itself in an expression, as shown by the following example.

Certain physical parameters of a model make a distinction between the value zero and a non-existent value. This is especially true during the solution of initial conditions of a model. Assume that you have an example model consisting of two parts joined together with a fixed joint. An initial conditions solution computes the initial velocities of these parts. If you assign one of the parts an explicit velocity, then Adams/Solver sees that the two parts are constrained and sets the initial velocity of the other. This can only work if the second part has no velocity; if its velocity is undefined.

This command says that this part is not moving in the x direction, so its velocity is zero:

part modify rigid_body initial_velocity part=part_2 vx=0.0

The following command says that the velocity of this part is undefined, so you must examine other parts of the model to determine its initial velocity:

part modify rigid_body initial_velocity part=part_2 vx=(NONE)

In general, setting a parameter to NONE sets that parameter's value to non-existent.

Functions

A function is an operand that takes an argument list and computes a value based on the values contained in the list. Each argument is an expression that is evaluated and then given to the function. Common examples are SIN( ), SQRT( ), and ABS( ).

Adams/View offers a wide variety of system-supplied design-time functions. For a complete list of design-time functions and how to use them, see Design-Time Functions.

The EVAL function is a special purpose design-time function that allows removal of subexpressions and dependencies from an expression. EVAL computes the value of its argument, without type coercion, and replaces itself with this value. This means that when you recall an expression from the database it never contains an EVAL function.

For example, if you create a variable whose value contains EVAL:

variable create variable=test real=(EVAL (2+2) / EVAL (2*3))

the database value for this variable is (4/6) and this is exactly the same as typing:

variable create variable=test real=(4/6)

There are two reasons to use the EVAL function:

• To eliminate costly recomputation of constant subexpressions. For example:

(EVAL(SQRT(2.2) + SIN(.55) + ATAN2(3,2)) + x) is replaced by: (57.8027713349 + x)


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=10marker create marker=(UNIQUE_NAME("marker")) &location=(EVAL(xxx)), 0, 0

end

If you don't use EVAL when defining the location of these markers, Adams parameterizes them to the variable xxx and moves them at each iteration of the loop. This would result in all of the markers being piled up at 10,0,0 after the loop terminated.

Database Objects and Their Component Values

Through expressions you can access most values stored in the Adams/View database, regardless of whether you entered them through the command language or read them from a file. Adams/View lets you access character strings, real numbers, integers, database objects, arrays, and boolean values.

To identify the database values you want to reference, use extensions of their Adams/View hierarchical names by entering an entity's name and appending to it the name of the desired data field. The data an object owns is listed in the data dictionary. For more information on the data dictionary, see Getting Data Owned by an Object.

Accessing the Database

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

• Syntax

• Syntax Examples

• Cautions

• Aliases

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

• Volume of one object to determine the mass of another.

• Locations of two coordinate systems to compute the orientation of a joint.

• Name of an object to derive new names for its children. For example, the name of a marker might be based upon the name of its parent part.


28

To identify the database values you want to reference, use extensions of their Adams/View hierarchical names. This means you enter an entity's name and append the name of the desired data field to it. For example, to access the mass of the part named .model_1.part_1 you would enter,

.model_1.part_1.mass

Based on this, Adams/View returns the real number value of the mass. We chose the name mass based on the full parameter name we used to set its value in the Adams/View command language. That is:

part create rigid_body mass_properties part_name=.model_1.part_1 mass=1.0

When accessing the value of a design variable, you don't need the data field. For example, in the following commands, the expressions in the second and third command return the same value:

variable create variable_name=DV_1 real_value=100 variable create variable_name=DV_2 real_value=(DV_1.real_value)variable create variable_name=DV_3 real_value=(DV_1)

Syntax

There is no specific command associated with database access. Adams/View allows database access in any command parameter where it allows an expression. See Learning Function Builder Basics, for more information on using expressions in Adams/View.

In the references given below, the dot (.) is used to separate components in the hierarchical name (just as it does in the current Adams/View command language). You must enclose this name in parenthesis, to tell Adams/View to recognize it as an expression. Note that enclosing a run-time function in parenthesis will not make it become an expression.

References can be either rooted or local. Rooted references have the following characteristics:

• Begin with a dot.

• Contain each specific component in the naming hierarchy (see the Rooted References table below).

• Parse faster than local references because they can be found by looking at the highest level of the database.

Rooted References

Database access: Type: Value retrieved:

.some_model.some_part.mass Real Mass of a part

.model_1.title String Title of model from .ADM file

.model_1.circle_1.sides Integer Number of sides of the circle

.model_1.part_1.location Array Three-element location array

.model_1.joint_1.i_marker Object The i_marker used in joint_1


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

Syntax Examples

The following examples show the proper syntax for a variety of operations.

Setting a value:

part modify rigid_body mass_properties part=part_1 & mass=100!

Computing a mass:

part create rigid_body mass_properties part=part_2 & mass=(part_1.mass / 2.0)!

Computing a mass from a volume:

geometry create shape frustum frustum_name=fru_1 & top_radius=5 &

bottom_radius=10 &length= 20part create rigid_body mass_properties part=part_2

& mass=((fru_1.length * (fru_1.top_radius +

fru_1.bottom_radius) / 2)**2 *PI)

Cautions

If you create a marker named "location" on part_1, then the following ambiguity can arise:

(part_1.location) meaning the marker named "location"

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_ marker_name.location[2]

Real The second location of the i marker of the joint that is at the indxth position in the coupler named coup


30

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

Indexed array: Alias:

alias location[1] loc_x

alias location[2] loc_y

alias location[3] loc_z


tire.inertia_moments

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.

Operators

Indexed array: Alias:

alias inertia_moments[1] ixx

alias inertia_moments[2] iyy

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

Operator: It means:

( ) Grouping

[ ] Indexing. Any matrix or multi-valued database object can be indexed.

** Exponentiation

- Unary minus = negation


32

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:

* / Multiplication/division

@ Matrix multiplication

+ - Addition/subtraction

<<===>>=!=

Relational. These operators allow you to compare objects of the same type.

less thanless than or equal toequal togreater thangreater than or equal tonot 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).

Operator: It means:


Coercion Examples

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_1part create rigid_body name_and_position part_name=PIpart create rigid_body name_and_position part_name=part_1marker 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 UpdatingAdams/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

Expression: Result: Description:

2 + "2" 4 The character string is coerced to integer before arithmetic is performed.

2 + 2 // 3 "43"

(2+2=4; 4//3=43)

Addition has higher precedence than concatenation; numbers are coerced to strings before concatenation.

marker_1 + 1 Error Cannot convert database object to integer.


34

value (either directly or indirectly), evaluation could continue endlessly. To avoid problems, Adams/View only resolves such expressions one level deep.

For example, take the following expressions:

variable create variable_name=I integer_value=1variable 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 OrientationAdams/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 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,1part create rigid_body name_and_location create part=part_2 location=2,2,2marker 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_3location=(LOC_RELATIVE_TO({0,0,0}, part_1)) &orientation=90d,0,0relative_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_1location=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_1location=0,1,2 relative_to=.mod_1.part_1

This works for any reference frame (marker or part) that you might want. All you need to do is just create an object (markers are convenient) at the correct location and with the correct orientation, then specify new locations and orientations relative_to that object.

When defining the locations or orientation of objects using expressions, you cannot use a relative_to reference frame. With the above commands, Adams/View transforms the information you supply for location and relative_to into a location relative to the part that owns the marker, and discards the values


36

you entered. This loss of information is usually of no consequence, as you can easily reconstruct it (that is, you can set relative_to to anything you want and see the location or orientation expressed in that reference frame).

In both of the above cases, the value stored in the database for marker1's location is (0,1,2), and the value you supplied in the relative_to parameter is discarded. (Not only is the location stored relative to the part, it is also stored in Cartesian coordinates, so if you are using cylindrical or spherical coordinates on data entry, that information is also discarded.) Expressions are not this easily manipulated. The original information that you enter for a location expression must be maintained in the Adams/View database to evaluate that expression.

This means that there are restrictions when you want to use expressions:

• You must set defaults units coordinate_system_type=cartesian.

• You must set defaults units orientation_type=body313.

• Any use of the relative_to parameter must be equivalent to system ground, as in relative_to=.mod_1.

Here is an example of a common mistake made with relative_to locations. In the example, marker_3 on part_3 must maintain its position in space but with respect to marker-2, which is on another part. It must be located at a position 5.0 units along the axis of marker_2 using LOC_ON_AXIS to compute the location of marker_3. See the diagram below.


marker create marker=.mod1.part_3.marker_3 & location=(LOC_ON_AXIS(marker_2, 5, "X"))

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.

ArraysIn the Adams/View expression language, an array is a collection of values of the same scalar type.

Array Examples

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

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

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


38

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

3. Mixed integer and real numbers are all converted to real numbers:

{1, 2.5, 3} becomes {1.0, 2.5, 3.0}

The next sections explain the different types of arrays.

• Empty Arrays

• Concantenating Arrays

• Matrices of Real Numbers

Empty Arrays

Adams/View allows arrays to be empty. This is denoted by a pair of braces {}.

variable create variable=list real=({})

Note that this is distinctly different than the use of NONE; the value of the variable named list is an array that contains no values.

The following command creates a variable, named nothing, that contains an undefined value:

variable create variable=nothing real=(NONE)

The next section shows how such variables are different in a practical sense.

Concatenating Arrays

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

variable create variable=list real=({})for variable=value start=10 end=20

variable modify variable=list real=(EVAL(list // {value}))end

The values resulting from the above example are: {10,11,12,13, ..... 20}.

If you create the initial value for list using NONE, as in the following example, you end up with a 12-element array containing an undefined value as the first element, followed by the values 10 through 20.

variable create variable=list real=(NONE)

The values resulting from the above example are: {0,10,11,12,13,..... 20}. In this case, the undefined value is 0.

Matrices of Real Numbers

Adams/View stores multi-valued parameter values as real-valued two dimensional matrices.

The following sections provide more information regarding matrices of real numbers:


• 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

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.

These parameter values:

Are stored as:

General math matrix syntax:

Location and orientation

Polyline location lists Mx3 matrices

Adams/Solver dense-matrix data elements

MxN matrices

All other real-valued matrices (such as spline x values or curve y-axis data)

1xN matrices

1

2

3

1 2 3

4 5 6

7 8 9

1 2 3 4

1 2


40

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

Entering Matrices in Expressions

When entering parameter values that are not expressions, simply enter the numbers one after another. For example, consider the polyline defined below by three points:

geometry create curve polyline polyline_name=polyline_1 &location=({{1,2,3}, {4,5,6}, {7,8,9}})

or

geometry create curve polyline polyline_name=polyline_1 &location=({[1,2,3], [4,5,6], [7,8,9]})

To enter a matrix in an expression, enclose the matrix in braces ({ }). Enter a multi-dimensional matrix in braces ({ }) or brackets ([ ]), depending on whether you want to enter column-major or row-major format, respectively. Each element inside a set of brackets denotes a row in the matrix. Each element inside a set of braces denotes a column in the matrix.

Note: @ is the matrix multiplication operator.


Creating Matrix Expressions of Various Dimensions

Indexing

Indexing allows you to reference elements within a matrix, as shown in the table below:

Adams matrix syntax: General math matrix

syntax: Matrix

dimension:

3 x 1

3 x 2

{[11,12,13], [21,22,23], [31,32,33]} =

{{11,21,31}, {12,22,32}, {13,23,33}}

3 x 3

{[1,2,3]} = {{1}, {2}, {3}} [1 2 3] 1 x 3

1

2

3

1 2

3 4

5 6

11 12 13

21 22 23

31 32 33


42

Indexing in Adams

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

Using Ranges of Indexes

You can also extract a complete row of a matrix as shown in the table below:

Adams index syntax:

Mathematical description: Math result: Adams result:

Element in 2nd row, 1st column of the 3 x 1 matrix

8

{[5,4,3]}[1,2] Element in 1st row, 2nd column of the 1 x 3 matrix

4

{[8,9], [5,6]}[2,1] Element in 2nd row, 1st column of 2 x 2 matrix

5

{1,2,3}[2] (see Note below)

Element in 2nd row, of the 3 x 1 matrix

2

9

8

7

5 4 3

8 9

5 6

1

2

3

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

Adams index syntax:


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

2nd to 3rd rows of the 1st to 2nd column

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

4 5 6

7 8 9


Extracting a Complete Row

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

Adams index syntax:


{9,8,7}[2] Element in 2nd row in 3 x 1 matrix

8

{9,8,7}[2,1:1] Element in 2nd row, 1st column of 3 x 1 matrix

8

{9,8,7}[2,*] Element in 2nd row, all columns of 3 x 1 matrix

8

{[8,9], [5,6]} [1,1:2] Element in 1st row, 1st to 2nd column of 2 x 2 matrix

{[8,9]}

{[8,9], [5,6]}[1,*] Element in 1st row, all columns of a 2 x 2 matrix

{[8,9]}

9

8

7

9

8

7

9

8

7

8 9

5 6

8 9

5 6

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


44

Extracting a Complete Column

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

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

Adams Index Syntax:

Mathematical Description: Math Result: Adams Result:

{[8,9], [5,6]}[1:2,1] Element in rows 1 to 2, 1st column of a 2 x 2 matrix

{8,5}

{[8, 9], [5, 6]} [*,1] Elements in all rows, 1st column of a 2 x 2 matrix

{8,5}

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

Elements in all rows, 1st column in a 3 x 3 matrix

{1,4,7}

8 9

5 6

8 9

5 6

1 2 3

4 5 6

7 8 9

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

Expression: Result:

marker_1.location {8,7,6}

marker_1.location [2] 7


3xN Matrix

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

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


46

1xN Matrix

Operators On Matrices

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

Operators on Matrices

Expression: Result:

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.

Expression: Result: Comments:

2 ** {0,1,2}{0,1,2,} ** 2{1,2,3} ** {4,5,6}

(20,21,22) = {1,2,4}(02,12,22) = {0,1,4,}(14,25,36) = {1,32, 729}

Exponentiation

-{0,1,2} {0,-1,-2} Negation

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

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

2 * {0,1,2}{0,1,2,} * 2{1,2,3} * {5,6,7}{[3,2]} * {[2,4]}

{0,2,4}{0,2,4}{5,12,21}{[6,8]}

Scalar multiplicationScalar multiplicationPairwise multiplicationPairwise multiplication

2 / {1,2,3}{0,1,2} / 2{1,2,3} / {5,6,7}

{2,1,0.667}{0,0.5,1}{0.2,0.333,0.429}

Division

2 + {0,1,2}{0,1,2} + 2{1,2,3} + {5,6,7}

{2,3,4}{2,3,4}{6,8,10}

Addition

1 23

41 3 2 4+ 11= =

1

23 4

3 4

6 83 4 6 8 = =


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

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

2 - {0,1,2}{0,1,2} - 2{1,2,3} - {5,6,7}

{2,1,0}{-2,-1,0}{-4,-4,-4}

Subtraction

2 == {0,1,2}{0,0,0} == 0{1,2,3 }== {1,2,3}

{0,0,1}{1,1,1}{1,1,1}

Equality

2 != {0,1,2}{0,0,0} != 0{1,2,3} != {1,2,3}

{1,1,0}{0,0,0}{0,0,0}

Inequality

2 <= {2,4,6}{2,4,6 } <= {3,4,5}

{1,1,1}{1,1,0}

Less than or equal (All other relational operators act similarly.)

!{0,1,2} {1,0,0} Logical NOT

2 && {0,1,2}{0,1,2} && 2{1,2,3} && {5,6,7}

{0,1,1}{0,1,1}{1,1,1}

Logical AND

2 || {0,1,2}{0,1,2 }|| 2{1,2,3} || {5,6,7}

{1,1,1}{1,1,1}{1,1,1}

Logical OR

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}

Expression: Result: Comments:


48

UnitsAdams/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 = 20part_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:


50

Simple Unit Labels and Their Minimal Abbreviations

Base units: Simple unit labels: Minimal abbreviations:

Length angstromcentimetercmfootinchkilometerkmmmetermicroinchmicrometermilemilsmillimetermmnanometeryard

angscentimetercfikilometerkmmmetmicroimicrommilemilsmillimetermmnanomy

Angle amangular_minutesangular_secondsasdegreeradianrevolutions

amangular_mangular_sasdrre

Mass gramkgkilogramkpound_masslbmmegagrammicrogrammilligramnanogramounce_masspound_massslinchslugtonneus_ton

gkgkilogramkpound_mlbmmegmicrogmillignanogounce_mpound_mslisltus_


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

Exceptions to Aliases

Time dayhourmicrosecondmillisecondminutemsnanosecondsecond

dahomicrosmillisminmsnanoss

Force centinewtondynekg_forcekilogram_forceknewtonkpound_forcelbfmeganewtonmicronewtonmillinewtonnanonewtonnewtonounce_forcepoundalpound_force

cedykg_kilogram_forceknkpound_flbfmeganmicronmillinnanonneounce_fpoundapound_f

Frequency hzradians/second

hzradians/sec

Base units: Simple unit labels: Minimal abbreviations:

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

Aliases: Unit labels:

d Degrees, although it conflicts with dynes

kg Kilograms, although it conflicts with kg_force

m Meters, although it conflicts with mile, minute, ms, millisecond, and millinewton

N Newtons, although it conflicts with nanonewton

r Radians although it conflicts with revolutions


52

The next table shows some examples of simple unit labels associated with a number within expressions:

Simple Unit Labels Associated with Numbers

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

The following table lists examples of composed unit labels:

Composed Unit Labels

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

Operator: Notation: Comment:

exponentiation ** Right operand must be an integer: inch**2

multiplication - or * Foot-pound_f = foot*pound_f

division /

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.

53Using the Adams/View Function BuilderAdams/View Function Builder Glossary

Adams/View Function Builder Glossary

A - B


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.

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

Adams/View Function BuilderAdams/View Function Builder Glossary

54

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.


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.



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.


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

Function

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

Function Builder

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

Function Category

Collection of functions grouped according to their type. For example, the function categories include: math functions, string functions, and database functions.


56

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.


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.


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


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

Run-Time Functions

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

Run-Time Mode

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

S - T

Single-Component Force

A force defined as one resultant magnitude along a direction.

Spline Functions

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

String Functions

Design-time functions that allow you to manipulate character strings.


58

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.

59Design-Time Functions


Adams/View Function BuilderAbout Design-Time Functions

60

About Design-Time FunctionsDesign-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 FunctionsUser-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))

61Design-Time FunctionsAbout Design-Time Functions

Compiled Functions

You can also write compiled functions in C or FORTRAN, link them into Adams/View, and even use them in an Adams/View expression. You can use these functions in the same way you would use the built-in functions.

Register the user-written functions by calling a subroutine built in to Adams/View. You must place this subroutine call in the registration subroutine supplied in source-code form with Adams/View.

To create your own compiled function:

1. Locate and copy the appropriate source code templates from $topdir/aview/user_subs. If you are programming in C, copy vc_init_usr.c. If you are programming in FORTRAN, copy vf_init_usr.f.

2. Write and debug your function by modifying the template. You can debug by compiling your function in debug mode, linking the executable in debug mode and using your native debugger.

3. Add your new function to the registration subroutine.

4. Link your new function and the modified registration subroutine with Adams/View. Depending on the platform you're on, look for instructions in the Running and Configuring Adams help.

5. Use your new function in an expression.

You can use the programming language's normal parameter passing method to access parameters. Adams allows you to use this mechanism only for a fixed set of parameter lists and return values. You can find the set of allowable parameter lists in the files $topdir/aview/user_subs/mdi_c.h and $topdir/aview/user_subs/mdi_f.f.

Registering functions allows you to add functions with arbitrary names. User-written functions have precedence over system-supplied functions. If you register a function with the name SQRT, then your new function is called whenever you use this name in an expression. You can't register a function that has the same name as an existing literal constant. For example, Adams/View rejects names such as PI and RTOD, and returns an error message.

If you have a function that duplicates a constant name, change the text name as shown next:

vc_function_add("RTOD", (FUNCTION)rtod, fn_R_RR, 2, 0); /* Won't work */

to

vc_function_add("MYRTOD", (FUNCTION)rtod, fn_R_RR, 2, 0); /* Will work */

When you register a function you must also specify the number and type of parameters, to give the expression parser the information it needs to make sure the input and output data for the function are correct.

Examples Involving Compiled Functions

The following examples show how you can write your own compiled functions and how you can access arrays within compiled functions:

../adams_configure/master.htm


62

• Writing Your Own Compiled Functions

• Accessing Arrays Within Compiled Functions

Writing Your Own Compiled Functions

This example adds a function that computes the remainder between two reals. When the function is registered in Adams/View, its type, and the number and types of its parameters are defined, so the parser can validate the input and output data.

Your code might look like this:

#include "mdi_c.h" /* This file is in $topdir/aview/user_subs */#include <math.h>typedef double REAL;REAL remainder (REAL number, REAL denom){int i;return(number - (i * denom) );}#inlcude "mdi_vc.h"void vc_initialize_user ()}REAL remainder ();vc_function_add("REMAINDER",(FUNCTION) remainder, fn_fn_R_RR, 2, 0) ;}

You must register the function in Adams/View. Do this by modifying a function that is supplied in source code form (in the file $topdir/aview/user_subs/vc_init_usr.c), compiling and linking it with Adams/View, as shown next:

#include "mdi_vc.h"void vc_initialize_user ( ){REAL dist2 ( ) ;vc_function_add("DIST2", (FUNCTION)dist2, fn_R_RR, 2, 0);}

To use this function in an expression in Adams/View, type:

variable set variable=myvar real=(EVAL(REMAINDER(101.0/17.0)))

If you perform an error check within your user-written function, you can cause the function to abort and report an error message by using the following routine:

void vc_error(char *Msg, ...);

The Msg parameter is a C format, and the optional parameters are the same as with a printf. Note that this function does not return to the calling routine.

Accessing Arrays Within Compiled Functions

In the Adams/View expression language, an array is a collection of values of the same scalar type. For more information on arrays, see Arrays.


The following C prototypes define the functional interface to the array object:

#define vc_MAX_RANK 7 /* Only 2 are usable in this release. */typedef int vc_DIMS[vc_MAX_RANK];typedef int vc_BNDS[vc_MAX_RANK][2];typedef void *vc_ARRAY;typedef int BOOL; /* True or false values */typedef double REAL;vc_ARRAY *vc_array_create(vc_DIMS Dims, int Rank, BOOL ColumnVector);void vc_array_set_values(vc_ARRAY *A, REAL *Values, int Index, int Count);void vc_array_get_values(vc_ARRAY *A, REAL *Values, int Index, int Count);REAL *vc_array_values (vc_ARRAY *A);void vc_array_set_dims(vc_ARRAY *A, vc_DIMS Dims, int Rank, BOOL ColumnVector);

void vc_array_get_dims(vc_ARRAY *A, vc_DIMS Dims, int *Rank, BOOL *ColumnVector);int vc_array_compute_index(vc_ARRAY *A, vc_BNDS Bounds, int nBounds);void vc_array_form_submatrix(vc_ARRAY *A, vc_BNDS Bounds, int nIndex);int vc_array_element_count(vc_ARRAY *A);BOOL vc_array_same_shape(vc_ARRAY *A1, vc_ARRAY *A2);vc_EL vc_array_elements (vc_ARRAY A);void vc_array_set_element_type (vc_ARRAY A, EXPR_TYPE ElementType);EXPR_TYPE vc_array_element_type (vc_ARRAY A);void vc_array_coerce_element_type (vc_ARRAY A, EXPR_TYPE ElementType);void vc_array_set_string_element (vc_ARRAY A, char *Value, int Index);int vc_array_source_object (vc_ARRAY A);

The source code for the DMAT function is given below as an example of how to use this interface:

vc_ARRAY vc_dmat(vc_ARRAY A){

vc_ARRAY NewArray;vc_DIMS Dims;int Size;int Rank;BOOL ColV;REAL *Values;int i;vc_array_get_dims(A, Dims, &Rank, &ColV); /* Verify the shape of the input array */if ( Rank > 2 || Dims[0] != 1 && Dims[1] != 1 )

{ vc_error("DMAT only works with a 1xN or Nx1 matrix, this one is %dx%d", Dims[0], Dims[1]);

}Size = vc_array_element_count(A);/* Set up dimensions of new

array */


64

Dims[0] = Size;Dims[1] = Size; NewArray = vc_array_create(Dims, 2, TRUE);Values = vc_array_values(A); /* Fetch the values for the

diagonal */for ( i = 0; i < Size; i++ )

{ vc_array_set_values(NewArray, &Values[i], i*(Size+1), 1);}

return(NewArray);}

System-Supplied FunctionsThe 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:

This function: Returns:

ABS The absolute value of an expression that represents a numerical value.

ACOS The arc cosine of an expression that represents a numerical value.

AINT The nearest integer whose magnitude is not larger than the integer value of a specified expression that represents a numerical value.

ANINT The nearest integer whose magnitude is not larger than the real value of an expression that represents a numerical value

ASIN The arc sine of an expression that represents a numerical value.

ATAN The arc tangent of an expression that represents a numerical value.

ATAN2 The arc tangent of two expressions, each representing a numerical value.

CEIL The smallest integer greater than x.

COS The cosine of an expression that represents a numerical value.

COSH The hyperbolic cosine of an expression that represents a numerical value.

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

EXP Returns the exponential for each element of x.

FLOOR The largest integer that is less than x.

INT The nearest value whose magnitude is not larger than x.

LOG The natural logarithm of an expression that represents a numerical value.

LOG10 Log to base 10 of an expression that represents a numerical value.

MAG The magnitude of a vector.

MOD The remainder of one expression, representing a numerical value, divided by another expression representing a numerical value.

NINT The whole number nearest to the input value.

RAND A pseudo-random value on the closed interval [0.0, 1.0], from a uniform distribution.

RTOI An integer representation of the input value, where the input value is a real number.

SIGN A numerical value which takes its sign from one argument and its magnitude from another.

SIN The sine of an expression that represents a numerical value.

SINH The hyperbolic sine of an expression that represents a numerical value.

SQRT The square root of an expression that represents a numerical value.


66


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:

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

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


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.

LOC_PLANE_MIRROR An array of three numbers representing a location expressed in the global coordinate system of a location mirrored across the specified plane.

LOC_RELATIVE_TO An array of three numbers, representing a location, by transforming a specified location that is relative to a coordinate system object.

LOC_SPHERICAL Cartesian coordinates (x, y, z) that are equivalent to spherical coordinates ( , , ).

LOC_TO_FLEXBODY_NODEID The node ID of the flexible body that is closest to the specified location

LOC_X_AXIS A normal vector defining the x-axis of a coordinate system object in the global coordinate system.

LOC_Y_AXIS A normal vector defining the y-axis of a coordinate system object in the global coordinate system.

LOC_Z_AXIS A normal vector defining the z-axis of a coordinate system object in the global coordinate system.

ORI_ALIGN_AXIS An orientation that aligns one axis of a coordinate system object with an axis of another.

ORI_ALONG_AXIS_EUL An orientation that aligns one axis of a coordinate system object with an axis of another.

ORI_ALL_AXES A body-fixed 313 Euler sequence describing an orientation in which the first axis of a coordinate system object is parallel to, and co-directed with, a line defined by the first two points in a plane, and its second axis is parallel to the plane.

ORI_ALONG_AXIS The alignment of a specified axis from one coordinate system object to another.

ORI_FRAME_MIRROR An orientation that has the specified axes mirrored about a plane within a coordinate system object.

ORI_GLOBAL An angle expressed in a coordinate system object to the global coordinate system.

ORI_IN_PLANE An orientation by directing one of the axes and defining one of the planes within a coordinate system object.

ORI_LOCAL An orientation, expressed in the global frame, in the local frame of the coordinate system object.



68

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:

ORI_MIRROR An orientation by performing a mirroring of the given orientations that reflect the specified axes.

ORI_ONE_AXIS A body-fixed 313 Euler rotation sequence expressed in the global coordinate system when given a line that is parallel to, and co-directed with, a specified axis.

ORI_ORI An orientation that represents the same orientation as expressed in the local frame of one coordinate system object to the local frame of another coordinate system object.

ORI_PLANE_MIRROR A sequence of body-fixed 313 Euler rotations by performing a mirroring of orientations.

ORI_RELATIVE_TO An orientation of a coordinate system object as specified by an angle.


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.




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:

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

PHI The third angle associated with a body-fixed 313 rotation sequence from one coordinate system object to another.

PITCH The negative value of the second angle associated with a body-fixed 321 rotation sequence from one coordinate system object to another.

PSI The first angle associated with a body-fixed 313 rotation sequence from one coordinate system object to another.

ROLL The third angle associated with a body-fixed 321 rotation sequence from one coordinate system object to another.

THETA The second angle associated with a body-fixed 313 rotation sequence from one coordinate system object to another.

YAW The first angle associated with a body-fixed 321 rotation sequence from one coordinate system object to another.


AKIMA_SPLINE An interpolated curve created from input points with a specified number of values.

AKIMA_SPLINE2 An Akima-spline fit of the dependent values.

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

ALLM The logical product of the elements of a matrix.

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

ANYM The logical sum of the elements of a matrix.

APPEND The rows of one matrix appended to the rows of another matrix.

BALANCE A similarity transformation T such that B = T/A*T has, as nearly as possible, approximately equal row and column norms.

BARTLETT The new array when the Bartlett window is applied to the input array.

BLACKMAN The new array when the Blackman window is applied to the input array.



70

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

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

BODELSM Computes the Bode response for a given set of A, B, C, and D matrices.

BODESEQ Returns the gain and/or phase values calculated from two sequences of time-based values describing the input and output of a linear system.

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

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

BUTTER_DENOMINATOR Calculates the denominator coefficients for the Butterworth filter.

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

BUTTER_NUMERATOR Calculates the numerator coefficients for the butterworth filter.

BUTTORD_FREQUENCY Calculates the cutoff frequency for the butterworth filter.

BUTTORD_ORDER Calculates the order for the butterworth filter.

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

CLIP An MxNumvals matrix of values extracted from an MxN matrix.

COLS The number of columns in a given matrix.

COMPRESS An array consisting of the non-empty values in the input array.

COND Returns the condition number of a matrix.

CONVERT_ANGLES A body-fixed 313 sequence converted into a user-specified sequence.

CROSS The cross-product of two matrixes.

CSPLINE An interpolated curve created from input points with a specified number of values.

CUBIC_SPLINE An interpolated curve created from input points with a specified number of values.

DET The determinant of a square matrix.

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

DIFF A 1xN array of approximations to the derivatives at the points in the input data.

DIFFERENTIATE The derivative at each input point on curve C.

DMAT A square matrix with the elements of M along the diagonal, and zero elsewhere.



DOE_MATRIX Returns a matrix of DOE experiments, a row from that matrix or the count of rows from that matrix.

DOE_NUM_TERMS Returns the number of terms in the polynomial produced by the OPTIMIZE FIT_RESPONSE_SURFACE command.

DOT The dot product of two matrixes.

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

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

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

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

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

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

ELEMENT Text that indicates if a real value is an element of an array.

EXCLUDE An array with a specified value excluded from it.

FFTMAG A 1xN array of magnitudes calculated by applying the FFT function to input values.

FFTPHASE A 1xN array of phase values calculated by applying the FFT function to input values.

FILTER A 1xN array of filtered input values, where N is the number of input values.

FILTFILT Zero phase digital filtering.

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

FIRST_N The first N elements of an array.

FREQUENCY The FFT frequencies of an array of time values.

GRIDDATA A real array of Zi values corresponding to the ordered pairs in Xi, and Yi.

HAMMING A 1xN array of values after applying the HAMMING window function.

HANNING A 1xN array of values after applying the HANNING window function.

HERMITE_SPLINE An interpolated curve created from input points with a specified number of values.

INCLUDE A value included into an array if the value is not already there.

INTEGR The integral produced at each input point on curve C.



72

INTEGRATE A curve of integrals produced from an input curve.

INTERP1 The Yi values corresponding to the Xi values

INTERP2 The Zi values corresponding to the Xi and Yi points.

INTERPFT An array of Y values nY long if given the x array and integer value nY.

INVERSE The inverse matrix of a square matrix.

LAST The last element of an array if an element exists; otherwise, returns a 0.

LAST_N The last N element of an array.

LINEAR_SPLINE An interpolated curve created from input points with a specified number of values.

MAX The value of the largest element of a matrix.

MAXI The index of the largest element of a matrix.

MEAN The mean of a matrix.

MESHGRID The X or Y grid coordinates.

MIN The value of the smallest element of a matrix.

MINI The index of the smallest element of a matrix.

NORM Scalar representing the norm of a matrix.

NORM2 The square root of the sum of the squares of the elements of a matrix.

NORMALIZE The normalized elements of a matrix.

NOTAKNOT_SPLINE An interpolated curve created from input points with a specified number of values.

PARZEN The 1xN array of values after applying the PARZEN window function.

POLYFIT Returns the coefficients of a polynomial fitted to the supplied function data.

PROD The product of the elements of a matrix by performing a matrix reduction using multiplication.

PSD The power spectral density computed from the complex Fourier coefficients.

PWELCH Estimate the power spectral density (PSD) of a signal using Welch's method.

RECTANGULAR The 1xN array of values after applying the RECTANGULAR window function.

RESAMPLE A curve resampled over a new interval with the spline algorithm you specified.

RESHAPE A new matrix created from an existing matrix with dimensions you specified in the shape-descriptor array.



REVERSE A reversed one-dimensional input array.

RMS The root mean square of the values.

ROWS The number of rows in a matrix.

SERIES An array it generated based on a start value, a number of increments, and an array length.

SERIES2 An increment it calculated based on start and end values and a given number of increments.

SHAPE The dimensions of a matrix.

SIM_TIME The simulation time for the last step of the default simulation.

SORT A matrix sorted in the direction you specified.

SORT_BY An array sorted by another array in the direction you specified.

SORT_INDEX The indexes of a matrix sorted in the direction you specified.

SPLINE An interpolated curve created from the input points with the number of points you specified.

SSQ The sum of the squares of the elements of a matrix.

STACK The concatenation of two matrixes with the same number of columns.

STEP An array of y values, on a step curve, corresponding to the x values.

SUM The sum of the elements of a matrix by performing a matrix reduction using addition.

TILDE The TILDE function of an array.

TMAT A 3x3 transformation matrix using the values in the orientation sequence you specified.

TMAT3 Returns a 3x3 transformation matrix using the values in the orientation sequence you specify.

TRANSPOSE The transpose of a matrix.

TRIANGULAR Apply the triangular window to the input array and return the new array.

UNIQUE An array from which it deleted all duplicate elements.

UNWRAP Unwraps phase angles in degree by changing absolute jumps greater than 180 degree to their 360 degree complement.

VAL An array element nearest to the number you specified.

VALAT A number from an array located at the same position as a number found in another array.

VALI The index of the element in an array nearest to the number you specified.

WELCH A 1xN array of values after applying the WELCH window function.



74

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:


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


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:

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.


DB_ACTIVE A Boolean value indicating that the object will or will not take part in simulations.

DB_ANCESTOR Returns the first ancestor of an object of the type you specify.

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

DB_CHILDREN An array of objects of a given type that are children of the object you specified.

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

DB_DEFAULT The default object of a given type.

DB_DEFAULT_NAME Returns the name for the given object based on the state of the default for formatting names.

DB_DEFAULT_NAME_FOR_TYPE Returns the name for the given object based on the state of the default for formatting names.

DB_DELETE_DEPENDENTS An array of objects that are dependents of the object you specified.



76

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

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

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

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

DB_FIELD_FILTER An array, from a given array of field names, containing a subset of the original array.

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

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

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

DB_FULL_NAME_FROM_SHORT Returns the full name for the named object of the specified type.

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

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

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

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

DB_OBJ_EXISTS_EXHAUSTIVE Returns a boolean value indicating whether the object specified exists or not.

DB_OF_CLASS A 1 if an object is a member of a given class; returns a 0 if it is not.

DB_OF_TYPE_EXISTS Returns a 1 if an object with the name and type you specified exits; returns a 0 if it does not exist.

DB_OLDEST_ANCESTOR Returns the most distant ancestor of an object of the type specified.

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

DB_SHORT_NAME Returns the shortest unique name for the given object.



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

Back to top


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:

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.

• EXPR_EXISTS

• EXPR_STRING

• PARAM_STRING

• UNIQUE_FULL_NAME

• UNIQUE_NAME

• USER_STRING


EXPR_EXISTS A 1 if an expression exists in a given field of an object that you specify; returns a 0 if it does not.

EXPR_REFERENCE A string containing the name of the reference to the expression.

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

PARAM_STRING A parameter's values as they appear in an Adams command file.

UNIQUE_FULL_NAME A text string containing a unique full name for the type of object you specified.

UNIQUE_ID Returns an adams_id unique for objects of the specified type.



78

GUI Functions Group

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

UNIQUE_LOCAL_NAME Returns a name of the form BASE_1, where "BASE" is a prefix that you supply and the number ("1" in this case) is computed by the function.

UNIQUE_NAME A text string that is a unique database name.

UNIQUE_NAME_IN_HIERARCHY A text string that is a unique database name, taking into account the inherent hierarchy in the given input

UNIQUE_PARTIAL_NAME A character string containing a unique object name.

UNITS_CONVERSION_FACTOR Returns the numeric conversion factor from the given unit value to the current default units.

UNITS_STRING A text string containing a units string associated with another string.

UNITS_TYPE Returns the character string value of the given unit type using the provided integer value.

UNITS_VALUE Returns the character string value of the given unit type using the default units settings.

USER_STRING A text string containing a value in the Object Field.


AGGREGATE_MASS Aggregate mass information.

ALERT An alert box using the labels you specify.

ALERT2 Displays the contents of the variable on separate lines and presents an OK button. It always returns 1.

ALERT3 Displays the contents of the variable on separate lines and presents an alert window with up to three buttons containing specified labels.

FILE_ALERT An integer representing the command button you selected after Adams/View displayed the Alert dialog box.

FIND_MACRO_FROM_COMMAND KEY of the macro using the specified commands.

NODE_ID_CLOSEST An integer node ID associated with the node of the flexible body closest to a specified marker.



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 thenodes of the flexible body within a radiusof a specified marker.

NODE_NODE_CLOSEST Returns an integer node id associated with a node of the flexible body, o_new_flex, closest to node, nodeId, on the flexible body o_old_flex.

PICK_OBJECT KEY of the selected object.

SECURITY_CHECK Returns a one or zero depending on whether or not the product name is properly licensed.

SELECT_DIRECTORY Returns the name of the directory you selected from the directory browser

SELECT_FIELD A selected field as a string.

SELECT_FILE A file name you selected.

SELECT_MULTI_TEXT An array of strings you selected.

SELECT_OBJECT A selected object, using the Database Navigator to provide you with selections.

SELECT_OBJECTS An array of selected objects, using the Database Navigator to provide you with selections.

SELECT_REQUEST_IDS An array of integers representing the selected IDs.

SELECT_TEXT The string you selected.

SELECT_TYPE A selection list of object types.

TABLE_COLUMN_SELECTED_CELLS An array of integers representing the 1-based row numbers of selected cells within a specified column in a table.

TABLE_GET_CELLS An array of strings representing the contents of the cells within the specified row/column range.

TABLE_GET_DIMENSION An integer representing the number of rows or columns in a table or the number of cells in a row or column.

TABLE_GET_REALS Returns an array of reals representing the contents of the cells within the specified row/column range.



80

String Functions Group

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

System Functions Group

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

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.


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.


BACKUP_FILE A backup of a specified file.

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

EXECUTE_VIEW_COMMAND A numerical value indicating whether EXECUTE_VIEW_COMMAND succeeded or failed in executing an Adams/View command.

FILE_DIRECTORY_NAME A directory name from the file specification.

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

FILE_MINUS_EXT The file name with its extension removed.

FILE_TEMP_NAME A string that has a non-existent temporary file name.



Design-Time Function DescriptionsFor each function we provide the following:

• Definition - A brief description of the function.

• Format - The function name and format as they appear in the Function Builder.

• Arguments - The arguments used by the function, and a short description of each argument.

• symbol - The mathematical equation relevant to the function.

• Examples - One or more examples of how to use the function.

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

GETCWD The current working directory as a character string.

GETENV Text string containing the value of the environment variable you specified.

MKDIR A numerical value indicating whether MKDIR succeeded in creating a user-specified directory.

PARSE_STATUS An array of integer status codes corresponding to the given search tag.

PUTENV The string value that PUTENV assigned to an environment variable.

REMOVE_FILE A 0 if successful in deleting a file; otherwise, it returns a nonzero value.

RENAME_FILE A specified file.

RMDIR A 1 if successful in removing the directory; otherwise, it returns 0.

SIM_STATUS An array of simulation status codes corresponding to the tag: ALVSIM:STATUS.

SYS_INFO A character string containing information about the system.

TERM_STATUS An array of simulation status codes corresponding to the tags: A3TERM:STATUS and TERM:STATUS.

UNIQUE_FILE_NAME A string that is the name of a non-existent file.

Notation: Stands for:

G Ground

O Object

R Reference frame


Adams/View Function BuilderFunctions: A - C

82

Functions: A - C

83Design-Time FunctionsFunctions: A - C

ABS

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

Format

ABS(x)

Argument

Example

The following example illustrates the use of the ABS function:

Learn more about math functions.

x Any valid expression that evaluates to a real number.

Function ABS(3*(-.89))

Result 2.67


84

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

Examples

The following examples illustrate the use of the ACOS function:



Function ACOS(.75)

Result 41

Function ACOS(PI/4)

Result 38


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

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

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)


86

The following example returns the off-diagonal entries of the inertia matrix for the aggregation of PART_2 and PART_3 in the ground reference frame. Note that array indexing has been used to return the 4th, 5th, and 6th entries from the returned array.

AGGREGATE_MASS( {PART_2, PART_3} , 0 , "inertias" )[4:6]

Alternatively, you can use the all type string and use array indexing to extract only the last three values. In this example, the computation is relative to PART_2.MARKER_1.

AGGREGATE_MASS({PART_2,PART_3}, PART_2.MARKER_1 , "All")[11:13]

Learn more about GUI functions.

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.


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)< 1AINT(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

Examples

The following examples illustrate the use of the AINT function:



Function AINT(-6.5)

Result -6

Function AINT(4.6)

Result 4


88

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

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:

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

Learn more about matrix/array functions.

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.

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}

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}


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.


90

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

Example

The following function creates an alert box:


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.



Default Choice Integer value (1, 2 or 3) indicating which command button is the default choice.

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

Result Alert box with "No" as the default choice


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

Example var set var=msg str="Out of", "disk", "space"var set var=OK int=(ALERT2 (msg.self, "ERROR"))


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


92

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

Example var set var=msg str="Out of", "disk", "space"var set var=OK int=(ALERT3 (msg.self, "ERROR", "OK", "Cancel", "", 1))


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.



choice An integer designating the default button number.


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

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)


real array Array of values to align (shift).

real number First value from aligned array.


94

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

Examples

The following examples illustrate the use of the ALLM function:


M A matrix of arbitrary shape.

Function ALLM({1, 0, 1})

Result 0

Function ALLM({1, 2, 3})

Result 1

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

Result 0


ANGLES

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

Format

ANGLES (D, OriType)

Arguments

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


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.


96

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 > 0ANINT(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

Examples

The following examples illustrate the use of the ANINT function:



Function ANINT(-4.6)

Result -5

Function ANINT(4.6)

Result 5


ANYM

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

Format

ANYM (M)

Argument

Examples

The following examples illustrate the use of the ANYM function:


M A matrix of arbitrary shape.

Function ANYM({8, 0, 1})

Result 1

Function ANYM({0, 0, 0})

Result 0

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

Result 1


98

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

Example

The following example illustrates the use of the APPEND function:

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


M1 A matrix of arbitrary shape.

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

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


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

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



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


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

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

– –


102

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

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

–


ATAN2

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

Format

ATAN2(x1, x2)

Arguments

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.

x1 Any valid expression that evaluates to a real number.


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

Result 45

2 x1 x2 atan–

2 x1 x2 0atan if x1 0

2 x1 x2 atan 0= if x1 0 x2 0=

2 x1 x2 atan = if x1 0 x2 0=

2 x1 x2 0atan if x1 0

abs 2 x1 x2 atan 2---= if x2 0=

2 x1 x2 undefinedatan if x1 0 and x2 0= =


104



AX

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

Format

AX (Object, Reference Frame)

Arguments

symbol

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

where:

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

• is the y-axis of the Reference Frame, 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:

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.

Function AX(marker_O, marker_R)

Result 35

AX zo yR zo zR– atan=

zoyR

zR


106

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.


AY


Format

AY (Object, Reference Frame)

Arguments

symbol

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

where:

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

• is the z-axis of the Reference Frame, 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:


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

Function AY(marker_O, marker_R)

Result 35

AY zo xR zo zR atan=

zozRxR


108

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)




AZ


Format

AZ (Object, Reference Frame)

Arguments

symbol

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

where:

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

• is the x-axis of the Reference Frame, 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:


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

Function AZ(marker_O, marker_R)

Result 35

AZ xo yR xo xR atan=

xoxRyR


110

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)




BACKUP_FILE

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

Format

BACKUP_FILE( file_name)

Argument

Example

The following example renames foo.dat to foo.dat% (on UNIX) or foo.daq (on Windows):

var set var=bkup int=(eval(BACKUP_FILE("foo.dat")))

Learn more about system functions.

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


112

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

Example

The following example illustrates the use of the BALANCE function:


This portion of the Adams/View Function Builder documentation, ©2006, has been reproduced here with permission from MathWorks, ©1994-2000 The MathWorks Inc.

A A square matrix.

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

Result {{1,2}, {3,4}}


BARTLETT

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

Format

BARTLETT (a)

Arguments

Example

The following is an illustration of the BARTLETT function:


a An array.

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

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


114

BARTLETT_WINDOW

Generate the Bartlett window.

Format

BARTLETT_WINDOW (n)

Arguments

Example

The following is an illustration of the BARTLETT_WINDOW function:


n An integer value.

Function bartlett_window (5)

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


BLACKMAN

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

Format

BLACKMAN (a)

Arguments

Example

The following is an illustration of the BLACKMAN function:


a An array.

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

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


116

BLACKMAN_WINDOW

Generate the Blackman window.

Format

BLACKMAN_WINDOW (n)

Arguments

Example

The following is an illustration of the BLACKMAN_WINDOW function:


n An integer value.

Function blackman_window (5)

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


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:

Fixed linear spacing per FREQARG:

FREQARG linearly-spaced

samples:

FREQARG logarithmically-

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.


118

Examples

The following example assumes that you have four Adams/View matrices, ABCD, as follows:

data_element create matrix full &matrix_name = .model_1.A &input_order = by_row &row_count = 3 &column_count = 3 &values = 0.0, 1.0, 0.0, 0.0, 0.0, 1.0, -0.22,-1.14,-0.4

data_element create matrix full &matrix_name = .model_1.B &input_order = by_column &row_count = 3 &column_count = 1 &values = 0.0, 0.0, 1.0

data_element create matrix full &matrix_name = .model_1.C &input_order = by_row &row_count = 1 &column_count = 3 &values = 0.01, 0.0, 0.0

data_element create matrix full &matrix_name = .model_1.D &input_order = by_column &row_count = 1 &column_count = 1 &values = 0.0

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

var set var=bode_mag_log real=(BODEABCD(7, 1, .model_1.A, & .model_1.B, .model_1.C, .model_1.D, 0.01, 10, 100))



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

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_1measure 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 &

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:



O_LSE Adams linear state equation entity.

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


120

linear_state_equation_name = .model_1.LSE &x_state_array_name = .model_1.x &u_input_array_name = .model_1.u &y_output_array_name = .model_1.y &a_state_matrix_name = .model_1.A &b_input_matrix_name = .model_1.B &c_output_matrix_name = .model_1.C &static_hold = on

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

variable set variable=bode_mag_log real=(BODELSE(7, 1, .model_1.lse, 0.01, 10, 100))



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.



If both phases and magnitudes are to be returned, then there are two rows for each input/output combination and the magnitudes are stored first.

LSM The Adams/View linear state matrix object containing the matrices computed by the system linearization.

freqStart Low frequency in the omega vector.


122

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 1row 2 = input 1/output 2row 3 = input 2/output 1row 4 = input 2/output 2var cre var=mags rea=(BodeLSM (4, 3, Stmat_1, 1, 100, 50))


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.


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

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.


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.


124

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

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



NUMER A 1xN array of transfer function numerators.

DENOM A 1xN array of transfer function denominators.



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.


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

Examples

The following function assumes that you created an Adams transfer function element, as follows:

model create model=model_1measure 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


TFSISO An Adams transfer function entity.



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.


126

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



BUTTER_DENOMINATOR

Calculates the denominator coefficients for the Butterworth filter.

Format

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

Argument

Example

The following example illustrates the BUTTER_DENOMINATOR function:


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.

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}


128

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.


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.


BUTTER_NUMERATOR

Calculates the numerator coefficients for the Butterworth filter.

Format

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

Arguments

Example

The following example illustrates the BUTTER_NUMERATOR function:


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.



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}


130

BUTTORD_FREQUENCY

Calculates the cutoff frequency for the Butterworth filter.

Format

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

Arguments

Example

The following is an illustration of the BUTTORD_FREQUENCY function:


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.


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.


BUTTORD_ORDER

Calculates the order for the Butterworth filter.

Format

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

Arguments

Example

The following is an illustration of the BUTTORD_ORDER function:


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.


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.


132

CEIL

Returns the smallest integer greater than x.

Format

CEIL(x)

Argument

Example

The following example illustrates the use of the CEIL function:



Function CEIL(10.001)

Result 11


CENTER

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

Format

CENTER (A)

Argument

Equation

Mathematically, CENTER is calculated as follows:

Example

The following example illustrates the use of the CENTER function:


A Array of arbitrary shape.

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

Result 2.5

CENTER A MIN A MAX A +2.0

------------------------------------------------=


134

CHDIR

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

Format

CHDIR (String)

Argument

Example

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


String Text string that specifies a directory.

Function CHDIR("/tmp")

Result 1


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

Example

The following example illustrates the use of the CLIP function:


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.

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

Result 8, 12, 16


136

COLS

Returns the number of columns in a given matrix.

Format

COLS (M)

Argument

Examples

The following examples illustrate the use of the COLS function:


M A given matrix.

Function COLS({1, 2, 3})

Result 1

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

Result 3

Function COLS(marker_1.location)

Result 1


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

Examples variable create variable=my_ints int=1, 0, 0, 2, 0, 3, 0, 0variable create variable=my_reals rea=1.1,0.0, 2.2, 3.3,0.0, 0.0, 4.4, 0.0variable 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 = ""


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.


138

COND

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

Format

COND (squareMatrix)

Argument


squareMatrix A square matrix representing a linear system.


CONVERT_ANGLES

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

Format

CONVERT_ANGLES (E, OriType)

Arguments

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


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


140

COS

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

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

COS(x)

Argument

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


COSH

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

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

COSH(x)

Argument

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


142

CROSS

Returns the cross-product of two matrices.

Format

CROSS (M1, M2)

Arguments

The following example illustrates the use of the CROSS function:


M1 First matrix.

M2 Second matrix.

Note: CROSS will only accept 3x1 or 1x3 arrays.

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

Result {0, 0, 1}


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

Example




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.



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}


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


144

CUBIC_SPLINE

Creates an interpolated curve from input points with a specified number of values. Interpolates using a third order Lagrangian polynomial.


Reference: Digital Computation and Numerical Methods. Southworth, 1965. Chapter 8.7

Format

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

Arguments

Example







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}


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

145Design-Time FunctionsFunctions: D - E

Functions: D - E

Adams/View Function BuilderFunctions: D - E

146

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

Format

DB_ACTIVE (object)

Argument

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.

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

object A database object about which activity information is desired.


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

Example

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


Child The object whose ancestor is to be found.

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

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

Result .model_1


148

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:



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

Example

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


Object Name Name of a database object.

Object Type Character string (see DB_TYPE).


150

DB_COUNT

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

Format

DB_COUNT (Object Name, Field Name)

Arguments

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



Field Name Character string.


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

Example

The following function creates a variable that is the default part:

variable create variable=default_part & object_value=(DB_DEFAULT(system_defaults, "part"))


Defaults Object Name Name of the defaults in the database, always system_defaults.



152

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

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


object Any Adams/View object.


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

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



type String for the object's type or class.


154

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

Example

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




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

Example

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




156

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

Example

The following commands delete all parametric dependencies on par3:




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

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.





158

DB_EXISTS

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

Format

DB_EXISTS (Name String)

Argument

Example

The following function creates marker_3 if .mod1.par1 exists:

if condition=(DB_EXISTS(".mod1.par1")) marker create marker=marker_3 end


Name String Character string representing the name of an object.


DB_FIELD_FILTER

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

Format

DB_FIELD_FILTER (Filter Strings, Field Strings)

Arguments

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

• object_type = database_object_type uses the type specified as the database_object_type for field lookups. The value of database_object_type is one of the values returned by the function SELECT_TYPE (but cannot be a class name).

• t = type selects all fields that can hold an object of type. type can be the following subset of types from the macro language:

If type is: The field holds:

Bool A boolean value.

String Strings

Real Real numbers

Integer Integer numbers

Point Ordered triples, such as location and orientation.

Database_object_type A database object


160

Example

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


• c = n where ; 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.

n 0


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

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


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

Field Name Character string.

Function variable create variable=var6 &string=(DB_FIELD_TYPE("Graphic_Interface_Dialog_Box", "width"))

Result REAL


162

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

Example

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


Objects to Filter Array of database objects

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


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

Example

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


Objects to Filter Array of database objects.

Filter Type String Character string (see DB_TYPE).


164

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

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


short_name Short name of the object.

type String for the object’s type or class.


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

Example

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


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


166

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

Examples

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





DB_OBJECT_COUNT

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

Format

DB_OBJECT_COUNT (Objects)

Argument

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


Objects Names of database objects.


168

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

Examples

The following illustrates the use of DB_OBJ_EXISTS:


Parent The object defining the search domain.

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

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

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


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

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


ContextObject The object in which to search for a child with the given name.

Name A character string naming the object.


170

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

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



Object Class Character string (see DB_TYPE).


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

Example if condition=(DB_OF_TYPE_EXISTS(".mod1.par1.node1", "marker")) marker copy marker=.mod1node1 new_marker=.mod1.ground.node1 end


Name String Character string representing the name of an object.

Object Type Character string, see DB_TYPE.


172

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

Example

The following example illustrates the use of the DB_OLDEST_ANCESTOR function:


Child The object whose ancestor is to be found.

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

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

Result .model_1


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

Example

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





174

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

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.




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

Example

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





176

DB_TYPE

Returns a string representing an object type.

Format

DB_TYPE (Object Name)

Argument

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


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


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

Example

The following commands return all the field names for maker:


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


178

DET

Returns the determinant of a square matrix.

Format

DET (M)

Argument

Example

The following example illustrates the use of the DET function:


M A square matrix.

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

Result -8.0


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

Example

The following example illustrates the use of the DETREND function:


INDEP A 1xN array of independent data.

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

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

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


180

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

Example

The following example illustrates the use of the DIFF function:


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.

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

Result 0, 2.0, 4.0, 6.0, 8.0


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

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.


C Input curve.


182

DIM

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

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

Format

DIM(x1, x2)

Arguments

Example

The following example illustrates the use of the DIM function:


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



Function DIM(5*4,5)

Results 15


DM

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

Format

DM (Object 1,Object 2)

Arguments

symbol

Mathematically, DM is calculated as follows:

where:

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


Example

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

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.

Function DM (marker_O1, marker_O2)

Result 13

DM R01 R02– R01 R02– =

R01

R02


184



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

Example

The following example illustrates the use of the DMAT function:

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.


M An Nx1 or 1xN array.

Function DMAT({1, 2, 3})

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


186

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.

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



188

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

Examples

The following examples illustrate the use of the DOE_NUM_TERMS function:


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

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


DOT

Returns the dot product of two matrixes.

Format

DOT (M1, M2)

Arguments

Example

The following example illustrates the use of the DOT function:


M1 First matrix.

M2 Second matrix.

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

Result 1


190

DX

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

Format

DX (Object 1, Object 2, Reference Frame)

Arguments

symbol

Mathematically, DX is calculated as follows:

where:



• is the unit vector along the x-axis of the Reference Frame, R.

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.

DX R01 R02– xR=

R01

R02

xR


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:

Learn more about modeling functions

Function DX(marker_O1, marker_O2, marker_R)

Result 12


192

DY

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

Format

DY (Object 1, Object 2, Reference Frame)

Arguments

symbol

Mathematically, DY is calculated as follows:

where:



• is the unit vector along the y-axis of the Reference Frame, R.



Reference Frame Coordinate system object defining the y-axis; used to measure the translational displacement component.

DY R01 R02– yR=

R01

R02

yR


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


194

DZ

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

Format

DZ (Object 1, Object 2, Reference Frame)

Arguments

symbol

Mathematically, DZ is calculated as follows:

where:



• is the unit vector along the z-axis of the Reference Frame, R.



Reference Frame Coordinate system object that defines the z-axis; used to measure the translational displacement component.

DZ R01 R02– zR=

R01

R02

zR


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


196

EIG_DI

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

Format

EIG_DI (A, B)

Arguments

Examples

The following example illustrates the use of the EIG_DI function:


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

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

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


EIG_DR

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

Format

EIG_DR (A, B)

Arguments

Examples

The following illustrates the use of the EIG_DR function:


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

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

Result {1.0, 0.0, 0.0, 1.0}


198

EIG_VI


Format

EIG_VI (A, B)

Arguments

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}


EIG_VR

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

Format

EIG_VR (A, B)

Arguments

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}


200

EIGENVALUES_I


Format

EIGENVALUES_I (A, B)

Arguments

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}


EIGENVALUES_R

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

Format

EIGENVALUES_R (A, B)

Arguments

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}


202

ELEMENT

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

Format

ELEMENT (A, X)

Arguments

Examples

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


A An array.

B A real number.

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

Result true

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

Result false


EXCLUDE

Excludes a value from an array.

Format

EXCLUDE (A, X)

Arguments

Example

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


A An array.

X A real number.

Function EXCLUDE(.MOD1.A,4)

Result removes 4 from the list


204

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

Example

The following example illustrates the use of the EXECUTE_VIEW_COMMAND function:


Command Character string containing an Adams/View command.

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

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


EXP

Returns the exponential for each element of x.

Format

EXP(x)

Argument

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.


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.

X Any valid expression that evaluates to a real number.

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

Result 54.6


206

Format

EXPR_EXISTS (Object Field)

Argument

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


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

Function EXPR_EXISTS(".mar1.location")

Result 1 (true)

Function EXPR_EXISTS(".mar1.orientation")

Result 0 (false)


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

Examples var set var=load_dep &str=(eval(expr_reference(".mod.par.mar.loc", 1)))


Exression A character string name of a database field.

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


208

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

Examples




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

Function EXPR_STRING("mar1.location")

Result "(LOC_RELATIVE_TO({0, 0, 0}, .mod1.ground.mar2))"

Function EXPR_STRING(".mar1.orientation")

Result " " (an empty string)

209Design-Time FunctionsFunctions: F - L

Functions: F - L

FFTMAG

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

Format

FFTMAG (A, N)

Arguments

Example

The following example illustrates the use of the FFTMAG function:


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.

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

Result 12.0, 7.1968, 4.2197

Adams/View Function BuilderFunctions: F - L

210

FFTPHASE

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

Format

FFTPHASE (A, N)

Arguments

Example

The following example illustrates the use of the FFTPHASE function:



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.

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

Result 0.0, 107.012, 157.356


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

Example

The following example illustrates the use of the FILE_ALERT function:


File Name Text string naming a file.

Function FILE_ALERT("aview.log%")

Result returns an Alert box, as shown below.


212

FILE_DIRECTORY_NAME

Returns a directory name from the file specification.

Format

FILE_DIRECTORY_NAME(file_name)

Argument

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"


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


FILE_EXISTS

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

Format

FILE_EXISTS (File Name)

Argument

Examples

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


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

Function FILE_EXISTS(aview.log%)

Result 1

Function FILE_EXISTS(avkiew.log%)

Result 0


214

FILE_MINUS_EXT

Returns the file name with its extension removed.

Format

FILE_MINUS_EXT (file_name)

Argument

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"


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


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



216

FILTER

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

Format

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

Arguments

Independent Variable A 1xN array of independent values.

Dependent Variable A 1xN array of dependent values as a function of the independent values.

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


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)

Denominator Coefficients

A set of denominator coefficients in the transfer function. The number of 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:

The denominator coefficients for a continuous filter are used as follows:

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

The denominator coefficients for a continuous filter are used as follows:

a0 zn a1 z n 1– a2 z n 2– +++

b0 zm b1 z m 1– ab2 z m 2– +++

a0 a1 z 1– a2 z 2– +++

b0 b1 z 1– b2 z 2– +++


218



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.


220

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)

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


command_str A string containing the user_entered_command of interest.


FIRST

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

Format

FIRST (A)

Argument

Examples

The following examples illustrate the use of the FIRST function:


A An array.

Function FIRST ({})

Result 0.0

Function FIRST ({1,2,3})

Result 1


222

FIRST_N

Returns the first N elements of an array.

Format

FIRST_N (A,N)

Arguments

Examples

The following examples illustrate the use of the FIRST_N function:


A An array.

N Number of elements to return.

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}


FLOOR

Returns the largest integer that is less than x.

Format

FLOOR(x)

Argument

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


224

FREQUENCY

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

Format

FREQUENCY (A, N)

Arguments

Example

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


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.

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


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


226

GETENV

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

Format

GETENV (Environment Variable)

Argument

Example

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


Environment Variable Character string representing an environment variable.

Function GETENV("USER")

Result tmazz


GRIDDATA

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

Format

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

Argument

Examplevariable create variable=Xi real=1,2,3,1,2,3,1,2,3variable create variable=Yi real=1,1,1,2,2,2,3,3,3variable 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)


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.


228

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

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.

Object The dialog box name

Note: The function CANNOT be used to unload the function-builder dialog.


HAMMING

Returns a 1xN array of values after applying the HAMMING window function.

Format

HAMMING (a)

Argument

Example

The following example illustrates the use of the HAMMING function:


a A 1xN array of real numbers.

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

Result {0.0800, 1.0800, 3.0000, 2.1600, 0.1600}


230

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

Example

The following example illustrates the use of the HAMMING_WINDOW function:


n An integer value.

Function hamming_window (5)

Result {0.0800, 0.5400, 1.0000, 0.5400, 0.0800}


HANNING

Returns a 1xN array of values after applying the HANNING window function.

Format

HANNING (A)

Argument

Example

The following example illustrates the use of the HANNING function:


A A 1xN array of real numbers.

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

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


232

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

Example

The following example illustrates the use of the HANNING_WINDOW function:


n An integer value.

Function hanning_window (5)

Result {0.2500, 0.7500, 1.0000, 0.7500, 0.2500}


HERMITE_SPLINE

Creates an interpolated curve from input points with a specified number of values. Interpolates using the Hermite cubic spline.


Format

HERMITE_SPLINE (Independent Data, Dependent Data, Number of Output Values)

Arguments

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.



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.



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}


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


234

INCLUDE

Includes a value into an array if the value is not already there.

Format

INCLUDE (A, X)

Arguments

Example

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


A An array.

X A real value.

Function INCLUDE(.MOD1.A,11)

Result includes 11 as an element of the array


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

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


236

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

Example

The following example illustrates the use of the INTEGR function:


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.

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

Result 0.0, 0.333, 2.667, 9.0, 21.333


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

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,*])


C Input curve.


238

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

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.

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.


• spline id is the identifier of the spline that specifies the RPC III or DAC file input. Setting up a Spline in Adams/Durability.

For more information on the INTERP function, see INTERP for Adams/Solver (C++) or INTERP for Adams/Solver (FORTRAN).


240

INTERP1

Calls the MATLAB INTERP1 function and returns a real array. Given a curve described by x and y, the INTERP1 function returns the Yi values corresponding to the Xi values.

Format

INTERP1 (x, y, Xi, method)

Argument

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}


(1.5,1.5)(2.5,2.5)


x The x values of the input curve.

y The y values of the input curve.

Xi The x values at which to evaluate the spline.

method A character string that indicates the interpolation method to be used. These come directly from the MATLAB function with the same name:

nearest - Nearest neighbor interpolation.

linear - Linear interpolation.

spline - Cubic spline interpolation

pchip - Piecewise cubic Hermite interpolation.

cubic - Same as pchip.

v5cubic - Cubic interpolation used in MATLAB 5.


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

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}


(1.5,1.5,1.5)(1.5,2.5,2.5)(2.5,1.5,1.5)(2.5,2.5,2.5)

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.


242



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

Examplevariable 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}


x An array of real numbers containing the x values to interpolate.

nY The count of y values to return.


244

INVERSE

Returns the inverse matrix of a square matrix. If an inverse doesn't exist, it generates an error.

Format

INVERSE(M)

Argument

Example

The following example illustrates the use of the INVERSE function:


M A square matrix.

Function INVERSE({[1,2.0], [2,1,-1], [3,1,1]})

Result {[-.25, .25, .25], [.625, -.125, -.125], [.125, -.625, .375]}


LAST

Returns the last element of an array if an element exists; otherwise, returns a 0.

Format

LAST (A)

Argument

Examples

The following examples illustrate the use of the LAST function:


A An array.

Function LAST({})

Result 0.0

Function LAST({1})

Result 1

Function LAST({1,2,3})

Result 3


246

LAST_N

Returns the last N element of an array.

Format

LAST_N (A,N)

Arguments

Examples

The following examples illustrate the use of the LAST function:


A An array.

N Number of elements to return.

Function LAST_N({3},2)

Result {}

Function LAST_N({1,2,3},0)

Result {}

Function LAST_N({1,2,3},2)

Result {2,3}


LINEAR_SPLINE

Creates an interpolated curve from input points with a specified number of values. Interpolates using linear interpolation.


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

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}


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


248

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:

Learn more about location/orientation functions.

Function LOC_ALONG_LINE(marker_2, marker_1, 5)

Result 7.5, 9.5, 0

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


250

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)

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.

flex_body Name of the flexible body.

node_id Node number.


LOC_CYLINDRICAL

Returns an array of three numbers that are the Cartesian coordinates (x, y, z) for a point equivalent to the

cylindrical coordinates (r, , z) for the same point. Both sets of coordinates are relative to the global coordinate system origin and axes. The relationship between the coordinates is:

• x = r cos

• y = r sin

• z = z

Format

LOC_CYLINDRICAL (R, Theta, Z)

Arguments

R The radius of the circle on which the point lies.

Theta ( ) Rotation about the z-axis starting from the x-axis. The positive or negative sense of the rotation is defined by the right-hand rule.

Z Distance along the global z-axis.


252

Example

In the following illustration, the LOC_CYLINDRICAL function returns an array of three numbers that are the Cartesian coordinates for a point.


Function LOC_CYLINDRICAL(1,30,0)

Result 0.866, 0.5, 0

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


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

Example

In the following illustration, the LOC_FRAME_MIRROR function returns an array of three numbers representing a location:

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.

Function LOC_FRAME_MIRROR({7,7,0}, marker_1, "xy")

Result 7, 5, 0 (in the global coordinate system)

Note: In this example, the xy plane of coordinate system object, marker_1, is parallel to the global xz plane.


254



LOC_GLOBAL

Returns an array of three numbers representing the global coordinates of a location obtained from transforming the local coordinates by a specified location.

Format

LOC_GLOBAL (Location, Frame Object)

Arguments

Location Array of numbers that specify a location expressed relative to a local coordinate system.

Frame Object Coordinate system object in which the local coordinates are expressed.


256

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)



LOC_INLINE

Returns an array of three numbers representing the transformation and normalization of coordinates for a location you specified. The location's coordinates are originally expressed in terms of one coordinate system and then transformed to the equivalent coordinates, as expressed relative to a new coordinate system.

Format

LOC_INLINE (Location, In Frame Object, To Frame Object)

Arguments

Location Array of three numbers specifiying a location expressed in terms of the original coordinate system.

In Frame Object Starting coordinate system object in which location coordinates are input.

To Frame Object New coordinate system into which the location coordinates are transformed.


258

Examples

In the following illustration, the LOC_INLINE function returns an array of three numbers representing the transformation and normalization of coordinates for a specified location:

Function LOC_INLINE({-8, -2, 0}, marker_1, marker_2)

Result 0.8, 0.6, 0.0

Note: LOC_INLINE normalizes the transformed coordinates before returning them.


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


260

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)


262

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)


264

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

Example

In the following illustration, the LOC_MIRROR function returns an array of three numbers representing a location:

Location Array of numbers that specifies a location expressed in the global coordinate system.


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.

Function LOC_MIRROR({7,7,0}, marker_1, "xy")


Note: In this example, the xy plane of coordinate system object, marker_1, is parallel to the global xz plane.


266

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

Examples

In the following illustration, the LOC_ON_AXIS function returns an array of three numbers representing a location:

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

Function LOC_ON_AXIS(marker_2, 5, "x")

Result 4, 11, 0



Function LOC_ON_AXIS(marker_2, 5, "y")

Result -1, 6, 0


268



Function LOC_ON_AXIS(marker_2, 5, "z")

Result 4, 6, 5


LOC_ON_LINE

Returns an array of three numbers representing the global coordinates of a location along a line defined by two points.

Format

LOC_ON_LINE (Line Point Locations, Distance)

Arguments

Line Point Locations 3x2 matrix containing two points describing a line. The coordinates of the points are expressed in the global coordinate system.

Distance Real number, measured from the first point, that determines how far to move along the line.


270

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


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

Example

The following example illustrates the use of the LOC_PERPENDICULAR function:


Plane Point Locations 3x3 matrix providing three non-colinear points describing a plane.

Function LOC_PERPENDICULAR({{10,12,0},{14,12,0},{12,10,0}})

Result 10, 12, 1


272

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


274

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

Example

In the following illustration, the LOC_RELATIVE_TO function returns an array of three numbers representing a location:

Location Array of numbers specifying a location expressed in a coordinate system object.

Frame Object Coordinate system object.

Function LOC_RELATIVE_TO({16,8,0}, marker_2)

Result -4, 22, 0


276

LOC_SPHERICAL

Returns Cartesian coordinates (x, y, z) that are equivalent to spherical coordinates ( , , ). In this case:

• x = sin cos

• y = sin sin

• z = sin

Format

LOC_SPHERICAL (Rho, Theta, Phi)

Arguments

Example

The following example illustrates the use of the LOC_SPHERICAL function:


Rho The radius of the sphere.

Theta Counterclockwise rotation about z.

Phi Counterclockwise rotation about x.

Function LOC_SPHERICAL(10, 8, 0)

Result 1.39, 0, 9.9


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

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.

flex_body Name of the flexible body.

location Three-dimensional vector.


278

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

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


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

Example

In the following illustration, the LOC_Y_AXIS function returns a normal vector defining the y-axis of marker_2:


Function LOC_Y_AXIS(marker_2)

Result 0, 1, 0


280

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

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


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

Example

The following example illustrates the use of the LOG function:



Function LOG(30)

Result 3.4


282

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

Example

The following example illustrates the use of the LOG10 function:



Function LOG10(42)

Result 1.6

283Design-Time FunctionsFunctions: M - P

Functions: M - P

MAG

Returns the magnitude of a vector.

Format

MAG(x, y, z)

Arguments

Example

The following example illustrates the use of the MAG function:


x Real value.

y Real value.

z Real value.

Function MAG(5,3,1)

Result 5.91

MAG x y z x2 y2 z2+ +=

Adams/View Function BuilderFunctions: M - P

284

MAX

Returns the value of the largest element of a matrix.

Format

MAX (M)

Argument

Example

The following example illustrates the use of the MAX function:


M A matrix.

Function MAX({{2,4,5},{1,8,2}})

Result 8.0


MAXI

Returns the index of the largest element of a matrix.

Format

MAXI (M)

Argument

Example

The following example illustrates the use of the MAXI function:


M A matrix.

Function MAXI({0.1, 0.2, 0.3, 3.3})

Result 4


286

MEAN

Returns the mean of a matrix.

Format

MEAN (M)

Argument

Example

The following example illustrates the use of the MEAN function:


M A matrix.

Function MEAN({0.1, 0.2, 0.3, 3.4})

Result 1.0


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

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:

object The object that the user is measuring

CoordSystem The key of a marker indicating the coordinate system the result will be reported in.

RefFrame The reference frame in which any time derivatives needed to compute the measure quantity will be computed. The RefFrame can be thought of the reference frame which the 'observer' is fixed in.

characteristic The characteristic to be measured. Available characteristics for an object are displayed in the characteristic list of the plot builder when the object is selected in the object list.

component The component of characteristic to be measured. Available components for an object/characteristic combination can be viewed in the component list of the plot builder when the object and characteristic are picked in their respective lists.

Function MEASURE ( part_2, MARKER_1, MARKER_1, cm_position, 1)


288

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

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}


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.


MIN

Returns the value of the smallest element of a matrix.

Format

MIN (M)

Argument

Example

The following example illustrates the use of the MIN function:


M A matrix.

Function MIN({{2,4,5},{1,8,2}})

Result 1.0


290

MINI

Returns the index of the smallest element of a matrix.

Format

MINI (M)

Argument

Example

The following example illustrates the use of the MINI function:


M A matrix.

Function MINI({0.1, 0.2, 0.3, 3.3})

Result 1


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

Example

The following function creates a new directory, named my_directory:


String Text string that names a directory.

Function MKDIR("my_directory")

Result 1


292

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

Example

The following example illustrates the use of the MOD function:




Function MOD(45,16)

Result 13


NINT

Returns the whole number nearest to the input value.

Format

NINT(x)

Argument

Examples

The following examples illustrate the use of the NINT function:



Function NINT(4.78)

Result 5

Function NINT(-.25)

Result 0


294

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

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


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.


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

Exampleif cond=(NODE_ID_IS_INTERFACE(FlexBodyObj, ThisNode))


flexible_body Key of flexible body.

node_id Specifies the node ID on flexible body.


296

NODE_IDS_CLOSEST_TO

Returns array containing node IDs (integers) of the number (num) ofnodes on a flexible body closest to a specified marker.

Format

node_ids_closest_to (marker, flex_body, num, intpt)

Arguments

Returns

If NODES_IDS_CLOSEST_TO finds no nodes, it returns a singleinteger value of -1 with no warning.

Example

The following example displays the three nodes on the flexible bodynamed link closest to marker_1 on ground. It displays the nodes in theInfo window, as shown in the figure below.



num Number of nodes requested.

intpt Integer flag:




var set var=.nodes int=(eval(node_ids_closest_to(marker_1, link, 3, 0))) &comments = "3 closest nodes to marker"



298

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

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.


geom Name of the geometry object. The geometry object must be either a cylinder or a spherical ellipsoid (that is, xscale==yscale==zscale).


var set var=.nodes int=(eval(node_ids_in_volume(link, sphere)))



300

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

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



radius Radius around marker to check for nodes.

intpt Integer flag:




302

NODE_NODE_CLOSEST

Returns an integer node ID associated with a node of the flexible body, o_new_flex, closest to node, old_nodeId, on the flexible body o_old_flex. If intptis set to 1, only the interface nodes are considered.

Format

int vc_node_node_closest(KEY o_old_flex, KEY o_new_flex, int old_nodeID, intpt)

Arguments

Example

The following example:

variable set variable = tmp & integer=(eval(node_node_closest(old_part, new_part,

old_node_id1)))

returns the ID of the interface node on new_part closest to the location of the old_node_id on old_part.


KEY o_old_flex The old flexible body.

Key o_new_flex The new flexible body.

nodeId The node ID on the old flexible body.

intpt An integer flag:

• 1: Consider only interface nodes

• 0: Consider all nodes


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

Examplevariable create variable=N real=(norm({1,2,3}))

produces a value of 3.7417 for N.




304

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

Example

The following example illustrates the use of the NORM2 function:


M A matrix.

Function NORM2({[1, 2], [3, 4]})

Result 5.47722 (SQRT(1**2 + 2**2 + 3**2 + 4**2))


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

Example

The following example illustrates the use of the NORMALIZE function:


M A matrix.

Function ({3,4,5})

Result {0.424, 0.566, 0.707}


306

NOTAKNOT_SPLINE

Creates an interpolated curve from input points with a specified number of values. Interpolates using the Not-a-knot cubic spline.


Format

NOTAKNOT_SPLINE (Independent Data, Dependent Data, Number of Output Values)

Arguments

Example




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.



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}


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


ON_OFF

Returns the character string on or off, depending on the state of the argument.

Format

ON_OFF (State)

Argument

Example

The following example illustrates the use of the ON_OFF function:

Learn more about string functions.

State Integer value denoting a Boolean value of on (1) or off (0).

Function ON_OFF(1)

Result on


308

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


310

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

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:

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.

Function ORI_ALIGN_AXIS_EUL({8,10,0}, “z-z”)

Result 188, 170, 90


312

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

Examples

In the following illustration, the ORI_ALL_AXES function returns a body-fixed 313 Euler sequence describing an orientation, as specified.

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.

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:


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

Result 315, 90, 0


314

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.

Format

ORI_ALONG_AXIS (From Frame, To Frame, Axis Name)

Example

In the following illustration, the ORI_ALONG_AXIS function returns the alignment of a specified axis:

Note: ORI_ALONG_AXIS duplicates the actions of the ALONG_AXIS_ORIENTATION parameter on the PART and MARKER commands.

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

Function ORI_ALONG_AXIS(marker_1, marker_2, "y")

Result 315, 0, 0



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


316

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)

Example

In the following illustration, the ORI_FRAME_MIRROR function returns an orientation, as specified:

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.

Function ORI_FRAME_MIRROR({6,14,0}, marker_1, “xz”, “xz”)

Result 174, 14, 180


318

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

Example

In the following illustration, the ORI_GLOBAL function returns an orientation, as specified:


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.

Function ORI_GLOBAL({marker_2.orientation}, marker_1)

Result 270, 0, 0


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.

Format

ORI_IN_PLANE (Frame Object 1, Frame Object 2, Frame Object 3, Directed Axes & Coordinate)

Note: ORI_IN_PLANE duplicates the actions of the IN_PLANE_ORIENTATION parameter on the PART and MARKER commands.

Frame Object 1 Coordinate system object defining a starting point for the orientation plane.

Frame Object 2 Coordinate system object defining another point for the orientation plane.

Frame Object 3 Coordinate system object defining another point for the orientation plane.

Directed Axes & Coordinate Character string defining which axis is to be directed and which coordinate system object plane is to be oriented. The possible values for this parameter are: x_xy, x_xz, y_yx, y_yz, z_zx, or z_zy.


320

Example

In the following illustration, the ORI_IN_PLANE function returns an orientation, as specified:


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

Result 135, 90, 90


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

Example

The following example illustrates the use of the ORI_LOCAL function.


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.

Function ORI_LOCAL({marker_1.orientation}, marker_2)

Result 90, 0, 0


322

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

Example

In the following illustration, the ORI_MIRROR function returns an orientation, as specified:

Body Fixed 313 Angles Array of body-fixed 313 Euler rotation sequences, expressed in a coordinate system object.


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.

Function ORI_MIRROR({{10,8,0}}, marker_1, “xy”, “xy”)

Result 190, 8, 180



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.


324

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

Examples

In the following illustration, the ORI_ONE_AXIS function returns a body-fixed 313 Euler sequence:

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

Function ORI_ONE_AXIS({{10,16,0}, {8,16,0}}, "x")

Result 270, 90, 90




Function ORI_ONE_AXIS({{10,16,0}, {8,16,0}}, "z")

Result 180, 180, 0

Function ORI_ONE_AXIS({{10,16,0}, {8,16,0}}, "y")

Result 90, 0, 0


326



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

Example

In the following illustration, the ORI_ORI function returns an orientation, as specified:


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.

Function ORI_ORI({marker_1.orientation}, marker_1, marker_2)

Result 180, 90, 90


328

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

Examples

In the following illustration, the ORI_PLANE_MIRROR function returns a sequence of body-fixed 313 Euler rotations:

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.

Function ORI_PLANE_MIRROR({marker_1.orientation},{{18,6,0},{18,12,0},{21,6,0}}, "xy")

Result 0, 0, 0



Function ORI_PLANE_MIRROR ({marker_1.orientation}, {{18,6,0}, {18,12,0},{21,6,0}}, "yz")

Result 180, 180, 0


330


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.

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.


332

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

Example

The following example illustrates the use of the ORI_RELATIVE_TO function:

Body 313 Rotations Array of body-fixed 313 Euler rotations.

Frame Object Coordinate system object in which each sequence in angle is expressed.

Function ORI_RELATIVE_TO({marker_1.orientation}, marker_2)

Result 180, 90, 180


334

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

Example if cond=(OTABLE_CHANGED_CELLS(my_otable))

o_table Object table of interest.


PARAM_STRING

Returns a parameter's values as they appear in an Adams command file.

Format

PARAM_STRING (Object Field)

Argument

Examples




Object Field Character string denoting the name of an object followed by a field name (for example, mar1.orientation).

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"


336

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

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

fileName Name of the message file in which to search for status codes.

tag Character string indicating the status coes to extract.

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



PARZEN

Returns the 1xN array of values after applying the PARZEN window function.

Format

PARZEN (a)

Argument

Example

The following example illustrates the use of the PARZEN function:


a 1xN array of real numbers.

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

Result {0.333, 1.333, 3.0, 2.667, 0.667}


338

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

Example

The following is an example of the use of the PARZEN_WINDOW function:


n An integer value.

Function PARZEN_WINDOW(5)

Result {0.3333, 0.6667, 1.0000, 0.6667, 0.3333}


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

Example

The following example illustrates the use of the PHI function:

PHI(marker_O, marker_R)

See the illustration for PSI.


Object Coordinate system object whose rotation is being measured.

Reference Frame Coordinate system marker with respect wi which the rotation is being measured.


340

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

Examplevar set var=pick_obj obj=(eval(PICK_OBJECT("marker")))


obj_type String indicating the type of object to be selected.


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.

Format

PITCH (Object, Reference Frame)

Arguments

Example

The following example illustrates the use of the PITCH function:

PITCH(marker_O, marker_R)

See the illustration for YAW.


Note: Opposite from convention, this function calculates the negative of the second Body 321 angle.


Reference Frame Coordinate system object with respect to which the rotation is being measured.


342

POLYFIT

Returns the coefficients of a polynomial fitted to the supplied function data.

Format

POLYFIT (x, y, order)

Arguments

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]


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.


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

Examplevariable create variable=Yp real=(polyval({1,2,3},{5,7,9}))

produces a value for Yp of

{86.0, 162.0, 262.0}

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.


344

PROD

Returns the product of the elements of a matrix by performing a matrix reduction using multiplication.

Format

PROD (M)

Argument

Example

The following example illustrates the use of the PROD function:


M A matrix.

Function PROD({2, 3, 4})

Result 24


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

Example

The following example illustrates the use of the PSD function:


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.

Function PSD({0,1,4,9,16},7)

Result 144.0, 250.786, 167.080, 91.006, 51.367, 38.688, 17.016


346

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.


Format

PSI (Object, Reference Frame)

Arguments

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:


Reference Frame The coordinate system marker with respect to which the rotation is being measured.


348

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

Example

The following function, assigns the value X11 to MDI_AVIEW_WIN:


Environment Variable Character string denoting an environment variable.

Value Character string to be stored as the value of the environment variable.

Function (PUTENV("MDI_AVIEW_WIN","X11"))

Result 0


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.

Adams/View Function BuilderFunctions: R - S

350

Functions: R - S

RAND

Returns a pseudo-random value on the closed interval [0.0, 1.0], from a uniform distribution.

Format

RAND()

Argument

None

Examples

The following examples illustrate the use of the RAND function:


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.

Function RAND ()

Result 0.59893834

Function RAND ()

Result 0.28873462

351Design-Time FunctionsFunctions: R - S

Real LIFE (FlexBody [, Analysis])

Returns the minimum life of a flexible body for the specified analysis. Learn more about LIFE function.

Arguments

• FlexBody: Name of flexible body.


Returns

• Real value: Minimum life of body.


352

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


• Value: Flag for value of stress to use.

Returns

• Real value: Minimum life of body.


RECTANGULAR

Returns the 1xN array of values after applying the RECTANGULAR window function.

Format

rectangular (a)

Argument

Example

The following example illustrates the use of the RECTANGULAR function:


a An array.

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

Result {1.0, 2.0, 3.0, 4.0, 2.0}


354

RECTANGULAR_WINDOW

Generate the RECTANGULAR window.

Format

RECTANGULAR_WINDOW (n)

Argument

Example

The following example is an illustration of the RECTANGULAR_WINDOW function:


n An integer value.

Function RECTANGULAR_WINDOW (5)

Result {1, 1, 1, 1, 1}


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

Example

The following example illustrates the use of the REMOVE_FILE function:


File Name The file to be deleted.

Function REMOVE_FILE("Test_File.doc")

Result deletes Test_File.doc and returns a 0


356

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

Example

The following example illustrates the use of the RENAME_FILE function:


File Name Text string containing the current file name.

New File Name Text string containing the new file name.

Function RENAME_FILE("Test.mif.backup", "Test.doc")

Result renames the specified file as Test.doc and returns a 0


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

Example

The following example illustrates the use of the RESAMPLE function:


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.

Function RESAMPLE({[1, 2, 3, 4], [2, 3, 2, 1]}, "CUBIC", 200)

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


358

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

Examples

The following example illustrates the use of the RESHAPE function:

Because scalars are coerced into 1x1 matrices, you can also have the following:


M A matrix.

S A shape-descriptor array. Can contain up to two dimensions.

Function RESHAPE({1, 0, 0, 0}, {3, 3})

Result {[1, 0, 0], [0, 1, 0], [0, 0, 1]}

Function RESHAPE(1, {2, 2})

Result {[1, 1], [1, 1]}


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

Example

The following example illustrates the use of the REVERSE function:


array A one-dimensional array.

Function REVERSE({"hello", "world"})

Result {"world", "hello"}


360

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

Examples var set var=deldir int=(eval(RMDIR("/usr/people/foo")))


path Name of the directory to remove.


RMS

Returns the root mean square of the values.

Format

RMS (Values)

Argument

Example

The following example illustrates the use of the RMS function:


Values The array of values for which to compute the RMS function.

Function RMS({0,1,4,9,16})

Result (SQRT(MEAN({0,1,4,9,16}**2)))


362

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.


Format

ROLL (Object, Reference Frame)

Arguments

Example

The following example illustrates the use of the ROLL function:

ROLL(marker_O, marker_R)

See the illustration for YAW.





ROWS

Returns the number of rows in a matrix.

Format

ROWS (M)

Argument

Example

The following example illustrates the use of the ROWS function:


M A matrix.

Function ROWS({1, 2, 3})

Result 3


364

RTOI

Returns an integer representation of the input value, where the input value is a real number.

Format

RTOI(x)

Argument

Examples

The following examples illustrate the use of the RTOI function:



Function RTOI (.09)

Result 0

Function RTOI (7.7)

Result 7


SECURITY_CHECK

Returns a 1 or 0, depending on whether or not the product name is properly licensed.

Format

SECURITY_CHECK (ProductName)

Argument

Examples var set var=fea_is_licensed & int=(eval(security_check("FEA")))


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.


366

SELECT_DIRECTORY

Returns the name of the directory you selected from the directory browser.

Format

SELECT_DIRECTORY (Dir)

Argument

ExampleSELECT_DIRECTORY("/staff/guest/files")


DIR The directory to which to initialize the directory browser.


368

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

Example

The following example displays a select list allowing you to select a field from the list:

SELECT_FIELD(.model_1.part_1)


Object A database object used to determine the type of object for which you want to see the fields.


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

Example

The following function returns a list of command files from which you can make a selection:

SELECT_FILE("*.cmd", "/staff/user")


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.


370

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

Example

The following example illustrates the use of the SELECT_MULTI_TEXT function:

SELECT_MULTI_TEXT({"one", "2", "three", "we"})


Strings An array of strings to be displayed.


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

Example

The following example displays all parts in model_1 whose names start with lin:

SELECT_OBJECT(.model_1, "lin*", "part")


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.


372

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

Example

The following example displays all the parts in model_1 whose names start with lin:

SELECT_OBJECT(.model_1, "lin*", "part")


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.


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

Examplevariable set variable=myids int=(eval(SELECT_REQUEST_IDS("testuser.req")))


request_file_name String repesenting request file name.


374

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

Example

The following example illustrates the use of the SELECT_TEXT function:

SELECT_TEXT({"one", "yes", "maybe"})


Strings An array of strings to be displayed.


SELECT_TYPE

Returns a selection list of object types. Returns the selection as a string.

Format

SELECT_TYPE (Object Type)

Argument

Example

The following example displays a list of all constraint types, such as joint and primitive joint:

SELECT_TYPE("Constraint")


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.


376

SERIES

Generates an array based on a start value, an increment value, and an array length.

Format

SERIES (Real, Real, Integer)

Arguments

Example

The following example illustrates the use of the SERIES function:


Real Start value.

Real Increment value.

Integer Array length.

Function SERIES(1,2,3)

Result 1, 3, 5


SHAPE

Returns the dimensions of a matrix.

Format

SHAPE (M)

Argument

Example

The following example illustrates the use of the SHAPE function:


M A matrix.

Function SHAPE({1, 2, 3})

Result {3, 1}


378

SERIES2

Calculates an increment based on start and end values and a given number of increments.

Format

SERIES 2 (Real, Real, Integer)

Arguments

Example

The following example illustrates the use of the SERIES2 function:


Real Start value.

Real End value.

Integer Number of increments.


Result 2, 4, 6, 8


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

Format

SIGN(x1, x2)

Arguments

Example

The following examples illustrate the use of the SIGN function:


Note: SIGN is discontinuous. Use this function with care



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


380

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

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


fileName Name of the file in which to look for simulation status codes.


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


382

SIN

Returns the sine of an expression that represents a numerical value.

Format

SIN(x)

Argument

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


SINH

Returns the hyperbolic sine of an expression that represents a numerical value:

SINH(x) = (ex - e-x) / 2.0Format

SINH(x)

Argument

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


384

SORT

Returns a matrix sorted in the direction you specified.

Format

SORT (M, D)

Arguments

Example

The following example illustrates the use of the SORT function:


M A matrix.

D Direction in which the matrix is sorted:

• a = ascending

• d = descending

Function SORT({3,2,1},"a")

Result {1,2,3}


SORT_BY

Returns an array sorted by another array in the direction you specified.

Format

SORT_BY (M1, M2, D)

Arguments

Examples

The following examples illustrate the use of the SORT_BY function:


M1 MxN matrix by which an array is sorted.

M2 MxN matrix the function will return.


• a = ascending

• d = descending

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


386

SORT_INDEX

Returns the indexes of a matrix sorted in the direction you specified.

Format

SORT_INDEX (M, D)

Arguments

Example

The following example illustrates the use of the SORT_INDEX function:


M A matrix.


• a = ascending

• d = descending

Function SORT_INDEX({3,5,4,2},"a")

Result {4,1,3,2}


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

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.


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.

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


388

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

Example

The following example illustrates the use of the SQRT function:



Function SQRT(5*45)

Result 15


SSQ

Returns the sum of the squares of the elements of a matrix.

Format

SSQ (M)

Argument

Example

The following example illustrates the use of the SSQ function:


M A matrix.

Function SSQ({[1, 2], [3, 4]})

Result 30 (1**2 + 2**2 + 3**2 + 4**2)


390

STACK

Returns the concatenation of two matrixes with the same number of columns.

Format

STACK (M1, M2)

Arguments

Example

The following example illustrates the use of the STACK function:


M1 A matrix of arbitrary shape.

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

Function STACK({[1,2], [3,4]}, {[1,1], [2,2]})

Result {[1,2,1,1], [3,4,2,2]}


STATUS_PRINT

Returns a text string to all status bars.

Format

STATUS_PRINT (Status String)

Argument

Example

The following function displays the string in all window status bars, and returns its argument:


Status String Text string.

Function STATUS_PRINT("List")

Result List


392

STEP

Returns an array of y values, on a step curve, corresponding to the x values.

Format

STEP (A, xo, ho,x1,h1)

Arguments

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)


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.


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

Examples

The following example illustrates the use of the STOI function:


String A character string representation of a number.

Function STOI("1")

Result 1


394

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

Examples

The following example illustrates the use of the STOO function:

marker create marker=.model_1.ground.mar1variable create variable=.model_1.Index int=1variable create variable=obj &

obj=(STOO(".model_1.ground.mar"//.model_1.Index))list variable


String A character string representation of an object's name.


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

Example

The following example illustrates the use of the STOR function:


String A character string representation of a number.

Function STOR("12")

Result 12.0


396

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

Examples

The following functions return modified strings, as specified:


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

Function STR_CASE("this is a TEST!",1)

Result THIS IS A TEST!


Result this is a test!


Result This Is A Test!

Function: STR_CASE("this is a TEST!",4)

Result This is a test!


STR_CHR

Returns a character whose ASCII value is mapped to an input integer.

Format

STR_CHR (Integer Value)

Argument

Example

The following example returns the ASCII value of the letter A:


Integer Value ASCII value to be mapped.

Function STR_CHR(65)

Result A


398

STR_COMPARE

Returns a numeric value indicating the relative alphabetical ordering of two strings. Returns 0 if the two strings are the same. Returns a positive number if the second string comes before the first. Returns a negative number if the second string comes after the first.

Format

STR_COMPARE (String 1, String 2)

Arguments

Examples

The following function shows that the two strings are identical:

The following function returns a positive number (whatever the numerical characters are), indicating that the second string comes before the first string:

The following function returns a negative number (whatever the numerical characters are), indicating that the second string comes after the first string in ASCII character order:


String 1 Text string.

String 2 Text string.

Function STR_COMPARE("adjective","adjective")

Result 0

Function STR_COMPARE("verb","subject")

Result 3

Function STR_COMPARE("subject","verb")

Result -3


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) as a decimal number (00-99)

N

%d Day of month (01-31) Y

%D Date as %m/%d/%y N

%e Day of month (1-31: single digits are preceded by a blank space) N

%h Abbreviated month name N

%H Hour (00-23) Y

%I Hour (01-12) Y

%j Day number of year (001-366) Y

%m Month number (01-12) Y

%M Minute (00-59) Y

%p Equivalent of either AM or PM Y


400

Windows Only

If # flag is used as prefix to any formatting code, the meaning of the format changes as described below:

Examples

The following function returns the current date and time in the stated argument format (January 5, 1998, is the current date):

The following function returns the current date and time in the underlying argument format (January 5, 1998 is the current date):

%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

Format code Meaning

%#a, %#A, %#b, %#B, %#p, %#X, %#z, %#Z, %#%

# flag is ignored.

%#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, %#U, %#w, %#W, %#y, %#Y

Remove leading zeros (if any).

Function STR_DATE("%Y %m %d, %H:%M:%S")

Result 1998 01 05, 19:55:48

Function STR_DATE("%c")

Result Mon Jan 5 10:35:01 1998


The following function returns the current date and time in the default format (January 5, 1998 is the current date):

The following function simply returns the input string, if the specified directive is invalid/not supported:


Function STR_DATE("")

Result 05 Jan 1998 13:22

Function STR_DATE("ABC%D")

Result ABC%D


402

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

Examples

The following function deletes the ninth character in the string and returns the resulting phrase:

In the following function, the out-of-range negative value (-100) of the Starting Position becomes 1:

In the following function, the out of range positive value (100) of the Starting Position doesn't have any effect on the string:


Input String Text string.

Starting Position Integer value indicating the start location.

Number to Delete Integer value indicating the number of characters to delete.

Function STR_DELETE ("This is your life", 9, 1)

Result This is our life

Function STR_DELETE ("This is your life", -100, 10)

Result ur life

Function STR_DELETE ("This is your life", 100, 10)

Result returns the original string


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

Examples

The following examples illustrate the use of the STR_FIND function:

The following function uses a second character in its search criteria to return 4, because letter "l" appears twice in the word hello:


Base String Text string.

Search String Text string.

Function STR_FIND ("Hello", "l")

Result 3

Function STR_FIND ("Hello", "o")

Result 5

Function STR_FIND ("Hello", "lo")

Result 4


404

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)

Examples

The following examples illustrate the use of the STR_FIND_COUNT function:

The following function returns 2 because the overlapping, matching 9's from 239990 to 129990 are not included:




Function STR_FIND_COUNT("hammer stammer", "mm")

Result 2

Function STR_FIND_COUNT("hellllo jello", "ll")

Result 3

Function STR_FIND_COUNT("239990 129990", "99")

Result 2


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

Exampleif cond=(STR_FIND_IN_STRINGS(unit_names, "force"))


array_of_strings The array of strings to search.

string The string to search for.


406

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

Examples

The following function returns 10 because the second occurrence of string an begins at character position 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:




Nth Occurance Integer value indicating the number of string occurrences to be found.

Function STR_FIND_N("meant human", "an", 2)

Result 10

Function STR_FIND_N("43### 55###9 22##5", "##", 3)

Result 16


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

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:

As with the STR_DELETE function, Insert Position can have any value, as shown in the following example:


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.

Function STR_INSERT ("That'sfolks", " all ", 7)

Result That's all folks

Function STR_INSERT ("A", "B", -10)

Result BA


408

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

Examples

The following examples illustrate the use of the STR_IS_REAL function:

if condition=(str_is_real ("Hi, Mom.")) ! returnsfalse

if condition=(str_is_real ($field_1_value))


String Represents a real number.


STR_IS_SPACE

Returns 1 (true) if a string is empty; otherwise, returns 0 (false).

Format

STR_IS_SPACE (Input String)

Argument

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


410

STR_LENGTH

Returns a numerical value corresponding to the length of a string.

Format

STR_LENGTH (Input String)

Argument

Examples

The following example illustrates the use of the STR_LENGTH function:

The following function returns 10 because the double slash marks (//) concatenated the two strings into one:


Input String Text String.

Function STR_LENGTH ("Hello there")

Result 11

Function STR_LENGTH ("Hello" // "there")

Result 10


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.



412

Examples

The following functions return 1 or 0, depending on whether a match occurred or not:


Function STR_MATCH("f?d","fad")

Result 1

Function STR_MATCH("f[xyz]d","fxd")

Result 1

Function STR_MATCH("f{ab,bc,cd}d","fbcx")

Result 0

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

Result 1


STR_PRINT

Writes a string into the aview.log file. It is very useful for debugging.

Format

STR_PRINT (String)

Argument

Examples

In the following functions, the double slash marks (//) allow two or more strings to be concatenated into a single string:


String Text 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


414

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

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


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

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:


Input Text String Text string. This string is unaltered during the evaluation of the function.

Separator Character Specified character that separates the substrings.

Function STR_SPLIT(" apple; orange; grape ", ";")

Result apple, orange, grape

Function STR_SPLIT(" apple; # orange# grape ", "#")

Result apple;, orange, grape


416

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

Example

The following example illustrates the use of the STR_SPRINTF function:


Format String A C language format string.

Array of Values Array of values used to satisfy the format elements in the format string.

Function STR_SPRINTF("The %s of %s is %03d%%.", {"value", "angle", 2})

Result The value of the angle is 002%


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

Examples

The following function returns a substring of the input string:

The following example shows that the Starting Position and Length arguments can have any value and not cause errors:



Starting Position Integer value that determines the starting point of the substring.

Length Integer value that designates the number of characters in the substring.

Function STR_SUBSTR ("This is one string", 9, 8)

Result one stri

Function STR_SUBSTR ("This is a string", -1000, 100)

Result returns the original string, since the values are out of range


418

STR_TIMESTAMP

Returns the current date and time in the default format.

Format

STR_TIMESTAMP ()

Argument

Example

The following function returns the current date and time (Jan 5, 1998, is the current date):


None No argument is needed; this function returns the current date in the following format:

%Y/%m/%d,%H:%M:%S

Function STR_TIMESTAMP()

Result 1998/01/05,02:30:28


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

Example

The following example illustrates the use of the STR_XLATE function:



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.

Function STR_XLATE ("Why/-are/-you/-here/-?", "/-", ">_")

Result Why>_are>_you>_here>_?


420

SUM

Returns the sum of the elements of a matrix by performing a matrix reduction using addition.

Format

SUM (M)

Argument

Examples

The following examples illustrate the use of the SUM function:


M A matrix.

Function SUM({[1, 2], [3, 4]})

Result 10

Function M = {[1, 2], [3, 4]}): {SUM(M[1]), SUM(M[2])}

Result {3, 7}


SYS_INFO

Returns a character string containing information that you requested about the system.

Format

SYS_INFO (info_type)

Argument

Example variable create variable=HostName str=(sys_info("hostname"))

Returns a value of the host machine, for example, SERV1.


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.

Adams/View Function BuilderFunctions: T - Z

422

Functions: T - Z

423Design-Time FunctionsFunctions: T - Z

TABLE_COLUMN_SELECTED_CELLS

Returns an array of integers representing the 1-based row numbers of selected cells within a specified column in a table. If no cells are selected in the column, returns a 0.

Format

TABLE_COLUMN_SELECTED_CELLS (Column, O_table, Dummy1, Dummy2, Dummy3)

Arguments

Example

The variable the_selected_cells will contain the row numbers (1-based) for all the cells that you select in column 1:


Column Column number (1-based).

O_table Data/object table of interest.

Dummy1,2,3 Not currently used.


424

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

Example

The following function gets the contents of the cells of the first two rows of the first two columns:



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.


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

Examples

The following example returns the number of rows in a table:

The following example returns the number of columns in a table:



Rows_or_cols String "rows" or "cols" to indicate desired dimension.


426

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.


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

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.


table A valid Data table object.

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


428

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

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.


table A valid Data table object.

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


TAN

Returns the tangent of an expression that represents a numerical value.

Format

TAN(x)

Argument

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


430

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

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


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

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.


fileName Name of the file in which to look for simulation status codes.


432

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.


Format

THETA (Object, Reference Frame)

Arguments

Example

The following example illustrates the use of the THETA function:

THETA(marker_O, marker_R)See the illustration for PSI.





TILDE

Returns the TILDE function of an array. You can use TILDE only on 3x1 matrixes.

Format

TILDE (A)

Argument

Example

The following example illustrates the use of the TILDE function:


A An array.

Function TILDE({x, y, z})

Result {[ 0, -z, y], [z, 0, -x], [-y, x, 0]}


434

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.

Format

TIMER_CPU(endFlag) returns REAL

Argument

Example variable set variable=mycpu real=(eval(timer_cpu(0)))file command read file=mybidcmdfilevariable set variable=mycpu=real=(eval(timer_cpu(0)))variable set var=foo string=(eval(str_print("file read took " //mycpu//"cpuseconds")))


Note: The time is returned in seconds.

startFlag If the endFlag is 0, then the timer is started and the current elapsed CPU is returned.

If the endFlag is 1, then the timer is stopped and the elapsed CUP time since the last timer started is returned.


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.

Format

TIMER_ELAPSED (endFlag) returns REAL

Arguments

Example variable set variable=myelapse real=(eval(timer_elapsed(0)))file command read file=mybigcmdfilevar set var=foo string=(eval(str_print("file read took"//myelapse//"seconds")))


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.

startFlag If the endFlag is 0, then the timer is started and the current elapsed CPU is returned.

If the endFlag is 1, then the timer is stopped and the elapsed CUP time since the last timer started is returned.


436

TMAT3

Returns a 3x3 transformation matrix using the values in the orientation sequence you specify.

Format

TMAT3 (E, OriType, OriSequence)

Arguments

Example

A typical invocation of this function might look like this:

TMAT3(mar1.orientation, "s" 123)


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.


TMAT

Returns a 3x3 transformation matrix using the values in the orientation sequence you specified.

Format

TMAT (E, OriType)

Arguments

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


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.


438

TRANSPOSE

Returns the transpose of a matrix.

Format

TRANSPOSE (M)

Argument

Examples

The following examples illustrate the use of the TRANSPOSE function:


M A matrix.

Function TRANSPOSE({1,2,3}

Result {[1,2,3]}

Function TRANSPOSE({[1,2],[3,4]})

Result {[1,3],[2,4]}


TRIANGULAR

Apply the TRIANGULAR window to the input array and return the new array.

Format

TRIANGULAR (a)

Argument

Example

The following example is an illustration of the TRIANGULAR function:


a An array.

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

Result {0.3333 1.3333 3.0000 2.6667 0.6667}


440

TRIANGULAR_WINDOW

Generate the TRIANGULAR window.

Format

TRIANGULAR_WINDOW (n)

Argument

Example

The following example is an illustration of the TRIANGULAR_WINDOW function:


n An integer.

Function triangular_window (5)

Result {0.3333 0.6667 1.0000 0.6667 0.3333}


UNIQUE

Deletes all duplicate elements from an array.

Format

UNIQUE (Array)

Argument

Example

The following example illustrates the use of the UNIQUE function:


Array An array.

Function UNIQUE ({9, 1, 1})

Result 1.0, 9.0


442

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

Example

The following example illustrates the use of the UNIQUE_FILE_NAME function:

Learn more about datatbase functions.

Initial File Name Prefix to use when creating the unique name.

Function UNIQUE_FILE_NAME("test")

Result test_1


UNIQUE_ID

Returns an Adams_ID unique for objects of the specified type.

Format

UNIQUE_ID (char * type)

Argument

Example var cre var=dv1 int=(eval(UNIQUE_ID("marker")))


type Text string representing an entity type.


444

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

Example

The following example illustrates the use of the UNIQUE_FULL_NAME function:


Type Text string that represents an entity type.

Function UNIQUE_FULL_NAME("marker")

Result .model_1.ground.MAR


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

Examples

The following illustrates the UNIQUE_LOCAL_NAME function:


Parent The object defining the search domain for children.

Base A character string specifying the prefix part of the name to be produced.

Function UNIQUE_LOCAL_NAME(.model_1, "PAR")

Result Returns PAR_2 if PAR_1 already exists.


446

UNIQUE_NAME

Returns a text string that is a unique database name.

Format

UNIQUE_NAME (Base Name)

Argument

Example

The following example illustrates the use of the UNIQUE_NAME function:


Base Name Starting point for a unique database name.

Function UNIQUE_NAME("stat")

Result stat_1


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

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.


Base Name Starting point for a unique database name.

Function UNIQUE_NAME_IN_HIERARCHY("stat")

Result stat_2


448

UNIQUE_PARTIAL_NAME

Returns a character string containing a unique object name.

Format

UNIQUE_PARTIAL_NAME (Parent, Type)

Arguments

Example

The following example produces PAR_1:

UNIQUE_PARTIAL_NAME(.model_1, "part")


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.


UNITS_STRING

Returns a text string containing a unit string associated with another string.

Format

UNITS_STRING (Object Field)

Argument

Example

The following example illustrates the use of the UNITS_STRING function:


Object Field Character string that names the field of an object.

Function UNITS_STRING(".mod1.part1.density")

Result returns something like kg/mm**3


450

UNITS_CONVERSION_FACTOR

Returns the numeric conversion factor from the given unit value to the current default units.

Format

UNITS_CONVERSION_FACTOR (UnitsValue)

Argument

Examples

The following illustrates the use of the UNITS_CONVERSION_FACTOR function:


UnitsValue A units value string defining the units from which you want to convert.

Function UNITS_CONVERSION_FACTOR("inch")

Result Returns 12.0 if the default length units are set to foot.


UNITS_TYPE

Returns the character string value of the given unit type using the provided integer value.

Format

UNITS_TYPE (UnitsType)

Arguments

Examples

The following is an illustration of the UNITS_TYPE function:


Units An encoded units value.

Function var cre var=x rea=1 units="mass/time**3"

UNITS_TYPE(x.units)

Result Returns mass/time**3


452

UNITS_VALUE

Returns the character string value of the given unit type using the default units settings.

Format

UNITS_VALUE (UnitsType)

Argument

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


Units A units type string, such as angle or length/time**2.

Function UNITS_VALUE("angle")

Result Returns degrees

Function UNITS_VALUE("acceleration*time")

Result Returns foot/second


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.


454

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

Example

The following example illustrates the use of the USER_STRING function:

USER_STRING(".mod1.mar1.location")


Object Field Character string containing an object name and field reference.


VAL

Returns an array element nearest the number you specified.

Format

VAL (A, X)

Arguments

Example

The following example illustrates the use of the VAL function:


A An array.

X A real number.

Function VAL({2,0,3}, 2.2)

Result 2


456

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.

Format

VALAT(X_array, Y_array, X_value)

Arguments

Examples model create model=mod1variable create variable=x_array rea=-1,0,2,3variable create variable=y_array rea= 1,2,3,4variable create variable=xx rea=0.0variable create variable=yy rea=(VALAT(x_array, y_array, xx))

VALAT produces values as follows:


Note: This function expects the values in X_array to be sorted in ascending order.

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.

xx -2, -1, 0, 1, 2, 3, 4

yy 0, 1, 2, 2.5, 3, 4, 5


VALI

Returns the index of the element in an array nearest to the number you specify.

Format

VALI (A, X)

Arguments

Example

The following example illustrates the use of the VALI function:


A An array.

X A real number.

Function VALI({2,0,3}, 2.2)

Result 1


458

WELCH

Returns a 1xN array of values after applying the WELCH_WINDOW function.

Format

WELCH (a)

Argument

Example

The following example illustrates the use of the WELCH function:


a A 1xN array of real numbers.

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

Result {0.556, 1.778, 3.0, 3.556, 1.111}


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

Example

The following example is an illustration of the WELCH_WINDOW function:


n An integer.

Function welch_window (5)

Result {0.5556, 0.8889, 1.0000, 0.8889, 0.5556}


460

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.


Format

YAW (Object, Reference Frame)

Arguments

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:




In Adams, PITCH is defined as the negative value of the second Body 321 rotation angle.


462

There are always two equivalent sets of rotation angles that yield the same final rotation.


461Run-Time Functions

Run-Time Functions

Adams/View Function BuilderAbout Run-Time Functions

462

About Run-Time FunctionsRun-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.

Learn more about:

• Run-Time Functions Categories

• Run-Time Functions Examples

Run-Time Functions CategoriesThis section introduces you to the run-time functions categories as they appear in the Function Builder. For more details regarding each function, please see Run-Time Functions Examples.

Note that although some run-time functions have the same names as certain design-time functions, they only work with a model at an analysis-time step.

The following sections give you an overview of the run-time functions categories. The functions categories are presented in the order they appear in the Function Builder.

• Displacement Functions

• Velocity Functions

• Acceleration Functions

• Contact Functions

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.

463Run-Time FunctionsAbout Run-Time Functions

• Spline Functions

• Force in Object Functions

• Resultant Force Functions

• Math Functions

• Data Element Access

• User-Written Subroutine Invocation

• Constants & Variables


Displacement functions 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:


Distance Along X (DX) An x component of the translational displacement vector from one coordinate system marker to another.

Distance Along Y (DY) A y component of the translational displacement vector from one coordinate system marker to another.

Distance Along Z (DZ) A z component of the translational displacement vector from one coordinate system marker to another.

Distance Magnitude (DM) The magnitude of the translational displacement vector from one coordinate system marker to another.

Angle About X (AX) The rotational displacement (in radians) of one coordinate system marker about the x-axis of another.

Angle About Y (AY) The rotational displacement (in radians) of one coordinate system marker about the y-axis of another.

Angle About Z (AZ) The rotational displacement (in radians) of one coordinate system marker about the z-axis of another.


464

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:

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.

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.




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:

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.

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.

Function: Returns:

·


466

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:

Spline Functions

Splining is a method of interpolation that allows derivation of intermediate locations on a curve or surface between known points.

You can use spline functions during a simulation to define smooth functions to approximately fit data points. Spline functions can be useful when:

• Driving a motion with test data.

• Defining a force with test data.

• Plotting smooth curves through data points.

The following sections provide more information about splines:

• Interpolation Methods Overview

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.

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.

Function: Returns:


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

Comparison of Interpolation Methods

The Akima interpolation is a local fit. Local methods require information only about points in the vicinity of the interval being interpolated to define the coefficients of the cubic polynomial. This means that each data point in an Akima spline only affects the nearby portion of the curve. Since it uses local methods, Akima is very fast.

Akima always produces good results for the value of the function being approximated. AKISPL returns good estimates for the first derivative of the approximated function when the data points are evenly spaced. In instances where the data points are unevenly spaced, the estimate of the first derivative may be in error. In all cases, the second derivative of the function being approximated is unreliable.

The cubic interpolation is a global fit. Global methods use all the given points to calculate all the coefficients for all the intervals in question, simultaneously. Therefore, each data point affects the entire cubic spline: if you move one point the whole curve changes accordingly, making a cubic spline wigglier and harder to force into a desired shape. This is especially noticeable on functions with linear portions or sharp changes in the curve. In these cases, a cubic spline will almost always have more wiggles than an Akima spline.

Both global and local methods work well on smoothly-curving functions.

CUBSPL, though not as fast as AKISPL, always produces good results for the value of the function being approximated, as well as its first and second derivatives. The data points don't have to be evenly spaced. The solution process often requires estimates of derivatives of the functions being defined. The smoother a derivative is, the easier it is for the solution process to converge.

Interpolation methods:

Fit characteristic:

Function name: Advantages: Disadvantages:

Cubic spline Global CUBSPL • Accurate derivatives

• Curve

• Surface

• Not as fast

• Some waviness

B-spline Global CURVE • Accurate derivatives

• Can be user-defined with CURSUB

Curve only (no surface)

Akima Local AKISPL • Fast

• Curve

• Surface

Inaccurate derivatives


468

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:


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.

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.


• Monitoring force magnitudes and triggering the occurrence of special events when these forces reach certain values.

Constraint Characteristics

Most constraints have the following characteristics:

• Connect two bodies, referred to as the first body and second body or the action and reaction body respectively.

• Are applied at two distinct points, though sometimes coincident.

• Depend on coordinate system axes to define constraint direction.

• Apply whatever forces are required to prevent movement in certain directions.

• Do not require the user to define the magnitudes of the forces they apply since Adams automatically calculates force magnitudes.

Force Characteristics

Most forces have the following characteristics:

• Are applied to two bodies, referred to as the first body and second body.

• Are applied at two distinct points, though sometimes coincident.

• Depend on coordinate system axes to define force application.

• Require the user to define the magnitudes of the forces they apply.

In Adams, you can define force magnitudes in two ways:

1. With linear spring-damper-like elements that use predefined equations that automatically depend only on displacement and velocity directly; for these forces you can simply input stiffness and damping coefficients.

2. With multiple-component, general-equation force elements that have no predefined equations. These allow you to create your own force magnitude equations with no restrictions on the dependencies.

When you define your own equations for force magnitudes, you have to tell Adams what the force depends on. For instance, a force could depend on the displacement between two coordinate system markers or their relative velocity or acceleration, or the force applied to a coordinate system marker by a constraint or force element.To help you define these dependencies, Adams offers you displacement functions (Displacement Functions), velocity functions (Velocity Functions), acceleration functions (Acceleration Functions), resultant force functions (Resultant Force Functions), as well as force in object functions.

Whenever you use the force in object functions, you must tell Adams how you want the force to be measured. You must specify:

• Which force-applying object you want to measure. For example: joint_4, motion_6, sforce_3, gforce_19, and so on.

• On which body you want to take the measurement, the first body or the second body.


470

• Which force vector component you want to obtain.

Using a Force in Object Function

In this example we'll calculate the force acting on a block located on an incline, as illustrated in body 1. Before working through this example, reference Six-component Force/Torque (GFORCE).

This example consists of a system defined as follows:

• A translational joint (JOINT_1) connects a block and an incline by way of coordinate system markers named block.marker_14 and incline.marker_15.

• A fixed joint (JOINT_2) connects the incline to ground by way of incline.marker_32 and ground.marker_33.

• A general-equation, multiple-component force, named GForce_7 is applied to the block, normal to the surface of the incline.

• The GForce_7 is applied to block.marker_28 and ground.marker_29, so that the block is the action body and ground is the reaction body.

• There is no gravity.

In this example, GFORCE is defined as: .

The GFORCE yields different results, as we change the arguments used:

F 30y28 40 z28+=


GFORCE(GForce_7, 0, 2, block.marker_28) = 0GFORCE(GForce_7, 0, 3, block.marker_28) = 30GFORCE(GForce_7, 0, 4, block.marker_28) = 40GFORCE(GForce_7, 0, 1, block.marker_14) = 50GFORCE(GForce_7, 0, 2, block.marker_14) = - 40GFORCE(GForce_7, 0, 3, block.marker_14) = 0GFORCE(GForce_7, 0, 4, block.marker_14) = - 30GFORCE(GForce_7, 1, 1, block.marker_28) = 50GFORCE(GForce_7, 1, 2, block.marker_28) = 0GFORCE(GForce_7, 1, 3, block.marker_28) = - 30GFORCE(GForce_7, 1, 4, block.marker_28) = - 40

Where to Find the Force in Object Functions

The following table lists the names and definitions for the force in object functions:

Function: Returns:

Joint Force (JOINT) A force or torque induced by a specified joint on one of the two bodies connected by the joint object.

Motion Force (MOTION) A force or torque component induced by a specified motion on one of the two bodies affected by the motion object.

Point-to-Curve Force (PTCV) A force or torque induced by a specified point-to-curve object on one of the two bodies connected by the point-to-curve object.

Curve-to-Curve Force (CVCV) A force or torque induced by a specified curve-to-curve object on one of the two bodies connected by the curve-to-curve object.

Joint Primitive Force (JPRIM) A force or torque induced by a specified joint primitive on one of the two bodies connected by the joint primitive.

Single-component Force (SFORCE) A force or torque applied by a specified single-component force on one or two bodies directly affected by the single-component force.

Three-component Force (VFORCE) A force or torque applied by a specified three-component force on one or two bodies directly affected by the three-component force.


472


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:

Three-component Torque (VTORQ) A force or torque applied by a specified three-component torque on one or two bodies directly affected by the three-component torque.

Six-component Force/Torque (GFORCE) A force or torque applied by a specified six-component force/torque on one or two bodies directly affected by the six-component force / torque.

Multipoint Force (NFORCE) A force or torque applied by a specified multipoint force on one or two bodies directly affected by the multipoint force.

Beam Force (BEAM) A force or torque applied by a specified beam force on one or two bodies directly affected by the beam force.

Bushing Force (BUSH) A force or torque applied by a specified bushing force on one or two bodies directly affected by the bushing force.

Field Force (FIELD) A force or torque applied by a specified field force on one or two bodies directly affected by the field force.

Spring-Damper Force (SPDP) A force or torque applied by a specified spring-damper force on one or two bodies affected by the spring-damper force.

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.

Function: Returns:


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:

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.

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.

Function: Returns:


474

ATAN2 Returns the arc tangent of two expressions each representing a numerical value.

Chebyshev Polynomial (CHEBY) Evaluates a Chebyshev polynomial at a user-specified numerical value.

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

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

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

EXP Returns the value ex, where x is any expression that represents a numerical value.

Fourier Cosine Series (FORCOS) Evaluates a Fourier Cosine series at a user-specified value x.

Fourier Sine Series (FORSIN) Evaluates a Fourier Sine series at a user-specified value x.

Haversine Step (HAVSIN) Defines a haversine function. HAVSIN is most often used to represent a smooth transition between two functions.

Inverse Power Spectral Density (INVPSD) Regenerates a time signal from a power spectral density description.

LOG Returns the natural logarithm of an expression that represents a numerical value.

LOG10 Returns log to base 10 of an expression that represents a numerical value.

MAX Returns the maximum of two expressions that represent numerical values.

MIN Returns the minimum of two expressions that represent numerical values.

MOD Returns the remainder when one expression representing a numerical value is divided by another expression that represents a numerical value.

Polynomial (POLY) Evaluates a standard polynomial at a user-specified value x.

SIGN Transfers the sign of one expression representing a numerical value to the magnitude of another expression representing a numerical value.



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:

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.

Function: Returns:

Algebraic Variable Value (VARVAL) The current value of the variable defined by the specified state variable modeling entity.

Array Element Value (ARYVAL) The value of the specified element of the specified array modeling entity.

Differential Variable Integrated Value (DIF) The integrated value of the variable defined by the specified differential equation modeling entity.

Differential Variable Value (DIF1) The value of the variable defined by the specified differential equation modeling entity.

Plant Input Value (PINVAL) The run-time value of a plant input.

Plant Output Value (POUVAL) The run-time value of a plant output.



476


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.


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:

Run-Time Functions DescriptionsFor 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.


USER Passes one or more values that are used as parameters in a user-written subroutine.

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.


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

Adams/View Function BuilderFunctions: A - M

478

Functions: A - M

479Run-Time FunctionsFunctions: A - M

ABS

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

Format

ABS (x)

Argument

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




480

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

Equation

Mathematically, ACCX is calculated as follows:

where:

• is the position vector from the global origin to the To Marker, T.

• is the second time-derivative of with respect to the Reference Frame, R.

• is the position vector from the global origin to the From Marker, F.


• is the unit vector along the x-axis of the Along Marker, A.

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.

ACCXt2

2

dd

R RT

t2

2

dd

R RF– xA=

RT

t2

2

d

dR

RT RT

RF

t2

2

d

dR

RF RF

xA


Example

The following function returns the x component of the acceleration vector of marker_T with respect to marker_F. The vector is expressed in the coordinate system of marker_A. All time-derivatives are taken in the ground reference frame, since the Reference Frame, R, is not specified.

ACCX(marker_T, marker_F, marker_A)

Learn more about acceleration functions.


482

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

Equation

Mathematically, ACCY is calculated as follows:

where:





• is the unit vector along the y-axis of the Along Marker, A.



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.


ACCYt2

2

dd

R RT

t2

2

dd

R RF– yA=

RT

t2

2

d

dR

RT RT

RF

t2

2

d

dR

RF RF

yA


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)



484

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

Equation

Mathematically, ACCZ is calculated as follows:

where:





• is the unit vector along the z-axis of the Along Marker, A.



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.


ACCZt2

2

dd

R RT

t2

2

dd

R RF– zA=

RT

t2

2

d

dR

RT RT

RF

t2

2

d

dR

RF RF

zA


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)



486

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

Equation

Mathematically, ACCM is calculated as follows:

where:





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.


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.


ACCMt2

2

dd

R RT

t2

2

dd

R RF–

t2

2

dd

R RT

t2

2

dd

R RF–

=

RT

t2

2

d

dR

RT RT

RF

t2

2

d

dR

RF RF


ACCM(marker_T, marker_F, marker_R)



488

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)< 1AINT(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.

Format

AINT (x)

Argument

Examples

The following functions show how AINT truncates results towards 0:


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.


Function AINT(0.85)

Result 0

Function AINT(-0.5)

Result 0

Function AINT(4.6)

Result 4

Function AINT(-6.8)

Result -6


ACOS

Returns the arc cosine of an expression that represents a numerical value. The evaluated expression must

return a value whose absolute value . The value returned by ACOS lies in the range [0, ], that

is, 0 < ACOS(x) < .

Format

ACOS (x)

Argument

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


X Any valid expression that evaluates to a real number.

is 1


490

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

Example

The following example illustrates the use of the VARVAL function:

VARVAL(variable_37)

Learn more about data element access.

Algebraic Variable Name Name of an existing state variable modeling entity; defined by an object name.


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

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)

First Independent Variable

(Required) Real variable that represents the first independent variable in the spline.

Second Independent Varialble

(Optional) Real variable that represents the second independent variable in the spline.

Spline Name (Required) The name of the existing data element spline modeling entity that defines the set of discrete data points to be used for the interpolation.

Derivative Order (Optional) The order of the derivative to be taken at the interpolated point (integer).

The legal values are:

• 0 - returns the curve coordinate value

• 1 - returns the first derivative

• 2 - returns the second derivative

Note: Derivative Order may not be specified when interpolating on a surface; that is, when the Second Independent Variable = 0.

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

-4.0 -3.6

-3.0 -2.5


492

Spline Defined Based on Tabular Data

Learn more about spline functions.

-2.0 -1.2

-1.0 -0.4

0.0 0.0

1 0.4

2 1.2

3 2.5

4 3.6

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


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

Equation

Mathematically, AX is calculated as follows:

where:

• is the y-axis of the To Marker, T.

• is the y-axis of the From Marker, 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:

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.

Function AX(marker_T, marker_F)

Result 0.5235 or /6

AX 2 yT zF yT yF atan=

yT

yF

zF


494

Learn more about displacement functions.


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

Equation

Mathematically, AY is calculated as follows:

where:

• is the z-axis of To Marker.

• is the z-axis of From Marker.

• is the x-axis of From Marker.

Example

The following function returns the angle between the x-axes of marker_T and marker_F:


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.

Function AY(marker_T, marker_F)

Result 0.5235 or /6

AY 2 zT xF zT zF atan=

zT

zF

xF


496



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

Equation

Mathematically, AZ is calculated as follows:

where:

• is the x-axis of To Marker.

• is the x-axis of From Marker.

• 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

AZ 2 xT yF xT xF atan=

xT

xF

yF


498



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

Equation

Mathematically, WDTX is calculated as follows:

where:

• is the angular velocity vector of the To Marker, T, with respect to the ground reference

frame.

• is the time-derivative of with respect to the Reference Frame, R.

• is the angular velocity vector of the From Marker, F, with respect to the ground reference

frame.


• is the unit vector along the x-axis of the About Marker, A.

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.


WDTXtd

dR T td

dR F– xA=

T

tddR T T

F

tddR F F

xA


500

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)



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

Equation

Mathematically, WDTY is calculated as follows:

where:


frame.



frame.


• is the unit vector along the y-axis of the About Marker, A.





WDTYtd

dR T td

dR F– yA=

T

tddR T T

F

tddR F F

yA


502

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)



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

Equation

Mathematically, WDTZ is calculated as follows:

where:


frame.



frame.


• is the unit vector along the z-axis of the About Marker, A.





WDTZtd

dR T td

dR F– zA=

T

tddR T T

F

tddR F F

zA


504

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)



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

Equation

Mathematically, WDTM is calculated as follows:

where:


frame.



frame.





WDTMtd

dR T td

dR F–

td

dR T td

dR F–

=

T

tddR T T

F

tddR F F


506

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)



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

Equation

Mathematically, WX is calculated as follows:

where:


frame, G.


frame, G.

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

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.

WX G

T G

F– xA=

G

T

G

F

xA


508

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

Equation

Mathematically, WY is calculated as follows:

where:


frame, G.


frame, G.

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




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.

WY G

T G

F– yA=

G

T

G

F

yA


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

Equation

Mathematically, WZ is calculated as follows:

where:


frame, G.


frame, G.

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




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.

WZ G

T G

F– zA=

G

T

G

F

yA


510

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

Equation

Mathematically, WM is calculated as follows:

where:


frame, G.


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)



From Marker (Optional) The coordinate system marker whose angular velocity is subtracted off. If not specified, this argument defaults to the global coordinate system.

WM G

T G

F– G

T G

F– =

G

T

G

F


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 > 0ANINT(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

Examples

The following functions show how ANINT rounds the results to the nearest integer:




Result -1

Function ANINT(0.33)

Result 0


Result -5

Function AINT(4.6)

Result 5


512

Array Element Value (ARYVAL)

Returns the value of the specified element of the specified array modeling entity.

Format

ARYVAL(Array Name, Element Number)

Arguments

Example

The following example illustrates the use of the ARYVAL function:

ARYVAL(array_45,3)


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.


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 (that is,

).

Format

ASIN(x)

Argument

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


2 2–

2 x 2 asin–


514

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

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




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 > 0ATAN2(x1, x2) = 0 if x1 = 0, x2 > 0ATAN2(x1, x2) = if x1 = 0, x2 < 0ATAN2(x1, x2) < 0 if x1 < 0ABS(ATAN2(x1, x2))= if x2 = 0ATAN2(x1, x2) undefined if x1 = 0, and x2 = 0

Format

ATAN2(x1, x2)

Arguments

Example

The following function shows arc tangent (in radians) of the expression a/b where a is the x component of the distance between marker_2 and marker_3 and b is the y component of the distance between marker_2 and marker_3:

ATAN2(DX(marker_2, marker_3), DY(marker_2, marker_3))





516

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

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)


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.





Direction Direction in which you want the curve evaluated.


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


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.


Format

PSI (To Marker, From Marker)

Arguments

Example

The following example returns all the angles of rotation associated with a body-fixed 313 rotation sequence:




518


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


520

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.


Format

PHI (To Marker, From Marker)

Arguments

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





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.


Format

THETA (To Marker, From Marker)

Arguments

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





522

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.


Format

YAW (To Marker, From Marker)

Arguments

Example

The following example returns all the angles of rotation associated with a body-fixed 321 rotation sequence:




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

Learn more about displacement functions


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

Format

PITCH (To Marker, From Marker)

Arguments

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


Note: Opposite from convention, this function calculates the negative of the second body-fixed 321 angle.




526

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.


Format

ROLL (To Marker, From Marker)

Arguments

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





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.


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


• Fm = 1 = force magnitude

• Fx = 2 = x component of the force

• Fy = 3 = y component of the force

• Fz = 4 = z component of the force

• Tm = 5 = torque magnitude

• Tx = 6 = x component of the torque

• Ty = 7 = y component of the torque

• Tz = 8 = z component of the torque

Along/About Axes (Optional) Coordinate system marker in which the results are measured.

To have your results measured in the global coordinate system, do one of the following:

• If you're entering your function through the Assist dialog box, leave the Along/About Axes text box empty.

• If you're entering your function directly in the function text box, enter a 0.


528

Example

The following function returns the z component of the force vector acting on the first body (at the I marker) of .model_2.beam_1, measured along the z-axis of the global coordinate system:

BEAM(.model_2.beam_1, 0, 4, 0)

Learn more about force in object functions.


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.




















530

Example

The following function returns the y component of the torque vector acting on the first body (at the I marker) of .model_2.bushing_1, measured along the y-axis of the global coordinate system:

BUSH(.model_2.bushing_1, 0, 7, 0)



Chebyshev Polynomial (CHEBY)

Evaluates a Chebyshev polynomial at a user-specified numerical value.

Format

CHEBY (x, Shift, Coefficients)

Arguments

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


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.


532

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

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

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.


This REQUEST statement outputs the x-, y- and z-components of the force and torque at the I marker of CONTACT/11. Since rm is specified as zero, all vectors are expressed in the global coordinate system.


534

COS

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

Format

COS (x)

Argument

Example

The following function returns the cosine of 2* *TIME, where TIME is the current simulation time:

COS(2* *TIME)




COSH

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

COSH(x) = (ex + e-x)/2.0

Format

COSH(x)

Argument

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




536

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

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:

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





Note: Derivative Order may not be specified when interpolating on a surface; that is, when the Second Independent

Variable 0.


Motion = CUBSPL(TIME, 0, spline_1)

Spline Defined Based on Tabular Data


Independent variable (Time) Dependent variable (Displacement)

0 100

1 125

2 130

3 80

4 40

5 20


538

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.

Format

CVCV (Curve-to-curve Name, On This Body, Force Component, Along/About Axes)

Arguments

Note: CVCV can only be used for output purposes. Therefore, it can be used only with output request and sensor objects.

Curve-to-curve Name (Required) Curve-to-curve for which the force is measured.






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)

















540

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

The equations:

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

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

x'1 t 5x2 t – =

x'2 t 3x1 t x2 t – =

x1 3x2– 0=

x2 t 0.95= t 0


VARIABLE/1, FU=DELAY(DIF(2), DIF(1)-3*DIF(2), 0.95)DIF/1, FU=5*VARVAL(1) DIF/2, FU=3*DIF(1)*VARVAL(1)

Notice that the integrator will take care of using zero for the delay when the expression for the delay is negative.

Example: part create equation differential_equation differential_equation_name = DIFF1 initial_condition = 1 function = (DELAY(DIFF1, 1,1,777)

Learn more about Constants & Variables.


542

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

Example

The following example illustrates the use of the DIF function:

DIF(diffeq_6)


Differential Variable Name Name of an existing differential equation modeling entity; defined by an object name.


Differential Variable Value (DIF1)

Returns the value of the variable defined by the specified differential equation modeling entity.

Format

DIF1(Differential Variable Name)

Argument

Example

The following example illustrates the use of the DIF1 function:

DIF1(.diffeq_4)


Differential Variable Name Name of an existing differential equation modeling entity; defined by an object name.


544

DIM

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

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

Format

DIM(x1,x2)

Arguments

Example

The following function returns 0 as long as , and TIME - 5 for TIME > 5. TIME is the current simulation time.

DIM(TIME,5)


x1 x2

Note: DIM is a discontinuous function and must be used with caution.



TIME 5


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

Equation

Mathematically, DX is calculated as follows:

where:




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:

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.

Function DX(marker_T, marker_F, marker_A)

Result 12

DX RT RF– xA=

RT

RF

xA


546



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

Equation

Mathematically, DY is calculated as follows:

where:




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:



Along Marker (Optional) Coordinate system marker along whose y-axis the distance is measured.


Function DY(marker_T, marker_F, marker_A)

Result -5

DY RT RF– yA=

RT

RF

yA


548



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

Equation

Mathematically, DZ is calculated as follows:

where:



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



Along Marker (Optional) Coordinate system marker along whose z-axis the distance is measured.


Function DZ(marker_T, marker_F, marker_A)

Result 0

DZ RT RF– zA=

RT

RF

zA


550



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

Equation

Mathematically, DM is calculated as follows:

where:



Example

The following function returns a number greater than or equal to 0:


From Marker (Optional) Coordinate system marker from which the distance is measured. If not specified, this argument defaults to the global coordinate system.

Function DM(marker_T, marker_F)

Result 13

DM RT RF– RT RF– =

RT

RF


552



DTOR

Returns the degrees-to-radian units conversion factor ( /180), same as (PI/180).

Format

DTOR

Argument

None

Example

The following example represents a value of 30 degrees in units of radians:

30d*DTOR or (30 *PI/180)

Learn more about Constants and Variables.


554

EXP

Returns the value ex, where x is any expression that represents a numerical value.

Format

EXP(x)

Argument

Example

The following function returns e2*TIME, where TIME is the current simulation time:

EXP(2*TIME)




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.




















556

Example

The following function returns the magnitude of the torque acting on the second body (at the J marker) of .model_1.field_11, measured in the global coordinate system:

FIELD(.model_1.field_11, 1, 5, 0)



Fourier Cosine Series (FORCOS)

Evaluates a Fourier Cosine series at a user-specified value x.

Format

FORCOS (x, Shift, Frequency, Coefficients)

Arguments

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.



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.


558

Fourier Sine Series (FORSIN)

Evaluates a Fourier Sine series at a user-specified value x.

Format

FORSIN (x, Shift, Frequency, Coefficients)

Arguments

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.



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.


Haversine Step (HAVSIN)

Defines a haversine function. HAVSIN is most often used to represent a smooth transition between two functions.

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

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


Begin At Real variable that specifies the x value at which the haversine function begins.


560

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)


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.


IF

Allows you to conditionally define a function expression.

Format

IF(Expression1: Expression2, Expression3, Expression4)

Arguments

Example

In the following illustration, the expression returns different values depending on the value of the variable called time:

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.

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.

Function IF(time-2.5:0,0.5,1)

Result 0.0 if time < 2.5

0.5 if time = 2.5

1.0 if time > 2.5


562

Learn more about constants and variables.


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

Equation

Mathematically, INVPSD is calculated as follows:

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, , is calculated by a pseudo-random number generator.

Using the same seed value will always result in the same set of phase angles.

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.


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

INVPSD Ai 2fi x i+ sin

i 1=

nf

=

i 0 i 2


564

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



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

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.

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.


566

• spline id is the identifier of the spline that specifies the RPC III or DAC file input. Setting up a Spline in Adams/Durability.

For more information on the INTERP function, see INTERP for Adams/Solver (C++) or INTERP for Adams/Solver (FORTRAN).


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.




















568

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)



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.




















570

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)



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

Example

The following function returns the natural logarithm of the expression (1+TIME), where TIME is the current simulation time:

LOG(1+TIME)




572

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

Example

The following function returns the base 10 logarithm of the expression:

LOG10(1+VM(marker_21, marker_31))




MIN

Returns the minimum of two expressions that represent numerical values:

MIN(x1,x2) = x1 if x1 < x2MIN(x1,x2) = x2 if x2 < x1

Format

MIN(x1,x2)

Arguments

Example

The following function is designed to always return a negative or zero value:

MIN(0, (25D-AZ(marker_2, marker_1)))


Note: The MIN function is generally discontinuous. Use this function expression with care when specifying force or motion input.




574

MAX

Returns the maximum of two expressions that represent numerical values:

MAX(x1,x2) = x1 if x1 > x2MAX(x1,x2) = x2 if x2 > x1

Format

MAX(x1,x2)

Arguments

Example

The following function is designed to always return a non-negative value:

MAX(0, (25D-AZ(marker_2, marker_1)))


Note: MAX is generally discontinuous. Use this function expression with care when specifying force or motion input.




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

Format

MOD(x1,x2)

Arguments

Examples

The following examples illustrate the use of the MOD function:


Note: MAX is generally discontinuous. Use this function expression with care when specifying force or motion input.



Function MOD(45, 15)

Result 0

Function MOD(45, 16)

Result 13


576

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)



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.















Along/About Axes (Optional)

Coordinate system marker in which the results are measured.





578

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)


579Run-Time FunctionsFunctions: N - Z

Functions: N - Z

Adams/View Function BuilderFunctions: N - Z

580

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.

Format

NFORCE (Multipoint Force Name, At This Marker, Force Component, Along/About Axes)

Arguments

Note: NFORCE can only be used for output purposes. Therefore, it can be used only with output request and sensor objects.

Multipoint Force Name (Required) Multipoint force for which the force is measured.

At This Marker (Required) Marker on which the force is measured.


• 0 = forces and torques on the I marker

• 1 = forces and torques on the J marker


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)

















582

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

Equation

The IMPACT function turns a force on and off depending on the value of the independent variable, as follows:

Mathematically, IMPACT is calculated as follows:

where:

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 Variable

Independent variable value at which to turn the one-sided impact on and 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

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.

FIMPACT

Off if q qo

On if q qo

=

MAX 0 K qo q– e Cq· STEP q qo d 1 qo 0 – –


• q is the displacement variable

• 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

q·


584

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

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.

Note: Assume that the flat surface being contacted by the sphere is an infinite plane.


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



586

PLANT INPUT VALUE (PINVAL)

Returns the run-time value of a plant input.

Format

PINVAL (Plant Input Name, Element Number)

Arguments

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.


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.


Plant Output Value (POUVAL)

Returns the run-time value of a plant output.

Format

POUVAL(Plant Output Name, Element Number)

Arguments

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,

At .75 seconds into the simulation,


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.

Function POUVAL(model_1.POU,1)

Result sin(2*PI*TIME)

Function POUVAL(model_1.PIN,1)

Result -1


588

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.

Format

PTCV (Point-to-Curve Name, On This Body, Component, Along/About Axes)

Arguments

Note: PTCV can only be used for output purposes. Therefore, it can be used only with output request and sensor objects.

Point-to-Curve Name

(Required) Point-to-curve object for which the force is measured.






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)

















590

Polynomial Fitted (POLYFIT)

Returns the coefficients of a polynomial fitted to the supplied function data.

Format

POLYFIT (x, y, order)

Arguments

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.


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


Polynomial (POLY)

Evaluates a standard polynomial at a user-specified value x.

Format

POLY (x, Shift, Coefficients)

Arguments

Examples

The following function defines a quadratic polynomial function with respect to the system variable TIME:

The following function defines a linear function with respect to the system variable TIME:

The following function defines a cubic polynomial function with respect to the system variable TIME:



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.

Function POLY(TIME, 0, 0, 0, 1)

Expanded function POLY = TIME2

Function POLY(TIME, 5, 0, 10)

Expanded function POLY=10*(TIME-5)

Function POLY(TIME, 10, 0, 25, 0, 0.75)

Expanded function POLY=-25*[TIME-10]+ 0.75*[TIME-10]3


592

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)



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 > 0SIGN(a1, a2) = -ABS(a1) if a2 < 0

Format

SIGN (x1,x2)

Arguments

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


Note: SIGN is discontinuous. Use this function with care to avoid creating expressions that are discontinuous.




594

Simple Harmonic (SHF)

Evaluates a simple harmonic function.

Format

SHF (x, Shift, Amplitude, Frequency, Phase Shift, Average Value of Displacement)

Arguments

Equation

Mathematically, SHF is defined as follows:

SHF = a*SIN( *(x-x0)-phi)+bwhere:

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


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 Displacement or b

Real variable that specifies the average value of displacement of the harmonic function.


In the function:

• x = TIME

• x0 = 25 degrees

• = 1 cycle (360D)

• phi = 0

• a = PI

• b = 5



596

SIN

Returns the sine of an expression that represents a numerical value.

Format

SIN(x)

Argument

Example

The following example returns the sine of 10*TIME, where TIME is the current simulation time:

SIN(10*TIME)




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 Force

(Required) Single-component force for which the force is measured.















Along/About Axes (Optional)Coordinate system marker in which the results are measured.





598

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)



SINH

Returns the hyperbolic sine of an expression that represents a numerical value:

SINH(x) = (ex-e-x)/2.0

Format

SINH(x)

Argument

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




600

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.




















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)



602

Spring-Damper Force (SPDP)

Returns a force or torque applied by a specified spring-damper force on one or two bodies affected by the spring-damper force.

Format

SPDP (Spring-Damper Force Name, On This Body, Force Component, Along/About Axes)

Arguments

Spring-Damper Force Name

(Required) Spring-damper force for which the force is measured.




















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)



604

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

Example

The following function returns the square root of the expression TIME:



Function SQRT(TIME*TIME)

Result TIME


STEP

Approximates the Heaviside step function with a cubic polynomial.

Format

STEP (x, Begin At, Initial Function Value, End At, Final Function Value)

Arguments

Extended Definition

The STEP function approximates the Heaviside step function with a cubic polynomial. The following figure illustrates the STEP function.

Note: STEP has continuous first derivatives, but its second derivatives are discontinuous at x=x0 and x=x1. Haversine Step (HAVSIN), STEP5, and TANH offer other approximations for the Heaviside step function. These have a higher degree of continuity and differentiability, but can have larger derivatives.

See Haversine Step (HAVSIN) for a plot comparing STEP, STEP5, TANH, and Haversine Step (HAVSIN).

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.


606

The equation defining the STEP function is:

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


a h1 h2–=

x xo– x1 xo– =

STEP

ho : x xo

ho a 2 3 2– – : xo x x1

h1 : x x1

=


STEP5

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

Format

STEP5 (x, Begin At, Initial Function Value, End At, Final Function Value)

Arguments

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)


Note: STEP5 has continuous first and second derivatives, but its third derivative is discontinuous at x=x0 and x=x1.

See Haversine Step (HAVSIN) for a plot comparing STEP, STEP5, TANH, and Haversine Step (HAVSIN).

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.


608

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

Equation

Mathematically, FX is calculated as follows:

where:

• is the sum of all applied and constraint forces involving both the Applied To Marker,

T, and the Applied From Marker, F.

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

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.

Function FX(marker_T, marker_F, marker_A)

Result 4

FX FT F xA=

FT F

xA


Learn more about resultant force functions.


610

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

Equation

Mathematically, FY is calculated as follows:

where:

• is the sum of all applied and constraint forces involving both the Applied To Marker,

T, and the Applied From Marker, F.

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

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.

Function FY(marker_T, marker_F, marker_A)

Result 3

FY FT F yA=

FT F

yA


612

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

Equation

Mathematically, FZ is calculated as follows:

where:

• is the sum of all applied and constraint forces involving both the Applied To

Marker, T, and the Applied From Marker, F.

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


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.

Function FZ(marker_T, marker_F, marker_A)

Result 0

FZ FT F zA=

FT F

zA


614

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

Equation

Mathematically, FM is calculated as follows:

where:

• is the sum of all applied and constraint forces involving both the Applied To


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:


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.

Function FM(marker_T, marker_F)

Result 5

FM FT F FT F=

FT F


616

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

Equation

Mathematically, TX is calculated as follows:

where:

• is the sum of all applied and constraint torques involving both the Applied To


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

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.

Function TX(marker_T, marker_F, marker_A)

Result 5.3

TX TT F xA=

TT F

xA


618

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

Equation

Mathematically, TY is calculated as follows:

where:

• is the sum of all applied and constraint torques involving both the Applied To


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



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.

Function TY(marker_T, marker_F, marker_A)

Result 7.2

TY TT F yA=

TT F

yA


620

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

Equation

Mathematically, TZ is calculated as follows:

where:

• is the sum of all applied and constraint torques involving both the Applied

To Marker, T, and the Applied From Marker, F.

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



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.

Function TZ(marker_T, marker_F, marker_A)

Result 9.7

TZ TT F zA=

TT F xA

zA


622

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

Equation

Mathematically, TM is calculated as follows:

where:

is the sum of all applied and constraint torques involving both the Applied To


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.

Applied To Marker (Required) Measure the sum of all torques applied to this coordinate system maker.

Applied From Marker (Optional) Measure the sum of all torques applied from this coordinate system maker. If you don't specify this argument, it returns the magnitude of the sum of all torques at the Applied To Marker due to action-only torque acting at the Applied To Marker.

Function TM(marker_T, marker_F)

Result 13.19

TM TT F TT F=

TT F xA


624

SWEEP

Returns a constant amplitude sinusoidal function with linearly increasing frequency.

Format

SWEEP (Independent Variable, Amplitude, Start Value, Start Frequency, End Value, End Frequency, Delta X)

Arguments

Equation

Mathematically, SWEEP is calculated as follows:

SWEEP = STEP5(x,0,0,dx,1)* a * sin(2 *(freq(x)*x + PHASE(x)))where:

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.

freq x

fo if x xo

fo

f1 fo– 2

-------------------x 2xo–

x1 xo–-----------------+ if xo x x1

f1 if x x1

=

PHASE x

0 if x xo

f1 fo– 0.5 xo

2x1 xo–----------------- if xo x x1

0.5DO f1 fo– x0 x1– if x x1

=


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)



626

TAN

Returns the tangent of an expression that represents a numerical value.

Format

TAN(x)

Argument

Example

The following function returns the tangent of 10*TIME, where TIME is the current simulation time:

TAN(10*TIME)




TANH

Returns the hyperbolic tangent of an expression that represents a numerical value:

TANH(x) = (ex-e-x)/(xa+exa)

Format

TANH(x)

Argument

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


Note: See Haversine Step (HAVSIN) for a plot comparing STEP, STEP5, TANH, and Haversine Step (HAVSIN).



628

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.




















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)



630

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.















About Axes (Optional) Coordinate system marker in which the results are measured.





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)



632

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



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

Equation

The BISTOP function turns a force on and off depending on the value of the independent variable q, as follows:

Mathematically, BISTOP is calculated as follows:

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 Displacement Value

Lower value for independent variable at which to trigger the first side of two-sided impact.

High Trigger for Displacement Value

Higher value for independent variable at which to trigger the second side of two-sided impact.

Stiffness Coefficient or K Stiffness coefficient for spring force; defined by a real number, a run-time function, a design-time function, a design variable or an expression.

Stiffness Force Exponent Exponent for nonlinear spring force; defined by a real number, a run-time function, a design-time function, a design variable or an expression.

Damping Coefficient or C Damping coefficient for damper force; defined by a real number, a run-time function, a design-time function, a design variable or an expression.

Damping Ramp-up Distance

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.

FBISTOP

On if q qo

Off if q1 q q2

=


634

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.

FBISTOP

K q1 q– e Cq· STEP q q1 d 1 q1 0 – – if q q1

0 if q1 q q2

K q q2– e Cq· STEP q q2 0 q2 d 1+ – if q2 q

=


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

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.

Parameters Real values that define the parameters for use by the user-written subroutine. Up to thirty parameters may be defined.


636

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

Equation

Mathematically, VR is calculated as follows:

where:



• [ is the position vector from the global origin to the From Marker, F.


• DM(T,F) is the distance between the To Marker, T, and the From Marker, F.

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.

VRtd

dRT td

dRF

R –

R RT RF–

DM T F -----------------------------------------------------------------------------=

RT

tdd

RTR

RT

RF

tdd

RFR

RF


Example

The following function returns the radial (relative) velocity of the velocity vector between marker_T and marker_F. The vector time-derivative is taken in the reference frame of marker_R.

VR(marker_T, marker_F, marker_R)



638

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

Equation

Mathematically, VX is calculated as follows:

where:








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.

VXtd

dRT td

dRF

R –

R xA=

RT

tdd

RTR

RT

RF

tdd

RFR

RF

xA


Example

The following function returns the x component of the velocity vector between marker_T and marker_F. The vector is expressed in the coordinate system of marker_A. All time-derivatives are calculated in the reference frame of marker_R.

VX(marker_T, marker_F, marker_A, marker_R)



640

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

Equation

Mathematically, VY is calculated as follows:

where:








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.


VYtd

dRT td

dRF

R –

R yA=

RT

tdd

RTR

RT

RF

tdd

RFR

RF

yA


Example

The following function returns the y component of the velocity vector between marker_T and marker_F. The vector is expressed in the coordinate system of marker_A. All time-derivatives are calculated in the reference frame of marker_R.

VY(marker_T, marker_F, marker_A, marker_R)



642

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

Equation

Mathematically, VZ is calculated as follows:

where:





• is the unit vector along the z-axis of the Along Marker, A.



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.


VZtd

dRT td

dRF

R –

R zA=

RT

tdd

RTR

RT

RF

tdd

RFR

RF

zA


Example

The following function returns the z component of the velocity vector between marker_T and marker_F. The vector is expressed in the coordinate system of marker_A. All time-derivatives are calculated in the reference frame of marker_R.

VZ(marker_T, marker_F, marker_A, marker_R)



644

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

Equation

Mathematically, VM is calculated as follows:

.

where:





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)





VMtd

dRT td

dRF

R –

R

tdd

RT tdd

RFR

–R

=

RT

tdd

RTR

RT

RF

tdd

RFR

RF

645Product-Specific Functions

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

Adams/View Function BuilderAdams/Solver (C++)

646

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

647Product-Specific FunctionsAdams/Durability

Adams/DurabilityWhen using Adams/Durability, you can use its functions to interrogate a flexible or rigid body for useful stress, strain, or life data. The user functions are:

• HOT_SPOTS

• LIFE

• MAX_STRESS

• TOP_SPOTS

These functions facilitate the definition of a design objective or variable that can be used in a design of experiments (DOE) or optimization study. When Adams/Durability is loaded, you can find these functions in the Misc. Functions category of the Adams/View Function Builder.

Adams/View Function BuilderTemplate-Based Products

648

Template-Based ProductsThis 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

649Adams/View Function Builder Examples

Adams/View Function Builder ExamplesSelect 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

Adams/View Function BuilderExpression Example

650

Expression ExampleThe 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))

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.

Note: You must enclose all Adams/View expressions in parentheses.

651Adams/View Function Builder ExamplesExample - Building Functions for Motions

Example - Building Functions for MotionsThis example demonstrates how you can restrict the angle of movement of a link using the Simple Harmonic (SHF) function.

To build a function for motion:

1. Create a link and place a revolute joint and a rotational joint motion at one end of the link.

2. Right-click the motion screen icon, and then select Modify.

The Impose Joint Motion dialog box appears.

3. Clear the F(time) text box.

4. Right-click the F(time) text box, and then select Function Builder.

5. From the Math Functions category, select Simple Harmonic.

6. Select Assist.

Adams/View Function BuilderExample - Building Functions for Motions

652

7. The Simple Harmonic Function dialog box appears. Fill in the dialog box as shown next:

8. Select OK in the following dialog boxes, in the order listed:

a. The Simple Harmonic Function dialog box.

The function you just defined appears in the function work area of the Function Builder.

b. The Function Builder.

The function appears in the F(time) text box.

c. The Impose Joint Motion dialog box.

The motion now uses the function you built.

Note: Adams/View cannot plot the Simple Harmonic function in the Function Builder, because it can't interpret it as a design-time function.

653Adams/View Function Builder ExamplesExample - Parameterizing Values for Marker Locations

Example - Parameterizing Values for Marker LocationsThis example shows how to use the LOC_ALONG_LINE function to parameterize the location of a marker with respect to another marker.

To parameterize a location:

1. Create three markers, MAR_1, MAR_2, and MAR_3, placed randomly.

2. Right-click the MAR_2 screen icon, and then select Modify.

The Marker Modify dialog box appears.

3. Clear the coordinate values from the Location text box.

4. Right-click the Location text box, point to Parameterize, and then select Expression Builder.

The Function Builder appears in expression mode.

5. Clear the text from the function work area.

6. From the Location/Orientation function category, select LOC_ALONG_LINE.

7. Select Assist.

The LOC_ALONG_LINE dialog box appears.

8. From the box pop-up menus, use Browse to insert:

• MAR_1 in Object for Start Point text box.

• MAR_3 in Object for Point on Line text box.

9. In the Distance text box, enter 50.

10. Select OK in the following dialog boxes, in the order listed:

• The LOC_ALONG_LINE dialog box.

The function you just defined appears in the function work area of the Function Builder.

• The Function Builder.

The function appears in the Location text box.

• The Marker Modify dialog box.

MAR_2 is now 50 units from MAR_1. MAR_1 and MAR_2 are parameterized. As a result, if you move one marker, the other marker moves along with it.

Adams/View Function BuilderExample - Parameterizing Values for Marker Locations

654

using adams/view function bld. - md adams 2010

Documents