Auxiliary functions

System functions

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

Time conversion "decodeTime"

The decodeTime() function takes a scalar timestamp t in UTC and converts it into the corresponding date and time representation with the optional offset tzDif to the local time. Various interpretations and output formats can be set.

TM1 = decodeTime(t);
TM2 = decodeTime(t, tzDif);
// Optional configuration
TMx = decodeTime(..., { scale: <enum>
                      , epoch: unix|<date>
                      , tzDif: <int>
                      , format: <str>
                      });

Property	Value	Description
scale	<enum>	Determines what the integer part of the timestamp describes: auto: The scale of the timestamp determines the resolution (def.), or the integer part of t counts... d: ... days s: ... seconds ms: ... milliseconds us: ... microseconds ns: ... nanoseconds
epoch	unix/<date>	The start time of the count is set to the given UTC date, format: 'yyyy-mm-dd', optionally with time specification 'yyyy-mm-dd HH:MM' (def.: unix 1970-01-01)
tzDif	<int>	Time offset in minutes to output the local time, example CET: +60, CEST: +120, EST: -300
format	<str>	Instead of a vector, a formatted date/time string is output. The function uses the c++ function strftime() internally. The formatting of the output is described here. In addition, the following placeholders can be used: %FMS: 3-digit milli-seconds %FUS: 6-digit micro-seconds %FNS: 9-digit nano-seconds each with leading zeros

Unless the output of a formatted date-time text is requested with the format property, the result is a vector with the following <uint> values:

// Returns the date-time information as a vector corresponding to
// the following content:
TM = [ year, month, day
     , hour, minute, second, nanoseconds
     , weekday // 0..6, 0 := Sunday
     , yearday];

Properties of a value

Function	Description
deltaT(x)	Returns the time interval between the last two evaluation times of the term x in seconds
deltaY(x)	Returns the difference in value of the last two samples of the term x, is positive with an increasing signal curve
sgn(x)	Sign of the value x $-1: x < 0$ $+1: x > 0$ $\enspace0:else$
sgn(x,eps)	Sign of the value x with tolerance $\epsilon$ (eps) $-1: x < -\epsilon$ $+1: x > \epsilon$ $\enspace0:else$
abs(x)	absolute value of the scalar value x, For the length of a vector see Length(V)

Characteristics of several values

Function	Description
abs(x1, ..., xN)	l2-norm of the scalar 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 the following description.
ceil(x)	smallest integer value $i >= x$ (data type-preserving)
ceil2i(x)	smallest integer value $i >= x$ (return type int)
floor(x)	largest integer value $i <= x$ (data type preserving)
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$, so that $x - 0.5 < i <= x + 0.5$ (data-preserving)
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 the following description.

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 use
// 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 max function parameter is used, this property has no function.
lower	off/<val>/erase	If activated, the replacement value is output when the lower limit (x < min) is exceeded or the sample is removed
upper	off/<val>/erase	If activated, the replacement value is output when the upper limit (x > max) is exceeded or the sample is removed
mode	<enum>	If x is a vector, all coordinates are output individually 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 tilted 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 value $\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...$$

Switching threshold with hysteresis "threshold"

This function generates a switching signal from the comparison of a signal against a fixed threshold value threshold. A hysteresis hysteresis and delay times delayOn, delayOff can be used to suppress interference on the signal curve.

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, is added to the threshold for the second limit value, def.: -0.10 Is 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 regard to the threshold. <bool>: It is assumed that this output value was issued before the first sample.

• The function returns true for the time at which the signal x exceeds the defined trigger threshold and false for the time at which the signal x falls into the reset.

If the delay times are set, the signal x must remain continuously in the triggering or resetting state for the specified interval before the switchover is realized. The switchover is therefore delayed compared to when the respective limit value is exceeded.

In auto operating mode (default), triggering is dependent on the sign of the hysteresis:

Hysteresis	Trigger (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}$