Berechnungsmodul "math"

---

WICHTIGE VORABINFORMATIONEN

important

Dieses Modul wird ohne jegliche ausdrückliche oder implizierte Garantien zur Verfügung gestellt, die unter anderem die implizierte Garantie der Verwendbarkeit des Moduls für einen bestimmten Zweck einschließen.

Auf keinen Fall sind optiMEAS GmbH oder die Beitragsleistenden dieses Moduls für irgendwelche direkten, indirekten, zufälligen, speziellen, beispielhaften oder Folgeschäden (u.a. Verschaffen von Ersatzgütern oder -dienstleistungen, Einschränkung und/oder Verlust der Nutzungsfähigkeit, von Daten, Profit oder Geschäftsunterbrechung), wie auch immer verursacht und unter welcher Verpflichtung auch immer, ob in Vertrag, strikter Verpflichtung oder unerlaubter Handlung (inkl. Fahrlässigkeit) verantwortlich, auf welchem Weg sie auch immer durch die Benutzung dieses Moduls entstanden sind, sogar, wenn sie auf die Möglichkeit eines solchen Schadens hingewiesen worden sind.

hinweis

Es ist davon auszugehen, dass Funktionalität bzgl. Funktionskatalog, Schnittstellen, Parametrisierung, oder ähnlichem unvollständig ist und in zukünftigen Versionen verändert bereitgestellt werden kann. Von daher erfolgt der Betrieb auf eigene Verantwortung.

tipp

Wir sind für sämtliche Verbesserungsvorschläge und Tips, die sich aus der Nutzung dieses Moduls ergeben, äußerst dankbar und ermutigen die Benutzer, diesbezüglich mit uns Kontakt aufzunehmen.

---

Beschreibung

Mittels des Berechnungsmoduls "math" kann ein unter Verwendung vielfältiger Funktionen benutzerdefinierter Formelsatz auf unterschiedliche Daten angewandt werden.

Zu den Daten (Argumenten, Ausdrücken) zählen hierbei einerseits i.A. zeitlich veränderliche smartCORE Kanaldaten, auf die über Kanalnamen zugegriffen werden kann, sowie andererseits konstante Ausdrücke, Resourcen, persistente Daten, sowie Daten, die mit Hilfe von Decodern bereitgestellt bzw. aufbereitet wurden.

Es werden neben eindimensionalen Daten auch mehrdimensionale in Form von Vektoren und Matrizen unterstützt, wobei allen Komponenten dieser Daten unterschiedliche Datentypen zugrundeliegen können und eine automatische Typumwandlung, falls notwendig, erfolgt.

Die Beschreibung des Sprachumfangs kann unter

Sprachreferenz

eingesehen werden.

Zu den unterstützten Funktionen zählen unter anderem

• arithmetisch-logische Operatoren inklusive ihrer Rangordnung und Assoziativität
• mathematisch-trigonometrische Funktionen
• zeitliche Filterfunktionen (wie z.B. die Differentiation und Integration von Funktionen)
• numerische Algorithmen (z.B. FFT, Dekomposition von Matrizen, Interpolation, Prädiktion)
• Abtastung (Sampling) von Messdaten
• Zählfunktionen und Timer
• Auswahlfunktionen, bit-orientierte Funktionen sowie Funktionen zur Typumwandlung (Type casts)
• Sequenzierung von Ausdrücken und Zuweisungen
• Funktionen, die auf Zeichenketten operieren

Funktionsreferenz

Beispiele

Im allgemeinen ist es im Rahmen der Konfiguration sinnvoll, ein minimales Beispiel zu betrachten und nach seinen Erfordernissen anzupassen.

Ein Minimalbeispiel, das aus zwei fiktiven smartCORE Einganskanälen Spannung und Strom unter Zuhilfenahme der physikalischen Größengleichung

$$P = U \cdot I \cdot \frac{[\rm{A}]}{[\rm{mA}]}$$ $$W = \frac{[\rm{kWh}]}{[\rm{Ws}]} \cdot \int_{0}^{t} P(\tau) d\tau$$

die Ausgangskanäle Leistung und Energie berechnet, sei im folgenden dargestellt

{
  "module":"math1",
  "factory":"mathmodule",
  "config": {
    "math": [
      "Leistung = Spannung * Strom * 1e-3;              //  Strom in mA!",
      "Energie = 1/(3600 * 1e3) * integrate(Leistung);  //  Energie in kWh!"
    ],
    "outputs": [
      {
        "datatype": "double",
        "name": "Leistung",
        "physicalUnit": "W"
      },
      {
        "datatype": "double",
        "name": "Energie",
        "physicalUnit": "kWh"
      }
    ]
  }
}

Für Berechnungen, deren Laufzeitkomplexität die Echtzeitanforderungen übersteigt, bietet sich die Verwendung einer Lookup Table (LUT) an. Im folgenden Beispiel wird das Kraftstoffvolumen in einem Tank anhand des am Boden dieses Tank vorherrschenden Drucks interpolativ aus der Lookup Table ermittelt, wobei die Inhalte dieser LUT aus einer im Dateisystem befindlichen Datei via resources bereitgestellt werden

{
  "module":"math1",
  "factory":"mathmodule",
  "config": {
    "math": [
      "Volumen = lookup(Druck, {$ref:'Tank_LUT'});"
    ],
    "outputs": [
      {
        "datatype": "double",
        "name": "Volumen",
        "physicalUnit": "l"
      },
    ],
    "resources": [
      "Tank_LUT": {
        "decoder": [
          "file"
        ],
        "value": "Tank_LUT.lut"
      }
    ]
  }
}

Der Inhalt der Datei Tank_LUT.lut wäre dann gemäß der Beschreibung zur Funktion lookup() wie folgt (wobei hier nicht alle 161 Stützstellen aufgeführt sind):

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
... usw

Motivation

Die Verwendung des Berechnungsmoduls mathmodule ermöglicht u.a. folgendes

• Diagnose und Analyse von Prozesszuständen direkt auf dem Gerät
• Verminderung des zu übertragenen Datenvolumens durch Fokussierung auf Kennwerte oder Trends
• Virtuelle Messungen auf Messsignalen, z.B. Dauer einer Türbewegung, Amplitude eines Signals, etc.
• Ereigniszähler, Betriebsstundenzähler, Integrale
• Klassierungen (Verweildauer, Überrollungen, Rainflow, ...)
• Verrechnung mehrkomponentiger Messgrößen (Rosetten-DMS)
• Schnelle PoC Implementierung zur (Vor-)Entwicklung von PlugIns
• Einfache Steuerungsfunktionen

JSON-Konfiguration

Eine minimal erforderliche Konfiguration des Berechnungsmoduls hat im wesentlichen folgende Struktur

{
  "module":"math1",
  "factory":"mathmodule",
  "config": {
    "math": [

      < MATH >

    ],
    "outputs": [

      < OUTPUTS >

    ]
  }
}

Eine vollständige Konfiguration des Berechnungsmoduls hat hingegen im wesentlichen folgende Struktur

{
  "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"
      },
      ...
    }
  }
}

Globale Modulparameter

Es können im Rahmen der Modulkonfiguration folgende Parameter verwendet werden

Parametername	Erforderlich	Datentyp	sinnvoller Wertebereich	Default-Wert	Beschreibung
packages	Nein	JSON Array of STRING		EMPTY JSON Array	Liste, die optionale Funktionspakete beinhaltet
evaluationTimeMs	Nein	INT	100 -	1000 (1 s)	Aufrufintervall der Berechnung (Polling Interval) in ms
inputTimeoutS	Nein	INT	10 -	15 (15 s)	Timeout, nach dem nicht mehr auf Kanaldaten gewartet, sondern die Berechnung unter Zuhilfenahme des letzten Kanalwertes fortgesetzt wird in s
discreteSampleTimeMs	Nein	INT	1 -	100 (100 ms)	Abtastzeit (Stützweite des zugrundeliegenden zeitlichen Gitters) für die zeitdiskrete Berechnung/Auswertung rekursiver Formelteile in ms
math	JA	JSON Array of STRING bzw. STRING			String, bzw. zu einem einzigen String konkatenierte Liste von Strings, die den Formelsatz der Berechnung darstellt (siehe unten)
outputs	JA	JSON Array of JSON Object for Channel Configuration			Liste sämtlicher Ausgabekanäle, bzw. darüberhinaus gehend auch aller persistenten Eingabekanäle (siehe unten)
resources	Nein	JSON Object for Resource Configuration			Objekt, das die benutzten Ressourcen konfiguriert (siehe unten)
minLogLevel	Nein	ENUM	OFF, DEBUG, INFO, WARNING, ERROR, FATAL	INFO	Ausgabefilter für Meldungen aus dem Mathe-Modul, nur Meldungen mit mindestens dem angegebenen Schweregrad werden in das Logfile geschrieben.

Konfiguration des Formelsatzes "math"

Der Formelsatz der periodisch auszuführenden Berechnung kann je nach Komplexität entweder als ein einziger String oder eine Liste von Strings (in Form eines JSON Arrays) spezifiziert werden. Wird eine Liste spezifiziert, so werden alle Listenelemente als Zeilen des Formelsatzes mit dem verbindenden Zeichen \n aneinandergereiht.

Weiterführende Informationen sind auf folgenden Seiten verfügbar:

• Beschreibung der allgemeinen Funktion
• Semantik und Syntax, Operatoren
• Funktionsreferenz
• Verwendung von Ressourcen
• sowie verschiedene Anwendungsbeispiele

Beispiele für Formelsätze sind im folgenden

{
  "module":"math1",
  "factory":"mathmodule",
  "config": {
    "math": "y = 42;"
  }
}

{
  "module":"math1",
  "factory":"mathmodule",
  "config": {
    "math": [
      "c = 42;",
      "y = c;"
    ]
  }
}

important

In dieser Dokumentation wird der Fokus auf den eigentlichen, mehrzeiligen Formelsatz gelegt. Bei der Übetragung des Formelsatzes in die JSON-Konfiguration müssen die einzelnen Zeilen des Formelsatzes deshalb in " ... " eingefasst werden. Dies bedingt, dass alle " und \-ESCAPE-Zeichen im Formeltext erneut durch das \-ESCAPE-Zeichen für die JSON Parser unsichtbar gemacht werden müssen.

Aus dem folgenden Formeltext mit verschiednen Textelementen und einer Konfiguration

s1a = '17" (inch)';
s1b = "17\" (inch)";
s2a = "Hat's funktioniert?\t[ja/nein]";
s2b = 'Hat\'s funktioniert?\t[ja/nein]';
fnc = myParameterFunction(x, {"property":"value"});

wird in der JSON-Konfiguration des Math Moduls

    "math": [
      "s1a = '17\" (inch)';",
      "s1b = \"17\\\" (inch)\";",
      "s2a = \"Hat's funktioniert?\\t[ja/nein]\";",
      "s2b= 'Hat\\'s funktioniert?\\t[ja/nein]';",
      "fnc = myParameterFunction(x, {\"property\":\"value\"});"
    ], ...

Diese zusätzliche Formatierung wird in den Beispielen dieser Funktionsreferenz nicht berücksichtigt, da sie in der Regel durch den verwendeten Editor z.B. im optiCONTROL automatisch umgesetzt wird.

Konfiguration der Ausgabekanäle "outputs"

Im allgemeinen dient das Berechnungsmodul der Berechnung von Ausgabewerten, die in smartCORE Kanäle produziert werden.

Für diese Kanäle muss es im Formelsatz jeweils genau eine Zuweisung geben und sie müssen unter "outputs" nach gängigen smartCORE Standards konfiguiert werden.

Zuweisungen, die nicht im Bereich der "outputs" veröffentlicht werden, werden als interne, lokale Variablen im Formelsatz betrachtet.

Folgendes Minimalbeispiel exportiert folglich den Kanal speed

{
  "module":"math1",
  "factory":"mathmodule",
  "config": {
    "math": [
      "c = 42;",
      "speed = c;"
    ],
    "outputs": [
      {
        "dataType": "double",
        "name": "speed",
        "physicalUnit": "m/s"
      }
    ]
  }
}

Eine etwas flexiblere Konfiguration, die darüberhinaus zusätzliche Kanalcharakteristika sowie eine einstufige Produktionsfilterkette beschreibt, würde wie folgt aussehen

{
  "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
          }
        ]
      }
    ]
  }
}

Konfiguration von Ressourcen "resources"

Die Bereitstellung von Ressourcen ist im Math Modul ein wichtiger Bestandteil, um auch komplexe Konfigurationen und Funktionalitäten zu realisieren. Die Beschreibung dazu findet sich hier.