EBSILON®Professional Online Dokumentation
Ein EbsScript wird normalerweise in der EBSILON-Oberfläche ausgeführt. Aus dem EbsScript heraus kann der EBSILON-Rechenkern aufgerufen werden (durch Befehle wie "simulate" oder "validate"), die Berechnung erfolgt dann mit den Parametern, wie sie zu Beginn des Aufrufs des Rechenkerns eingestellt waren. Während der Berechnung durch den Rechenkern besteht kein Zugriff durch EbsScript oder durch den Anwender (auch ein Abbruch ist währenddessen nicht möglich). Erst nach Abschluss der Berechnung wird die Kontrolle wieder an EbsScript zurückgegeben.
Mit Hilfe des KernelScripting ist dagegen ein direkter Zugriff während einer Berechnung möglich. Dazu wird das Bauteil 93 ("KernelScripting") verwendet. Das Verhalten dieses Bauteils ist vom Anwender mit Hilfe eines EbsScripts unter Verwendung der Funktionen aus der Interface-Unit KernelScripting zu programmieren. Mit diesen Funktionen kann auf die auf die Werte der Leitungen und Komponenten im jedem Iterationsschritt zugegriffen werden. Auch die Werte auf den Ausgangsleitungen eines Bauteils 93 können mit diesen Funktionen gesetzt werden.
Das Bauteil 93 kann wie alle Bauteile mehrmals in eine Schaltung eingebaut werden. Dabei wird für jedes Bauteil 93 ein anderes EbsScript verwendet werden, so dass beliebig viele eigene Komponenten erstellt werden können.
Mit dem Bauteil 93 kann man wahlweise
a) die Ergebnisse auf den Ausgangsleitungen direkt setzen oder
b) einen komplette Gleichungssatz vorgeben.
- Im Modus "Ergebnisse auf den Ausgangsleitungen berechnen": Verwenden der Funktionen ksSetPipeValue - der Vorgabewert FDEFEQN muss dazu auf 1 stehen
- Im Modus "Gleichungen vorgeben": Verwenden der Funktionen ksAddEquation, ksSetEquation - der Vorgabewert FDEFEQN muss dazu auf 0 stehen
Die Funktionen zum Setzen von Fluiddaten ksSetPipeFluidData und fluidSetAnalysis können immer genutzt werden.
Der EBSILON-Rechenkern ruft im ersten Iterationsschritt nacheinander alle Bauteil auf, um Initialisierungen durchzuführen. In diesem Schritt liefert die Funktion:
- ksGetMode ; (siehe unten) den Wert "Initializing".
Nach der Initialisierung beginnt die Berechnungsphase. In dieser Phase liefert die Funktion
- ksGetMode den Wert "Calculating".
Da die Lösung iterativ erfolgt, erstreckt sich diese Phase über viele Iterationsschritte.
Die Nummer des aktuellen Iterationsschritts kann mit der Funktion:
- ksGetItNo
abgefragt werden. In jedem Iterationsschritt werden zunächst nacheinander alle Bauteile aufgerufen und setzen ihre Gleichungen für die Matrix ab.
Wenn alle Bauteile ihre Gleichungen abgesetzt haben, wird das Gleichungssystem gelöst und es folgt der nächste Iterationsschritt, solange bis die Konvergenzkriterien erreicht sind oder die eingestellte maximale Anzahl von Iterationen überschritten wurde. Danach erfolgt nochmals ein Durchgang durch alle Bauteile. In diesem Abschlussschritt liefert
die Funktion:
- ksGetMode den Wert "Finishing".
Dieser Schritt kann dazu verwendet werden, Komponenten-Ergebniswerte zu berechnen.
Innerhalb des Bauteils 93 gibt es einen EbsScript-Editor, der sich auf dem Blatt "Skript" des Eigenschaftenfenster befindet. Für den Zugriff auf die internen Berechnungsabläufe gibt es spezielle Funktionen, die in der Unit "KernelScripting" definiert sind. Diese Unit muss mit der Zeile
uses @KernelScripting;
zu Beginn des Scripts eingebunden werden.
Das "@" vor dem Unit-Namen dient als Kennzeichen für eine Interface-Unit. Eine solche Interface-Unit hat keine eigene Implementierung innerhalb von EbsScript, sondern ist direkt in EBSILON implementiert. Bei normalen EbsScript-Units, die vom Anwender erstellt werden, muss die Bezeichnung der Unit mit ihrem Namen im EbsScript-Explorer übereinstimmen und kann nicht mit "@" beginnen.
Die Unit KernelScripting enthält folgende Funktionen:
discontinue;
Argumente: keine
Rückgabewert: keiner
Zweck der Funktion:
Die Funktion "discontinue" ermöglicht im Kernel-Scripting die Unterbrechung der EbsScript-Ausführung. Das EbsScript wird dann im nächsten Iterationsschritt an derselben Stelle fortgesetzt. Auf diese Weise können lokale Variablen beibehalten werden.
Beispiel:
uses @KernelScripting;
var
i:integer;
begin
i:=1;
while (true) do
begin
println("Step ",ksGetItNo(),": i=",i);
i:=2*i;
discontinue;
end;
end.
In diesem EbsScript ist eine Endlosschleife (while (true)) programmiert, deren Ausführung aber durch den Befehl „discontinue“ unterbrochen wird. Im nächsten Iterationsschritt wird die Programmausführung dann genau an der Stelle fortgesetzt. Endgültig beendet wird die Ausführung erst mit dem Ende der Simulation. Bei der nächsten Simulation wird also wieder von vorne angefangen. Das Beispiel erzeugt folgende Ausgabe:
Step 1: i=1
Step 2: i=2
Step 3: i=4
Step 4: i=8
Step 5: i=16
Step 6: i=32
Step 7: i=64
Step 8: i=128
...
ksGetComp : ebsComp93
Argumente : keine
Rückgabewert: EBSCOMP93: aktives Bauteil 93
Zweck der Funktion: Liefert das gerade behandelte Bauteil 93 (als Objekt vom Datentyp ebscomp93)
ksGetFPROG : INTEGER
Argumente : keine
Rückgabewert: INTEGER:
Zweck der Funktion: Liefert den Programm-Index, d.h. den Wert des Spezifikationswertes FPROG.
ksGetItNo : INTEGER
Argumente : keine
Rückgabewert: INTEGER:
Zweck der Funktion: Liefert die Nummer des aktuellen Iterationsschritts.
ksGetMode : Mode
Argumente : keine
Rückgabewert: INTEGER: Mode
Zweck der Funktion:
Liefert den Modus, in dem sich der Rechenkern gerade befindet z.B.:
( je nach Berechnungsphase ) MODE: Wert "Initializing"
initializing (1) in der Initialisierungsphase,
calculating (2) während der Berechnungs-Iterationen,
finishing (3) in der Abschlussphase.
auxiliary-call preiteration (4) Hilfsaufruf Voriteration
ksGetRES (index:Integer) : REAL
Argumente: INTEGER: Index (bezeichneter Ergebniswert)
Rückgabewert: REAL: Ergebniswert
Zweck der Funktion: Liefert den Wert des durch den Index bezeichneten Ergebniswertes.
procedure ksSetRES (index:Integer; value:Real)
Argumente: INTEGER: Index (bezeichneter Ergebniswert)
REAL: value
Rückgabewert: keiner
Zweck der Prozedur: Setzt den Wert des durch den Index bezeichneten Ergebniswertes.
ksGetSPEC (index:Integer) : REAL
Argumente: INTEGER: Index (bezeichneter Spezifikationswert)
Rückgabewert: REAL: Spezifikationswert
Zweck der Funktion: Liefert den Wert des durch den Index bezeichneten Spezifikationswertes.
procedure ksSetSPEC (index:Integer; value:Real)
Argumente: INTEGER: Index (bezeichneter Spezifikationswert)
REAL: value
Rückgabewert: keiner
Zweck der Prozedur: Setzt den Wert des durch den Index bezeichneten Spezifikationswertes.
ksGetAccuracyCurrentStep():IterationStepAccuracyType
Argumente: keine
Rückgabewert: IterationStepAccuracyType
Zweck der Funktion: Liefert die aktuelle Konvergenz
ksGetAccuracyTrend():array of IterationStepAccuracyType
Argumente: keine
Rückgabewert: ARRAY of IterationStepAccuracyType
Zweck der Funktion: Liefert Konvergenztrend (aktuelle Konvergenz am Ende des Arrays)
ksCopyPipe( source, dest:Integer; copyValues:Boolean = False; copyFluidData:Boolean = True ):Boolean;
Argumente: INTEGER: source, dest
BOOLEAN = False: copyValues
BOOLEAN = True: copyFluidData
Rückgabewert: BOOLEAN: False / True
Zweck der Funktion: Kopiert physikalische Werte (Standard :Aus), Fluidspezifikationen (Standard: Ein)
procedure ksGetPipeFluidData (index:Integer; var fluidData:FluidData; definedBy:CompositionDefinedByEnum = CompositionDefinedByMass)
Argumente: INTEGER: Index (bezeichnete Leitung)
FLUIDDATA: var fluidData
CompositionDefinedByMass =CompositionDefinedByEnum (Definition der Zusammensetzung)
Rückgabewert: keiner
Zweck der Prozedur:
Liefert die Fluiddaten (Stoffwertzusammensetzung und materialspezifische Größen) auf der durch den Index bezeichneten Leitung.FluidData ist eine Datenstruktur (record), die in der Unit KernelScripting definiert ist.
procedure ksSetPipeFluidData (index:Integer; const fluidData:FluidData; definedBy:CompositionDefinedByEnum = CompositionDefinedByMass)
Argumente: INTEGER: Index (bezeichnete Leitung)
FLUIDDATA: const fluiddata
CompositionDefinedByMass =CompositionDefinedByEnum (Definition der Zusammensetzung)
Rückgabewert: keiner
Zweck der Prozedur:
Setzt die Fluiddaten (Stoffwertzusammensetzung und materialspezifische Größen) auf der durch den Index bezeichneten Leitung. FluidData ist eine Datenstruktur (record), die in der Unit KernelScripting definiert ist. Diese Daten müssen stets vollständig gesetzt werden. Diese Funktion kann nur für eine Ausgangsleitung verwendet werden.
ksGetPipeValue (index:Integer; physValue:PhysValue) : REAL
Argumente: INTEGER: Index (bezeichnete Leitung)
PHYSVALUE: physValueM (für Massenstrom),
physValueP (für Druck),
physValueH (für Enthalpie))
Rückgabewert: REAL: PhysValue
Zweck der Funktion:
Liefert den Wert der Größe PhysValue auf der durch den Index bezeichneten Leitung. PhysValue kann die Werte PhysValueM (für Massenstrom), PhysValueP (für Druck), PhysValueH (für Enthalpie) annehmen. Andere thermodynamische Größen wie Temperatur oder Entropie stehen an dieser Stelle nicht zur Verfügung, da sie aus Rechenzeitgründen nicht für alle Leitungen in jedem Iterationsschritt berechnet werden. Falls sie benötigt werden, können sie jedoch mit Hilfe von Stoffwertfunktionen wie waterSteamTable innerhalb des EbsScripts berechnet werden.
procedure ksSetPipeValue (index:Integer; physValue:PhysValue; value:Real)
Argumente: INTEGER: Index (bezeichneter Ergebniswert)
PHYSVALUE: physValue
( PhysValueM (für Massenstrom),
PhysValueP (für Druck),
PhysValueH (für Enthalpie))
REAL: value
Rückgabewert: keiner
Zweck der Prozedur:
Setzt den Wert der Größe PhysValue auf der durch den Index bezeichneten Leitung. Diese Funktion kann nur für eine Ausgangsleitung verwendet werden. Es können nur Massenstrom (PhysValueM), Druck (PhysValueP) und Enthalpie (PhysValueH) gesetzt werden.
Bei sechs Eingangsleitungen hat z.B. die Ausgangsleitung 1 die Anschlussnummer 7.
Für Ausgangsleitungen, die in der Schaltung nicht verbunden sind, brauchen keine Werte vorgegeben werden. Wenn sie jedoch verwendet werden, müssen stets alle Werte vorgegeben werden.
Das gilt auch für Logikleitungen, Elektroleitungen und mechanischen Wellen. Welcher Wert hier für den Druck gesetzt wird, spielt keine Rolle. Für den Massenstrom ist hier jedoch M=1 zu setzen, da die Leistung als Produkt aus Massenstrom und Enthalpie berechnet wird. Um die Leistung zu setzen, kann dann H auf den Wert der Leistung gesetzt werden.
Man beachte, dass das KernelScripting wie in EbsScript üblich immer mit den Ebsilon-Standardeinheiten arbeitet (bar, °C, kg/s, kJ/kg, kW, ...).
ksGetGlobalMaxTimeInterval : REAL
Argumente: keine
Rückgabewert: REAL: globale max. Restlaufzeit
Zweck der Funktion:
Liefert die globale maximale Restlaufzeit (Minimum über die Restlaufzeiten alle Zeit-beschränkenden Bauteile) (nur für Zeitreihen-Berechnungen)
ksGetMaxTimeInterval: REAL
Argumente: keine
Rückgabewert: REAL : maximale Restlaufzeit des aktuellen Bauteils 93
Zweck der Funktion:
Liefert die maximale Restlaufzeit des aktuellen Bauteils 93 (nur für Zeitreihen-Berechnungen)
procedure ksSetMaxTimeInterval (Real: time)
Argumente: REAL: time
Rückgabewert: keiner
Zweck der Prozedur:
Setzt maximale Restlaufzeit des aktuellen Bauteils 93 (nur für Zeitreihen-Berechnungen)
procedure ksGetPipeUniversalFluid:( index:Integer; var universalFluid:UniversalFluidType; definedBy:UniversalCompositionDefinedByEnum = UniversalCompositionDefinedByMass );
Argumente: INTEGER: Index
UniversalFluidType: var UniversalFluid
UniversalCompositionDefinedByEnum = UniversalCompositionDefinedByMass: definedBy
Rückgabewert: keiner
Zweck der Prozedur: Liest Universal-Fluid Daten vom angegebenen Anschluss (Index)
procedure ksSetPipeUniversalFluid:( index:Integer; const universalFluid:UniversalFluidType; definedBy:UniversalCompositionDefinedByEnum = UniversalCompositionDefinedByMass )
Argumente: INTEGER: Index
UniversalFluidType: const UniversalFluid
UniversalCompositionDefinedByEnum = UniversalCompositionDefinedByMass: definedBy
Rückgabewert: keiner
Zweck der Prozedur: Schreibt Universal-Fluid Daten auf angegebenen Anschluss
Die alten Funktionen bzw. Prozeduren:
stehen aus Kompatibilitätsgründen ebenfalls noch zur Verfügung, unterscheiden sich von den oben genannten Funktionen KsGetPipeFluidData, KsSetPipeFluidData, KsGetPipeValue und KsSetPipeValue jedoch lediglich in der Indizierung der Leitung. Während bei den oben genannten neueren Funktionen der Index einfach mit der Anschlussnummer der Leitung übereinstimmt, erfolgte bei den alten Funktionen eine separate Indizierung für Ein- und Ausgänge. Bei den Eingangsleitungen waren Index und Anschlussnummer identisch (1-6), bei den Ausgängen gab es einen Versatz (die Anschlüsse 7 bis 15 waren über die Indizes 1 bis 9 anzusprechen). Der Klarheit wegen empfiehlt sich die Verwendung der neuen Funktionen, bei denen der Index stets mit der Nummer des Anschlusses übereinstimmt (1 bis 6 für die Eingänge, 7 bis 15 für die Ausgänge).
Aus dem EbsScript heraus besteht die Möglichkeit, auf alle Größen der Schaltung lesend zuzugreifen, insbesondere auch auf alle Leitungswerte, und zwar auf die im jeweiligen aktuellen Iterationsschritt gültigen Werte der Variablen Massenstrom, Druck und Enthalpie (siehe obige Erläuterung zu ksGetInPipeValue). Ein Verändern von Werten darf jedoch nur durch die hierfür implementierten "ksSet..."-Funktionen vorgenommen werden.
Bestimmte EbsScript-Funktionen können im KernelScripting nicht verwendet werden. Ein Aufruf des Rechenkerns ist grundsätzlich nicht möglich. Andere Funktionen (Profilwechsel, Einlesen von Daten, Ändern von Farben) wirken nur in der Oberfläche und sind für den Rechengang ohne Einfluss.
Eine Anwendung des print-Befehls ist dagegen im KernelScripting möglich und zu Diagnosezwecken äußerst nützlich. Die print-Ausgaben können nach Abschluss der Rechnung in der EbsKernel-Ausgabeleiste betrachtet werden, die unter dem Menüpunkt "Ansicht" aktiviert werden kann. In der EbsKernel-Ausgabeleiste wird ein Blatt für jedes in der Schaltung enthaltene Bauteil 93 angelegt, außerdem ein Gesamtblatt für alle Ausgaben.
Vorgabe von Gleichungen als String
Normalerweise berechnet man im EbsScript aus den Eingangsgrößen die Werte für die Ausgangsgrößen und setzt sie auf die entsprechenden Ausgangsleitungen. Dieses Verfahren ist jedoch für die Validierung ungeeignet, da auf diese Weise keine Fehlerfortpflanzung betrachtet wird. Als Alternative besteht die Möglichkeit, Gleichungen zu definieren, die Größen auf allen Anschlussleitungen miteinander verknüpfen können.
Hierzu stehen die Funktionen:
ksAddEquation ( equation:String; parameterVariables:String = ""; allowGeneralSolver:Boolean = false ):Integer
Argumente: STRING: equation
STRING ="" : ParameterVariables - Variablen, deren Werte während der Lösung des
Gleichungssystem im aktuellen Iterationsschritt als unveränderbaren
Parameter (konstant) gehalten werden
BOOLEAN = false: allowGeneralSolver
Rückgabewert: INTEGER:
Zweck der Funktion:
Setzt eine neue Gleichung ab. Liefert Rückgabe Index der neuen Gleichung oder -1 im Fehlerfall.
ksSetEquation( eqIndex:Integer; equation:String; parameterVariables:String = ""; allowGeneralSolver:Boolean = false ):Boolean
Argumente: INTEGER: eqindex
STRING: equation
STRING ="" : ParameterVariables – Variablen, deren Werte während der Lösung des
Gleichungssystem im aktuellen Iterationsschritt als unveränderbaren
Parameter (konstant) gehalten werden
Rückgabewert: BOOLEAN:
Zweck der Funktion:
Setzt die Koeffizienten der vorher mit ksAddEquation-Funktion gesetzten Gleichung für den aktuellen Iterationsschritt neu.
ksGetEquation( eqIndex:Integer ):String
Argumente: INTEGER: eqIndex
Rückgabewert: STRING:
Zweck der Funktion: Liefert die Gleichung für den vorgegebenen Index als String.
ksGetMaxEquationIndex:Integer
Argumente: keine
Rückgabewert: INTEGER:
Zweck der Funktion:
Liefert den maximalen Index der Gleichungen für das aktuelle Bauteil 93 (entspricht der Anzahl der abgesetzten Gleichungen).
ksRemoveEquation( eqIndex:Integer ): BOOLEAN
Argumente: INTEGER: eqIndex
Rückgabewert: BOOLEAN:
Zweck der Funktion: Entfernt die Gleichung für den vorgegebenen Index.
und die Prozedur
procedure ksRemoveAllEquations
Argumente: keine
Rückgabewert: keiner
Zweck der Prozedur: Entfernt alle im Bauteil abgesetzten Gleichungen
zur Verfügung.
Die Gleichung ist als String (z.B. ”M2 - M1 = 0”) zu übergeben.
Die Anwendung dieser Funktionen soll durch das folgende Beispiel erläutert werden, das die Berechnung eines einfachen Wärmetauschers zeigt, bei dem nur Massen- und Energiebilanzen (ohne Druckverluste) berücksichtigt werden. Im Beispiel verläuft der Primärstrom von Anschluss 2 zu Anschluss 9, der Sekundärstrom von Anschluss 5 zu Anschluss 14. Als Fluid wird Wasser genutzt, um keine Gleichungen für die Zusammensetzung absetzen zu müssen.
uses @KernelScripting;
var i,iIndex,iLZ:integer;
strEquation:string;
bOk:boolean;
begin
iLZ:=ksGetItNo;
ksRemoveAllEquations;
strEquation:="M9-M2=0";
ksSetEquation (1,strEquation);
strEquation:="M11-M5=0";
ksSetEquation (2,strEquation);
strEquation:="P9-P2=0";
ksSetEquation (3,strEquation);
strEquation:="P11-P5=0";
ksSetEquation (4,strEquation);
strEquation:=printToString ("m2*H2 - m2*H9 + m5*H5 - m5*H11 = 0");
ksSetEquation (5,strEquation);
// Output of the equations in Log-output (optional)
iIndex:=ksGetMaxEquationIndex;
for i:=1 to iIndex do begin
strEquation:=ksGetEquation(i);
print (strEquation,"\n");
end;
end;
Vorgabe von Gleichungen als Struktur
Alternativ zur Vorgabe der Gleichungen als String, besteht auch die Möglichkeit, die Gleichungsinformationen in einer Struktur zu übergeben. Dies geschieht mit Hilfe der Funktion
ksAddEquationNew ( equation:EquationType) : INTEGER
Argumente: EQUATION: equation
Rückgabewert: INTEGER:
Zweck der Funktion: Setzt eine neue Gleichung ab.
ksSetEquationNew ( eqIndex:Integer; equation:EquationType) : BOOLEAN
Argumente: INTEGER: eqIndex
EquationType: equation
Rückgabewert: BOOLEAN
Zweck der Funktion:
Setzt die Koeffizienten für den aktuellen Iterationsschritt für die vorher abgesetzte Gleichung mit dem vorgegebenen Index ab.
ksGetEquationNew ( eqIndex:Integer; equation:EquationType) : BOOLEAN
Argumente: EquationType: eqIndex
Rückgabewert: BOOLEAN
Zweck der Funktion: Liefert die Gleichung für den vorgegebenen Index.
ksGetEquationParameter( eqIndex:Integer; index: integer) : Real
Argumente: INTEGER: eqIndex
INTEGER: index
Rückgabewert: REAL
Zweck der Funktion: Liefert den Wert des Parameters mit dem vorgegebenen „index“ für die Gleichung mit dem Index „eqIndex“
ksGetEquationParameters( eqIndex:Integer; ) :ARRAY OF REAL
Argumente: INTEGER: eqIndex
Rückgabewert: ARRAY OF REAL:
Zweck der Funktion: Liefert Werte aller Parameter für die Gleichung mit dem Index „eqIndex“.
procedure ksSetEquationParameter( eqIndex:Integer; index: integer; param:real) : Real
Argumente: INTEGER: eqIndex
INTEGER: index
REAL: param
Rückgabewert: keiner
Zweck der Prozedur: Für die angegebene Gleichung: setzt Parameter b {index} = param
procedure ksSetEquationParameters( eqIndex:Integer; const params: array * of real; start: integer = 1)
Argumente: INTEGER: eqIndex
ARRAY OF REAL: const params
INTEGER=1: param
Rückgabewert: keiner
Zweck der Prozedur: Für die angegebene Gleichung: setzt die Parameter b {start}, ..., b {start + length (param)} auf die Werte im Array "param"
Beispiel:
uses @KernelScripting;
var
equation, equation1:EquationType;
begin
ksRemoveAllEquations;
setLength(equation.LHS, 2);
equation.LHS[0].Coeff.CoeffValue:=CoeffValueReal;
equation.LHS[0].Coeff.Value:=1;
equation.LHS[0].LineIndex:=1;
equation.LHS[0].LineType:=PhysValueM;
equation.LHS[1].Coeff.CoeffValue:=CoeffValueReal;
equation.LHS[1].Coeff.Value:=-1;
equation.LHS[1].LineIndex:=7;
equation.LHS[1].LineType:=PhysValueM;
equation.RHS.CoeffValue:=CoeffValueReal;
equation.RHS.value:=0.0;
ksAddEquationNew(equation);
equation.LHS[0].LineType:=PhysValueP;
equation.LHS[1].LineType:=PhysValueP;
equation.RHS.value:=0.1;
ksSetEquationNew(2, equation);
equation.LHS[0].LineType:=PhysValueH;
equation.LHS[1].Coeff.Value:=-2;
equation.LHS[1].LineType:=PhysValueH;
equation.RHS.value:=0;
ksSetEquationNew(3, equation);
ksGetEquationNew(1, equation1);
println (length(equation1.LHS)," ",equation1.LHS[1].Coeff.Value);
end.
Nichtlineare Gleichungen:
In den Strings, die die Gleichungen für ein Bauteil 93 definieren dürfen neben den Variablen „m1“ – „m20“, „p1“ – „p20“, „p1“ – „p20“ (und „xn2_1“ - „xn2_20“, „xo2_1“ - „xo2_20“usw.
für alle Stoffe wenn Materialgleichungen aktiviert sind), die Grundrechenarten „+“, „-„, „*“, „/“ sowie „^“ für Potenz und die mathematischen Funktionen exp, ln (natürlicher Logarithmus), log (Logarithmus zur Basis 10), sqrt (Wurzel), sin, cos, tan, asin, acos, atan, sinh, cosh, tanh, arsinh, arcosh, artanh verwendet werden.
Des weiteren können Funktionen aus internen Units und benutzerdefinierten Standard-Units aufgerufen werden, die einen numerischen Typen (REAL, INTEGER) zurückgeben und ausschließlich (nicht „var“ bzw. „const“) Parameter von numerischem Typ haben (default Parameter sind zulässig).
Ein Beispiel hierfür ist die Funktion „propertyCallId“ in der Unit „@Standard”, deren Verwendung im Komponentenbeispiel „Component_93.ebs“ z.B. im Bauteil „Kernel_Scripting_9“ demonstriert wird.
Funktion „value_of“: value_of(x) hat den Wert x, aber immer die Ableitung 0, d.h. verhält sich, als ob der Wert von x vorher ausgerechnet wurde, und als Konstante in die Gleichung eingetragen wurde.
Anwendungsfall: siehe Komponentenbeispiel „Component_93.ebs“ im Bauteil „Kernel_Scrpting_9“: der Teilterm
+ 0.15*( H9 - value_of(H9))
In der Temperaturgleichung hat den Wert 0 aber eine Ableitung von 0.15 und verhindert damit das Verschwinden der Ableitung im Nassdampfgebiet.
Ohne diesen Teilterm hat die Ableitung nach H9 den Wert 0, d.h. falls während der Lösungssuche das Nassdampfgebiet durchschritten wird, erfolgt keine Änderung an H9.
Abfrage des aktuellen Zustandes der Iteration und Einfluss - Maßnahmen darauf:
Bei der Programmierung von KernelScripting-Bauteilen besteht die Möglichkeit, auf den aktuellen Zustand der Iteration zurückzugreifen und diesen direkt zu beeinflussen. Hierfür stehen folgende Funktionen zur Verfügung:
ksGetCurrentAccuracy( {physValue:PhysValue} ): REAL
Argumente: PHYSVALUE: physValue
Rückgabewert: REAL:
Zweck der Funktion: Ermöglicht die Abfrage des aktuellen Konvergenzgrades, jeweils für den Massenstrom (PhysValueM), den Druck (PhysValueP) und die Enthalpie (PhysValueH).
Die Ergebnisse dieser Funktion im jeweiligen Iterationsschritt entsprechen den im Konvergenzdiagramm dargestellten Kurven. Es besteht damit die
Möglichkeit, bestimmte Maßnahmen in Abhängigkeit vom Fortschritt der Iteration zu treffen.
ksGetFinishingReason(): FinishingReasonEnum
Argumente: keine
Rückgabewert: FinishingReasonEnum
Zweck der Funktion:
Ermöglicht im letzten Iterationsschritt eine Analyse, warum die Berechnung beendet wird:
FinishingReasonEnum = (=0 / =1/ =2 / =3/ =4);
o FinishingReasonConvergency (1), wenn der vorgegebene Konvergenzgrad erreicht wurde
o FinishingReasonErrorAbort (2), wenn ein Fehler zu einem vorzeitigen Abbruch geführt hat
o FinishingReasonMaxIterationsReached (3), wenn die vorgegebene maximale Anzahl der Iterationsschritte erreicht wurde, ohne dass der gewünschte Konvergenzgrad erreicht wurde
o FinishingReasonMaxTimeReached (4), wenn die vorgegebene maximale Rechenzeit erreicht wurde
(2) Der Fall „2“ tritt ein, wenn z.B. ein Bauteil 93-Script mit Fehlern endet (z.B. nNull-Division oder mit „exit(-1);“ ) oder wenn ein Bauteil im ersten Schritt die Simulation
aufgrund inkonsistenter Eingabedaten abbricht.(1) „normale Simulationsfehler“ werden erst im letzten Schritt generiert, daher ist dann der Wert „1"
Bei Aufruf der Funktion außerhalb des „Finishing“-Schritts wird
o FinishingReasonInvalid (0) zurückgegeben.
= 0, // ksGetFinishingReason called when Mode <> Finishing
= 1, // calculation was terminated due to convergency
procedure ksSignalNotConverged( signal:Boolean = True )
Argumente: BOOLEAN: Boolean = true: signal
Rückgabewert: keiner
Zweck der Prozedur:
Mit dieser Funktion kann verhindert werden, dass die Berechnung im aktuellen Iterationsschritt beendet wird. Dies ist insbesondere dann hilfreich, wenn noch nicht alle internen Berechnungen abgeschlossen sind.
procedure ksSetComponentCalcState (component:ebscomp; enable_calculation:Boolean; recursive:Boolean = False )
Argumente: component : ebscomp
enable_calculation: Boolean
recursive: BOOLEAN: Boolean = false
Rückgabewert: keiner
Zweck der Prozedur:
Diese Funktion erlaubt es, während der Simulation die Berechnung eines Bauteils temporär abzuschalten. Temporär abgeschaltet Bauteile behalten dabei die Gleichungen aus dem vorherigen Iterationsschritt. Wenn „component“ ein Macro-Objekt ist kann mit „recursive=True“ alle Objekte innerhalb des Macros temporär ein- bzw. ausgeschaltet werden.
Bitte beachten Sie, dass es sich hierbei um eine sehr fortgeschrittene Funktionalität handelt, die bei fehlerhafter Verwendung zu schwer nachvollziehbaren Berechnungsfehlern führen kann.
Generierung von Fehlermeldungen:
Bei KernelScripting und Kernelexpressions ist es möglich mittels der Prozeduren
procedure ksSetWarning( text:String )
procedure ksSetError( text:String; abortCalculation:Boolean = true )
procedure ksSetComment( text:String )
Fehler-, Warn- und Kommentar-Meldungen zu generieren.
Optional kann dabei auch ein Abbruch der Berechnung veranlasst werden.
Das Aufrufen von ksSetError mit "abortCalculation = true" führt zu einem Abbruch der laufenden Simulation.
In Makro-Skripten und beim KernelScripting können auch für bestimmte Bauteile Fehler gesetzt werden.
Hinweis: Gleichungsänderungen beim KernelScripting
Eine der Voraussetzungen für die Schnelligkeit des Lösungsverfahrens ist Ebsilon liegt darin begründet, dass sich die Struktur des Gleichungssystems im Laufe der Iteration
nicht ändert (d.h. es sind nur Änderungen in den Werten der Koeffizienten und der Rechthand-Seite, nicht aber in den Variablen zulässig).
Dadurch erspart man sich die Wiederholung etlicher Abläufe in jedem Iterationsschritt. Beim KernelScripting liegt das Absetzen der Gleichungen in der Verantwortung des Anwenders. Dadurch konnte hier der Fall auftreten, dass während der Iteration strukturelle Änderungen des Gleichungssystems vorgenommen wurden. Der Anwender wurde zwar durch eine Warnung darauf aufmerksam gemacht, die Berechnung jedoch trotzdem durchgeführt.
In Release 12 wird in diesen Fällen jedoch eine Fehlermeldung generiert. Das Script bzw. das Modell muss dann entsprechend angepasst werden, so dass keine strukturellen Änderungen im Gleichungssystem mehr auftreten. In vielen Fällen wird dies dadurch möglich sein, dass man in bestimmten Iterationsschritten Koeffizienten mit dem Wert 0 verwendet.
Funktionen zum Absetzen nicht lokaler Gleichungen beim KernelScripting
Diese Funktionen wurden zur Erstellung eines Prototyps für die Sammelschiene implementiert und können dazu verwendet werden, um von einem Bauteil aus Gleichungen für Leitungen abzusetzen, die nicht direkt an dieses Bauteil angeschlossen sind.
ksGetLineIndexFromLine ( line:ebspipe ):integer
Argumente: EBSPIPE: line
Rückgabewert: INTEGER: L
Zweck der Funktion: Liefert den internen Leitungsindex L einer Leitung
ksGetVariableMatrixIndex( variable:string ):integer
Argumente: STRING: variable
Rückgabewert: INTEGER:
Zweck der Funktion: Liefert den internen Variablenindex zu einer Variablen (z.B. zu „h1“)
ksGetEquationPivotMatrixIndex ( eqIndex:integer ):integer
Argumente: INTEGER: eqIndex
Rückgabewert: INTEGER:
Zweck der Funktion: Liefert den internen Variablenindex des Pivot-Elements einer Gleichung
Gleichungen mit Parametern:
Um aufwändige String-Operationen beim Zusammenbasteln der Gleichung zu vermeiden, kann man Gleichungen mit Parametern erstellen:
ksGetMatrixIndexVariable (matrix_index:integer; use_local_naming:boolean = true):string;
Argumente: INTEGER: matrix_integer
BOOLEAN: use_local_naming
Rückgabewert: STRING:
Zweck der Funktion: Liefert die für den vorgegebenen Matrix-Index interne Variable als String
ksGetParameter (index:Integer) : REAL
Argumente: INTEGER: index
Rückgabewert: REAL:
Zweck der Funktion: Liefert Parameter a (Index)
ksGetParameters : ARRAY OF REAL
Argumente: keine
Rückgabewert: ARRAY OF REAL
Zweck der Funktion:
Liefert alle "a" -Parameter (!!! Ergebnis-Feld ist nullbasiert, so dass der Wert von "a (i)" bei Index i-1 liegt)
procedure ksSetParameter (index:Integer, parameter: REAL)
Argumente: INTEGER: index
REAL: parameter
Rückgabewert: keiner
Zweck der Prozedur: Setzt Parameter a (Index) = Parameter
procedure ksSetParameters : (const params: array * of real; start:integer = 1)
Argumente: ARRAY OF REAL : const params
INTEGER =1: START
Rückgabewert: keiner
Zweck der Prozedur:
Setzt die Parameter a (start), ..., a (start + length (param)) auf die Werte im Array "param"
procedure ksResetParameters
Argumente: keine
Rückgabewert: keiner
Zweck der Prozedur:
Verwirft alle zuvor eingestellten "a" -Parameterwerte (d. h. setzt alle Parameter auf 0 )
procedure ksResetEquationParameters (eqIndex:Integer)
Argumente: INTEGER: eqIndex
Rückgabewert: keiner
Zweck der Prozedur:
Für die spezifizierte Gleichung: verwirft alle zuvor gesetzten "b" -Parameterwerte (d. h. setzt alle Parameter auf 0)