Expressions: Difference between revisions

From FreeCAD Documentation
(some corrections)
(revise list referencing to avoid confusions between name and label)
(33 intermediate revisions by 6 users not shown)
Line 1: Line 1:
<languages/>
<languages/>


<translate>
<!--T:26-->
<div style="float:right; clean:both; margin-left:0.5em;">__TOC__</div>
<div style="float:right; clean:both; margin-left:0.5em;">__TOC__</div>
<translate>


<!--T:1-->
==Overview== <!--T:1-->
{{Version|0.16}}


<!--T:2-->
<!--T:2-->
It is now possible to define properties using mathematical expressions. From the GUI, spin boxes or input fields that are bound to properties contain a blue icon [[Image:Sketcher_Expressions.png|24px]]. Clicking on the icon or typing the equal sign (=) brings up the expression editor for that particular property.
It is possible to define properties using mathematical expressions. From the GUI, spin boxes or input fields that are bound to properties contain a blue icon [[Image:Sketcher_Expressions.png|24px]]. Clicking on the icon or typing the equal sign (=) brings up the expression editor for that particular property.


<!--T:3-->
<!--T:3-->
A FreeCAD expression is a mathematical expression following notation for the standard mathematical operators and functions as described below. In addition, the expression may reference other properties, and also use conditionals. Numbers in an expression may have an optional unit attached to them.
A FreeCAD expression is a mathematical expression following notation for the standard mathematical operators and functions as described below. In addition, the expression may reference other properties, and also use conditionals. Numbers in an expression may have an optional unit attached to them.


<!--T:62-->
<!--T:54-->
Numbers may use either a comma ',' or a decimal point '.' separating whole digits from decimals.
Numbers may use either a comma ',' or a decimal point '.' separating whole digits from decimals.
When the decimal marker is used, it ''must'' be followed by at least one digit.
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.
Thus, the expressions '''1.+2.''' and '''1,+2,''' are invalid, but '''1.0 + 2.0''' and '''1,0 + 2,0''' are valid.

<!--T:4-->
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 (the reason for this is that an expression like '''1in + 4''' will most likely be interpreted as '''1in + 4in''' by humans, but all units are converted to the SI system internally, and the system is not able to guess this). These [[#Units|units]] are currently recognized.


<!--T:27-->
<!--T:27-->
You can use [[#Supported Constants|predefined constants]] and [[#Supported Functions|functions]].
The constants ''pi'' and ''e'' are predefined, and must be written in lowercase.


<!--T:4-->
===Referencing objects=== <!--T:69-->

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 (the reason for this is that an expression like 1in + 4 will most likely be interpreted as 1in + 4in by humans, but all units are converted to the SI system internally, and the system is not able to guess this).
<!--T:67-->
You can reference to an object by its {{incode|Name}} or by its {{incode|Label}}. In the case of a {{incode|Label}}, it must be enclosed in double {{incode|<<}} and {{incode|>>}} symbols, such as {{incode|<<Label>>}}.

<!--T:70-->
You can reference any numerical property of this object. For example, to refer to a Cylinder's height, you may use {{incode|Cylinder.Height}} or {{incode|<<Long_name_of_cylinder>>.Height}}.

<!--T:71-->
To reference list objects, the syntax is {{incode|<<object_label>>.list[list_index]}} or {{incode|object_name.list[list_index]}}. If you want for example reference a constraint in a sketch, do it this way '''<<MySketch>>.Constraints[16]'''. If you are in the same sketch you can omit its name and just use '''Constraints[16]'''.<br/>
'''Note:''' The index starts with 0, therefore constraint 17 has the index 16.

<!--T:72-->
For more info about referencing objects, see [[#Reference To CAD-Data|this section]].


== Supported Operators == <!--T:52-->
==Supported Operators== <!--T:52-->


<!--T:53-->
<!--T:53-->
The following operators are supported:
The following operators are supported:
{| class="wikitable float-right mw-collapsible mw-uncollapsed"
{| class="wikitable float-right mw-collapsible mw-uncollapsed"
!style="width: 33%;"|Unit
!style="width: 33%;"|Operator
!style="width: 66%;"|Description
!style="width: 66%;"|Description
|-
|-
Line 47: Line 60:
| ^
| ^
| [https://en.wikipedia.org/wiki/Exponentiation Exponentiation]
| [https://en.wikipedia.org/wiki/Exponentiation Exponentiation]
|}

==Supported Constants== <!--T:58-->

<!--T:59-->
The following constants are supported:
{| class="wikitable float-right mw-collapsible mw-uncollapsed"
!style="width: 33%;"|Constant
!style="width: 66%;"|Description
|-
| e
| [https://en.wikipedia.org/wiki/E_(mathematical_constant) Euler's number]
|-
| pi
| [https://en.wikipedia.org/wiki/Pi Pi]
|}
|}


== Supported Functions == <!--T:5-->
== Supported Functions == <!--T:5-->


=== General Mathematical Functions === <!--T:64-->
=== General Mathematical Functions === <!--T:55-->


<!--T:7-->
<!--T:7-->
Line 57: Line 85:


<!--T:28-->
<!--T:28-->
Multiple arguments to a function may be separated by either a semicolon (';') or
Multiple arguments to a function may be separated by either a semicolon ';' or a comma <em>followed by a space</em> ', '. In the latter case, the comma is converted to a semicolon after entry. When a semicolon is used, no trailing space is necessary.
a comma <em>followed by a space</em> (", ").
In the latter case, the comma is converted to a semicolon after entry.
When a semicolon is used, no trailing space is necessary.


<!--T:29-->
<!--T:29-->
[https://en.wikipedia.org/wiki/Trigonometric_functions Trigonometric functions] use degree as their default unit. For radian measure, add '''rad''' following the <em>first</em> value in an expression. So e.g. '''cos(45)''' is the same as '''cos(pi rad / 4)'''.<br/>
Trigonometric functions use degrees as their default unit;
These trigonometric functions are supported:
for radian measure, add '''rad''' following the <em>first</em> value in an expression.
{| class="wikitable float-right mw-collapsible mw-collapsed"
Example: cos(45) is the same as cos(pi rad / 4).
!style="width: 33%;"|Function
!style="width: 33%;"|Description
!style="width: 33%;"|Value range
|-
| acos(x)
| [https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties Arc cosine]
| -1 <= x <= 1
|-
| asin(x)
| [https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties Arc sine]
| -1 <= x <= 1
|-
| atan(x)
| [https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties Arc tangent]
| all
|-
| atan2(x, y)
| [https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties Arc tangent] of ''x/y''
| all, except y = 0
|-
| cos(x)
| [https://en.wikipedia.org/wiki/Trigonometric_functions#Right-angled_triangle_definitions Cosine]
| all
|-
| cosh(x)
| [https://en.wikipedia.org/wiki/Hyperbolic_function#Trigonometric_definitions Hyperbolic cosine]
| all
|-
| sin(x)
| [https://en.wikipedia.org/wiki/Trigonometric_functions#Right-angled_triangle_definitions Sine]
| all
|-
| sinh(x)
| [https://en.wikipedia.org/wiki/Hyperbolic_function#Trigonometric_definitions Hyperbolic sine]
| all
|-
| tan(x)
| [https://en.wikipedia.org/wiki/Trigonometric_functions#Right-angled_triangle_definitions Tangent]
| all, except of x = n·90 with n = integer
|-
| tanh(x)
| [https://en.wikipedia.org/wiki/Hyperbolic_function#Trigonometric_definitions Hyperbolic tangent]
| all
|}


<!--T:30-->
<!--T:30-->
These functions for exponentiation and logarithmization are supported:
{{APIFunction |abs|x| Absolute value | value <nowiki> >= 0 </nowiki> }}
{| class="wikitable float-right mw-collapsible mw-collapsed"
{{APIFunction |acos|x| Arc cosine; <nowiki> -1 <= x <= 1 </nowiki> | acos(x) }}
!style="width: 33%;"|Function
{{APIFunction |asin|x| Arc sine; <nowiki> -1 <= x <= 1 </nowiki> | asin(x) }}
!style="width: 33%;"|Description
{{APIFunction |atan|x| Arc tangent | atan(x) }}
!style="width: 33%;"|Value range
{{APIFunction |atan2|y, x| Arc tangent of y / x; | atan2(y,x) }}
|-
{{APIFunction |ceil|x| Ceiling | The smallest integer value greater than or equal to x {{Version|0.16}} }}
| exp(x)
{{APIFunction |cos|angle| Cosine; angle is in degrees (any value) | <nowiki> -1 <= cos(x) <= 1 </nowiki> }}
| [https://en.wikipedia.org/wiki/Exponential_function#Formal_definition Exponential function]
{{APIFunction |cosh|x| Hyperbolic cosine of x | cosh(x) }}
| all
{{APIFunction |exp|y| Natural exponent | e<sup> y</sup> }}
|-
{{APIFunction |floor|x| Floor | The largest integer value less than or equal to x {{Version|0.16}} }}
| log(x)
{{APIFunction |log|x| Natural logarithm | log<sub>e</sub> x }}
| [https://en.wikipedia.org/wiki/Natural_logarithm Natural logarithm]
{{APIFunction |log10|x| Logarithm base 10 | log<sub>10</sub> x }}
| x > 0
{{APIFunction |mod|x, y| Remainder x/y | Remainder after dividing x by y }}
|-
{{APIFunction |pow|x, y| Power function| x<sup> y</sup> }}
| log10(x)
{{APIFunction |round|x| | x rounded to the nearest integer {{Version|0.16}} }}
| [https://en.wikipedia.org/wiki/Common_logarithm Common logarithm]
{{APIFunction |sin|angle| Cosine; angle in degrees (any value) | <nowiki> -1 <= sin(x) <= 1 </nowiki> }}
| x > 0
{{APIFunction |sinh|x| Hyperbolic sine of x | sinh(x) }}
|-
{{APIFunction |sqrt|x| Square root; <nowiki> x >= 0 </nowiki> | Square root of x }}
| pow(x, y)
{{APIFunction |tan|angle| Tangent; angle in degrees (any value) | tan(angle) }}
| [https://en.wikipedia.org/wiki/Exponentiation Exponentiation]
{{APIFunction |tanh|x| Hyperbolic tangent of x | tanh(x) }}
| all
{{APIFunction |trunc|x| Truncate | x truncated to the nearest integer {{Version|0.16}} }}
|-

| sqrt(x)
=== Statistical / Aggregating Functions === <!--T:8-->
| [https://en.wikipedia.org/wiki/Square_root Square root]
The aggregating functions listed below are supported.
| x >= 0
Aggregating functions take one or more arguments, separated by a semicolon ';' or a comma <em>and</em> a space ", ".
|}
Arguments may include references to cells in a spreadsheet;
cell references consist of the (CAPITAL) row letter followed by the column number.
Arguments may include ranges of cells (two cell references separated by a colon).
Example: ''average(B1:B8)''


<!--T:31-->
<!--T:31-->
These functions for rounding, truncation and remainder are supported:
{{APIFunction |average|x y| Average of values in cells x through y | sum(x, y) / count(x, y) }}
{| class="wikitable float-right mw-collapsible mw-collapsed"
{{APIFunction |count|x y| Number of cells from x through y | The number of cells from x through y, inclusive }}
!style="width: 20%;"|Function
{{APIFunction |max|x y| Maximum value in cells x through y | Maximum value }}
!style="width: 55%;"|Description
{{APIFunction |min|x y| Minimum value in cells x through y | Minimum value }}
!style="width: 25%;"|Value range
{{APIFunction |stddev|x y| Standard deviation of values in cells x through y | Standard deviation }}
|-
{{APIFunction |sum|x y| Sum of values in cells x through y | Sum }}
| abs(x)
| [https://en.wikipedia.org/wiki/Absolute_value Absolute value]
| all
|-
| ceil(x)
| [https://en.wikipedia.org/wiki/Floor_and_ceiling_functions Ceiling function] smallest integer value greater than or equal to x
| all
|-
| floor(x)
| [https://en.wikipedia.org/wiki/Floor_and_ceiling_functions Floor function], largest integer value less than or equal to x
| all
|-
| mod(x, y)
| [https://en.wikipedia.org/wiki/Remainder Remainder] after dividing ''x'' by ''y''
| all, except y = 0
|-
| round(x)
| [https://en.wikipedia.org/wiki/Rounding Rounding] to the nearest integer
| all
|-
| trunc(x)
| [https://en.wikipedia.org/wiki/Truncation Truncation] to the nearest integer
| all
|}

=== Statistical / Aggregate Functions === <!--T:8-->
[https://en.wikipedia.org/wiki/Aggregate_function Aggregate functions] take one or more arguments, separated by a semicolon ';' or a comma ''and'' a space ', '.<br/>
Arguments may include references to cells in a spreadsheet. Cell references consist of the (CAPITAL) row letter followed by the column number.<br/>
Arguments may include ranges of cells (two cell references separated by a colon), for example '''average(B1:B8)'''.

<!--T:60-->
These aggregate functions are supported:
{| class="wikitable float-right mw-collapsible mw-collapsed"
!style="width: 20%;"|Function
!style="width: 55%;"|Description
!style="width: 25%;"|Value range
|-
| average(x:y)
| [https://en.wikipedia.org/wiki/Arithmetic_mean Arithmetic mean] of values in cells x through y; sum(x:y) / count(x:y)
| all
|-
| count(x:y)
| [https://en.wikipedia.org/wiki/Counting Counting] of cells from x through y
| all
|-
| max(x:y)
| [https://en.wikipedia.org/wiki/Maxima_and_minima Maximum] value in cells x through y
| all
|-
| min(x:y)
| [https://en.wikipedia.org/wiki/Maxima_and_minima Minimum] value in cells x through y
| all
|-
| stddev(x:y)
| [https://en.wikipedia.org/wiki/Standard_deviation Standard deviation] of values in cells x through y
| all
|-
| sum(x: y)
| [https://en.wikipedia.org/wiki/Summation Sum] of values in cells x through y
| all
|}


== Conditional Expressions == <!--T:32-->
== Conditional Expressions == <!--T:32-->
Line 139: Line 266:


<!--T:35-->
<!--T:35-->
Units can directly be used in expressions. The parser connects them the the previous value. So ''''2mm'''' or ''''2 mm'''' is valid while '''' mm'''' is invalid because there is no preceding value.
Units can directly be used 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.

<!--T:56-->
All values must have a unit. Therefore you must in general use a unit for values in spreadsheets.<br/>
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.

<!--T:57-->
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³.


<!--T:36-->
<!--T:36-->
Line 174: Line 308:
| gon
| gon
| [https://en.wikipedia.org/wiki/Gon_(unit) Gradian]
| [https://en.wikipedia.org/wiki/Gon_(unit) Gradian]
|-
| S
| [https://en.wikipedia.org/wiki/Minute_and_second_of_arc Second of arc]
|-
| ″
| [https://en.wikipedia.org/wiki/Minute_and_second_of_arc Second of arc]; alternative to the unit ''S''
|-
| M
| [https://en.wikipedia.org/wiki/Minute_and_second_of_arc Minute of arc]
|-
| ′
| [https://en.wikipedia.org/wiki/Minute_and_second_of_arc Minute of arc]; alternative to the unit ''M''
|}
|}


Line 209: Line 355:
| VAs
| VAs
| [https://en.wikipedia.org/wiki/Joule Volt-ampere-second]; alternative to the unit ''Joule''
| [https://en.wikipedia.org/wiki/Joule Volt-ampere-second]; alternative to the unit ''Joule''
|-
| CV
| [https://en.wikipedia.org/wiki/Joule Coulomb·Volt]; alternative to the unit ''Joule''
|}
|}


Line 338: Line 487:
|}
|}


<!--T:46-->
<!--T:61-->
Power:
Power:
{| class="wikitable float-right mw-collapsible mw-collapsed"
{| class="wikitable float-right mw-collapsible mw-collapsed"
Line 421: Line 570:
| h
| h
| [https://en.wikipedia.org/wiki/Hour Hour]
| [https://en.wikipedia.org/wiki/Hour Hour]
|-
| Hz (1/s)
| [https://en.wikipedia.org/wiki/Hertz Hertz], {{Version|0.19}}
|-
| kHz
| Kilo[https://en.wikipedia.org/wiki/Hertz hertz], {{Version|0.19}}
|-
| MHz
| Mega[https://en.wikipedia.org/wiki/Hertz hertz], {{Version|0.19}}
|-
| GHz
| Giga[https://en.wikipedia.org/wiki/Hertz hertz], {{Version|0.19}}
|}
|}


Line 453: Line 614:
| [https://en.wikipedia.org/wiki/Coulomb Coulomb]
| [https://en.wikipedia.org/wiki/Coulomb Coulomb]
| 1 A*s
| 1 A*s
|-
| mV
| Milli[https://en.wikipedia.org/wiki/Volt volt]
| 0.001 V/A
|-
|-
| V
| V
| [https://en.wikipedia.org/wiki/Volt Volt]
| [https://en.wikipedia.org/wiki/Volt Volt]
| 1 V/A
| 1 W/A
|-
| kV
| Kilo[https://en.wikipedia.org/wiki/Volt volt]
| 1000 V/A
|-
|-
| eV
| eV
| [https://en.wikipedia.org/wiki/Electronvolt Electronvolt]
| [https://en.wikipedia.org/wiki/Electronvolt Electronvolt]
| 1.602176634e-19 J
| 1.602176634e-19 J
|-
| kJ
| Kilo[https://en.wikipedia.org/wiki/Joule joule]
| 1000 J
|-
| MJ
| Mega[https://en.wikipedia.org/wiki/Joule joule]
| 1e6 J
|-
|-
| kWh
| kWh
| [https://en.wikipedia.org/wiki/Kilowatt_hour Kilowatt hour]
| [https://en.wikipedia.org/wiki/Kilowatt_hour Kilowatt hour]
| 3.6e6 J
| 3.6e6 J
|-
| bar
| [https://en.wikipedia.org/wiki/Bar_(unit) Bar]
| 100 kPa
|-
| T
| [https://en.wikipedia.org/wiki/Tesla_(unit) Tesla]
| 1 kg/s^2/A
|-
| F
| [https://en.wikipedia.org/wiki/Farad Farad]
| 1 s^4*A^2/m^2/kg
|-
| H
| [https://en.wikipedia.org/wiki/Henry_(unit) Henry]
| 1 kg*m^2/s^2/A^2
|-
|-
| u
| u
Line 494: Line 655:
| 4.184 J
| 4.184 J
|-
|-
| kcal
| sr
| Kilo[https://en.wikipedia.org/wiki/Calorie calorie]
| [https://en.wikipedia.org/wiki/Steradian Steradian]
| not directly
| 4184 J
|-
|-
| uA
| lm
| Micro[https://en.wikipedia.org/wiki/Ampere ampere]; alternative to the unit ''µA''
| [https://en.wikipedia.org/wiki/Lumen_(unit) Lumen]
| not directly
| 0.001 mA
|-
|-
| µA
| lx
| Micro[https://en.wikipedia.org/wiki/Ampere ampere]; alternative to the unit ''uA''
| [https://en.wikipedia.org/wiki/Lux Lux]
| not directly
| 0.001 mA
|-
| nA
| Nano[https://en.wikipedia.org/wiki/Ampere ampere]
| 1e-6 mA
|-
| ng
| Nano[https://en.wikipedia.org/wiki/Gram gram]
| 0.001 ug
|-
|-
| Mpsi
| Mpsi
Line 518: Line 671:
| 1000 ksi
| 1000 ksi
|}
|}

unknown but recognized: CV


== Reference To CAD-Data == <!--T:12-->
== Reference To CAD-Data == <!--T:12-->
Line 578: Line 729:


<!--T:21-->
<!--T:21-->
It is possible (with limitations) to define a Property of an object in your current document (".FCstd" file) by using an Expression to reference a Property of an object contained in a different document (".FCstd" file). For example, a cell in a spreadsheet or the Length of a Part Cube, 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.
It is possible to reference a spreadsheet in one document from another document.


<!--T:22-->
<!--T:22-->
Line 584: Line 735:


<!--T:23-->
<!--T:23-->
Once the master document with the spreadsheet is created and saved (named), it is safe to create dependent documents. Assuming the master document was named "master", the spreadsheet was renamed "modelConstants", and a cell was given an alias-name "Length", the value may be accessed as "master#modelConstants.Length". Note that the master document must always be loaded for the values in the master to be available to the dependent document.
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:

<!--T:65-->
master#modelConstants.Length

<!--T:66-->
Note that the master document must be loaded for the values in the master to be available to the dependent document.


<!--T:24-->
<!--T:24-->

Revision as of 11:37, 25 October 2019

Overview

It is possible to define properties using mathematical expressions. From the GUI, spin boxes or input fields that are bound to properties contain a blue icon File:Sketcher Expressions.png. Clicking on the icon or typing the equal sign (=) brings up the expression editor for that particular property.

A FreeCAD expression is a mathematical expression following notation for the standard mathematical operators and functions as described below. In addition, the expression may reference other 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 '.' separating 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 (the reason for this is that an expression like 1in + 4 will most likely be interpreted as 1in + 4in by humans, but all units are converted to the SI system internally, and the system is not able to guess this). These units are currently recognized.

You can use predefined constants and functions.

Referencing objects

You can reference to an object by its Name or by its Label. In the case of a Label, it must be enclosed in double << and >> symbols, such as <<Label>>.

You can reference any numerical property of this object. For example, to refer to a Cylinder's height, you may use Cylinder.Height or <<Long_name_of_cylinder>>.Height.

To reference list objects, the syntax is <<object_label>>.list[list_index] or object_name.list[list_index]. If you want for example reference a constraint in a sketch, do it this way <<MySketch>>.Constraints[16]. If you are in the same sketch you can omit its name and just use Constraints[16].
Note: The index starts with 0, therefore constraint 17 has the index 16.

For more info about referencing objects, see this section.

Supported Operators

The following operators are supported:

Operator Description
+ Addition
- Subtraction
* Multiplication
/ Division
^ Exponentiation

Supported Constants

The following constants are supported:

Constant Description
e Euler's number
pi Pi

Supported Functions

General Mathematical Functions

The mathematical functions listed below are available.

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.

Trigonometric functions use degree as their default unit. For radian measure, add rad following the first value in an expression. So e.g. cos(45) is the same as cos(pi rad / 4).
These trigonometric functions are supported:

Function Description Value range
acos(x) Arc cosine -1 <= x <= 1
asin(x) Arc sine -1 <= x <= 1
atan(x) Arc tangent all
atan2(x, y) Arc tangent of x/y all, except y = 0
cos(x) Cosine all
cosh(x) Hyperbolic cosine all
sin(x) Sine all
sinh(x) Hyperbolic sine all
tan(x) Tangent all, except of x = n·90 with n = integer
tanh(x) Hyperbolic tangent all

These functions for exponentiation and logarithmization are supported:

Function Description Value 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

These functions for rounding, truncation and remainder are supported:

Function Description Value 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 all, except y = 0
round(x) Rounding to the nearest integer all
trunc(x) Truncation to the nearest integer all

Statistical / Aggregate Functions

Aggregate functions take one or more arguments, separated by a semicolon ';' or a comma and a space ', '.
Arguments may include references to cells in a spreadsheet. Cell references consist of the (CAPITAL) row letter followed by the column number.
Arguments may include ranges of cells (two cell references separated by a colon), for example average(B1:B8).

These aggregate functions are supported:

Function Description Value range
average(x:y) Arithmetic mean of values in cells x through y; sum(x:y) / count(x:y) all
count(x:y) Counting of cells from x through y all
max(x:y) Maximum value in cells x through y all
min(x:y) Minimum value in cells x through y all
stddev(x:y) Standard deviation of values in cells x through y all
sum(x: y) Sum of values in cells x through y all

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).

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 directly be used 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 with a name of a unit you must put the variable into << >> to prevent that it will be recognized as unit. For example if you have the dimension 'Sketch.Constraints.A' it would be recognized as 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
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
Second of arc; alternative to the unit S
M Minute of arc
Minute of arc; alternative to the unit M

Current:

Unit Description
mA Milliampere
A Ampere
kA Kiloampere
MA Megaampere

Energy / Work:

Unit Description
J Joule
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

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 mu
mm Millimeter
cm Centimeter
mm Millimeter
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
ft Foot; alternative to the unit '
' Foot; alternative to the unit ft
yd Yard
mi Mile

Luminous intensity:

Unit Description
cd Candela

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
VA Volt-ampere

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
psi Pound-force per square inch
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, introduced in version 0.19
kHz Kilohertz, introduced in version 0.19
MHz Megahertz, introduced in version 0.19
GHz Gigahertz, introduced in version 0.19

Torque:

Unit Description
Nm Newton metre

Volume:

Unit Description
l Liter

The following commonly used units are not yet supported:

Unit Description Alternative
C Coulomb 1 A*s
V Volt 1 W/A
eV Electronvolt 1.602176634e-19 J
kWh Kilowatt hour 3.6e6 J
bar Bar 100 kPa
T Tesla 1 kg/s^2/A
F Farad 1 s^4*A^2/m^2/kg
H Henry 1 kg*m^2/s^2/A^2
u Atomic mass unit; alternative to the unit 'Da' 1.66053906660e-27 kg
Da Dalton; alternative to the unit 'u' 1.66053906660e-27 kg
cal Calorie 4.184 J
sr Steradian not directly
lm Lumen not directly
lx Lux not directly
Mpsi Megapound-force per square inch 1000 ksi

Reference To CAD-Data

It is possible to use data from the model itself in an expression. To reference a property use "object.property". If the property is a compound of fields, the individual fields can be accessed as "object.property.field".

The following table shows some examples:

CAD-Data Call in expression Result
Parametric Length of a Part-Workbench Cube Cube.Length Length with units mm
Volume of the Cube Cube.Shape.Volume Volume in mm³ without units
Type of the Cube-shape Cube.Shape.ShapeType String: Solid
Label of the Cube Cube.Label String: Label
x-coordinate of center of mass of the Cube Cube.Shape.CenterOfMass.x x-coordinate in mm without units
Value of constraint in a sketch Constraints.Width Numeric value of the named constraint 'Width' in the sketch, if the expression is used in the sketch itself.
Value of constraint in a sketch MySketch.Constraints.Width Numeric value of the named constraint 'Width' in the sketch, if the expression is used outside of the sketch.
Value of a spreadsheet alias Spreadsheet.Depth Value of the alias "Depth" in the spreadsheet "Spreadsheet"
Value of a local property Length Value of the Length property in e.g a Pad object, if the expression is used in e.g Length2 in the same object.

Document-wide global variables

There is no concept of global variables in FreeCAD 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 (".FCstd" file) by using an Expression to reference a Property of an object contained in a different document (".FCstd" file). For example, a cell in a spreadsheet or the Length of a Part Cube, 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.

Unfortunately, the integrated checker sometimes claims that a valid name doesn't exist. Continue typing anyway. When you have completed the full reference, the OK button will become active.

Of course, it's up to you to load the corresponding documents later when you want to change anything.

Known issues / remaining tasks

  • The dependency graph is 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. As a work-around, use multiple spreadsheets -- one to drive your model, and one for reporting.
  • The expression parser does not handle parentheses well, and is unable to properly parse some expressions. For example: "= (A1 > A2) ? 1 : 0" results in an error, while "= A1 > A2 ? 1 : 0" is accepted. The expression "= 5 + ((A1>A2) ? 1 : 0)" cannot be entered in any form.
  • There is no expression manager implemented where all expressions in a document are listed, and can be created, deleted, queried, etc.
  • The names of Sketcher constraints must not contain any blanks when the value is calculated by an expression, see forum discussion.
  • Open bugs/tickets for Expressions can be found in the FreeCAD Bugtracker Expressions category