Calculation module "math"
IMPORTANT PRELIMINARY INFORMATION
*This module is provided "as is" without warranty of any kind, either express or implied, including, but not limited to, the implied warranties of merchantability and 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, without limitation, procurement of substitute goods or services, limitation and/or loss of use, data, profits or business interruption) however caused and under any theory of liability, whether in contract, strict liability or tort (including negligence), however caused, even if advised of the possibility of such damages, in whatever way arising from the use of this module, even if you have been advised of the possibility of such damage.
It is to be assumed that functionality with regard to function catalog, interfaces, parameterization or similar is incomplete and may be provided modified in future versions. Therefore, operation is at your own risk.
We are extremely grateful for any suggestions for improvement and tips resulting from the use of this module and encourage users to contact us in this regard.
Description
Using the "math" calculation module, a user-defined set of formulas can be applied to different data using a variety of functions.
The data (arguments, expressions) generally include time-varying smartCORE channel data, which can be accessed via channel names, as well as constant expressions, resources, persistent data and data provided or processed with the help of decoders.
In addition to one-dimensional data, multi-dimensional 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 an automatic type conversion takes place if necessary.
The description of the language scope can be found at
can be viewed.
The supported functions include
- arithmetic-logical operators including their order of precedence and associativity
- mathematical-trigonometric functions
- temporal filter functions (e.g. differentiation and integration of functions)
- numerical algorithms (e.g. FFT, decomposition of matrices, interpolation, prediction)
- Sampling of measurement data
- Counting functions and timers
- Selection functions, bit-oriented functions and functions for type conversion (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 as part of the configuration and adapt it according to your requirements.
A minimal example consisting of two fictitious smartCORE input channels voltage and current using the physical quantity equation
the output channels power and energy is calculated, is 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 the 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 this 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"
}
]
}
}
The content of the file Tank_LUT.lut would then be as follows according to the description of the lookup() function (not all 161 grid 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
The use of the calculation module mathmodule enables, among other things, the following
- Diagnosis and analysis of process states directly on the device
- Reduction of the volume of data to be transmitted 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 hours counters, integrals
- Classifications (dwell time, rollovers, rainflow, ...)
- Calculation of multi-component measured variables (rosette strain gage)
- Fast PoC implementation for (pre-)development of plug-ins
- Simple control functions
JSON configuration
A 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 as part of the module configuration
| Parameter name | Required | Data type | Meaningful 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 in ms |
| inputTimeoutS | No | INT | 10 - | 15 (15 s) | Timeout after which the system no longer waits for channel data but continues the calculation using the last channel value in s |
| discreteSampleTimeMs | No | INT | 1 - | 100 (100 ms) | Sampling time (support width of the underlying temporal grid) for the discrete-time calculation/evaluation of recursive formula parts in ms |
| math | JA | JSON Array of STRING or STRING | String, or list of strings concatenated to a single string, which represents the formula set of the calculation (see below) | ||
| outputs | YES | JSON Array of JSON Object for Channel Configuration | List of all output channels, or moreover 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 formula set "math"
Depending on its complexity, the formula set for the periodic calculation can either be specified as a single string or a list of strings (in the form of a JSON array). If a list is specified, all list elements are strung together 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
- and various application examples
The following are examples of formula sets
{
"module": "math1",
"factory": "mathmodule",
"config": {
"math": "y = 42;"
}
}
{
"module": "math1",
"factory": "mathmodule",
"config": {
"math": [
"c = 42;",
"y = c;"
]
}
}
In this documentation, the focus is placed 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 again be made invisible to the JSON parser by the \-ESCAPE character.
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\'s work?\t[yes/no]';
fnc = myParameterFunction(x, {"property": "value"});
is defined in the JSON configuration of the Math module
"math": [
"s1a = '17\" (inch)';",
"s1b = \"17\\\\" (inch)\";",
"s2a = \"Did it work?\\t[yes/no]\";",
"s2b= 'Did\\'s work?\\t[yes/no]';",
"fnc = myParameterFunction(x, {\"property\":\"value\"});"
], ...
**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.
Configuration of the output channels "outputs"
In general, the calculation module is used to calculate output values that are produced in smartCORE channels.
There must be exactly one assignment for each of these channels 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 regarded as internal, local variables in the formula set.
The following minimal example therefore exports the speed channel
{
"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 as follows
{
"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 component in the Math module in order to realize even complex configurations and functionalities. The description can be found here.