Expression Language Reference

This section explains how you can use expressions in Adams View to compute values or to parameterize your model. Parametrization lets you keep the associativity between model objects.

Learn more about:

You use expressions in Adams View in the expression mode of the Function Builder. Expressions are combinations of constants, operators, functions, and database object references, all enclosed in parentheses. In Adams View you can use expressions to specify parameter values, such as locations of markers or functions of motions.

Adams View uses expressions for two purposes:

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

The following sections introduce the elements you can use in expressions, and their proper syntax:

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 allow you to indicate what you want to operate on. The kinds of operands allowed in Adams View expressions are:

The first kind of operand is a literal constant value. Here are some examples of literal constant values:

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.

NONE is a constant that behaves in a unique way. It can be coerced to any type and allows you to erase values from the database when used in certain contexts.

If used in arithmetic expressions, NONE equates to zero (10 + NONE is equal to 10). If used in string expressions, NONE is the empty string. Both of these facts can occasionally be useful in forcing type conversion of some value. For instance, the concatenation operator (//) takes a pair of strings and concatenates them into one: NONE // 2 forces the number 2 to become a character string, and NONE + "10" forces the string "10" to become the number 10.

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

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

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

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:

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

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:

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

There are two reasons to use the EVAL function:

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.

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:

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

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,

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:

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:

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:

Local references have the following characteristics:

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

Setting a value:

Computing a mass:

Computing a mass from a volume:

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

or

The first interpretation in the above example is how Adams would treat the expression. The algorithm used is:

In this particular case, either interpretation of expression (part_1.location) is valid in most contexts, but can produce very different results.

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:

or

When you use the alias (in the first example), the command executes faster, since no arithmetic has to be done to index the array element.

The following fields list some examples of aliases:

part.location
marker.location

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:

In this case, Adams View would return the location -50.0, -200.0.

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.

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.

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.

Real expressions containing integer division do not convert operands to real before division. This results in values as computed by Adams View, as shown in the example below,

not as evaluated in mixed mode arithmetic,

Also, in Adams View, 8/10 is equal to 0.

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:

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:

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:

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.

Adams View monitors the values referenced by each expression. If you change a value used in an expression, Adams View immediately updates the expression.

When Adams View evaluates an expression, it can in turn cause the value of other expressions to change. Those expressions are re-evaluated to determine their new values. If an expression depends on its current value (either directly or indirectly), evaluation could continue endlessly. To avoid problems, Adams View only resolves such expressions one level deep.

For example, take the following expressions:

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:

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.

Adams View stores the positions (location and orientation) of objects in Cartesian/Euler coordinates, relative to the parent of the object containing the position (a marker's location is stored relative to the coordinate system of the part that owns the marker and all part locations are stored relative to the coordinate system of the model that owns the parts). When positions are specified with literal values, not expressions, Adams View computes database values using the current unit settings, and the default coordinate system (using the RELATIVE_TO parameter) before storing them.

When you use an expression to specify a position, Adams View stores the expression directly. Therefore, you must specify all position expressions consistent with how Adams View stores the positions. If you use an expression to specify the x, y, and z location of a marker, the coordinate system type must be Cartesian.

When you reference location and orientation values in an expression, Adams View uses their values exactly as they are stored. If you reference the location of a marker, its value is in Cartesian coordinates relative to its parent part.

You can use expressions to specify individual position components or an entire location or orientation. An example of using an expression to specify an individual component of a location is:

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

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:

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:

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:

In the second case, you would create the marker relative to part_1 to which it belongs:

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

When defining the locations or orientation of objects using expressions, you cannot use a relative_to reference frame. With the above commands, Adams View transforms the information you supply for location and relative_to into a location relative to the part that owns the marker, and discards the values you entered. This loss of information is usually of no consequence, as you can easily reconstruct it (that is, you can set relative_to to anything you want and see the location or orientation expressed in that reference frame).

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

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

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.

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:

Without this, the value is implicitly used relative to the owning part of the marker, therefore marker_3 appears in the wrong location.

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

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:

The next sections explain the different types of arrays.

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

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:

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

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

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.

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

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

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

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.

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.

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.

 

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:

or

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.

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

 

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

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

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

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:

Adams View handles fields containing more than one location or orientation as 3xN matrices. For example, consider the three-point polyline defined below:

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:

Using matrix composition with database objects, you can create a three-point polyline from marker locations:

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:

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

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:

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

Adams View allows you to assign units to numbers to explicitly define dimensions. For instance, the number 90 might be meaningful in the context of an angle only if it has units of degrees, while the number 3.14159 should probably have units of radians. Therefore, Adams View allows you to place labels on these values: (90d) or (3.14159r).

The following sections introduce you to unit sensitivity and unit labels:

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,

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:

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.

Changing the model mass units, in this case from grams to kilograms, changes the mass of part_2 to 0.03 kg.

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:

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

To label an expression with units, you can use either simple unit labels or composed 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:

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

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

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:

The following table lists examples of composed unit labels: