Funzioni di utilità
Funzioni di sistema
| Funzione | Descrizione |
|---|---|
| time() | Restituisce l'istante di valutazione del modulo in secondi UTC |
Proprietà di un canale o di un valore
| Funzione | Descrizione |
|---|---|
| deltaT(x) | Restituisce in secondi la distanza temporale degli ultimi due istanti di valutazione del termine x |
| deltaY(x) | Restituisce la differenza di valore degli ultimi due campioni del termine x, è positiva con andamento crescente del segnale |
| time(x) | Restituisce l'istante dell'ultimo campione di dati modificato del termine x |
| sgn(x) | Segno del valore x |
| sgn(x,eps) | Segno del valore x con tolleranza (eps) |
| abs(x) | Valore assoluto del valore scalare x, Per la lunghezza di un vettore vedere Length(V) |
| isConnected(x) | Interrogare la connessione smartCORE |
| isEmpty(x) | Interrogare lo stato della sorgente dati |
| isTimeout(x) | Interrogare una lacuna nei dati |
| isDefault(x) | Interrogare se il canale è sul valore sostitutivo |
| isError(x) | Interrogare lo stato di errore di un risultato |
| typeOf(x) | Interrogare il tipo di dati |
| value(x, ...) | Interrogare i valori di un canale senza riferimento temporale |
| shiftT(x,dT) | Spostamento temporale dei dati di un canale |
Interrogare la connessione smartCORE "isConnected" 1
La funzione restituisce true se il canale è stato collegato con successo, come ingresso, a un canale smartCORE.
Se all'avvio di smartCORE e del modulo Math non è possibile trovare alcun canale smartCORE, ciò non viene solo scritto nel file di log, ma viene anche segnalato tramite questo stato (false).
In tal caso il valore default viene scritto come costante nella variabile, in modo che i calcoli possano essere eseguiti. Questo è inizialmente false, ma tramite la macro #property può essere impostato con default=<variant> su qualsiasi valore e tipo costante. Vedere anche isDefault().
L'interrogazione restituisce lo stato per l'intervallo batch in corso.
s1 = isConnected(x);
s2 = isConnected($'other.y');
L'argomento della funzione deve essere direttamente una variabile di ingresso.
Interrogare lo stato della sorgente dati "isEmpty" 1
La funzione restituisce true se, all'avvio di smartCORE e del modulo Math, nel canale di ingresso smartCORE non sono ancora stati prodotti dati. Ciò può accadere quando altre sorgenti dati possono produrre dati solo dopo una fase di inizializzazione o dopo la prolungata costituzione di una connessione dati.
Se, con canale che rimane vuoto, si verifica inoltre la condizione di timeout riferita all'istante di avvio del modulo Math ed è impostato un valore di default esplicito tramite la macro #property con l'opzione default=<val>, questo viene utilizzato temporaneamente come valore sostitutivo fino all'arrivo del primo campione di dati. Vedere anche isDefault().
L'interrogazione restituisce lo stato per l'intervallo batch in corso ed è indipendente dai contenuti dei dati e dai timestamp del canale.
s1 = isEmpty(x);
s2 = isEmpty($'other.y');
L'argomento della funzione deve essere direttamente una variabile di ingresso.
Interrogare una lacuna nei dati "isTimeout" 1
La funzione restituisce true se il campione più recente nel segnale di ingresso smartCORE è più vecchio di un intervallo di timeout impostabile e quindi probabilmente sul segnale di ingresso smartCORE non sono stati prodotti dati nuovi. Ciò può avere diverse cause, come ad es. la mancata ricezione di un messaggio CANbus, l'assenza del segnale GPS o l'assenza di una connessione Internet per l'interrogazione di informazioni di controllo. Non appena arrivano nuovi dati, lo stato torna a false.
Per ogni canale di ingresso, tramite la macro #property con l'opzione timeout=<val> è possibile assegnare un valore di timeout individuale. Questo sovrascrive per il canale l'impostazione globale tramite inputTimeoutS, preimpostata a .
Se, con canale che rimane vuoto, si verifica la condizione di timeout riferita all'istante di avvio del modulo Math ed è impostato un valore di default esplicito tramite la macro #property con l'opzione default=<val>, questo viene utilizzato temporaneamente come valore sostitutivo fino all'arrivo del primo campione di dati. Vedere anche isDefault().
Se nel canale sono già presenti campioni di dati, nello stato timeout la validità del valore più recente della variabile viene prolungata. Esso resta allora indietro, rispetto al tempo di esecuzione attuale del modulo Math, dell'intervallo di timeout impostato. I calcoli dipendenti possono quindi proseguire fino a tale istante.
Questo sfasamento temporale è visibile solo dove i dati vengono visualizzati o utilizzati senza timestamp, ad es. nei dati live MQTT, ma non nei file OSF.
L'interrogazione restituisce lo stato per l'intervallo batch in corso ed è indipendente dai contenuti dei dati e dai timestamp del canale.
s1 = isTimeout(x);
s2 = isTimeout($'other.y');
L'argomento della funzione deve essere direttamente una variabile di ingresso.
Interrogare se il canale è sul valore sostitutivo "isDefault" 2
La funzione restituisce true se il canale è impostato in modo permanente o temporaneo su un valore sostitutivo di default.
Per ogni canale di ingresso, tramite la macro #property con l'opzione default=<val> è possibile assegnare un valore di default costante individuale. Se questo non è impostato, viene utilizzato false (<bool> => 0, 0.0, "false").
Il valore di default viene utilizzato come valore sostitutivo costante quando il canale non ha potuto essere collegato a un canale smartCORE.
Il valore di default viene utilizzato come valore sostitutivo temporaneo quando
- il canale è stato collegato
isConnected() - e il canale è ancora vuoto
isEmpty() - e il canale è andato in timeout
isTimeout() - e
- il valore di default è stato impostato esplicitamente tramite la macro
#property - oppure il canale è stato contrassegnato come
#timeless.
- il valore di default è stato impostato esplicitamente tramite la macro
L'interrogazione restituisce lo stato per l'intervallo batch in corso ed è indipendente dai contenuti dei dati e dai timestamp del canale.
s1 = isDefault(x);
s2 = isDefault($'other.y');
L'argomento della funzione deve essere direttamente una variabile di ingresso.
Interrogare lo stato di errore di un risultato "isError" 1
La funzione restituisce true se la valutazione di un termine ha generato un errore di runtime. Il messaggio di errore, all'emissione della variabile verso smartCORE, viene salvato anche nel file di log oppure può essere ulteriormente utilizzato come stringa nel modulo 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';
Si raccomanda di utilizzare una variabile (locale) per riutilizzare il risultato.
Interrogare il tipo di dati "typeOf" 1
La funzione typeOf restituisce il tipo di dati del valore passato come valore ENUM:
t = typeOf(x);
I valori hanno la seguente corrispondenza:
| Valore | Tipo di dati |
|---|---|
| 0 | void |
| 1 | <bool> |
| 2 | <uint> |
| 3 | <int> |
| 4 | <dbl> |
| 5 | <cxFlt> |
| 6 | <str> |
| > 0x80000000 | (Riservato) |
| 0x8000B10B | BLOB - oggetto binario, ad es. di una transition() |
| 0x8000EBAD | ERROR - errore di runtime di un termine |
Interrogare i valori di un canale senza riferimento temporale "value" 2
Questa funzione consente di sciogliere, in un punto determinato del calcolo, la dipendenza temporale di un percorso di calcolo in modo simile a #timeless.
A tal fine, l'ultimo valore disponibile prima dell'intervallo batch (evaluationTimeMs) viene utilizzato come valore iniziale per l'intervallo, poi vengono copiati tutti i campioni con timestamp nell'intervallo batch e infine l'ultimo valore viene esteso fino alla fine dell'intervallo. Se come argomento viene utilizzato un canale vuoto, è possibile indicare esplicitamente un valore sostitutivo.
L'interrogazione restituisce valori per l'intervallo batch in corso ed è indipendente dai contenuti dei dati e dai timestamp del canale.
v1 = value(x);
v2 = value(x, def); // use def, if isEmpty(x)
Tipicamente un riferimento circolare nel modulo Math comporta il passaggio a un intervallo di campionamento discreto (discreteSampleTimeMs) per il canale interessato, che deve allora essere dotato anche di un valore iniziale esplicito (sintassi @0):
zv@0 = 0; // startvalue for discrete calculation
zv = a * zv + (1 - a) * x; // example for circular use of 'zv'
Nel contesto di controlli logici, macchine a stati, monitoraggi di valori limite, ecc. può essere opportuno eseguire i calcoli con la corretta temporizzazione e tuttavia utilizzare una retroazione di un risultato di calcolo all'inizio del calcolo. La funzione value() rappresenta esattamente il punto in cui la retroazione viene interrotta localmente nel senso di #timeless.
Lo scioglimento delle dipendenze temporali comporta, nel punto corrispondente, un comportamento che non è più prevedibile e definito al 100%. Brevi variazioni del segnale sul termine di ingresso possono essere ignorate oppure le modifiche possono diventare visibili solo in un intervallo batch successivo. Gli effetti della funzione devono essere verificati con cura prima dell'impiego in produzione!
Spostamento temporale dei dati di un canale "shiftT" 2
Per spostare i dati di un canale di un determinato intervallo di tempo dT si può utilizzare la funzione shiftT(). Poiché uno spostamento e il successivo calcolo con la corretta temporizzazione con altri dati comporta sempre una bufferizzazione, lo spostamento dovrebbe rimanere limitato a pochi secondi.
A tutti i timestamp dei dati del termine x viene sommato l'intervallo di tempo dT in secondi. Uno spostamento con dT > 0.0 sposta i dati nel futuro, dT < 0.0 nel passato.
xs = shiftT(x, dT);
Con questa funzione è possibile compensare ritardi temporali noti dovuti alla trasmissione dei dati dal vero sistema di acquisizione (convertitore AD, microcontrollore) di un segnale analogico fino alla ricezione e alla marcatura temporale dei dati in smartCORE. Ciò può essere utile per compensare sfasamenti, in particolare con segnali campionati a frequenza molto elevata.
Grandezze caratteristiche di più valori
| Funzione | Descrizione |
|---|---|
| abs(x1, ..., xN) | norma l2 dei singoli valori (x1, ..., xN), |
| min(x1, ..., xN) | Minimo dei singoli valori (x1, ..., xN) |
| max(x1, ..., xN) | Massimo dei singoli valori (x1, ..., xN) |
| mean(x1, ..., xN) | Media aritmetica dei singoli valori (x1, ..., xN) |
| rms(x1, ..., xN) | Radice quadrata della media aritmetica dei singoli valori elevati al quadrato (x1, ..., xN) |
Limitazione e arrotondamento
| Funzione | Descrizione |
|---|---|
| range(x, ...) | Limita il valore di ingresso a un determinato intervallo di valori. Vedere la descrizione seguente. |
| ceil(x) | valore intero più piccolo (conserva il tipo di dati) |
| ceil2i(x) | valore intero più piccolo (tipo restituito int) |
| floor(x) | valore intero più grande (conserva il tipo di dati) |
| floor2i(x) | valore intero più grande (tipo restituito int) |
| trunc(x) | se allora valore intero più grande , altrimenti valore intero più piccolo |
| round(x) | valore intero , tale che (conserva il tipo di dati) |
| round2i(x) | valore intero , tale che (tipo restituito int) |
| notZero(x, ...) | Segue x, purché , altrimenti se viene impostato , in caso contrario Vedere la descrizione seguente. |
Intervallo di valori "range"
La funzione restringe l'intervallo di valori per un dato segnale di ingresso x (scalare o vettore) a un intervallo e, tramite la configurazione opzionale, offre molteplici varianti.
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>
});
| Proprietà | Valore | Descrizione |
|---|---|---|
| min | off/<val> | Disattivazione o configurazione fissa di un limite inferiore (scalare). Se viene utilizzato il parametro di funzione min, questa proprietà non ha alcun effetto. |
| max | off/<val> | Disattivazione o configurazione fissa di un limite superiore (scalare). Se viene utilizzato il parametro di funzione max, questa proprietà non ha alcun effetto. |
| lower | off/<val>/erase | Se attivata, al superamento del limite inferiore (x < min) viene emesso il valore sostitutivo oppure il campione viene rimosso |
| upper | off/<val>/erase | Se attivata, al superamento del limite superiore (x > max) viene emesso il valore sostitutivo oppure il campione viene rimosso |
| mode | <enum> | Se x è un vettore, in funzione di mode - box: tutte le coordinate singolarmente… - length: la lunghezza del vettore ( >= 0.0 )... - azimuth: l'angolo del vettore nel piano XY... - elevation: l'angolo del vettore dal piano XY verso l'asse Z… ...vengono limitate all'intervallo impostato |
| defXY | [<dbl>, <dbl>] | Nella modalità elevation, defXY è la direzione standard quando il vettore deve essere riportato indietro dalla verticale (def.: [1, 0, 0]). |
| limVar | <str> | limVar definisce opzionalmente il nome di una variabile locale <bool> per segnalare la limitazione attiva |
Non zero "notZero"
La funzione fa in modo che un valore critico (def.: 0.0) non venga mai emesso. Al suo posto, l'intervallo di valori attorno alla grandezza critica viene escluso mediante una grandezza (def.: 1e-6). L'applicazione della funzione è ottimizzata, ad es., per le divisioni in cui sarebbe possibile una divisione per zero, che deve essere esclusa.
xnz1 = notZero(x); // eps := 1e-6, x_crit := 0.0
xnz2 = notZero(x, eps); // x_crit := 0.0
xnz3 = notZero(x, eps, x_crit);
Un esempio è la conversione sicura della portata volumetrica di carburante in e della velocità in in un consumo in :
consumption = volFlow / notZero(speed, 0.1) * 100;
Soglia di commutazione con isteresi "threshold"
Questa funzione genera un segnale di commutazione dal confronto di un segnale con un valore di soglia fisso threshold. Mediante un'isteresi hysteresis e tempi di ritardo delayOn, delayOff è possibile sopprimere i disturbi sull'andamento del segnale.
La funzione può essere utilizzata in diverse forme di applicazione:
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>
});
| Proprietà | Valore | Significato |
|---|---|---|
| threshold | <dbl> | Soglia di intervento, def.: 0.55 Viene sovrascritta con l'argomento t |
| hysteresis | <dbl> | Larghezza della zona di isteresi, viene sommata a threshold per il secondo valore limite, def.: -0.10 Viene sovrascritta con l'argomento h |
| delayOn | <dbl> | tempo di filtro opzionale in secondi per il processo di attivazione |
| delayOff | <dbl> | tempo di filtro opzionale in secondi per il processo di disattivazione |
| logic | <enum> | - auto: la funzione è determinata dal segno dell'isteresi - above: intervento al di sopra della zona di isteresi - below: intervento al di sotto della zona di isteresi |
| startup | inf|<bool> | Comportamento all'avvio: inf: la posizione del primo campione rispetto alla soglia determina il valore di uscita (def.). <bool>: si assume che questo valore di uscita sia stato emesso prima del primo campione. |
- La funzione restituisce true per l'istante in cui il segnale x supera la soglia di intervento definita e false per l'istante in cui il segnale x rientra nel ripristino.
Se vengono impostati i tempi di ritardo, il segnale x deve rimanere continuativamente per l'intervallo indicato nello stato di intervento o di ripristino prima che avvenga la commutazione. La commutazione risulta così ritardata rispetto al superamento del rispettivo valore limite.
Nella modalità auto (default) l'intervento avviene in funzione del segno dell'isteresi:
| Isteresi | Intervento (true) | Ripristino (false) |
|---|---|---|
Nelle modalità above e below, threshold e hysteresis definiscono due limiti di una zona di isteresi:
| Modalità | Intervento (true) | Ripristino (false) |
|---|---|---|
| above | ||
| below |
Limitazione della pendenza "rampLimit" 3
La funzione fa in modo che le variazioni sul segnale di ingresso x vengano trasmesse con una pendenza di rampa limitata. Opzionalmente si possono utilizzare uno o due parametri aggiuntivi per definire un gradiente massimo indipendente dalla direzione oppure gradienti diversi per andamenti crescenti e decrescenti.
y1 = rampLimit(x, maxGrad);
y2 = rampLimit(x, maxPosGrad, maxNegGrad);
| Proprietà | Valore | Significato |
|---|---|---|
| x | <dbl> | Segnale di ingresso |
| maxGrad | <dbl> | Gradiente massimo comune per andamenti del segnale crescenti e decrescenti |
| maxPosGrad | <dbl> | Gradiente massimo per andamenti del segnale crescenti |
| maxNegGrad | <dbl> | Gradiente massimo per andamenti del segnale decrescenti |
L'unità dei gradienti massimi è [unità di x] / s. L'indicazione è priva di segno, cioè . Un gradiente di 0.0 commuta la funzione in bypass nella direzione corrispondente: il segnale di ingresso viene emesso direttamente.