Fonctions utilitaires

Fonctions système

Fonction	Description
time()	Renvoie l'instant d'évaluation du module en secondes UTC

Propriétés d'un canal ou d'une valeur

Fonction	Description
deltaT(x)	Renvoie l'écart temporel entre les deux derniers instants d'évaluation du terme x en secondes
deltaY(x)	Renvoie la différence de valeur entre les deux derniers échantillons du terme x, positive lorsque le signal est croissant
time(x)	Renvoie l'instant du dernier échantillon de données modifié du terme x
sgn(x)	Signe de la valeur x $-1: x < 0$ $+1: x > 0$ $\enspace0:sonst$
sgn(x,eps)	Signe de la valeur x avec tolérance $\epsilon$ (eps) $-1: x < -\epsilon$ $+1: x > \epsilon$ $\enspace0:sonst$
abs(x)	Valeur absolue de la valeur scalaire x, Pour la longueur d'un vecteur, voir `Length(V)`
isConnected(x)	Interroger la connexion SmartCORE
isEmpty(x)	Interroger l'état de la source de données
isTimeout(x)	Interroger une lacune de données
isDefault(x)	Interroger un canal sur sa valeur de remplacement
isError(x)	Interroger l'état d'erreur d'un résultat
typeOf(x)	Interroger le type de données
value(x, ...)	Interroger les valeurs d'un canal sans notion de temps
shiftT(x,dT)	Décalage temporel des données d'un canal

Interroger la connexion SmartCORE « isConnected » ¹

La fonction renvoie true lorsque le canal a été connecté avec succès, en tant qu'entrée, à un canal smartCORE.

Si, au démarrage de smartCORE et du module Math, aucun canal smartCORE ne peut être trouvé, cela n'est pas seulement consigné dans le fichier journal, mais également signalé par cet état (false).

Dans ce cas, la valeur default est écrite comme constante dans la variable, de sorte que les calculs puissent être exécutés. Celle-ci est d'abord false, mais peut être réglée sur n'importe quelle valeur constante et de n'importe quel type via la macro #property au moyen de default=<variant>. Voir aussi isDefault().

L'interrogation fournit l'état pour l'intervalle de lot (batch) en cours.

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

important

L'argument de la fonction doit être directement une variable d'entrée.

Interroger l'état de la source de données « isEmpty » ¹

La fonction renvoie true lorsque, au démarrage de smartCORE et du module Math, aucune donnée n'a encore été produite dans le canal d'entrée smartCORE. Cela peut se produire lorsque d'autres sources de données ne peuvent produire des données qu'après une phase d'initialisation ou l'établissement prolongé d'une connexion de données.

Si, pour un canal qui reste vide, la condition de timeout se produit par rapport à l'instant de démarrage du module Math et qu'une valeur par défaut explicite est définie via la macro #property avec l'option default=<val>, celle-ci est utilisée temporairement comme valeur de remplacement jusqu'à l'arrivée du premier échantillon de données. Voir aussi isDefault().

L'interrogation fournit l'état pour l'intervalle de lot (batch) en cours et est indépendante des contenus de données et des horodatages du canal.

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

important

L'argument de la fonction doit être directement une variable d'entrée.

Interroger une lacune de données « isTimeout » ¹

La fonction renvoie true lorsque l'échantillon le plus récent du signal d'entrée smartCORE est plus ancien qu'un intervalle de timeout réglable et que, par conséquent, probablement aucune nouvelle donnée n'a été produite sur le signal d'entrée smartCORE. Cela peut avoir différentes causes, comme par exemple l'absence d'un message de bus CAN, un signal GPS manquant ou l'absence de connexion Internet pour interroger des informations de commande. Dès que de nouvelles données arrivent, l'état repasse à false.

Pour chaque canal d'entrée, une valeur de timeout individuelle peut être attribuée via la macro #property avec l'option timeout=<val>. Celle-ci remplace, pour le canal, le réglage global inputTimeoutS, préréglé à $15 s$ .

Si des échantillons de données sont déjà présents dans le canal, la validité de la valeur la plus récente de la variable est prolongée dans l'état timeout. Elle est alors en retard sur l'heure d'exécution actuelle du module Math de l'intervalle de timeout réglé. Les calculs dépendants peuvent ainsi se poursuivre jusqu'à cet instant.

remarque

Ce décalage temporel n'est visible que là où des données sont visualisées ou utilisées sans horodatage, donc par exemple dans les données en direct MQTT, mais pas dans les fichiers OSF.

L'interrogation fournit l'état pour l'intervalle de lot (batch) en cours et est indépendante des contenus de données et des horodatages du canal.

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

important

L'argument de la fonction doit être directement une variable d'entrée.

Interroger un canal sur sa valeur de remplacement « isDefault » ²

La fonction renvoie true lorsque le canal est réglé durablement ou temporairement sur une valeur de remplacement par défaut.

Pour chaque canal d'entrée, une valeur par défaut individuelle et constante peut être attribuée via la macro #property avec l'option default=<val>. Si elle n'est pas définie, false (<bool> => 0, 0.0, "false") est utilisé.

La valeur par défaut est utilisée comme valeur de remplacement constante lorsque le canal n'a pas pu être connecté à un canal smartCORE.

La valeur par défaut est utilisée comme valeur de remplacement temporaire lorsque

le canal a été connecté isConnected()
et que le canal est encore vide isEmpty()
et que le canal est entré en timeout isTimeout()
et que
- la valeur par défaut a été explicitement définie via la macro #property
- ou que le canal a été marqué comme #timeless.

L'interrogation fournit l'état pour l'intervalle de lot (batch) en cours et est indépendante des contenus de données et des horodatages du canal.

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

important

L'argument de la fonction doit être directement une variable d'entrée.

Interroger l'état d'erreur d'un résultat « isError » ¹

La fonction renvoie true lorsque l'évaluation d'un terme a produit une erreur d'exécution. Le message d'erreur est également consigné dans le fichier journal lors de la sortie de la variable vers smartCORE, ou peut être réutilisé sous forme de chaîne dans le module Math.

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';

remarque

Il est recommandé d'utiliser une variable (locale) pour réutiliser le résultat.

Interroger le type de données « typeOf » ¹

La fonction typeOf renvoie le type de données de la valeur transmise sous forme de valeur ENUM :

t = typeOf(x);

Les valeurs ont les correspondances suivantes :

Valeur	Type de données
0	`void`
1	`<bool>`
2	`<uint>`
3	`<int>`
4	`<dbl>`
5	`<cxFlt>`
6	`<str>`
> 0x80000000	(Réservé)
0x8000B10B	BLOB - objet binaire, par ex. d'une `transition()`
0x8000EBAD	ERROR - erreur d'exécution d'un terme

Interroger les valeurs d'un canal sans notion de temps « value » ²

Cette fonction permet, à un endroit précis du calcul, de lever la dépendance temporelle d'un chemin de calcul, de manière similaire à #timeless.

Pour cela, la dernière valeur disponible avant l'intervalle de lot (evaluationTimeMs) est utilisée comme valeur de départ pour l'intervalle, puis tous les échantillons dont l'horodatage se situe dans l'intervalle de lot sont copiés et, enfin, la dernière valeur est prolongée jusqu'à la fin de l'intervalle. Si un canal vide est utilisé comme argument, une valeur de remplacement peut être indiquée explicitement.

L'interrogation fournit des valeurs pour l'intervalle de lot (batch) en cours et est indépendante des contenus de données et des horodatages du canal.

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

Typiquement, une référence circulaire dans le module Math entraîne le passage à un intervalle d'échantillonnage discret (discreteSampleTimeMs) pour le canal concerné, qui doit alors aussi être doté d'une valeur de départ explicite (syntaxe @0) :

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

astuce

Dans le contexte de commandes logiques, de machines à états, de surveillances de valeurs limites, etc., il peut être judicieux d'exécuter les calculs en respectant le temps tout en utilisant une rétroaction d'un résultat de calcul vers le début du calcul. La fonction value() représente précisément l'endroit où la rétroaction est rompue localement au sens de #timeless.

attention

La levée des dépendances temporelles conduit, à l'endroit concerné, à un comportement qui n'est plus prévisible et défini à 100 %. Des variations de signal de courte durée sur le terme d'entrée peuvent être manquées, ou des changements ne devenir visibles que dans un intervalle de lot ultérieur. Les effets de la fonction doivent être soigneusement vérifiés avant toute utilisation en production !

Décalage temporel des données d'un canal « shiftT » ²

Pour décaler les données d'un canal d'un intervalle de temps dT donné, la fonction shiftT() peut être utilisée. Comme un décalage suivi d'un calcul respectant le temps avec d'autres données entraîne toujours une mise en tampon, le décalage doit rester limité à quelques secondes.

L'intervalle de temps dT en secondes est ajouté à tous les horodatages des données du terme x. Un décalage avec dT > 0.0 décale les données vers le futur, dT < 0.0 vers le passé.

xs = shiftT(x, dT);

astuce

Cette fonction permet de compenser des retards connus dus à la transmission des données, depuis le système d'acquisition réel (convertisseur A/N, microcontrôleur) d'un signal analogique jusqu'à la réception et à l'horodatage des données dans smartCORE. Cela peut être utile pour compenser des déphasages, notamment pour des signaux échantillonnés à très haute fréquence.

Grandeurs caractéristiques de plusieurs valeurs

Fonction	Description
abs(x1, ..., xN)	norme l2 des valeurs individuelles (x1, ..., xN), $= \sqrt{\sum_{i=1}^N x_i^2}$
min(x1, ..., xN)	Minimum des valeurs individuelles (x1, ..., xN)
max(x1, ..., xN)	Maximum des valeurs individuelles (x1, ..., xN)
mean(x1, ..., xN)	Moyenne arithmétique des valeurs individuelles (x1, ..., xN) $= \frac{1}{N} \sum_{i=1}^N x_i$
rms(x1, ..., xN)	Racine carrée de la moyenne arithmétique des valeurs individuelles élevées au carré (x1, ..., xN) $= \sqrt{\frac{1}{N}\sum_{i=1}^N x_i^2}$

Limitation et arrondi

Fonction	Description
range(x, ...)	Limite la valeur d'entrée à une plage de valeurs donnée. Voir la description ci-après.
ceil(x)	plus petite valeur entière $i >= x$ (conserve le type de données)
ceil2i(x)	plus petite valeur entière $i >= x$ (type de retour int)
floor(x)	plus grande valeur entière $i <= x$ (conserve le type de données)
floor2i(x)	plus grande valeur entière $i <= x$ (type de retour int)
trunc(x)	si $x >= 0$ , alors plus grande valeur entière $i <= x$ , sinon plus petite valeur entière $i >= x$
round(x)	valeur entière $i$ telle que $x - 0.5 < i <= x + 0.5$ (conserve le type de données)
round2i(x)	valeur entière $i$ telle que $x - 0.5 < i <= x + 0.5$ (type de retour int)
notZero(x, ...)	Suit x tant que $\\|x-x_{crit}\\| \ge \epsilon$ , sinon si $x \ge x_{crit}$ , on pose $x_{crit}+\epsilon$ , dans les autres cas $x_{crit}-\epsilon$ Voir la description ci-après.

Plage de valeurs « range »

La fonction restreint la plage de valeurs d'un signal d'entrée x donné (scalaire ou vecteur) à un intervalle $[min, max]$ et offre, via la configuration facultative, de nombreuses variantes.

Limitation de la plage de valeurs

r1  = range(x);
r2  = range(x, [min, max]);        // bessere Lesbarkeit
r3  = range(x, min, max);          // nicht mehr verwenden
// Optionale Konfiguration für alle Varianten
rx  = range(..., { min: off|<val>
                 , max: off|<val>
                 , lower: off|<val>|erase
                 , upper: off|<val>|erase
                 , mode: <enum>
                 , defXY: [<dbl>, <dbl>]
                 , limVar: <str>
                 });

Propriété	Valeur	Description
min	`off/<val>`	Désactivation ou configuration fixe d'une limite inférieure (scalaire). Si le paramètre de fonction min est utilisé, cette propriété est sans effet.
max	`off/<val>`	Désactivation ou configuration fixe d'une limite supérieure (scalaire). Si le paramètre de fonction max est utilisé, cette propriété est sans effet.
lower	`off/<val>/erase`	Si activée, la valeur de remplacement est émise lorsque la limite inférieure est franchie (x < min), ou l'échantillon est supprimé
upper	`off/<val>/erase`	Si activée, la valeur de remplacement est émise lorsque la limite supérieure est dépassée (x > max), ou l'échantillon est supprimé
mode	`<enum>`	Si x est un vecteur, selon mode - box : toutes les coordonnées individuellement… - length : la longueur du vecteur ( >= 0.0 )... - azimuth : l'angle du vecteur dans le plan XY... - elevation : l'angle du vecteur entre le plan XY et l'axe Z… ...sont limités à la plage réglée $[min, max]$
defXY	`[<dbl>, <dbl>]`	En mode elevation, defXY est la direction par défaut lorsque le vecteur doit être ramené de la verticale (déf. : [1, 0, 0]).
limVar	`<str>`	limVar définit facultativement le nom d'une variable locale `<bool>` afin de signaler la limitation active

Non-zéro « notZero »

La fonction garantit qu'une valeur critique (déf. : 0.0) n'est jamais émise. À la place, la plage de valeurs autour de la grandeur critique est exclue au moyen d'une grandeur $\epsilon$ (déf. : 1e-6). L'application de la fonction est par exemple optimisée pour les divisions dans lesquelles une division par zéro serait possible et doit être exclue.

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

\rm{notZero}(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..

Un exemple est la conversion sûre d'un débit volumique de carburant en $l/h$ et d'une vitesse en $km/h$ en une consommation en $l/100km$ :

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

Seuil de commutation avec hystérésis « threshold »

Cette fonction génère un signal de commutation à partir de la comparaison d'un signal avec une valeur de seuil fixe threshold. Au moyen d'une hystérésis hysteresis et de temps de retard delayOn, delayOff, les perturbations sur l'allure du signal peuvent être supprimées.

Threshold avec hystérésis

La fonction peut être utilisée sous différentes formes d'application :

trig1 = threshold(x);
trig2 = threshold(x, t);
trig3 = threshold(x, t, h);
// Optionale Konfiguration für alle Varianten
trigX = threshold(..., { threshold: <dbl>
                       , hysteresis: <dbl>
                       , delayOn: <dbl>
                       , delayOff: <dbl> 
                       , logic: <enum>
                       , startup: inf|<bool>
                       });

Propriété	Valeur	Signification
threshold	`<dbl>`	Seuil de déclenchement, déf. : 0.55 Est remplacé par l'argument t
hysteresis	`<dbl>`	Largeur de la zone d'hystérésis, ajoutée au threshold pour la seconde valeur limite, déf. : -0.10 Est remplacée par l'argument h
delayOn	`<dbl>`	temps de filtrage facultatif en secondes pour la mise en marche
delayOff	`<dbl>`	temps de filtrage facultatif en secondes pour l'arrêt
logic	`<enum>`	- auto : le fonctionnement est déterminé par le signe de l'hystérésis - above : déclenchement au-dessus de la zone d'hystérésis - below : déclenchement en dessous de la zone d'hystérésis
startup	`inf\|<bool>`	Comportement au démarrage : inf : la position du premier échantillon par rapport au seuil détermine la valeur de sortie (déf.). `<bool>` : on suppose que cette valeur de sortie a été émise avant le premier échantillon.

La fonction renvoie true à l'instant où le signal x dépasse le seuil de déclenchement défini et false à l'instant où le signal x retombe dans la zone de rappel.

Threshold avec hystérésis

Si les temps de retard sont réglés, le signal x doit rester en continu pendant l'intervalle indiqué dans la zone de déclenchement ou de rappel avant que la commutation ne soit réalisée. La commutation est ainsi retardée par rapport au franchissement de la valeur limite respective.

Dans le mode de fonctionnement auto (par défaut), le déclenchement s'effectue en fonction du signe de l'hystérésis :

Hystérésis	Déclenchement (true)	Rappel (false)
$hysterese < 0$	$x > threshold$	$x < threshold + hysteresis$
$hysterese > 0$	$x < threshold$	$x > threshold + hysteresis$

Dans les modes de fonctionnement above et below, threshold et hysteresis définissent deux limites d'une zone d'hystérésis :

g_{low} = min(threshold, threshold + hysteresis)

g_{high} = max(threshold, threshold + hysteresis)

zone = [g_{low}, g_{high}]

Mode de fonctionnement	Déclenchement (true)	Rappel (false)
above	$x > g_{high}$	$x < g_{low}$
below	$x < g_{low}$	$x > g_{high}$

Limitation de pente « rampLimit » ³

La fonction garantit que les variations du signal d'entrée x sont transmises avec une pente de rampe limitée. Un ou deux paramètres supplémentaires peuvent être utilisés en option pour définir soit un gradient maximal indépendant du sens, soit des gradients différents pour les allures croissantes et décroissantes.

y1 = rampLimit(x, maxGrad); 
y2 = rampLimit(x, maxPosGrad, maxNegGrad); 

Propriété	Valeur	Signification
x	`<dbl>`	Signal d'entrée
maxGrad	`<dbl>`	Gradient maximal commun pour les allures de signal croissantes et décroissantes
maxPosGrad	`<dbl>`	Gradient maximal pour les allures de signal croissantes
maxNegGrad	`<dbl>`	Gradient maximal pour les allures de signal décroissantes

L'unité des gradients maximaux est [Einheit von x] / s. L'indication est sans signe, c'est-à-dire $maxGrad \ge 0.0$ . Un gradient de 0.0 met la fonction en bypass dans le sens correspondant : le signal d'entrée est émis directement.

Disponible à partir de la version 10 du catalogue. ↩ ↩² ↩³ ↩⁴ ↩⁵
Disponible à partir de la version 11 du catalogue. ↩ ↩² ↩³
Disponible à partir de la version 12 du catalogue. ↩

Fonctions système​

Propriétés d'un canal ou d'une valeur​

Interroger la connexion SmartCORE « isConnected » 1​

Interroger l'état de la source de données « isEmpty » 1​

Interroger une lacune de données « isTimeout » 1​

Interroger un canal sur sa valeur de remplacement « isDefault » 2​

Interroger l'état d'erreur d'un résultat « isError » 1​

Interroger le type de données « typeOf » 1​

Interroger les valeurs d'un canal sans notion de temps « value » 2​

Décalage temporel des données d'un canal « shiftT » 2​

Grandeurs caractéristiques de plusieurs valeurs​

Limitation et arrondi​

Plage de valeurs « range »​

Non-zéro « notZero »​

Seuil de commutation avec hystérésis « threshold »​

Limitation de pente « rampLimit » 3​

Footnotes​

Fonctions système

Propriétés d'un canal ou d'une valeur

Interroger la connexion SmartCORE « isConnected » ¹

Interroger l'état de la source de données « isEmpty » ¹

Interroger une lacune de données « isTimeout » ¹

Interroger un canal sur sa valeur de remplacement « isDefault » ²

Interroger l'état d'erreur d'un résultat « isError » ¹

Interroger le type de données « typeOf » ¹

Interroger les valeurs d'un canal sans notion de temps « value » ²

Décalage temporel des données d'un canal « shiftT » ²

Grandeurs caractéristiques de plusieurs valeurs

Limitation et arrondi

Plage de valeurs « range »

Non-zéro « notZero »

Seuil de commutation avec hystérésis « threshold »

Limitation de pente « rampLimit » ³

Footnotes