Field Expression Syntax

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.
`$$V + 10 m/s`	The velocity vector field with an offset of 10 meters per second.
`sqrt($$V[1] 2 + $$V[2] 2 + $$V[3] ** 2)`	The magnitude of the velocity vector field.
`$$V.magnitude`	The magnitude of the velocity vector field.
`$$$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.

Unit strings might be appended to numeric literals. Units support multiplication, division, and exponentiation operators. The following are valid numeric literals with unit strings:

1 m
1e0m
1e2cm
100 cm
39.4 in
1 m/s
1 m / s
1 m*s**-1
2.24 mph
2.24 mi/hr
1 J
1 N*m

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} = {(\frac{9}{2} S : S \cdot S)}^{\frac{1}{3}}

The von Mises invariant of a tensor $S$ is:

q = \sqrt{\frac{3}{2} (S : S)}

Functions

The following functions are supported in field expressions. In the call signature, "string" refers to a string literal and "constant" refers to a nonfield scalar value or expression. Similarly, "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
	cbrt	cbrt(constant \| scalar)	The cubic root
	ceil	ceil(constant \| scalar)	Rounds to next greater integer
	exp	exp(constant \| scalar)	Exponential function
	floor	floor(constant \| scalar)	Rounds to next lesser integer
	ln	ln(constant \| scalar)	Natural logarithm
	log10	log10(constant \| scalar)	Base-10 logarithm
	round	round(constant \| scalar)	Rounds to nearest integer
	sign	sign(constant \| scalar)	Returns 1 if positive, -1 if negative
	sqrt	sqrt(constant \| scalar)	The square root
	trunc	trunc(constant \| scalar)	Truncates nonintegral digits
Trigonometric	sin	sin(constant \| scalar)	The trigonometric functions
	cos	cos(constant \| scalar)
	tan	tan(constant \| scalar)
	asin	asin(constant \| scalar)	The inverse trigonometric functions
	acos	acos(constant \| scalar)
	atan	atan(constant \| scalar)
	atan2	atan2(constant \| scalar, constant \| scalar)
	sinh	sinh(constant \| scalar)	The hyperbolic trigonometric functions
	cosh	cosh(constant \| scalar)
	tanh	tanh(constant \| scalar)
	asinh	asinh(constant \| scalar)	The inverse hyperbolic trigonometric functions
	acosh	acosh(constant \| scalar)
	atanh	atanh(constant \| scalar)
Field	frame	frame (scalar\|vector\|tensor), string\|constant, constant, string\|constant	Lock a given expression ( to a specific step, frame, or load case). A value of -1 indicates the currently selected step, frame, or load case. first argument: field expression to lock second argument: step ID or number (default: -1) third argument: frame number (default: -1) fourth argument: load case ID or number (default: -1)
	mass_average	mass_average(scalar)	The mass-averaged value of a field
	mass_integral	mass_integral(scalar)	The integral of the field multiplied by mass
	massflow	massflow()	The mass flow through a surface
	massflow_average	massflow_average(scalar)	The average mass flow value of a field through a surface
	massflux	massflux()	The mass flux
	max	max(scalar)	The maximum value in the field
	min	min(scalar)	The minimum value in the field
	sum	sum(scalar)	The sum of all values in the field
	surface_average	surface_average(scalar)	The surface area-averaged value of a field
	surface_integral	surface_integral(scalar)	The integral of the field multiplied by surface area
	volume_average	volume_average(scalar)	The volume-averaged value of a field
	volume_integral	volume_integral(scalar)	The integral of the field multiplied by volume
	uniformity	uniformity(scalar)	The uniformity of the field
Vector	dot	dot(vector, vector)	The inner-product of two vector fields
Vector	cross	cross(vector, vector)	The cross product of two vector fields
Gradients	curl	curl(vector)	The curl of a field
	div	div(vector)	The divergence of a field
	grad	grad(scalar \| vector)	The gradient of a field
	qcriterion	qcriterion(vector)	The Q-Criterion function
Other	tr	tr(tensor)	The trace of a tensor
Other	transform	transform(vector \| tensor, string)	The field in an alternate user-defined coordinate system

The surface uniformity of a scalar field is defined as:

u (x) = 1 - \frac{s a (| s a (x) - x |)}{2 \cdot s a (| x |)},

where

sa

is the surface average given by

s a (x) = \frac{\sum (x \cdot ‖ \overset{⇀}{A} ‖)}{\sum ‖ \overset{⇀}{A} ‖} .

The Q-Criterion of a vector $v$ is:

Q = \frac{1}{2} ({| \nabla v - {(\nabla v)}^{T} |}^{2} - {| \nabla v + {(\nabla v)}^{T} |}^{2})