Expressions
Overview
It is possible to define properties using mathematical expressions. In the GUI, spin boxes or input fields that are bound to properties show a blue icon when activated. Clicking on the icon or typing the equal sign = opens the expression editor for that particular property. If the input field shows a ... button instead of an icon, the expression editor can be opened by right-clicking the property and selecting Expression... from the context menu.
A LabRPS expression is a mathematical expression using the standard mathematical operators, functions and predefined constants as described below. In addition, the expression may reference object properties, and also use conditionals. Numbers in an expression may have an optional unit attached to them.
Numbers may use either a comma ,
or a decimal point .
to separate whole digits from decimals. When the decimal marker is used, it must be followed by at least one digit. Thus, the expressions 1. + 2.
and 1, + 2,
are invalid, but 1.0 + 2.0
and 1,0 + 2,0
are valid.
Operators and functions are unit-aware, and require valid combinations of units, if supplied. For example, 2mm + 4mm
is a valid expression, while 2mm + 4
is not. This also applies to references to object properties that have units, such as Length properties. Thus Pad001.Length + 1
is invalid since it adds a pure number to a property with length units, it requires Pad001.Length + 1mm
.
Some unit related errors can seem unintuitive, with expressions either being rejected or producing results that do not match the units of the property being set. Here are some examples:
1/2mm
is not interpreted as half a millimeter but as 1/(2mm)
, resulting in: 0.5 mm^-1
.
sqrt(2)mm
is not valid because the function call is not a number. This has to be entered as sqrt(2) * 1mm
.
Function arguments
Multiple arguments to a function may be separated by either a semicolon ;
or a comma followed by a space ,
. In the latter case, the comma is converted to a semicolon after entry. When a semicolon is used, no trailing space is necessary.
Arguments may include references to cells in a spreadsheet. A cell reference consists of the cell's uppercase row letter followed by its column number, for example A1
. A cell may also be referenced by using the cell's alias instead, for example Spreadsheet.NumberOfSample
.
Referencing objects
As already shown above, you can reference an object by its DataName. But you can also use its DataLabel. In the case of a DataLabel, it must be enclosed in double <<
and >>
symbols, such as <<Label>>
.
You can reference any property of an object. For example, to reference a Cylinder's height, you may use Cylinder.Height
or <<Label_of_cylinder>>.Height
.
For more information about referencing objects.
Supported constants
The following constants are supported:
Constant | Description |
---|---|
e | Euler's number |
pi | Pi |
Supported operators
The following operators are supported:
Operator | Description |
---|---|
+ | Addition |
- | Subtraction |
* | Multiplication |
/ | Floating point Division |
% | Remainder |
^ | Exponentiation |
Supported functions
General mathematical functions
The following mathematical functions are supported:
Trigonometric functions
Trigonometric functions use degree as their default unit. For radians add rad
following the first value in an expression. So e.g. cos(45)
is the same as cos(pi rad / 4)
. Expressions in degrees can use either deg
or °
, e.g. 360deg - atan2(3; 4)
or 360° - atan2(3; 4)
. If an expression is without units and needs to be converted to degrees or radians for compatibility, multiply by 1deg
, 1°
or 1rad
as appropriate, e.g. (360 - X) * 1deg
; (360 - X) * 1°
; (0.5 + pi / 2) * 1rad
.
Function | Description | Input range |
---|---|---|
acos(x)
|
Arc cosine | -1 <= x <= 1 |
asin(x)
|
Arc sine | -1 <= x <= 1 |
atan(x)
|
Arc tangent, return value in the range -90° < value < 90° | all |
atan2(y; x)
|
Arc tangent of y/x accounting for quadrant, return value in the range -180° < value <= 180° | all, the invalid input x = y = 0 returns 0 |
cos(x)
|
Cosine | all |
cosh(x)
|
Hyperbolic cosine | all |
sin(x)
|
Sine | all |
sinh(x)
|
Hyperbolic sine | all |
tan(x)
|
Tangent | all, except x = n*90 with n = odd integer |
tanh(x)
|
Hyperbolic tangent | all |
hypot(x; y)
|
Pythagorean addition (hypotenuse), e.g. hypot(4; 3) = 5 | x and y >= 0 |
cath(x; y)
|
Given hypotenuse, and one side, returns other side of triangle, e.g. cath(5; 3) = 4 | x >= y >= 0 |
Exponential and logarithmic functions
Function | Description | Input range |
---|---|---|
exp(x)
|
Exponential function | all |
log(x)
|
Natural logarithm | x > 0 |
log10(x)
|
Common logarithm | x > 0 |
pow(x; y)
|
Exponentiation | all |
sqrt(x)
|
Square root | x >= 0 |
Rounding, truncation and remainder functions
Function | Description | Input range |
---|---|---|
abs(x)
|
Absolute value | all |
ceil(x)
|
Ceiling function, smallest integer value greater than or equal to x | all |
floor(x)
|
Floor function, largest integer value less than or equal to x | all |
mod(x; y)
|
Remainder after dividing x by y, sign of result is that of the dividend. | all, except y = 0 |
round(x)
|
Rounding to the nearest integer | all |
trunc(x)
|
Truncation to the nearest integer in the direction of zero | all |
Statistical / aggregate functions
Aggregate functions take one or more arguments.
Individual arguments to aggregate functions may consist of ranges of cells. A range of cells is expressed as two cell references separated by a colon :
, for example average(B1:B8)
or sum(A1:A4; B1:B4)
.
The cell references may also use cell aliases, for example average(StartTemp:EndTemp)
.
The following aggregate functions are supported:
Function | Description | Input range |
---|---|---|
average(a; b; c; ...)
|
Average value of the arguments, same as sum(a; b; c; ...) / count(a; b; c; ...) | all |
count(a; b; c; ...)
|
Count of the arguments, typically used for cell ranges | all |
max(a; b; c; ...)
|
Maximum value of the arguments | all |
min(a; b; c; ...)
|
Minimum value of the arguments | all |
stddev(a; b; c; ...)
|
Standard deviation of the values of the arguments | all |
sum(a; b; c; ...)
|
Sum of the values of the arguments, typically used for cell ranges | all |
String manipulation
String identification
Strings are identified in expressions by surrounding them with opening/closing double chevrons (as are labels).
In following example, "TEXT" is recognized as a string : <<TEXT>>
String concatenation
Strings can be concatenated using the '+' sign.
Following example <<MY>> + <<TEXT>>
will be concatenated to "MYTEXT".
String conversion
Numerical values can be converted to strings with the str
function:
str(SimulationPoint.Z.Value)
String formatting
String formatting is supported using the (old) %-style Python way.
All %-specifiers as defined in Python documentation.
Conditional expressions
Conditional expressions are of the form condition ? resultTrue : resultFalse
. The condition is defined as an expression that evaluates to either 0
(false) or non-zero (true).
Note that to use a boolean property as the condition this syntax must be used: VarSet.MyBool == 1 ? 10 mm : 15 mm
.
The following relational operators are defined:
Unit | Description |
---|---|
== | equal to |
!= | not equal to |
> | greater than |
< | less than |
>= | greater than or equal to |
<= | less than or equal to |
Units
Units can be used directly in expressions. The parser connects them to the previous value. So 2mm
or 2 mm
is valid while mm
is invalid because there is no preceding value.
All values must have a unit. Therefore you must in general use a unit for values in spreadsheets.
In some cases it works even without a unit, for example if you have e.g. in spreadsheet cell B1 just the number 1.5
and refer to it for a pad height. This only works because the pad height predefines the unit mm
that is used if no unit is given. It will nevertheless fail if you use for the pad height e.g. Sketch1.Constraints.Width - Spreadsheet.B1
because Sketch1.Constraints.Width
has a unit and Spreadsheet.B1
has not.
Units with exponents can directly be entered. So e.g. mm^3
will be recognized as mm³ and m^3
will be recognized as m³.
If you have a variable whose name is that of a unit you must put the variable between << >>
to prevent it from being recognized as a unit. For example if you have the dimension Sketch.Constraints.A
it would be recognized as the unit ampere. Therefore you must write it in the expression as Sketch.Constraints.<<A>>
.
The following units are recognized by the expression parser:
Amount of substance
Unit | Description |
---|---|
mmol | Millimole |
mol | Mole |
Angle
Unit | Description |
---|---|
° | Degree; alternative to the unit deg |
deg | Degree; alternative to the unit ° |
rad | Radian |
gon | Gradian |
S | Second of arc; alternative to the unit ″ |
″ | Second of arc; alternative to the unit S |
M | Minute of arc; alternative to the unit ′ |
′ | Minute of arc; alternative to the unit M |
Current
Unit | Description |
---|---|
mA | Milliampere |
A | Ampere |
kA | Kiloampere |
MA | Megaampere |
Electric capacitance
Unit | Description |
---|---|
pF | Picofarad |
nF | Nanofarad |
uF | Microfarad; alternative to the unit µF |
µF | Microfarad; alternative to the unit uF |
mF | Millifarad |
F | Farad; 1 F = 1 s^4·A^2/m^2/kg |
Electric charge
Unit | Description |
---|---|
C | Coulomb; 1 C = 1 A*s |
Electric conductivity
Unit | Description |
---|---|
uS | Microsiemens; alternative to the unit µS |
µS | Microsiemens; alternative to the unit uS |
mS | Millisiemens |
S | Siemens; 1 S = 1 s^3·A^2/kg/m^2 |
kS | KiloSiemens |
MS | MegaSiemens |
Electric inductance
Unit | Description |
---|---|
nH | Nanohenry |
uH | Microhenry; alternative to the unit µH |
µH | Microhenry; alternative to the unit uH |
mH | Millihenry |
H | Henry; 1 H = 1 kg·m^2/s^2/A^2 |
Electric potential
Unit | Description |
---|---|
mV | Millivolt |
V | Volt |
kV | Kilovolt |
Electric resistance
Unit | Description |
---|---|
Ohm | Ohm; 1 Ohm = 1 kg·m^2/s^3/A^2 |
kOhm | Kiloohm |
MOhm | Megaohm |
Energy/work
Unit | Description |
---|---|
mJ | Millijoule |
J | Joule |
kJ | Kilojoule |
eV | Electronvolt; 1 eV = 1.602176634e-19 J |
keV | Kiloelectronvolt |
MeV | Megaelectronvolt |
kWh | Kilowatt hour; 1 kWh = 3.6e6 J |
Ws | Watt second; alternative to the unit Joule |
VAs | Volt-ampere-second; alternative to the unit Joule |
CV | Coulomb-volt; alternative to the unit Joule |
cal | Calorie; 1 cal = 4.184 J |
kcal | Kilocalorie |
Force
Unit | Description |
---|---|
mN | Millinewton |
N | Newton |
kN | Kilonewton |
MN | Meganewton |
lbf | Pound of force |
Length
Unit | Description |
---|---|
nm | Nanometer |
um | Micrometer; alternative to the unit µm |
µm | Micrometer; alternative to the unit um |
mm | Millimeter |
cm | Centimeter |
dm | Decimeter |
m | Meter |
km | Kilometer |
mil | Thousandth of an inch; alternative to the unit thou |
thou | Thousandth of an inch; alternative to the unit mil |
in | Inch; alternative to the unit " |
" | Inch; alternative to the unit in |
ft | Foot; alternative to the unit ' |
' | Foot; alternative to the unit ft |
yd | Yard |
mi | Mile |
Luminous intensity
Unit | Description |
---|---|
cd | Candela |
Magnetic flux
Unit | Description |
---|---|
Wb | Weber; 1 Wb = 1 kg*m^2/s^2/A |
Magnetic flux density
Unit | Description |
---|---|
G | Gauss; 1 G = 1 e-4 T |
T | Tesla; 1 T = 1 kg/s^2/A |
Mass
Unit | Description |
---|---|
ug | Microgram; alternative to the unit µg |
µg | Microgram; alternative to the unit ug |
mg | Milligram |
g | Gram |
kg | Kilogram |
t | Tonne |
oz | Ounce |
lb | Pound; alternative to the unit lbm |
lbm | Pound; alternative to the unit lb |
st | Stone |
cwt | Hundredweight |
Power
Unit | Description |
---|---|
W | Watt |
kW | Kilowatt |
Pressure
Unit | Description |
---|---|
Pa | Pascal |
kPa | Kilopascal |
MPa | Megapascal |
GPa | Gigapascal |
uTorr | Microtorr; alternative to the unit µTorr |
µTorr | Microtorr; alternative to the unit uTorr |
mTorr | Millitorr |
Torr | Torr; 1 Torr = 133.32 Pa |
psi | Pound-force per square inch; 1 psi = 6.895 kPa |
ksi | Kilopound-force per square inch |
Temperature
Unit | Description |
---|---|
uK | Microkelvin; alternative to the unit µK |
µK | Microkelvin; alternative to the unit uK |
mK | Millikelvin |
K | Kelvin |
Time
Unit | Description |
---|---|
s | Second |
min | Minute |
h | Hour |
Hz (1/s) | Hertz |
kHz | Kilohertz, |
MHz | Megahertz |
GHz | Gigahertz |
THz | Terahertz |
Volume
Unit | Description |
---|---|
ml | Milliliter |
l | Liter |
cft | Cubicfoot |
Special imperial units
Unit | Description |
---|---|
mph | Miles per hour |
sqft | Square foot |
Unsupported units
The following commonly used units are not yet supported, for some an alternative is provided:
Unit | Description | Alternative |
---|---|---|
°C | Celsius | [°C] + 273.15 K |
°F | Fahrenheit; | ([°F] + 459.67) × 5/9 |
u | Atomic mass unit; alternative to the unit Da | 1.66053906660e-27 kg |
Da | Dalton; alternative to the unit u | 1.66053906660e-27 kg |
sr | Steradian | not directly |
lm | Lumen | not directly |
lx | Lux | not directly |
px | Pixel | not directly |
Invalid characters and names
The expression feature is very powerful but to achieve this power it has some limitations concerning some characters. To overcome this, LabRPS offers to use labels and reference them instead of the object names. In labels you can use almost all special characters.
In cases where you cannot use a label, such as the name of a sketch's constraints, you must be aware what characters are not allowed.
Labels
For labels there are no invalid characters, however some characters need to be escaped:
Characters | Description |
---|---|
' , \ , "
|
Need to be escaped by adding \ in front of them.
|
For example, the label Sketch\002
must be referenced as <<Sketch\\002>>
.
Names
Names of objects like dimensions, sketches, etc. may not have the characters or character sequences listed below, otherwise the name is invalid:
Characters / Character sequences | Description |
---|---|
+, -, *, /, ^, _, <, >, (, ), {, }, [, ], ., ,, = | Characters that are math operators or part of mathematical constructs |
A, kA, mA, MA, J, K, ' , ft , °, and many more! | Characters and character sequences that are units (see the Units paragraph) |
#, !, ?, §, $, %, &, :, ;, \, |, ~, ∆, ¿, and many more! | Characters used as placeholder or to trigger special operations |
pi, e | Mathematical constants |
´, `, ' , " | Characters used for accents |
space | A space defines the end of a name and can therefore not be used |
For example, the following name is valid: <<Sketch>>.Constraints.T2üßµ@
. While these are invalid names: <<Sketch>>.Constraints.test\result_2
(\r means "carriage return") or <<Sketch>>.Constraints.mol
(mol is a unit).
Since shorter names (especially if they have only one or two characters) can easily result in invalid names, consider using longer names and/or establishing a suitable naming convention.
Cell aliases
Cyclic dependencies
LabRPS checks dependencies based on the relationship between document objects, not properties. This means that you cannot provide data to an object and query that same object for results. For example, even though there are no cyclic dependencies when the properties themselves are considered, you may not have an object which gets its dimensions from a spreadsheet and then display the volume of that object in the same spreadsheet. You have to use two spreadsheets, one to drive your model and the other for reporting.
As a workaround it is possible to display a cell range from the second spreadsheet in the first (or vice versa) by creating a cell binding with the Hide dependency of binding option.
Another way to workaround cyclic dependencies is to hide the reference by using the href
or hiddenref
function for individual expressions, for example: href(Sim.ModulationFunction)
.
Please note that both mentioned workarounds should be used with caution, and that they do not work if the properties that are reported depend on dimensions that are driven from the same spreadsheet.
Document-wide global variables
There is no concept of global variables in LabRPS at the moment. Instead, arbitrary variables can be defined as cells in a spreadsheet using the Spreadsheet workbench, and then be given a name using the alias property for the cell (right-click on cell). Then they can be accessed from any expression just as any other object property.
Cross-document linking
It is possible (with limitations) to define a Property of an object in your current document (".RPSstd" file) by using an Expression to reference a Property of an object contained in a different document (".RPSstd" file). For example, a cell in a spreadsheet etc. in one document can be defined by an Expression that references the X Placement value or another Property of an object contained in a different document.
A document's name is used to reference it from other documents. When saving a document the first time, you choose a file name; this is usually different from the initial default "Unnamed1" (or its translated equivalent). To prevent links being lost when the master document is renamed upon saving, it is recommended that you first create the master document, create a spreadsheet inside it, and save it. Subsequently, you can still make changes to the file and its spreadsheet but you should not rename it.
Once the master document with the spreadsheet is created and saved (named), it is safe to create dependent documents. For example, assuming you name the master document master
, the spreadsheet modelConstants
, and give a cell an alias-name Length
, you can then access the value as:
master#modelConstants.Length
Note that the master document must be loaded for the values in the master to be available to the dependent document.
Of course, it's up to you to load the corresponding documents later when you want to change anything.
Scripting
import LabRPS as App doc = App.ActiveDocument point1 = doc.addObject("WindLabAPI::WindLabFeatureSimulationLocation", "Point1") point2 = doc.addObject("WindLabAPI::WindLabFeatureSimulationLocation", "Point2") point1.setExpression("Height", f"{point2}.Z / 2") doc.recompute() # Expressions are stored in the ExpressionEngine property: for prop, exp in point1.ExpressionEngine: val = getattr(point1, prop) print(f"Property: '{prop}' -- Expression: '{exp}' -- Current value: {val}")
- LabRPS scripting: Python, Introduction to Python, Python scripting tutorial, LabRPS Scripting Basics
- Modules: Units, Quantity
- Workbenches: Gui Commands, Commands
- Parametric objects: Scripted objects, Viewproviders
- Graphical interface: Interface creation, Interface creation completely in Python, PySide, PySide examples beginner, intermediate, advanced
- Macros: Macros, How to install macros
- Other: Expressions
- Hubs: User hub, Power users hub, Developer hub