Help functions

System functions

Function	Description
time()	Returns the evaluation time of the module in seconds UTC

Properties of a channel or value

Function	Description
deltaT(x)	Returns the time interval between the last two evaluation times of term x in seconds
deltaY(x)	Returns the value difference between the last two samples of term x; is positive for an increasing signal curve
time(x)	Returns the time of the last changed data sample of term x
sgn(x)	Sign of value x $-1: x < 0$ $+1: x > 0$ $\enspace0:otherwise$
sgn(x,eps)	Sign of the value x with tolerance $\epsilon$ (eps) $-1: x < -\epsilon$ $+1: x > \epsilon$ $\enspace0:otherwise$
abs(x)	Absolute value of the scalar value x, For the length of a vector, see Length(V)
isConnected(x)	Query SmartCORE connection
isEmpty(x)	Query data source status
isTimeout(x)	Query data gap
isDefault(x)	Query channel for default value
isError(x)	Query error status of a result
typeOf(x)	Query data type
value(x, ...)	Query values of a channel timelessly
shiftT(x,dT)	Time shift of channel data

Query SmartCORE connection "isConnected" ¹

The function returns true if the channel has been successfully connected to a smartCORE channel as an input.

If no smartCORE channel can be found when the smartCORE and Math module are started, this is not only output in the log file, but also signaled via this status (false).

In this case, the default value is written to the variable as a constant so that calculations can be performed. This is initially false, but can be set to any constant value and type using the #property macro with default=<variant>. See also isDefault().

The query returns the status for the current batch interval.

s1 = isConnected(x);
s2 = isConnected($'other.y');

important

The argument of the function must be an input variable.

Query the status of the data source "isEmpty" ¹

The function returns true if no data has been produced in the smartCORE input channel when the smartCORE and Math Module are started. This can happen if other data sources can only produce data after an initialization phase or a lengthy process of establishing a data connection.

If the channel remains empty and the timeout condition related to the start time of the Math module occurs, and if an explicit default value is set via the #property macro with the option default=<val>, this value is temporarily used as a substitute value until the first data sample arrives. See also isDefault().

The query returns the status for the current batch interval and is independent of the data contents and timestamps of the channel.

s1 = isEmpty(x);
s2 = isEmpty($'other.y');

important

The argument of the function must be an input variable.

Query data gap "isTimeout" ¹

The function returns true if the most recent sample in the smartCORE input signal is older than a configurable timeout interval and therefore no new data has likely been produced on the smartCORE input signal. This can have various causes, such as the absence of a CANbus message, a missing GPS signal, or a missing Internet connection for querying control information. As soon as new data arrives, the status reverts to false.

An individual timeout value can be assigned to each input channel using the #property macro with the option timeout=<val>. This overrides the global setting for the channel using inputTimeoutS, which is preset to $15 s$.

If the timeout condition occurs in relation to the start time of the Math module when the channel remains empty, and if an explicit default value is set using the #property macro with the option default=<val>, this value is temporarily used as a replacement value until the first data sample arrives. See also isDefault().

If data samples are already present in the channel, the validity of the most recent value of the variable is extended in the timeout status. It then runs behind the set timeout interval of the current execution time of the Math module. Dependent calculations can then be continued until this point in time.

note

This time offset can only be seen where data without timestamps is visualized or used, e.g., in the MQTT live data, but not in the OSF files.

The query returns the status for the current batch interval and is independent of the data contents and timestamps of the channel.

s1 = isTimeout(x);
s2 = isTimeout($'other.y');

important

The argument of the function must be an input variable.

Query channel for default value "isDefault" ²

The function returns true if the channel is permanently or temporarily set to a default replacement value.

For each input channel, an individual, constant default value can be assigned using the #property macro with the option default=<val>. If this is not set, false (<bool> => 0, 0.0, "false") is used.

The default value is used as a constant replacement value if the channel could not be connected to a smartCORE channel.

The default value is used as a temporary replacement value if

• the channel has been connected isConnected()
• and the channel is still empty isEmpty()
• and the channel has timed out isTimeout()
• and
  • the default value has been explicitly set via the #property macro
  • or the channel has been marked as #timeless.

The query returns the status for the current batch interval and is independent of the data contents and timestamps of the channel.

s1 = isDefault(x);
s2 = isDefault($'other.y');

important

The argument of the function must be an input variable.

Query the error status of a result "isError" ¹

The function returns true if the evaluation of a term has generated a runtime error. The error message is also stored in the log file when the variables are output to the smartCORE or can be further used as a string in the Math module.

res = ...;                                // some expression
use     = isError(res) ? 12.34 : res;   // use alternate value on error
errCode = isError(res) ? int(res) : 0;
errMsg  = isError(res) ? str(res) : 'ok';

note

It is recommended to use a (local) variable to reuse the result.

Query data type "typeOf" ¹

The typeOf function returns the data type of the passed value as an ENUM value:

t = typeOf(x);

The values have the following correspondence:

Value	Data type
0	void
1	<bool>
2	<uint>
3	<int>
4	<dbl>
5	<cxFlt>
6	<str>
> 0x80000000	(Reserved)
0x8000B10B	BLOB - Binary object, e.g., a transition()
0x8000EBAD	ERROR - Runtime error of a term

Query channel values timelessly "value" ²

This function allows you to resolve the time dependency of a calculation path at a specific point in the calculation, similar to #timeless.

To do this, the last value available before the batch interval (evaluationTimeMs) is used as the start value for the interval, then all samples with timestamps in the batch interval are copied, and finally the last value is extended to the end of the interval. If an empty channel is used as an argument, a replacement value can be specified explicitly.

The query returns values for the current batch interval and is independent of the data contents and timestamps of the channel.

v1 = value(x);
v2 = value(x, def);      // use def, if isEmpty(x)

Typically, a circular reference in the Math Module causes a switch to a discrete sampling interval (discreteSampleTimeMs) for the affected channel, which must then also be assigned an explicit start value (@0 syntax):

zv@0 = 0;                      // start value for discrete calculation
zv   = a * zv + (1 - a) * x;   // example for circular use of 'zv'

tip

In the context of logical controls, state machines, limit value monitoring, etc., it can be useful to perform the calculations in real time and still use a feedback of a calculation result to the start of the calculation. The function value() represents exactly the point at which the feedback is broken locally in the sense of #timeless.

caution

Resolving the time dependencies leads to behavior at the corresponding point that is no longer 100% predictable and defined. Short-term signal changes on the input term may be overlooked, or changes may only become visible in a later batch interval. The effects of the function must be carefully checked before productive use!

Time shift of channel data "shiftT" ²

The shiftT() function can be used to shift the data of a channel by a specific time interval dT. Since shifting and subsequent time-correct calculation with other data always leads to buffering, the shift should be limited to a few seconds.

The time interval dT in seconds is added to all timestamps of the x-term data. A shift with dT > 0.0 shifts the data into the future, dT < 0.0 into the past.

xs = shiftT(x, dT); 

tip

This function can be used to compensate for known time delays caused by data transmission from the actual acquisition system (AD converter, microcontroller) of an analog signal to the reception and time stamping of the data in the smartCORE. This can be useful for compensating for phase shifts, especially in the case of very high-frequency sampled signals.

Parameters of multiple values

Function	Description
abs(x1, ..., xN)	l2 norm of the individual values (x1, ..., xN), $= \sqrt{\sum_{i=1}^N x_i^2}$
min(x1, ..., xN)	Minimum of the individual values (x1, ..., xN)
max(x1, ..., xN)	Maximum of the individual values (x1, ..., xN)
mean(x1, ..., xN)	Arithmetic mean of the individual values (x1, ..., xN) $= \frac{1}{N} \sum_{i=1}^N x_i$
rms(x1, ..., xN)	Square root of the arithmetic mean of the squared individual values (x1, ..., xN) $= \sqrt{\frac{1}{N}\sum_{i=1}^N x_i^2}$

Limiting and rounding

Function	Description
range(x, ...)	Limits the input value to a specific range of values. See description below.
ceil(x)	Smallest integer value $i >= x$ (preserving data type)
ceil2i(x)	smallest integer value $i >= x$ (return type int)
floor(x)	largest integer value $i <= x$ (data type preserved)
floor2i(x)	largest integer value $i <= x$ (return type int)
trunc(x)	if $x >= 0$, then largest integer value $i <= x$, otherwise smallest integer value $i >= x$
round(x)	integer value $i$ such that $x - 0.5 < i <= x + 0.5$ (preserves data type)
round2i(x)	integer value $i$ such that $x - 0.5 < i <= x + 0.5$ (return type int)
nonZero(x, ...)	Follows x if $\|x-x_{crit}\| \ge \epsilon$, otherwise if $x \ge x_{crit}$, $x_{crit}+\epsilon$ is set, otherwise $x_{crit}-\epsilon$ See description below.

Value range "range"

The function restricts the value range for a given input signal x (scalar or vector) to a range $[min, max]$ and offers a wide range of variants via the optional configuration.

r1  = range(x);
r2  = range(x, [min, max]);        // better readability
r3  = range(x, min, max);          // no longer used
// Optional configuration for all variants
rx  = range(..., { min: off|<val>
                 , max: off|<val>
                 , lower: off|<val>|erase
                 , upper: off|<val>|erase
                 , mode: <enum>
                 , defXY: [<dbl>, <dbl>]
                 , limVar: <str>
                 });

Property	Value	Description
min	off/<val>	Deactivation or fixed configuration of a lower (scalar) limit. If the function parameter min is used, this property has no function.
max	off/<val>	Deactivation or fixed configuration of an upper (scalar) limit. If the function parameter max is used, this property has no function.
lower	off/<val>/erase	If activated, the replacement value is output when the lower limit is exceeded (x < min) or the sample is removed.
upper	off/<val>/erase	If enabled, the replacement value is output when the upper limit is exceeded (x > max) or the sample is removed.
mode	<enum>	If x is a vector, depending on mode - box: all coordinates individually... - length: the length of the vector ( >= 0.0 )... - azimuth: the angle of the vector in the XY plane... - elevation: the angle of the vector from the XY plane to the Z axis... ...limited to the set range $[min, max]$
defXY	[<dbl>, <dbl>]	In elevation mode, defXY is the default direction when the vector must be swung back from the vertical (def.: [1, 0, 0]).
limVar	<str>	limVar optionally defines the name of a local <bool> variable to signal the active limitation

Non-zero "nonZero"

The function ensures that a critical value (def.: 0.0) is never output. Instead, the value range is omitted by a factor of $\epsilon$ (def.: 1e-6) around the critical value. The application of the function is optimized, for example, for divisions where division by zero would be possible and must be excluded.

xnz1 = nonZero(x);                // eps := 1e-6, x_crit := 0.0
xnz2 = nonZero(x, eps);           // x_crit := 0.0
xnz3 = nonZero(x, eps, x_crit);

$$\rm{nonZero}(x) = \left\{ {\begin{array}{ll} {x:}&{\left| {x - {x_{crit}}} \right| \ge \varepsilon }\\ {{x_{crit}} + \varepsilon :}&{x \in [{x_{crit}},{x_{crit}} + \varepsilon [}\\ {{x_{crit}} - \varepsilon :}&{x \in ]{x_{crit}} - \varepsilon ,{x_{crit}}[} \end{array}} \right..$$

One example is the safe conversion of fuel flow rate in $l/h$ and speed in $km/h$ into consumption in $l/100km$:

consumption = volFlow / nonZero(speed, 0.1) * 100;

Switching threshold with hysteresis "threshold"

This function generates a switching signal from the comparison of a signal against a fixed threshold value threshold. Disturbances in the signal curve can be suppressed by means of hysteresis hysteresis and delay times delayOn, delayOff.

The function can be used in various applications:

trig1 = threshold(x);
trig2 = threshold(x, t);
trig3 = threshold(x, t, h);
// Optional configuration for all variants
trigX = threshold(..., { threshold: <dbl>
                       , hysteresis: <dbl>
                       , delayOn: <dbl>
                       , delayOff: <dbl> 
                       , logic: <enum>
                       , startup: inf|<bool>
                       });

Property	Value	Meaning
threshold	<dbl>	Trigger threshold, def.: 0.55 Overwritten with argument t
hysteresis	<dbl>	Width of the hysteresis zone, added to the threshold for the second limit value, def.: -0.10 Overwritten with argument h
delayOn	<dbl>	Optional filter time in seconds for the switch-on process
delayOff	<dbl>	Optional filter time in seconds for the switch-off process
logic	<enum>	- auto: Function is determined by the sign of the hysteresis - above: Triggering above the hysteresis zone - below: Triggering below the hysteresis zone
startup	inf|<bool>	Start behavior: inf: The position of the first sample determines the output value (def.) with respect to the threshold. <bool>: It is assumed that this output value was output before the first sample.

• The function returns true for the point in time when the signal x exceeds the defined trigger threshold and false for the point in time when the signal x falls back to the reset value.

If the delay times are set, the signal x must remain continuously in the trigger or reset state for the specified interval before the switchover is implemented. The switchover is thus delayed relative to the crossing of the respective threshold value.

In auto mode (default), triggering depends on the sign of the hysteresis:

Hysteresis	Triggering (true)	Reset (false)
$hysteresis < 0$	$x > threshold$	$x < threshold + hysteresis$
$hysteresis > 0$	$x < threshold$	$x > threshold + hysteresis$

In the above and below operating modes, threshold and hysteresis define two limits of a hysteresis zone:

$$g_{low} = min(threshold, threshold + hysteresis)$$ $$g_{high} = max(threshold, threshold + hysteresis)$$ $$zone = [g_{low}, g_{high}]$$

Operating mode	Trigger (true)	Reset (false)
above	$x > g_{high}$	$x < g_{low}$
below	$x < g_{low}$	$x > g_{high}$

Footnotes

1. Available from catalog version 10. ↩ ↩² ↩³ ↩⁴ ↩⁵

2. Available from catalog version 11. ↩ ↩² ↩³