Field Expression Syntax

The following sections describe the field expression syntax:

This page discusses:

 

See Also
Field Expressions
Using Field Expressions

Overview

Field expressions are defined in a syntax similar to JavaScript, but with some notable exceptions. Examples of valid expressions include:

Expression Description
$NT The standard nodal temperature scalar field.
$$V The standard velocity vector field.
sqrt($$V[1] ** 2 + $$V[2] ** 2 + $$V[3] ** 2) The magnitude of the velocity vector field.
$$V.magnitude
$$$S[1,1] The x-component normal stress of the stress tensor field.
$$COORD / max($$COORD.magnitude) The normalized nodal position vector.
transform($$U, "CSYS.1")[1] The first component of the displacement vector in a user-defined coordinate system CSYS.1.

Literals

Numeric

Numeric literals can be written in decimal or exponential notation. The following numbers are equivalent:

  • .1234
  • 0.1234
  • 1.234e-1
  • 1.234E-1
  • 0.01234e+01
  • 0.01234e1
A single leading plus (+) or minus (-) sign is allowed.

Boolean

Boolean literals true and false are supported. When they are used in numeric contexts, true is evaluated as 1, and false is evaluated as 0. For example, 1 + true evaluates to 2.

If a logical expression is used within Physics Results Explorer, the Boolean value is converted to an integer: either 0 (for false values) or 1 (for true values).

String

Where string literals are supported, they are enclosed in single quotes or double quotes. For example: 

            "MY_CSYS"

Constants

The following mathematical constants are available:

Name Approximate Value
E 2.718282
PI 3.141593

Operators

Arithmetic Operators

The following arithmetic operations are available:

Operator Description
+ Addition (or unary positive)
- Subtraction (or unary negative)
* Scalar multiplication
/ Scalar division
% Modulo
** Exponentiation

Logical Operators

The following logical operations are available:

Operator Description
|| Logical OR
&& Logical AND
! Logical NOT

Comparison Operators

The following comparison operations are available:

Operator Description
< Less than
<= Less than or equal
== Equal
!= Not equal
>= Greater than or equal
> Greater than

Ternary Operator

The ternary if-then-else operator is available as: 

            <condition> ? <if true> : <if false>
where <condition> is a logical expression. If true, the value is <if true>; if false, the value is <if false>.

Fields or Field Expressions

Access result fields or other field expressions by prepending the name of the field with $ (for scalar fields), $$ (for vector fields), or $$$ (for tensor fields).

For example, to reference the vector field of velocity, use 

          $$V

If a scalar field is used in a logical expression, all zero values in the field are interpreted as logically false, while all other values are interpreted as logically true.

Components of a Vector or Tensor

Access components of a vector or tensor using bracket notation, with the component index starting at 1. For example, you can access the first component of a vector expression by using: 

          ($$V * 5)[1]

To access the 1-2 component of a tensor, use: 

          ($$$S * 2)[1,2]

Invariants of a Vector or Tensor

Access invariants of a vector or tensor using dot notation. For example, the magnitude of the velocity field is expressed as: 

          $$V.magnitude
Supported invariants are:
Name Application Description
magnitude Vectors Magnitude of a vector
inv1 Tensors First invariant (trace)
inv3 Tensors Third invariant
min_principal Tensors Minimum principal value
mid_principal Tensors Middle principal value
max_principal Tensors Maximum principal value
absmax_principal Tensors Maximum (absolute value) principal value
mises Tensors Von Mises invariant
tresca Tensors Tresca invariant (difference between minimum and maximum principal values)

The third invariant of a tensor S is:

III 3 = ( 92 S : S ⋅ S ) 13

The von Mises invariant of a tensor S is:

q = 32 ( S : S )

Functions

The following functions are supported in field expressions. In the call signature, "string" refers to a string literal, "constant" refers to a non-field scalar value or expression, while "scalar", "vector", and "tensor" refer to scalar, vector, or tensor fields, respectively.

Category Name Signature Description of returned value
Arithmetic abs abs( constant | scalar | vector | tensor ) Rounds to nearest integer
round round( constant | scalar ) Rounds to nearest integer
ceil ceil( constant | scalar ) Rounds to next greater integer
floor floor( constant | scalar ) Rounds to next lesser integer
trunc trunc( constant | scalar ) Truncates non-integral digits
sign sign( constant | scalar ) Returns 1 if positive, -1 if negative
ln ln( constant | scalar ) Natural logarithm
log10 log10( constant | scalar ) Base-10 logarithm
exp exp( constant | scalar ) Exponential function
sqrt sqrt( constant | scalar ) The square root
cbrt cbrt( constant | scalar ) The cubic root
Trigonometric sin sin( constant | scalar ) The trigonometric sine function
asin asin( constant | scalar ) The inverse trigonometric sine function
sinh sinh( constant | scalar ) The hyperbolic sine function
asinh asinh( constant | scalar ) The inverse hyperbolic sine function
cos cos( constant | scalar ) The trigonometric cosine function
acos acos( constant | scalar ) The inverse trigonometric cosine function
cosh cosh( constant | scalar ) The hyperbolic cosine function
acosh acosh( constant | scalar ) The inverse hyperbolic cosine function
tan tan( constant | scalar ) The trigonometric tangent function
atan atan( constant | scalar ) The inverse trigonometric tangent function
atan2 atan2( constant | scalar , constant | scalar ) The inverse trigonometric tangent function (accepts two arguments: the numerator and denominator)
tanh tanh( constant | scalar ) The hyperbolic tangent function
atanh atanh( constant | scalar ) The inverse hyperbolic tangent function
Field min min( scalar ) Returns the minimum value in the field
max max( scalar ) Returns the maximum value in the field
sum sum( scalar ) Sums all values in the field
volume_integral volume_integral( scalar ) Returns the integral of the field multiplied by volume
volume_average volume_average( scalar ) Returns the volume-averaged value of a field
mass_integral mass_integral( scalar ) Returns the integral of the field multiplied by mass
mass_average mass_average( scalar ) Returns the mass-averaged value of a field
surface_integral surface_integral( scalar ) Returns the integral of the field multiplied by surface area
surface_average surface_average( scalar ) Returns the surface area-averaged value of a field
Vector dot dot( vector , vector ) The inner-product of two vector fields
cross cross( vector , vector ) The cross-product of two vector fields
Gradients grad grad( scalar | vector ) The gradient of a field
div div( vector ) The divergence of a field
curl curl( vector ) The curl of a field
qcriterion qcriterion( vector ) The Q-Criterion function
Other tr tr( tensor ) The trace of a tensor
transform transform( vector | tensor , string ) Returns a field in an alternate user-defined coordinate system

The Q-Criterion of a vector v is:

Q= 12 ( | ∇ v - ( ∇ v ) T | 2 - | ∇ v + ( ∇ v ) T | 2 )