Expressions, Functions, Quantities, and Units

The Workbench expression parser supports standard math functions and operators, as well as units for quantities. Dimensional quantities are defined in units that are a combination of one or more separate units.

Workbench expression and mathematical function evaluation is based on the Python 2.6 programming language (See the Python website) and inherits some behavior as described here. All Python numeric and function capabilities can be used. For example, Python provides support for hexadecimal (base 16) numbers. Appending a zero and an x to the front of a number tells Python to treat the number as a hexadecimal numeric literal.

Expressions

When entering expressions, you must use the list and decimal separators defined in your locale settings. For example, if a comma is defined as a decimal separator and a semicolon defined as a list separator, use these when you type in an expression.

The expression defined for a custom Boolean parameter can be the Python values True or False, or it can be a Python logical expression such as P1 > P2 or P1 == 10 and P2 == 10. For a parameterized Boolean parameter, you can select True/False from the drop-down in the Value column.

The expression defined for a custom string parameter must be quoted with single or double quotes, such as ‘string value’ or "string value".

Do not start expression definitions with an = operator. Given existing parameters P1, P2, and P3 to define a derived parameter P4 such that P4=P1*P2*P3, type the expression P1*P2*P3 in the Value field.

When you click away from the field, the expression is solved.

Functions

Expressions support the following intrinsic functions, which support both standard numeric values and quantities as arguments.

abs(arg)	cos(arg)	int2(quantity, reference)	nint2(quantity, reference)	sinh(arg)
acos(arg)	cosh(arg)	log(arg)	pow(value, exponent)	sqrt(arg)
asin(arg)	exp(arg)	loge(arg)	round(arg)	tan(arg)
atan(arg)	fabs(arg)	log10(arg)	round2(quantity, reference)	tanh(arg)
atan2(arg1,arg2)	floor(arg)	max(arg list)	sign(arg)	PI, pi − constant
ceil(arg)	floor2(quantity, reference)	min(arg list)	sign2(quantity, reference)	E, e − constant
ceil2(quantity, reference)	int(arg)	nint(arg)	sin(arg)

Rounding Functions

The following rounding functions are designed to perform with, and restricted for use with, dimensionless quantity arguments for which the results are in the same unit system:

ceil
floor
int
nint
round
trunc

If these functions are used on quantities with units, an error message is displayed.

To perform rounding operations on quantities, use the following functions:

ceil2
floor2
int2
nint2
round2
trunc2

These functions support both numeric values and quantities. When used for quantities, the format is func(quantity, reference). The quantity argument is converted to the unit of the reference argument, then the resultant quantity value is rounded to the nearest reference value.

For example, to calculate a ceiling value rounded up to the nearest whole meter, enter ceil2(quantity, 1[m]).

Sign Function

Like the rounding functions, the sign function is designed for dimensionless quantities and numbers. To perform this operation on quantities, use the sign2 function.

The format is sign2(quantity, reference), but in this case the value of the reference argument has no significance in the calculation, only the unit used for conversion matters.

For example, both sign2(3 [cm], 1 [in]) and sign2(3 [cm], 10 [in]) return 1, indicating that the value of 3 cm converted into inches is a positive number.

Trigonometric Functions

The arguments for trigonometric functions are evaluated as follows:

If the argument is a real number or integer, the argument is evaluated as radians.
If the argument is a quantity (which has a value and units), the argument must be of type Angle. The evaluation is based on the supplied units ([deg] or [rad]).

Quantities

Expressions that involve quantities must be dimensionally consistent. The + and − operators require that the two operands have compatible units. For example, you cannot add an Area parameter to a Length parameter. Both units must be Length or both units must be Area. The * and / operators do not have this limitation. They allow one operand to be a quantity with a unit and the other operand to be a dimensionless factor. Or, they allow both operands to be quantities with units where the result is a different quantity type. For example, Length/Time results in a quantity with a Velocity unit.

If the expression defining a custom parameter results in a quantity, Workbench infers its quantity name from the value produced by the expression evaluation. Consequently, if the expression is a sum of multiple terms, every term must be using the same quantity name. For example, if the resulting quantity is 3.4[m^2], the new custom parameter must have its Quantity Name property set to Area. In some cases, more than one quantity name may be valid for the expression. In these cases, the Quantity Name property is not set, but you can select from a list for the Quantity Name property in the Properties pane for the parameter. Once the quantity name is determined from the unit of the value, it can be subsequently changed only by changing the Quantity Name property for the parameter. For example, you cannot change the expression from Area to Volume without changing the Quantity Name property.

Once the value quantity name (such as Area) is determined from the unit of the value, it can only be subsequently changed by changing the Quantity Name property for the parameter. You cannot change the expression (for example, from area to volume) without changing the Quantity Name property. Automatic unit conversion is only done when the quantity name is known. If you want to express a temperature difference, start with temperature in absolute units.

Units

You can include units, assuming that the unit makes sense in context of the expression. For example, P2+3[mm]*P3 is valid if mm is a valid unit expression for P2 and P3. For example, mm is a valid unit expression if P2 is torque and P3 is force, or if P2 is area and P3 is length.

The project unit system is used to evaluate the expressions. For temperatures, absolute temperature values are used in expression evaluation. All quantity values in an expression are converted to the project unit system.

The general units syntax in Workbench is defined as multiplier|unit|^power, where:

multiplier is a multiplying quantity or its abbreviation, such as mega (M) or pico (p)
unit is the unit string or abbreviation, such as gram (g), pound (lb), foot (ft), or meter (m)
power is the power to which the unit is raised

The following tables are examples of multipliers and commonly used units

Table 7: Unit Multipliers

Multiplier Name	Multiplier Value	Multiplier Abbreviation
exa	10¹⁸	E
peta	10¹⁵	P
tera	10¹²	T
giga	10⁹	G
mega	10⁶	M
kilo	10³	k
hecto	10²	h
deca	10¹	da
deci	10^-1	d
centi	10^-2	c
milli	10^-3	m
micro	10^-6	u
nano	10^-9	n
pico	10^-12	p
femto	10^-15	f
atto	10^-18	a

Table 8: Example Quantities and Units

Quantity

Dimensionality

Example Units

Acceleration

Length Time^-2

m s^-2

ft s^-2

in s^-2

um ms^-2

Current

Density

Mass Length^-3

kg m^-3

g cm^-3

lb ft^-3

slug in^-3

slinch in^-3

Electric Charge

Current Time

A s

coulomb

pA s

Energy

Mass Length^2 Time^-2

BTU

erg

lbf ft

slug in^2 s^-2

Force

Mass Length Time^-2

dyne

pdl

lbf

slug in s^-2

Length

foot

micron

yard

Pressure

Mass Length^-1 Time^-2

MPa

N m^-2

bar

torr

mm Hg

psi

psf

atm

dyne cm^-2

Power

Mass Length^2 Time^-3

BTU s^-1

erg s^-1

lbf ft s^-1

Temperature

Temperature Difference

Temperature

Temperature Variance

Temperature^2

K^2

C^2

R^2

F^2

When typing units in an expression, you must enclose the units in square braces [...]. You generally do not see the braces when selecting units from a list of commonly used units. In general, units declarations must obey the following rules:

A units string consists of one or more units quantities, each with an optional multiplier and optional power. Each separate units quantity is separated by one or more spaces.
Abbreviations for multipliers and unit names are typically used, but full names are also supported.
Powers are denoted by the ^ (caret) symbol. A power of 1 is assumed if no power is given. A negative power is typically used for unit division. For example, [kg m^-3] corresponds to kilograms per cubic meter.
If you enter units that are inconsistent with the physical quantity being described, then an expression error occurs.
Units do not have to be given in terms of the fundamental units, which are mass, length, time, temperature, angle, and solid angle. For instance, Pa (Pascals) and J (Joules) are both acceptable as parts of unit strings.
Units strings are case sensitive. For example, Kg and KG are invalid units strings; kg is correct.

Caution: When the specified project unit system uses the relative temperature units (C or F), the evaluation of expressions involving temperature, temperature differences, or temperature variances is a special case.

For the unit conversion of a specific temperature value, 1 degC = 274.15 K. However, the unit conversion for a temperature interval (delta T) is 1 degC = 1 K. The expression evaluator takes any temperature value and treats it as a specific temperature (not a temperature interval) by converting it to the absolute unit of the project unit system (either K or R). If the intent is to perform the evaluation in terms of temperature intervals, you need to start with temperatures in absolute units.

Similarly, any expressions to be evaluated in terms of temperatures or temperature differences are converted to absolute units for calculation. In an expression with a temperature unit raised to a power other than 1 or a unit involving both temperatures and other units (for example a temperature gradient [C/m]), the temperature is assumed to be a temperature difference.

Table 9: Scenarios in which temperature-related units are converted before and during expression evaluation

Scenario	Example
Temperature unit conversion	10[C] * 2 = 566.3[K] = 293.15[C]
Temperatures appearing as part of a mixed unit are converted as temperature intervals	10[C/m] * 50 [m] = 500[K]
Temperatures raised to a power other than 1 are converted as temperature intervals	10[C^3] * 10[C] = 2831.5[K^4]

Sound Pressure Level and A Weighted Sound Pressure Level are dimensionless quantities with units dB and dBA, respectively.

Math operations between these two units or either of these and a numerical value will result in a value with no unit. For example, 10 db x 10 = 100. (no unit)
Math operations between either of these units and a dimensional unit will result in a value with the dimensional unit. For example, 10 db x 10 m = 100 m.