Expressions in System Coupling

System Coupling supports the use of expressions to specify values for the following data model settings:

  • All settings with immutable single-valued real or integer values

  • Source-side data transfer values

  • Time step size

Expression Definition

You can define an expression using any consistent mathematical combination of the following elements:

  • Values: These may be single values, field values, or dimensional constants. For more information, see Expression Values and Constants.

  • Variables: These may be participant variables or System Coupling's built-in variables and may have either scalar or vector tensor types. Source and target tensor types must be consistent. For more information, see Variables in Expressions.

  • Standard numerical operators and functions: Mathematical capabilities supported by the Python programming language (essentially, the functionality defined by the C programming standard) can be used in expressions. For more information, see Mathematical Operators, Constants, and Functions.

  • Conditional and Boolean statements: Conditional and Boolean statements can be used to build expressions. For more information, see Conditional and Boolean/Logical Statements.

  • Quantity units: These may be any consistent units supported by System Coupling. Source and target units must be consistent. For more information, see Units in Expressions.

  • Python functions: Python functions can be created, loaded each time the coupled analysis is opened, and used to provide single-valued data in expressions. For more information, see Python Expression Functions.

  • Named expressions: Expressions can be saved and referenced by name in other expressions. For more information, see Named Expressions.

Expression Evaluation

Expressions are evaluated as follows:

  • Expressions are evaluated during the solution.

  • Expression operators are evaluated from left-to-right in order of their precedence (that is, according to standard order-of-operation rules).

  • Expressions may evaluate to real or integer single values or field values, which may be either immutable or mutable.

  • Values used in mapping and data transfers between participants can be scalars or vectors, consistent with the tensor type of the target variable.

  • Expressions that include Python functions are evaluated at least once per solve. For details, see Expression Function Definition, Validation, and Evaluation.

  • For data transfers, the expression is evaluated on the source side of the interface and then mapped to the target side.

For more information on using expressions in System Coupling, see the following sections:

 

Expressions Validation

Note:  System Coupling's evaluation of expressions is based on the Python 3.10 programming language. For more information, see the resources published by the Python Software Foundation.

When entering an expression, construct it in the form of an operand, followed optionally by operators and additional operands. (For example, if Temp1 and Temp2 are existing variables in a coupled analysis, you can define a setting value as Temp1 + 3 * Temp2 ).

Ensure that the expression meets the following syntactic requirements, and has:

Syntactically Valid Names

The names used in expressions to reference various coupled analysis objects (which includes variable names, function names, and so on) must adhere to the Python language's naming rules. For example, names:

  • must be unique within the analysis

  • are case-sensitive

  • can be constructed only of letters, digits, and the underscore characters

  • cannot have a digit as the first character

  • cannot include spaces

  • cannot include reserved keywords

  • cannot have the same name as a variable (either participant variables or built-in System Coupling variables)

The Expression Name used to define named expressions must also conform to these rules. For more information, see Named Expressions.

Supported Variables

Expressions must include only variables that are supported for the data model setting being defined. For example:

  • Expressions used to define source-side data transfer variables cannot reference target-side variables.

  • In a steady analysis, expressions used to define source-side data transfer values cannot reference time-based variables.

  • For expressions used to define a mutable time step size, only System Coupling's Step, Time, and PreviousTimestepSize solution variables are supported for use in the expression.

Consistent Variable Locations

Data transfer variables must have a data location definition. When multiple variables are referenced in an expression, all must have Location set to the same type (either Node or Element).

Consistent Variable Tensor Types

Data transfer variables must have a TensorType defined (Vector or Scalar). When multiple variables are referenced in an expression, they are subject to the following constraints:

  • Terms that are added to or subtracted from each other must have the same tensor type.

  • A vector term may not be multiplied by another vector term.

  • A vector and a scalar may be multiplied in either order and results in a vector value in which each component of the original vector has been multiplied by the scalar.

  • A vector term may not be divided by another vector term.

  • A vector may be divided by a scalar (but not vice versa) and results in a vector value in which each component of the original vector has been divided by the scalar.

Consistent Target Values

Expressions must evaluate to a value that is consistent with the requirements of the data model setting being defined — that is, the evaluated value must match the following characteristics of the target value:

  • single-valued or field

  • immutable or mutable

  • vector or scalar tensor type

For more information, see Expression Values.

Dimensional Consistency

Expressions must evaluate to units that are consistent with the units of the data model setting being defined. For example, an expression defining a data transfer source variable must evaluate to units that are dimensionally compatible with those of the target variable.

For more detailed information, see Units in Expressions.

 

Expression Values

Expressions must result in a value that is consistent with the requirements of the data model setting being defined. The evaluated value(s) must match the characteristics of the target value: whether it is a single value or a field, and whether it is immutable or mutable.

Single Values

  • When an expression evaluates to a single value, it returns a single value at each point of the calculation — that is, there is one value at each coupling step or iteration in the analysis.

  • Single values are not dependent on mesh or location.

Fields

  • When an expression evaluates to a field, it returns a field of values at a given point in the calculation — that is, at a given point in the calculation, there are values throughout the regions on a coupling interface.

  • Fields are dependent on mesh and location, so evaluation of the expression may yield different values for each node or element of the mesh at each coupling step or iteration.

Note:  It is possible to assign a single value to a field. In this case, each location in the field will be set to this value.

Immutable Values

  • An expression that does not reference any variables evaluates to an immutable value.

  • When an expression evaluates to an immutable value(s), the returned value(s) do not change over the course of the analysis.

  • The expression is evaluated once and the value(s) remain the same at each coupling step or iteration.

Mutable Values

  • An expression that references one or more variables evaluates to a mutable value.

  • When an expression evaluates to a mutable value(s), the returned value(s) vary over the course of the analysis.

  • The expression is evaluated multiple times, yielding different values at each coupling step or iteration.

Table 11: Example expression values

Evaluated ValueSetting(s)Description

Immutable Single Value

End Time

An expression defining the End Time value is evaluated once. The value does not change during the analysis.

Mutable Single Value

Time Step Size

An expression defining a mutable Time Step Size value may evaluate to 1 [s] at a given coupling step and to 2 [s] at a later step.

Mutable Field

Value

An expression defining the source side variable values for a Force transfer will yield different values for each coordinate (for example, force) at different coupling steps or iterations.

Note also that the components of a vector field may be accessed as scalar fields – force.x, force.y, and force.z.)


 

Expression Definitions

For details on components that may be used to define an expression, see the following sections:

 
Variables in Expressions

For more information on the use of variables in expressions, see the following sections:

 
Variable Sources

Expressions may reference System Coupling's built-in variables and/or variables provided by participants.

Note:

  • Currently, all built-in System Coupling variables have mutable values.

  • The Area variable is supported only for transfers element data from surfaces. That is, the source participant must have Region.Topology set to Surface and Variable.Location set to Element.

  • The Area and Volume variables are not available for point cloud regions.

System Coupling's Built-in Variables

System Coupling has the following built-in variables, which can be used in expressions:

  • Solution Variables:

    • Iteration

    • Time

    • Timestep

    • PreviousTimestepSize

  • Region Variables:

    • Area

    • Normal

    • Position

    • Volume

For more detailed information on these variables, see Built-In Variables in the System Coupling Settings and Commands Reference documentation.

Coupling Participant Variables

Any variable listed by a coupling participant as a System Coupling variable for the region(s) on the coupling interface may be used in expressions.

 
Data Transfer Variable Tensor Types

System Coupling supports the use of both scalar and vector variables (that is, variables with TensorType set to Scalar or Vector, respectively) in expressions.

Note:  Vector-valued data transfers are defined by a single vector-valued expression in the data transfer's Value setting.

Previously, vector transfers were defined using separate components in the data transfer's ValueX, ValueY, and ValueZ settings. These components are now combined into the single Value setting.

For source-side expressions, the tensor type of the target variable determines both how the variable is defined and the tensor type of the source-side expression (that is, the Value setting), as follows:

  • If the target variable is scalar:

    • The source variable is defined as a single value.

    • The source expression must resolve to a scalar value.

  • If the target variable is vector:

    • The source variable is defined as Cartesian coordinates (x, y, and z). To access the vector components of a variable, enter the variable name followed by a period ('.') and the vector component name. For example:

      Force.x
      Force.y
      Force.z

    • The source expression must resolve to a vector value.

 
Mathematical Operators, Constants, and Functions

The following sections detail System Coupling's support for mathematical operators, constants, and functions:

 
Operators
DescriptionSettingX UnitsY Units

Negation

-x[a]

any

 

Addition

x[a] + y[b]

any

[a]

Subtraction

x[a] - y[b]

any

[a]

Multiplication

x[a] * y[b]

any

any

Division

x[a] / y[b]

any

any

Exponent

x[a] ** y

any

dimensionless

 
Boolean/Logical Operators
DescriptionSyntaxX UnitsY Units

NOT

not x

  

Less Than or Equal to

x[a] <= y[b]

any

[a]

Less Than

x[a] < y[b]

any

[a]

Greater than or equal to

x[a] >= y[b]

any

[a]

Greater than

x[a] > y[b]

any

[a]

Not equal to

x[a] != y[b]

any

[a]

Equal to

x[a] == y[b]

any

[a]

AND

x and y

  

OR

x or y

  
 
Constants
DescriptionSymbolValue

pi

pi

3.1415927

Base of natural logarithm

e

2.7182818

 
Functions
DescriptionSettingX UnitsY Units

Modulus

x % y

dimensionless

dimensionless

Floor Divide

x[a] // y

any

[a]

Integer

int(x)

dimensionless

 

Nearest Integer

nint(x)

dimensionless

 

Ceiling

ceil(x)

dimensionless

 

Absolute Value

fabs(x[a])

any

 

Absolute Value

abs(x[a])

any

 

Floor

floor(x[a])

dimensionless

 

ex

exp(x)

dimensionless

 

Natural logarithm

log(x)

dimensionless

 

Base 10 logarithm

log10(x)

dimensionless

 

Power

pow(x[a], y)

any

 

Square root

sqrt(x[a])

any

 

Arc cosine1

acos(x)

dimensionless

 

Arc sine1

asin(x)

dimensionless

 

Arc tangent1

atan(x)

dimensionless

 

Arc tangent with quadrant1

atan2(x[a], y[b])3

any

[a]

Cosine

cos(x)

angle

 

Sine

sin(x[a])

angle

 

Tangent

tan(x[a])

angle

 

Hyperbolic cosine

cosh(x)

dimensionless

 

Hyperbolic sine

sinh(x)

dimensionless

 

Hyperbolic tangent

tanh(x)

dimensionless

 

Minimum

min(x[a], y[a])

any

[a]

Maximum

max(x[a], y[a])

any

[a]

Conditional2

x[a] if <log_expr> else y[b]

any

[a]

1: The results of inverse trig functions are unitless if the arguments are unitless. You must perform a mathematical operation on the result to add units if you need them. For example, multiply the result of the function by 1 [radian].

2: The Conditional function is supported for the following structural and thermal loads: Pressure, Moment, Force (when defined by force per-unit-area and directional components), Heat Flux, Temperature, and Convection (on ambient temperature).

 
Conditional and Boolean/Logical Statements

System Coupling supports the use of conditional, Boolean, and Logical statements in expressions. These statements can be used to build expressions, which in turn can be used as operands in other expressions.

Conditional statements

Conditional statements use the if-else construct to test a condition and optionally provide actions to be taken if the condition is met and/or is not met.

Boolean/Logical statements

Boolean/Logical statements use Boolean and numeric Logical operators to set variable values.

Example 1: Expressions using conditional and Boolean/Logical statements

500 [N] if diameter >= 15 [mm] else 250 [N]
500 [N] if diameter >= 15 [mm] else 250 [N]

 
Units in Expressions

Dimensional quantities are defined in units that can be a combination of one or more base units. Expressions must have compatible units, as follows:

Addition and Subtraction operators

The addition and subtraction (+ and -) operators require that the two operands have compatible units. For example, you cannot add or subtract an Area parameter and a Length value. Both units must be Length or both units must be Area.

However, you can add or subtract two dissimilar units that are of the same dimensionality. For example, 1 [m] + 1 [ft] is a valid expression because both units are of the quantity type Length.

Multiplication and Division operators

The multiplication and division (* and /) operators do not require that operands have the compatible units. They allow the following permutations:

  • One operand can be a quantity with a unit and the other operand can be a dimensionless factor.

  • Both operands can be quantities with units, where the result is a different quantity type. For example, Length/Time results in units of equivalent dimension to a Velocity unit.

Trigonometric functions

The resulting units for arguments to a trigonometric function may be dimensionless or resolve to an angle, which allows for the following permutations:

  • If the argument is a number or dimensionless, then the value is interpreted as radians. For example:

    1 [] = 1 [rad]

  • If the argument is a quantity, then the units must resolve to type Angle. For example:

    1 [rev] = 360 [deg] = pi * 2[rad]
Whole expressions

You can apply a unit to a whole expression by multiplying it by a dimensional constant. For example:

sin(0.1) * 1 [N]

Note:  The notation sin(0.1) [N] is invalid because the syntax is ambiguous in Python.

For general information on supported units, see Units in System Coupling.

 
Python Expression Functions

You can reference external Python functions in expression definitions. To make a function available for use in expressions, you must first define it in a Python module and then add it to the coupled analysis as an expression function object.

When you add the first expression function object, the Library singleton is added to the data model (if it does not already exist), with the ExpressionFunction object container and the new expression function object defined beneath it.

Note:  The singleton is shown in the GUI as the Library | Expression Function branch.

Once the object is added to the data model, the function is loaded each time the analysis is opened and you can reference the function by name in expressions. Once in use, an expression function cannot be deleted.

For more information, see:

 
Expression Function Definition, Validation, and Evaluation
Function Definition

  • Functions are defined in one or more Python module files.

  • Python modules must be placed in a user-created Modules subdirectory in System Coupling's working directory.

  • Defined functions added to the coupled analysis are available for use in expressions.

  • Function names referenced in expressions may be different than the Python names of the functions.

  • Function arguments referenced in an expression are dimensionless and return dimensionless values.

Function Validation

  • Expression modules and functions must follow Python's syntax and naming rules.

  • Expression function parameters must be unique within the analysis.

  • The number of arguments passed to a function in an expression must match the number of parameters defined for the function.

  • Functions are expected always to return the same value for given argument values.

  • A function that is called with no arguments, or with arguments that do not depend on any variables, is assumed to return an immutable value and may be referenced in an expression that resolves to an immutable value.

  • Inconsistencies between modules and expression definitions may cause validation errors. For more information, see Reloading Expression Function Modules.

Function Evaluation

  • If a function does not reference any variables in its arguments (or has no arguments), then the expression is treated as if it is returning an immutable value. As such, it can be referenced in expressions resolving to an immutable value and will be evaluated at least once per solve.

  • If a function references a variable in its arguments, it will be called when the variable value updates (per iteration for iteration-based analyses or per step for step-based analyses).

 
Defining an Expression Function

Expression functions are defined in a Python module. To define an expression function, perform the following steps:

  1. Create the module.

    1. In System Coupling's working directory, create a Modules subdirectory.

      This is where System Coupling looks for Python expression modules and functions.

    2. Inside the subdirectory, create a Python module (for example, a file called myModule.py).

  2. Define the function.

    1. In the file, define the function, providing arguments for the function name and definition. The example below defines a function called f.

      
def f(step):
    return 2*step

    2. Save the file.

The function may now be added to the data model.

 
Adding an Expression Function

To make a function available for use in expressions, you must add an expression function object to the data model. This can be done using either the GUI or the CLI.

Adding an Expression Function in the GUI

  1. Perform one of the following actions:

    • From the Menu Bar, select Setup > Add Expression Function.

    • In the Outline tree, right-click the Setup branch and select Add Expression Function.

    The Expression Function branch is added to the Library branch, with the new expression function defined underneath it.

    Note:  Once the Expression Function branch exists, you may add new expression functions by right-clicking the branch and selecting Add.

  2. Click the expression function.

    Corresponding settings are shown in the Properties pane below.

  3. Set values for the function to be added, as follows:

    1. Module: Select name of the module containing the function to be added. The drop-down is populated with the names of Python modules in System Coupling's Modules directory.

    2. Function: Select the name of the Python function to be added. The drop-down is populated with the functions defined in the module specified by the Module setting.

    3. Function Name: (Optional) Type in the name to be used when adding the function to an expression. If a name is not selected, then this setting defaults to the Python function name selected for the Function setting.

Adding an Expression Function in the CLI

Run the AddExpressionFunction() command, using the Module argument to specify the module containing the function to be added and the Function argument to specify the Python name of the function to be added.

Optionally, you may use the FunctionName argument to specify the name to be used when adding the function to an expression. If a name is not specified, then this setting defaults to the Python function name specified by the Function argument.


>>> AddExpressionFunction(
	Module = 'myModule', 
	Function = 'f',
	FunctionName = 'stepFunction')

When the command is run, the expression function object is added under the Library singleton.

Once the expression function object has been added to the data model, you can reference the function by name in expressions. Once in use, an expression function cannot be deleted.

For more detailed information, see ExpressionFunction in the System Coupling Settings and Commands Reference documentation.

 
Reloading Expression Function Modules

By default, expression function modules are loaded and applied to a coupled analysis only once per System Coupling session. Because of this, changes made to modules during a session are not applied to the current session automatically and are instead applied the next time the coupled analysis is opened. However, changes to modules made during a session are saved to any snapshots that are created.

System Coupling generates a warning when it detects the following issues:

  • There is a discrepancy between a module and analysis expression definitions.

    The module file has been modified since it was last loaded and may no longer be consistent with the expression definitions in the coupled analysis. Depending on the nature of the modifications, this could result in unexpected errors or differences in results.

  • Expression function modules have failed to load.

    One or more modules in the Modules directory have failed to load or reload to the coupled analysis. This check is performed on all modules, regardless of whether their functions have been added to the analysis.

To synchronize the modules and expression definitions, reload the modified modules from either the GUI or the CLI.

Reloading Modules in the GUI

When module issues are detected, a warning is written to the Messages tab.

In the Outline tree, right-click the Library | Expression Function branch and select Reload Expression Function Modules.

Reloading Modules in the CLI

When module issues are detected, a warning is written to the CLI.

Run the ReloadExpressionFunctionModules() command.

The modules are reloaded to the coupled analysis.

Note:  When you delete a function from a module and then reload the module, the deleted function is not removed from the coupled analysis. If the deleted function is referenced by an expression function object and the object is used in an expression, no error will be shown until the analysis is saved and then reopened in a new System Coupling session.

 
Named Expressions

For ease of reference, you can add named expressions that can be incorporated into other expression definitions. To make an expression available for use in other expressions, you must add a named expression object to the data model.

When you add the first named expression object, the Library singleton is added to the data model (if it does not already exist), with the Expression object defined beneath it.

Note:  The object container is shown in the GUI as the Library | Named Expression branch.

Named expressions follow the naming and definition rules outlined in Expressions Validation.

For more information, see:

For more detailed information, see Expression in the System Coupling Settings and Commands Reference documentation.

 
Adding a Named Expression

Named expressions may be added either in the GUI or the CLI, as follows:

Adding a Named Expression in the GUI

  1. Perform one of the following actions:

    • From the Menu Bar, select Setup > Add Named Expression.

    • In the Outline tree, right-click the Setup branch and select Create Named Expression.

    The Named Expression branch is added to the Library branch, with the new expression defined underneath it.

    Note:  Once the Named Expression branch exists, you may add named expressions by right-clicking it and selecting Add.

  2. Click the named expression.

    Settings are shown below in the Properties pane.

  3. Enter the expression as the value of the Expression String setting.

Adding a Named Expression in the CLI

Run the AddNamedExpression() command, using the ExpressionName argument to specify a display name for the expression and the ExpressionString argument to specify its definition.

 
>>> AddNamedExpression( 
        ExpressionName = 'HeatRateExpr' 
        Expression String = 'heatrate/5')

When the command is run, the expression object is added under the Library singleton.

 
Using a Named Expression

Once the named expression object has been added to the data model, you can reference the expression by name in other expressions by right-clicking the setting's value field and selecting Insert named expression. Once in use, a named expression cannot be deleted.

 

Using Expressions to Set Data Model Values

For instructions on creating expressions and using them to set data model values, see the following sections:

 
Creating an Expression for an Immutable Single Value

You can use either the GUI or the CLI to create an expression for any data model setting with an immutable single real or integer value.

Creating an Expression for an Immutable Single Value in the GUI

  1. Under Setup, locate the setting to be defined.

  2. In the Properties pane, enter the expression as the value for the setting.

    Note:  If one or more named expressions are defined, you can right-click the setting's value field and select Insert named expression.

Creating an Expression for an Immutable Single Value in the CLI

In the CLI, enter the path to the setting, then enter an equal sign (=) and type in the expression string inside single quotes.

 
Identifying Valid Expression Variables for Mutable Values

System Coupling's variables can be used to define expressions for settings with mutable values.

Note:  Currently, the only supported settings with mutable values are:

  • Data transfer source variables

  • TimeStepSize (when AnalysisType is Transient and the DurationOption is set to EndTime)

The units resulting from a source expression must be consistent with the target variable's units. Thus, to add a variable to an expression defining the source variable for a data transfer, you must identify both the name and units of source-side variables that are valid for use in expressions. You can obtain this information either from the GUI or by running a command.

Both the GUI and command-line methods provide the following information:

  • A way to identify the target units

  • A list of all variables that are available and valid for use in a source expression on the selected object

    In the list, variables with the same quantity type and/or dimensionality as the target of the expression are listed first. Any of the variables returned may be included in an expression, provided that other validation criteria do not prevent their use.

Note:  The source and target units are not required to match, so long as appropriately dimensioned adjustment factors are used in the expression. The source expression needs only to resolve to units that are dimensionally consistent with the target units, as described in Units in Expressions.

Identifying Expression Variables for Mutable Values in the GUI

Right-click inside the expression field, select Insert variable, and select a variable from the drop-down menu. The menu is populated with the variables available for the setting.

When a variable is highlighted in the drop-down, its units are shown in a tooltip.

Identifying Expression Variables for Mutable Values in the CLI

Run the PrintExpressionVariables() command as illustrated in the examples below to obtain a list of available variables in table format.

Example 2: Use with ObjectPath to get source-side variables for a data transfer


>>> PrintExpressionVariables(ObjectPath = '/SystemCoupling/CouplingInterface:Interface-1/
DataTransfer:Transfer-1')
 
+-----------------------------------------------------------------------------+
|                             Available Variables                             |
+-----------------------------------------------------------------------------+
| Variable                            |   Tensor Type        Dimension        |
+-----------------------------------------------------------------------------+
| Target                              |                                       |
|   Loss                              |     (Scalar)       [kg m^2 s^-3]      |
| Source                              |                                       |
|   heatflow                          |     (Scalar)       [kg m^2 s^-3]      |
|   Position                          |     (Vector)            [m]           |
|   Normal                            |     (Vector)            [ ]           |
|   Area                              |     (Scalar)           [m^2]          |
|   Step                              |     (Scalar)            [ ]           |
|   Iteration                         |     (Scalar)            [ ]           |
|   Time                              |     (Scalar)            [s]           |
+-----------------------------------------------------------------------------+

Example 3: Use with DatamodelRoot() to get source-side variables for a data transfer


>>> DatamodelRoot().CouplingInterface['Interface-1'].DataTransfer['Transfer-1'].
PrintExpressionVariables() 
 
+-----------------------------------------------------------------------------+
|                             Available Variables                             |
+-----------------------------------------------------------------------------+
| Variable                            |   Tensor Type        Dimension        |
+-----------------------------------------------------------------------------+
| Target                              |                                       |
|   Loss                              |     (Scalar)       [kg m^2 s^-3]      |
| Source                              |                                       |
|   heatflow                          |     (Scalar)       [kg m^2 s^-3]      |
|   Position                          |     (Vector)            [m]           |
|   Normal                            |     (Vector)            [ ]           |
|   Area                              |     (Scalar)           [m^2]          |
|   Step                              |     (Scalar)            [ ]           |
|   Iteration                         |     (Scalar)            [ ]           |
|   Time                              |     (Scalar)            [s]           |
+-----------------------------------------------------------------------------+

 
Creating an Expression for a Mutable Time Step Size

When Duration Option is set to End Time, you can use an expression to define a mutable time step size for a coupled analysis. This can be done either in the GUI or the CLI.

Note:

  • When you create an expression to define a mutable time step size, System Coupling's Step, Time, and PreviousTimestepSize solution variables are the only variables that can be referenced in the expression.

  • Regardless of the duration option, you may define an immutable time step size as described in Creating an Expression for an Immutable Single Value.

Creating an Expression for a Mutable Time Step Size in the GUI

  1. Under Setup, click Solution Control.

  2. In the Properties pane below, enter in an expression for the Time Step Size setting.

    Note:

    • To add a System Coupling variable, right-click the field, select Insert variable, and select the variable to be used.

    • If one or more named expressions are defined, you can right-click the field and select Insert named expression.

Creating an Expression for a Mutable Time Step Size in the CLI

Enter the expression as the value of the TimeStepSize setting, as shown in the example below.


>>> DatamodelRoot().SolutionControl.TimeStepSize = '0.2 if Step < 5 else 0.25'

Tip:  To find out what variables may be referenced in the expression, use one of the methods described in Identifying Expression Variables for Mutable Values in the CLI.

 
Creating an Expression for a Data Transfer Source Variable

Expressions can be used to define real values for source-side data transfer variables.

Note:

  • Expressions are not supported for data transfer source variables with complex number values (that is, for source variables with DataType set to Complex).

  • Expressions are not supported for data transfers from solvers to FMUs.

When using expressions to define a source-side data transfer variable, keep the following considerations in mind:

  • The right-hand side of the expression must resolve to a quantity having the same dimensions as the target variable. If an expression references a source variable with a different IsExtensive property than the target variable, then the expression will need to be corrected by area or volume. For example, if transferring a variable with Force quantity type (for which isExtensive is set to True, with dimensions of Newtons) to the MAPDL Force Density variable (for which isExtensive is set to False, with dimensions of Force/Area), then the expression must divide by area, as follows:

    Value = 'Force / Area'

    Note:  The exception is when variables are accessed using the System Coupling GUI's Insert Variable option, in which case the correction is automatically included in the expression.

  • In most cases, expressions used in data transfers are used to make minor adjustments to the transferred quantities, such as scaling them up or down based on some physical considerations not included in the model (examples are provided below). It is also possible to have the expression be independent of any variable from the source participant. If doing so, keep the following in mind:

    • In an FSI simulation, you may want to replace the force transferred by the CFD participant with a uniform pressure force. The following example does this for the Force target variable, assuming a pressure of 2e5 [Pa]:

      Value = '2e5 [Pa] * Area * Normal'

    • The data transfer expression is evaluated on each mesh location of the interface. If the target variable has the IsExtensive property set and you would like to set the integrated quantity over all mesh locations, then you will need to scale the expression to account for it being applied on all mesh locations.

      For instance, suppose the target variable is Force (for which isExtensive is set to True), and you would like to impose a constant total force of 1 [N] in the x-direction distributed by the area associated with each mesh location. If the total area is 0.01 [m^2], then each mesh location will receive a fraction of the total force based on its area, as follows:

      Value = 'vector(1 [N] * Area / 0.01 [m^2], 0 [N], 0 [N])'

The following sections provide instructions on creating an expression to define data transfer source-side variable value(s):

 
Creating an Expression for a Data Transfer Source Variable in the GUI

To create an expression for a source-side data transfer variable in the GUI, perform the following steps:

  1. In the Outline tree under Coupling Interface, expand the Data Transfer branch.

  2. Click the data transfer for which you are defining the source-side variable.

    Corresponding settings are shown below in the Properties pane.

  3. Set Option to Using Expression.

  4. Set Target Side to the side of the interface that is to receive the data transfer, either One or Two.

    The Target Variable setting is automatically populated with the variable associated with the specified interface side.

    Value settings consistent with the Tensor Type of the Using Variable option's default source variable become available — that is, according to whether the default variable is a scalar or a vector.

  5. Set the source variable's value by entering an expression for its Value setting, as in the examples shown below:

    • For a variable with a scalar value:

      Value = '2e5 [Pa] * Area * Normal'

    • For a variable with a vector value:

      Value = 'vector(1 [N] * Area / 0.01 [m^2], 0 [N], 0 [N])'
    Tip:

    • To add a System Coupling variable, right-click the field, select Insert variable, and select the variable to be used.

    • If one or more named expressions are defined, you can right-click the field and select Insert named expression.

 
Creating an Expression for a Data Transfer Source Variable in the CLI

You can create source-variable expressions in the CLI either by running a command to add a data transfer or by editing the data model. For details, see:

Tip:  To find out what variables may be referenced in the expression(s), use one of the methods described in Identifying Expression Variables for Mutable Values in the CLI.

 
Creating a Source-Variable Expression by Running a Command

Run the AddDataTransfer() command, using the appropriate arguments to create an expression-based data transfer.

Set the source variable's value by entering an expression for its Value field, as shown in the example below.

Example 4: Add an expression-based transfer of a vector quantity 


>>> AddDataTransfer(
	Interface = 'Interface-1',
	TargetSide = 'One',
	TargetVariable = 'INCD',
	Value = 'vector(INCD * Position.x / 1[m], INCD * Position.y / 0.5 [m], 
	INCD * Position.z / 0.02 [m])')

When the command is run, the DataTransfer object is added to the coupling interface.

 
Creating a Source-Variable Expression by Editing the Data Model

  1. For the data transfer for which you are defining the source-side variable, set Option to UsingExpression.

    
>>> DatamodelRoot().CouplingInterface['Interface-1'].DataTransfer['Temperature-1']
.Option = 'UsingExpression'

  2. Set TargetSide to the side of the interface that is to receive the data transfer, either One or Two.

    
>>> DatamodelRoot().CouplingInterface['Interface-1'].DataTransfer['Temperature-1']
.TargetSide = 'Two'

    The TargetVariable setting is automatically populated with the variable associated with the specified interface side. Additional settings become available and are determined by the tensor type of the data transfer.

    Tip:  To reference a participant variable in the expression, use the value of its DisplayName setting when creating the expression.

  3. Set the source-side variable's value by entering an expression for its Value field, as shown in the examples below.

    Example 5: Add an expression-based transfer of a scalar quantity 

    
>>> DatamodelRoot().CouplingInterface['Interface-1'].DataTransfer['Temperature-1']
.Value = '100 [K]'

    Example 6: Add an expression-based transfer of a vector quantity 

    
>>> DatamodelRoot().CouplingInterface['Interface-1'].DataTransfer['Force-3']
.Value = 'vector(force.x*1.1, force.y, force.z)'

When the edits are applied, the data transfer object is available in the data model under the DataTransfer object container.