The calculation protocol enables the creation synthetic Points whose Measurement values are based on the result of mathematical and logical expressions that may take other Points as their inputs. Calculated points are included in the equipment model just like telemetered points, but are assigned to an Endpoint configured with the calculator protocol. The calculator front-end process for these Endpoints maintains a subscription to any input Points, and publishes new values according to each calculated Point's configuration.
The configuration for a calculated Point is stored the "calculation" EntityKeyValue for that Point. The serialized format is the "Calculation" protocol buffer structure defined in the service APIs. The calculation configuration can therefore be created or updated programmatically using the modeling APIs. Additionally, the XML loading format contains the ability to configure calculations in XML as part of the importing process.
Calculations may be based on inputs, which specify another Point in the system whose Measurement values the evaluation uses. Inputs are assigned to a variable that can be referenced in the calculation formula.
Calculations may also refer to a time range over a single input (such as computing average, or integration). A multi-valued input defines a time offset into the past that specifies the valid range for samples, and can be configured to retrieve history when initialized.
The formula to be evaluated by the calculation is user-provided expression that includes input symbols, arithmetic, and function calls. The formula language is designed to be as similar as possible to spreadsheet calculations.
Examples:
Inputs are A and B:
(A + B) / 1000.0Inputs are A, B, and C, and the SUM() function is used:
SUM(A, B, C)Inputs are STATUS, A, B and SCALE and the IF() function is used:
IF(STATUS > 0, A, B) * SCALE When new values are calculated and posted is configured by the trigger strategy of the calculation. The choices of strategies are:
| Strategy | Description |
|---|---|
| On any update | The calculation is re-evaluated whenever a new Measurement arrives for one of the input Points. |
| Periodic | The calculation is re-evaluated on a fixed interval provided in the configuration for the calculated Point. |
Input values from Measurements in the system may not all have valid quality. The input quality strategy configures how calculations are evaluated when invalid qualities are present.
| Strategy | Description |
|---|---|
| ACCEPT_ALL | Measurements of any quality will be used as inputs. |
| ONLY_WHEN_ALL_OK | Only evaluate the calculation when all input Measurements have GOOD quality. |
| REMOVE_BAD_AND_CALC | Removes bad quality Measurements from the inputs and evaluates the calculation. For singular inputs, this will result in an input not being present and the calculation not being evaluated. For ranged inputs, only the poor quality Measurements in the range will be filtered out, and the calculation will proceed. |
The output quality strategy defines the quality of the resulting Measurements produced by evaluating the calculation.
| Strategy | Description |
|---|---|
| WORST_QUALITY | Uses the "worst" quality of the input Measurements. |
| ALWAYS_OK | Calculated Measurements always have good quality. |
The following are the functions and symbols that can be used in calculation formulas:
| Function(s) | Symbol | Arg # | Description |
|---|---|---|---|
| SUM | + | 1..n | Outputs the sum of all arguments. |
| -- | - | 2 | Outputs the difference between two arguments. |
| PRODUCT | * | 1..n | Outputs the product of all arguments. |
| QUOTIENT | / | 2 | Outputs the quotient of two arguments. |
| POWER | ^ | 2 | Outputs the first argument to the power of the second. |
| SQRT | 1 | Outputs the square root of the single argument. | |
| AVERAGE | 1..n | Outputs the average of the arguments. | |
| MAX | 1..n | Outputs the highest value of the arguments. | |
| MIN | 1..n | Outputs the lowest value of the arguments. | |
| ABS | 1 | Outputs the absolute value of the argument. | |
| GT | 2 | Outputs 'true' if first argument is greater than the second, otherwise 'false'. | |
| GTE | 2 | Outputs 'true' if first argument is greater than or equal to the second, otherwise 'false'. | |
| LT | 2 | Outputs 'true' if first argument is less than the second, otherwise 'false'. | |
| LTE | 2 | Outputs 'true' if first argument is less than or equal to the second, otherwise 'false'. | |
| EQ | 2 | Outputs 'true' if arguments are equal, otherwise 'false'. | |
| COUNT | 1..n | Outputs the number of the boolean arguments that are 'true'. | |
| AND | 1..n | Outputs 'true' if all arguments are boolean 'true', otherwise 'false'. | |
| OR | 1..n | Outputs 'true' if any of the arguments are boolean 'true', otherwise 'false'. | |
| NOT | 1 | Outputs 'false' if the boolean argument is 'true', otherwise 'true'. | |
| IF | 3 | Takes three arguments. If the first argument is boolean 'true', outputs the second argument. Otherwise outputs the third argument. | |
| LATEST | 1..n | Outputs the latest value of the arguments to arrive. | |
| INTEGRATE | 1 | Outputs the integral of the single argument's time-series values. |