Calculation module "math"
IMPORTANT PRELIMINARY INFORMATION
This module is provided without any express or implied warranties, including, but not limited to, the implied warranty of merchantability or fitness for a particular purpose.
In no event shall optiMEAS GmbH or the contributors to this module be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, profit, or business interruption), however caused and under any theory of liability, whether in contract, strict liability, or tort (including negligence), arising in any way from the use of this module, even if advised of the possibility of such damages.
It should be assumed that functionality with regard to the function catalog, interfaces, parameterization, or similar is incomplete and may be modified in future versions. Therefore, operation is at your own risk.
We are extremely grateful for any suggestions for improvement and tips that arise from the use of this module and encourage users to contact us in this regard.
Description
The "math" calculation module can be used to apply a user-defined formula set to different data using a variety of functions.
The data (arguments, expressions) includes, on the one hand, time-varying smartCORE channel data that can be accessed via channel names and, on the other hand, constant expressions, resources, persistent data, and data that has been provided or processed using decoders.
In addition to one-dimensional data, multidimensional data in the form of vectors and matrices is also supported, whereby all components of this data can be based on different data types and automatic type conversion takes place if necessary.
The description of the language scope can be found at
.
Supported functions include
- Arithmetic and logical operators, including their precedence and associativity
- Mathematical and trigonometric functions
- Temporal filter functions (such as the differentiation and integration of functions)
- Numerical algorithms (e.g., FFT, matrix decomposition, interpolation, prediction)
- Sampling of measurement data
- Counting functions and timers
- Selection functions, bit-oriented functions, and type casts
- Sequencing of expressions and assignments
- Functions that operate on character strings
Examples
In general, it makes sense to look at a minimal example during configuration and adapt it to your requirements.
A minimal example consisting of two fictitious smartCORE input channels voltage and current using the physical equation
the output channels power and energy are calculated, as shown below
{
"module":"math1",
"factory":"mathmodule",
"config": {
"math": [
"Power = voltage * current * 1e-3; // Current in mA!",
"Energy = 1/(3600 * 1e3) * integrate(Power); // Energy in kWh!"
],
"outputs": [
{
"datatype": "double",
"name": "Power",
"physicalUnit": "W"
},
{
"datatype": "double",
"name": "Energy",
"physicalUnit": "kWh"
}
]
}
}
For calculations whose runtime complexity exceeds real-time requirements, the use of a lookup table (LUT) is recommended. In the following example, the fuel volume in a tank is determined interpolatively from the lookup table based on the pressure prevailing at the bottom of the tank, whereby the contents of this LUT are provided from a file located in the file system via resources
{
"module":"math1",
"factory":"mathmodule",
"config": {
"math": [
"Volume = lookup(Pressure, {$ref:'Tank_LUT'});"
],
"outputs": [
{
"datatype": "double",
"name": "Volume",
"physicalUnit": "l"
},
],
"resources": [
"Tank_LUT": {
"decoder": [
"file"
],
"value": "Tank_LUT.lut"
}
]
}
}
According to the description of the lookup() function, the contents of the Tank_LUT.lut file would then be as follows (not all 161 support points are listed here):
IN kPa 0.0 0.167751 161
OUT l
0
42.942
87.924
134.946
184.008
235.11
288.252
343.434
400.656
459.918
521.22
584.562
649.944...
etc.
Motivation
Using the calculation module mathmodule enables the following, among other things
- Diagnosis and analysis of process states directly on the device
- Reduction of the data volume to be transferred by focusing on characteristic values or trends
- Virtual measurements on measurement signals, e.g., duration of a door movement, amplitude of a signal, etc.
- Event counters, operating hour counters, integrals
- Classifications (dwell time, rollovers, rainflow, etc.)
- Calculation of multi-component measured variables (rosette strain gauges)
- Fast PoC implementation for (preliminary) development of plug-ins
- Simple control functions
JSON configuration
The minimum required configuration of the calculation module essentially has the following structure
{
"module":"math1",
"factory":"mathmodule",
"config": {
"math": [
< MATH >
],
"outputs": [
< OUTPUTS >
]
}
}
A complete configuration of the calculation module, on the other hand, essentially has the following structure
{
"module":"math1",
"factory":"mathmodule",
"config": {
"packages": [
"some function package",
"another function package",
...
],
"evaluationTimeMs": 1000,
"inputTimeoutS": 15,
"discreteSampleTimeMs": 100,
"math": [
< MATH >
],
"outputs": [
< OUTPUTS >
],
"resources": {
"someTextResource": [
< LINES OF TEXT >
],
"someObjectResource": {
< JSON STYLE Config >
},
"someDecodableResource": {
"decoder": [
< DECODERS >
],
"value": "someInitialStringValue"
},
...
}
}
}
Global module parameters
The following parameters can be used in the module configuration
| Parameter name | Required | Data type | Useful value range | Default value | Description |
|---|---|---|---|---|---|
| packages | No | JSON Array of STRING | EMPTY JSON Array | List containing optional function packages | |
| evaluationTimeMs | No | INT | 100 - | 1000 (1 s) | Polling interval of the calculation in ms |
| inputTimeoutS | No | INT | 10 - | 15 (15 s) | Timeout after which channel data is no longer waited for, but the calculation is continued using the last channel value in s |
| discreteSampleTimeMs | No | INT | 1 - | 100 (100 ms) | Sampling time (support width of the underlying time grid) for the time-discrete calculation/evaluation of recursive formula parts in ms |
| math | YES | JSON array of STRING or STRING | String, or a list of strings concatenated into a single string, representing the formula set of the calculation (see below) | ||
| outputs | YES | JSON array of JSON object for channel configuration | List of all output channels, or, in addition, all persistent input channels (see below) | ||
| resources | No | JSON object for resource configuration | Object that configures the resources used (see below) | ||
| minLogLevel | No | ENUM | OFF, DEBUG, INFO, WARNING, ERROR, FATAL | INFO | Output filter for messages from the math module; only messages with at least the specified severity level are written to the log file. |
Configuration of the "math" formula set
Depending on its complexity, the formula set for the periodically executed calculation can be specified either as a single string or as a list of strings (in the form of a JSON array). If a list is specified, all list elements are concatenated as lines of the formula set with the connecting character \n .
Further information is available on the following pages:
- Description of the general function
- Semantics and syntax, operators
- Function reference
- Use of resources
- as well as various application examples
Examples of formula sets are provided in the following
{
"module":"math1",
"factory":"mathmodule",
"config": {
"math": "y = 42;"
}
}
{
"module":"math1",
"factory":"mathmodule",
"config": {
"math": [
"c = 42;",
"y = c;"
]
}
}
This documentation focuses on the actual multi-line formula set. When transferring the formula set to the JSON configuration, the individual lines of the formula set must therefore be enclosed in " ... ". This means that all " and \-ESCAPE characters in the formula text must be made invisible again for the JSON parser using the \-ESCAPE character.
This additional formatting is not taken into account in the examples in this function reference, as it is usually implemented automatically by the editor used, e.g., in optiCONTROL.
From the following formula text with various text elements and a configuration
s1a = '17" (inch)';
s1b = "17\" (inch)";
s2a = "Did it work?\t[yes/no]";
s2b = 'Did it work?\t[yes/no]';
fnc = myParameterFunction(x, {"property":"value"});
the following formula text with various text elements and a configuration
"math": [
"s1a = '17\" (inch)';",
"s1b = \"17\\\" (inch)\";",
"s2a = \"Did it work?\\t[yes/no]\";",
"s2b= 'Did\\'t it work?\\t[yes/no]';",
"fnc = myParameterFunction(x, {\"property\":\"value\"});"
], ...
Configuration of output channels "outputs"
In general, the calculation module is used to calculate output values that are produced in smartCORE channels.
For these channels, there must be exactly one assignment in the formula set, and they must be configured under "outputs" according to common smartCORE standards.
Assignments that are not published in the "outputs" area are considered internal, local variables in the formula set.
The following minimal example therefore exports the channel speed
{
"module":"math1",
"factory":"mathmodule",
"config": {
"math": [
"c = 42;",
"speed = c;"
],
"outputs": [
{
"dataType": "double",
"name": "speed",
"physicalUnit": "m/s"
}
]
}
}
A slightly more flexible configuration, which also describes additional channel characteristics and a single-stage production filter chain, would look like this
{
"module":"math1",
"factory":"mathmodule",
"config": {
"math": [
"c = 42;",
"speed = c;"
],
"outputs": [
{
"dataType": "double",
"name": "speed",
"physicalUnit": "m/s",
"bufferSize": 1024,
"channelType": "timestamped",
"filter": [
{
"name": "datareduction",
"absTolerance": 0.0,
"timeoutMs", 60000
}
]
}
]
}
}
Configuration of resources "resources"
The provision of resources is an important part of the Math module in order to implement even complex configurations and functionalities. The description can be found here.