Adding a calculation
There are a number of ways to add a calculation
Right click on a Group - puts the calculation into the selected group
From “Group Details” – this will store the calculation within the selected group
Right clicking on the project – this will store the calculation at the top level of the tree, below the project
When in Connections and devices Mode only – right clicking on the “Virtual Calculations” group (this will always place the calculation in the Calculations group)…
…
Using the Add new feature below the Resource Browser
Using the button in Project Details – this will store the calculation at the top level of the tree, below the project
When a calculation has been added the “Calculation Designer” will load on the right-hand side of the page which will look as follows…
General Settings
The general settings are located in a stacking panel on the right-hand side of the calculation designer…
It is mandatory for users to specify a sensor type for their calculation – the default is “Custom”. The key resource is for information only (modified in the Resource tab) and the Notes section will allow users to document and explain the purpose of the calculation if they so wish (optional).
When selecting a Sensor type a “Custom” selection will create the calculated sensor as a “Generic” sensor type, allowing users to create metrics and units as they wish.
An “Existing” selection will allow the users to choose the sensor the wish to create the calculation as from the drop-down list. This option will provide the metrics, units and configuration from the chosen sensor type – this definition needs adhered to when building the calculation.
Calculation Toolbar
The calculation toolbar is located above the expression definitions in the calculation designer and will offer users full use of an extensive library of both standard and industry specific calculator functions…
There are 5 sections…
Most Popular
This section picks the most frequently used functions from each of the other toolbar groups to aid user workflow when creating calculations.
Trigonometric
|
acos() - Returns the arccosine (inverse cosine) of a value. |
|
Example: acos(0.5) |
|
acosh() - Returns the hyperbolic arccosine (inverse hyperbolic cosine) of a value. |
|
Example: acosh(1.5) |
|
asin() - Returns the arcsine (inverse sine) of a value. |
|
Example: asin(0.5) |
|
asinh() - Returns the hyperbolic arcsine (inverse hyperbolic sine) of a value. |
|
Example: asinh(1) |
|
atan() - Returns the arctangent (inverse tangent) of a value. |
|
Example: atan(1) |
|
atan2() -Returns the arctangent (inverse tangent) of y/x, considering the correct quadrant. |
|
Example: atan2(1, 1) |
|
atanh() - Returns the hyperbolic arctangent (inverse hyperbolic tangent) of a value. |
|
Example: atanh(0.5) |
|
cos() - Returns the cosine of the specified angle (in radians). |
|
Example: cos(0) |
|
cosec() - Returns the cosecant of the specified angle (in radians). |
|
Example: cosec(0.5) |
|
cosh() - Returns the hyperbolic cosine of a value. |
|
Example: cosh(1) |
|
cot() - Returns the cotangent of the specified angle (in radians). |
|
Example: cot(1) |
|
sec() - Returns the secant of the specified angle (in radians). |
|
Example: sec(0.5) |
|
sin() - Returns the sine of the specified angle (in radians). |
|
Example: sin(0) |
|
sinh() - Returns the hyperbolic sine of a value. |
|
Example: sinh(1) |
|
tan() - Returns the tangent of the specified angle (in radians). |
|
Example: tan(0) |
|
tanh() - Returns the hyperbolic tangent of a value. |
|
Example: tanh(1) |
Mathematical
|
abs() - Returns the absolute value of a value. |
|
Example: abs(-1) |
|
cb() - Returns the cube of a value. |
|
Example: cb(3) |
|
cbrt() - Returns the cube root of a value. |
|
Example: cbrt(9) |
|
ln() - Returns the natural logarithm of a value. |
|
Example: ln(10) |
|
log10() - Returns the base-10 logarithm of a value. |
|
Example: log10(100) |
|
pow() - Raises a value to a specified power. |
|
Example: pow(2, 3) |
|
sqr() - Returns the square of a value. |
|
Example: sqr(2) |
|
sqrt() - Returns the square root of a value. |
|
Example: sqrt(4) |
Geothermal
The first of our industry specific calculation functions.
|
H() - Retrieves the enthalpy (in J/kg) at a given pressure (in Pascals) and temperature (in Kelvin). |
|
Example: H(101325, 273.15) |
|
hGas() - Retrieves the gas enthalpy (in J/kg) at a given pressure (in Pascals) and temperature (in Kelvin). |
|
Example: hGas(101325, 273.15) |
|
hLiquid() - Retrieves the liquid enthalpy (in J/kg) at a given pressure (in Pascals) and temperature (in Kelvin). |
|
Example: hLiquid(101325, 273.15) |
|
muGas() - Retrieves the gas viscosity (in Pa.s) at a given temperature (in Kelvin). |
|
Example: muGas(273.15) |
|
muLiquid() - Retrieves the liquid viscosity (in Pa.s) at a given temperature (in Kelvin). |
|
Example: muLiquid(273.15) |
|
psat() - Retrieves the saturation pressure (in Pascals) at a given temperature (in Kelvin). |
|
Example: psat(273.15) |
|
rho() - Retrieves the density (in kg/m^3) at a given pressure (in Pascals) and temperature (in Kelvin). |
|
Example: rho(101325, 273.15) |
|
rhoGas() - Retrieves the gas density (in kg/m^3) at a given pressure (in Pascals) and temperature (in Kelvin). |
|
Example: rhoGas(101325, 273.15) |
|
rhoLiquid() - Retrieves the liquid density (in kg/m^3) at a given temperature (in Kelvin). |
|
Example: rhoLiquid(273.15) |
|
sigma() - Retrieves the surface tension (in N/m) at a given temperature (in Kelvin). |
|
Example: sigma(273.15) |
|
T() - Retrieves the temperature (in Kelvin) at a given pressure (in Pascals) and enthalpy (in J/kg). |
|
Example: T(101325, 334000) |
|
Tsat() - Retrieves the saturation temperature (in Kelvin) at a given pressure (in Pascals). |
|
Example: Tsat(101325) |
Conditional
This set of capabilities ensures users can introduce nested or chained if/else functionality into their calculations. When used in combination with NULL outputs or other available functions these can be extremely powerful to generate insightful insights into raw data.
|
!= - Not Equal To |
|
< - Less Than |
|
= - Equal To |
|
> - Greater Than |
|
and – Returns true if both left and right values are true. |
|
Example: A and B |
|
between – Checks if a value is between two other values. Same as (A >= x and A <= y) |
|
Example: 5 between 1 and 10 |
|
if/else – if the condition is true, the then value is returned; otherwise, the else value is returned |
|
Example: if 1 > 0 then 1 else 0 |
|
null – represents a null value |
|
Example: null |
|
or - Returns true if either left or right value is true. |
|
Example: A or B |
When the “Show descriptive tooltips” is turned on – upon hovering any toolbar button users will be given informative tooltips detailing the purpose of each function..
Test
The test feature allows a user to run a calculation and generate results which will be displayed on screen – but importantly, not stored to the calculation sensor. These results are no longer available when the modal is closed, no observations will be stored against the calculation.
The test feature is located at the top of the Calculation Designer page…
As indicated in the information message before a test takes place, tests are limited to a maximum of 50,000 observations – this is to maintain performance of the application. If you are performing historical aggregations with large data sets, the observations generated may differ slightly.
If a calculation has an error the modal will display an error highlighting the calculation cannot be tested at this time…
When a valid calculation is run the calculation results will be displayed in the modal with all available metrics as columns in the table…
Metric numerical data can be sorted using the column headers. Date can be sorted but also includes a filter to give users the capability to find data for specific dates and times that bit easier….
Calculation Name
When creating a new calculation the calculation is given a name by default – “New Calculation”, this can be retained but it is suggested that the calculation is given a more descriptive name.
To do this simply click on the calculation name itself at the top of the page or click on the edit button alongside it, see below…
Clicking on this will open a modal dialog for renaming the calculation – simply give the calculation a name and click “Done” to save the name.
There is a 45-character limit on calculation names.
Run Automation (Scheduling)
This is an important capability of the calculation feature which will allow users to configure and automate the processing of calculations they have created at given intervals, without the need for manual user intervention.
When automation is configured on a calculation a green tick will appear beside the option in the right-hand menu as shown below…
To enable the automation of calculations the user must click/move the slider to “Enable automated running” - this is enabled by default when creating a new calculation.
The default settings for the automation of a calculation are to run once per day on a schedule – at the end of each day.
An important aspect of the configuration of a calculation is to understand the timestamps associated with any given result(s) – in the calculator we have 2 options…
Whenever key resource has a new observation
This option will generate timestamps which match the key resource of the calculation. On initial save all historical calculations will be performed and the timestamps for these calculations will match timestamps of the key resource.
Any new/future calculations will not take place until the key resource – something all calculations have – receives a new observation. When this is received the calculation will trigger and the timestamp for the calculated result will match that of the observation received.
To identify a key resource there is a key icon shown next to the chosen row in the “Resources” tab of the calculation…
On a schedule
When run automation is enabled the default specification is “On a schedule”.
This means that the calculation will run on a predefined schedule. Any observation timestamps will match the schedule frequency – in this case daily at 11:59PM each day…
To modify the schedule simply click “Change schedule” as indicated below…
This will then present the user with a modal popup which will allow the user to specify the schedule frequency, from hourly all the way to monthly…
There is an override option within the schedule to “Match key resource timestamps” – when this is selected the calculation time stamps will revert to method used in option 1, but calculations will not be processed immediately – only when triggered by its associated schedule.
Historical Backfill
When a calculation is configured for the first time and the user clicks “Save” – this will specify when and how time stamps will be generated going forward – BUT – it might be the case that the sensors and metrics used within the calculation already have data associated to them.
In this case the calculation will begin to process its historical backlog – depending upon data frequency/content this could take a few minutes.
Users have the option to prevent this from occurring simply by choosing the date they would like the calculations to start - using the Start date option…
Data Synchronization
This feature provides users with the capability to apply smoothing techniques to observations – based on a selected period of time for that smoothing average.
This feature can be useful to remove outliers within the data, essentially applying a smoother average as opposed to what the raw data may return.
Data Synchronization is available for use in the following scenarios:
Multiple Resources are present (from different sensors, not multiple metrics from the same resource)
AND
"Whenever key resource has a new observation" OR "Match key resource timestamps" is enabled (when in schedule mode).
The configuration is not applicable for "On Schedule" by default currently because:
Each resource output is already "synchronized" or timestamp aligned with the Schedule (say, Every Day @ 12 AM).
Each resource takes its LAST "One" available observation by default (as it only needs to produce a single timestamped output).
Calculation Expression(s)
The expression builder is the central element of the calculation designer - with all of the available tools and configuration surrounding it. This is where the calculation expression(s) is defined.
When initially loading the calculation designer for a new calculation you will be presented with the default display which includes one metric and “Custom” which will save this calculation as a generic sensor type, meaning the user can add a number of additional outputs.
There are several elements to the expression builder itself.
Metric
The metric section shown below allows a user to name the metric for the calculation being created.
In “Existing” mode these options will be disabled as the sensor has already been defined…
In “Custom” mode (generic sensor) these will be editable allowing users to specify name(s) for each metric in use for the calculation. These names will then be visible throughout other areas of iTwin IoT.
Unit
In a similar way to the metric name, when using “Existing” sensor types to create the calculation users cannot choose a unit – these are already predefined and disabled…
When creating a “Custom” calculation users have the ability to pick from a predefined list if units by clicking the information icon…
This will then bring up a modal offering the user to pick their unit from a list of available predefined units.
Units are a mandatory item for each output.
Right Menu
To the top right of each output there is a small menu which looks as follows…
These buttons will perform the following actions (in order from left to right)…
Prettify – this will format the expression into an easy to read, “prettier” expression. No modifications will be made to the expression, spacing will be introduced to pad it out.
Copy expression – this will copy the contents of the expression in the output to the clipboard – useful if pasting to other expressions etc.
Delete – deletes this output from the calculation.
Add above – adds a new output above the output this button was clicked from.
Add below – adds a new output below the output this button was clicked from.
Move up – moves this output up, 1 row above the output currently above itself.
Move down – moves this output down, 1 row below the output currently below itself.
Certain buttons may be disabled at times indicating it is not possible to perform that action for the given output.
Validation/Result Status Panel
To indicate whether a calculation expression is valid there is a status panel below each expression, this will indicate the validity of the expression.
An example of an invalid expression (with suggestions on how to resolve)…
An example of a valid expression (last result of the calculation is displayed)…
When a calculation expression is invalid and the user attempts to “Save” the calculation - a warning dialog appears indicating that this must be resolved before going any further…
Additional Outputs
Calculations can have a number of metrics in the same way as sensors, however…
An additional capability when using calculations to generate metrics - you can use the result(s) of the first output to feed into the second etc. When you introduce boolean logic, aggregations and then alerts you could build up a single calculation which would give you a daily average for 2 different sensors – if this average was above x.xx you could set the value to 1 and place an alert on this to inform users there is an issue with a specific asset. An example is shown below…
The averages for input 1 and input 2 would be specified in the metric drop down within the resources panel. You can see in the example above we are able to reference the output values for both output 1 and 2 in output3.
All 3 of these outputs would then be generated as metric values when the calculation is executed…
Outputs are numbered as you can see below…
IntelliSense
Each output is equipped with IntelliSense to help users quickly construct their calculation expression reducing the chance of errors in the process.
IntelliSense will auto suggest useful functions, constants, inputs and outputs available for use in the current expression. Simply start typing and suggested offerings will appear as shown below in a few examples…
IntelliSense example - Sensors…
IntelliSense example – Constants & Functions
IntelliSense example - Outputs
Clicking or pressing enter or tab will place the selected row into the expression.
Resources Tab
The resources tab allows users to identify sensors used in expressions within a calculation, view details about those sensors and specify aggregations to use for the chosen metrics where applicable.
The resources tab will look similar to the example shown below…
The “+Metric” button enables users to add additional metrics for specific sensors if the default metric is not the desired option for use in the calculation expression.
Resources can be added to the table in 3 ways
- Dragging a sensor directly into the resource table from the Resource Browser (tree).
- Dragging a sensor directly into an expression (automatically added to the resources table).
- Using the entity picker to select a sensor using the button located to the right of the resources panel shown below…
Some notable columns in the resources panel include both “Last Obs.” and “In Use”…
The “Last Obs.” column displays both the date and value of the last observation recorded against this sensor/metric.
The “In Use” column shows a blue tick when this metric is in use within an expression.
To remove a metric from the resources table users can hover over the metric – at this point there are 2 options. Clicking the item highlighted below will remove the metric from the resources table.
Clicking the 2nd item when hovered will enable users to quickly add sensors to an expression where the cursor is currently located…
Aggregations
An extremely powerful feature of the calculator is its ability to perform aggregations.
An aggregation calculation combines multiple data values into a single, summary result based on a period of time, typically using functions like sum, average, count, minimum, or maximum.
This process condenses large datasets into single numbers for statistical analysis or reporting, allowing for easier interpretation and comparison of data – essentially offering users the ability to create operational insights into their data.
Common calculation examples would be “Daily Averages”, “Monthly Maximums“, “Weekly Totals”, “Yearly Usage” etc.
The primary goal is to create a meaningful summary statistic from a larger collection of data.
Aggregations can be applied on a per metric basis with a column on each row of the Resource tab dedicated to specifying the aggregation for each calculation input (if required).
It is important to understand that when both schedules and aggregations are in use this introduces multiple date and time frequencies into calculations…
The schedule frequency – defines how often the calculation should run and will define the date/time of the observations stored for this calculation.
The aggregation frequency – defines the period of time to base the aggregation on for the specific input/metric.
This additional date/time frequency allows users to specify individual metric aggregation time frames although users will find it common to have daily aggregations alongside daily schedules. An alternative example is where a user might want to do a rolling weekly count on a sensor (fluid usage) and we want to know this count every day. The configuration available to the user means both capabilities are possible.
The available aggregation options and an explanation of each are…
|
Average
|
Returns the arithmetic mean of an input set
|
|
Maximum
|
Returns the largest value in an input set
|
|
Median
|
Returns the middle value of a sorted input set
|
|
Minimum
|
Returns the smallest value in an input set
|
|
Mode
|
Returns the most frequently occurring number in an input set
|
|
Standard Deviation
|
Returns the standard deviation of an input set
|
|
Sum
|
Returns the sum of all numbers in an input set
|
Aggregations can be applied by clicking on the “Edit aggregation” of a metric…
When clicked users will be presented with a modal dialog where they can specify the aggregation method…
Depending upon the method selected they will be presented with further options – specifically related to the amount of observations to use for the aggregation or the period of time to base the aggregation on…
There are a number of sample aggregation calculations available in the Sample Calculations section of the help documentation.
Constants Tab
The constants tab can be found next to the resources tab below the calculation expression designer.
What are constants?
A constant is a named variable with an associated value which can be used in calculation expression(s). The system comes with several preconfigured “Standard Constants” but any number can be added and created. iTwin IoT has the concept of local constants and group constants.
Local Constants
A local constant is a constant which is local to the calculation itself – it cannot be shared or used in any other calculations.
A local constant is created by clicking “+ Local Constant” as shown below...
This will then open a dialog as follows…
Clicking Save then results in…
This constant will be shown above the standard and group constant expandable sections, showing the source as the calculation currently being modified.
Note: Constant names CANNOT include spaces.
Renaming a local constant
To rename a constant click the pencil icon next to the existing name in the constants table…
This will open a modal dialog giving the user the option to alter the name of the constant and also choose whether this rename will update (maintain reference) to expressions using this constant, or disconnect them and remove any reference to this reference value – in most cases rendering calculation expressions invalid.
Update references – All existing references to this resource in the current calculation will be updated to reflect this new name.
Disconnect references - All existing references to this resource in the current calculation will be disconnected.
Group Constants
Group constants are similar to local constants in that they have a named variable with an associated value, the difference is that these are defined as a property of a group to control access within a tree structure. These are created and edited using “Properties” from the context menu in the tree (right click on a group).
Any calculation within or below a group in the tree will inherit these constants for use in their expressions.
Any useable/accessible group constant is displayed in an expandable section (“Group constants”) within the constants tab…
Examples of useful implementations…
- Costs for fluids/chemicals on a per area/group basis.
- Environmental Targets on a per area/group basis.
As noted above, group constants are managed using the “Properties” feature of the Explorer, this means they cannot be edited or renamed within the calculation itself.
Sensor Config
It is important users can access the Sensor Configuration for a calculation to ensure they can view details, edit sensor configuration or browse revision management which is not accessible using the tree as it is not a “Standard” sensor, but a “Calculated” sensor. The sensor type for each calculation is specified during the calculation configuration.
The selection below allows users to specify the sensor type the calculation should be created as…
A “Custom” selection will create the calculated sensor as a “Generic” sensor type, allowing users to create metrics and units as the wish.
An “Existing” selection will allow the users to choose the sensor the wish to create the calculation as from the drop-down list. This option will provide the metrics, units and configuration from the chosen sensor type.
This selection cannot be modified once the calculation is initially created.
Sensor Configuration can be navigated to by clicking the button shown below which is located in a toolbar at the top of the page…
IMAGE COMING SOON…
Sensor Configuration is also accessible by clicking on any sensor within the tree, but importantly this is not the case for calculations (they show the calculation designer) which therefore brings the need for this option.
Once a calculation is created the sensor type cannot be changed. These settings are disabled after the initial save of a calculation.
Clear Observations
CONTENT COMING SOON…
Duplicate
When rolling out and creating calculations at scale, sometimes it can be useful to take a copy of an existing calculation, make some small changes (perhaps to the referenced sensors), and then save this as a new calculation rather than having to create each one from scratch.
This is possible using the “Duplicate” feature of the explorer.
To duplicate a calculation simply select the duplicate button when using the calculation designer…
IMAGE COMING SOON…
This button will open a modal popup – depending upon your actions within the currently selected calculation before clicking on this button you may be offered some options.
Standard Duplication
If there have been no changes made to the existing calculation users will see the following dialog…
After clicking “Duplicate” this will close the modal and refresh the Calculation Designer screen behind with the new calculation details duplicated from the original selection ready for some minor modifications before saving.
Note: the duplicate calculation will not be created until “Save” is clicked.
If the user has made some modifications to the calculation and not saved these before clicking “Duplicate” the user will be shown the following modal dialog offering them some options…
Discard all changes, then duplicate
Choosing this option and clicking “Duplicate” will close the modal and refresh the Calculation Designer screen behind with the new calculation details duplicated from the original selection ready for some minor modifications before saving – the changes made to the original calculation before saving will not be duplicated nor will they be saved.
Duplicate with changes, then discard current changes
Choosing this option and clicking “Duplicate” will close the modal and refresh the Calculation Designer screen behind with the new calculation details duplicated from the original selection – including any new changes since the initial load, ready for some minor modifications before saving – the changes made to the original calculation before saving will not be saved but will be part of the new duplicated calculation.
Delete
The delete option can be found in the navigation at the top part of the screen…
IMAGE COMING SOON…
Delete does exactly what you might expect, it will delete the calculation you are currently creating/modifying and anything related to it. To confirm, this delete action will delete the calculation, any sensor configuration associated to the calculated sensor and also any observations stored within the calculation.
Deleting a calculation is also accessible from the context menu in the tree – right clicking on a calculation will display the option below..
A confirmation dialog will appear before any deletion is committed...