EBSILON®Professional

Macros, KernelScripting
and Programmable component

Dr. Hans-Peter Wolf

Topics

1. Creation of Macros
• Pipes
• Specification values
• Charlines
• Inner topology
• EbsScript before / after simulation
• Result values

2. KernelScripting (component 93)

• KernelScripting Programming
• Accessing pipe values
• Available libraries
(KernelScripting, System, Fluid, …)

Macros, KernelScripting and Programmable component 2

Topics

3. Programmable component (component 65)

4. Fluid types
• Water/steam
• Air and fluegas
• Combustibles
• User defined
• 2-phase fluid
• Universal fluid

5. Combination of Macro, KernelScripting and Fluid types

Macros, KernelScripting and Programmable component 3

Creation of Macros

Insert -> Macro object

• Creates an empty Macro

„outer“ view

• Right mouse button „Open Macro-Object“ opens the definition of

the Macro

„inner“ view

Macros, KernelScripting and Programmable component 4

Macros, Connection of Pipes

Definition of Pipe interface

• Fluid type
• Flow direction into / out of Macro
• Long description
• Short description

Macros, KernelScripting and Programmable component 5

Macros, Specification values

Definition of Specification values

• Identifier
• Description
• Quantity
• Combo entries

„inner“ view „outer“ view

Macros, KernelScripting and Programmable component 6

Macros, charlines

Definition of charlines
• Identifier
• Name
• Points (obsolete)
• x-Description and x-Quantity
• y-Description and y-Quantity
• Optionally define multi-dimensional charlines

„inner “ view „outer“ view

Macros, KernelScripting and Programmable component 7

Macros, inner topology

Definition of inner topology

„inner“ view „outer“ view

Macros, KernelScripting and Programmable component 8

Macros, EbsScript before simulation

Execution of EbsScript before simulation to access and process

specification values

Macros, KernelScripting and Programmable component 9

Macros, EbsScript after simulation

Execution of EbsScript after simulation to calculate result values

Macros, KernelScripting and Programmable component 10

Macros, result values

Definition of result values

• Identifier
• Description
• Quantity
• Combo entries

„inner“ view „outer“ view

Macros, KernelScripting and Programmable component 11

Macros, exercise
Macro_01.ebs

Create a Macro :

• Split of inlet stream into 3 outlet streams

• Split factors as specification values

• The outlet temperature should be a function of the inlet mass flow and
should be defined using a charline

• The difference of inlet- and outlet energy flow should be defined as a result
value

Macros, KernelScripting and Programmable component 12

KernelScripting, component 93

Embedded script

component 93

Macros, KernelScripting and Programmable component 13

KernelScripting, component 93

Component 93 allows the creation of components with „user-defined physics“

using EbsScript programming language. Contrary to „normal“ EbsScripts the
EbsScript of component 93 is executed in each iteration step of the
Simulation.

To define the EbsScript the EbsScript-Editor (tab „Script“) is used. For

accessing the internal calculation objects special functions exist, which are
defined in Unit „KernelScripting“, which must be defined as

uses @KernelScripting;

At the beginning of the EbsScript. The „@“ marks the unit as a so-called
interface unit

Macros, KernelScripting and Programmable component 14

KernelScripting, important functions
(defined in @KernelScripting)

function ksGetComp:ebsComp93;
returns the actual instance of the component

function ksGetMode:Mode;
returns the actual calculation mode of the Ebsilon calculation kernel :
initializing (Initialization phase)
calculating (during iteration)
finishing (at end of iteration)
These result values are predefined as „enums“ of type „Mode“

function ksGetItNo:Integer;
Returns the number of the actual iteration step

function ksGetFPROG:Integer;
Returns the program-index, i.e. the value of the specification value FPROG.

function ksGetSPEC (index:Integer):Real;

Returns the value of the specification value having the specified index
Macros, KernelScripting and Programmable component 15
KernelScripting, important functions
(defined in @KernelScripting)

function ksGetPipeValue (index:Integer;

physValue:PhysValue) :Real;
Returns the value of the quantity PhysValue on pipe having the specified
index. PhysValue can be of type PhysValueM (massflow), PhysValueP
(pressure) or PhysValueH (enthalpy). Other thermodynamic quantities like
temperature or entropy are not defined. If they are needed they can be
calculated using property table functions like WaterSteamTable.

function ksGetPipeFluidData (index:Integer;

var fluidData:FluidData);
Returns the fluid data (composition and other material dependant data) for the
pipe specified by index. FluidData is a data structure („record“) defined in
Unit KernelScripting.

procedure ksSetRES (index:Integer; value:Real);

Initializes the value of the result value having index.

Macros, KernelScripting and Programmable component 16

KernelScripting, important functions
(defined in @KernelScripting)

Procedure ksSetPipeValue (index:Integer; physValue:PhysValue;

value:Real);
Initializes the value of the quantity PhysValue on pipe having the specified index
with value. This Procedure can only be used for outlet pipes. Only massflow
(PhysValueM), pressure (PhysValueP) or enthalpy (PhysValueH) can be
initialized.

For outlet pipes, which are not connected to other components of the model, no
values have to be initialized. In case these pipes are connected, all values must be
initialized, also for logical, electrical and mechanical pipes/lines. For such pipes
pressure and massflow should be initialized with 1. To initialize the value of the
energy flow, the enthalpy H must be initialized with the value of the energy flow.

Please take note that calculations are done in the Ebsilon standard unit
system (bar, °C, kg/s, kJ/kg, kW, …).

Macros, KernelScripting and Programmable component 17

KernelScripting, important functions
(defined in @KernelScripting)

Procedure ksSetPipeFluidData (index:Integer;

var fluidData:FluidData);
Initializes the fluid data (composition and material specific quantities) on pipe
having index. FluidData is a data structure („record“) defined in Unit
KernelScripting. The complete data structure has to be initialized. This
Procedure can only be used for outlet pipes.

Macros, KernelScripting and Programmable component 18

KernelScripting, important functions

From the EbsScript defined in the KernelScripting component all objects of the
Ebsilon model can be accessed (read), in particular all pipe values of massflow,
pressure and enthalpy. Pipe values are accessed for the actual iteration step.

Some EbsScript functions cannot be used inside a KernelScripting. Calling the

functions „simulate“ or „validate“ or „tscalculate“ is prohibited.

The print-function can be used inside the KernelScripting for debugging and
diagnostic purposes. The printout is displayed at the end of the simulation in the
EbsKernel toolbar. In the EbsKernel toolbar one page for each KernelScripting
component is used.

Macros, KernelScripting and Programmable component 19

KernelScripting, important functions
(defined in @Fluid)

function fluidGetAnalysis( obj:ebsData;

var fluidData:FluidData;
definedBy:CompositionDefinedByEnum ):Boolean;internal;
Returns the composition of a fluid for a pipe given by obj

function fluidSetAnalysis( obj:ebsData;

var fluidData:FluidData;
definedBy:CompositionDefinedByEnum ):Boolean; internal;
initializes the composition of a fluid for a pipe given by obj

function fluidTranslateAnalysis( var fluidData:FluidData;

definedByIn:CompositionDefinedByEnum;
definedByOut:CompositionDefinedByEnum ):Boolean;
internal;
Changes compisition given by mass fractions to volume fractions

Macros, KernelScripting and Programmable component 20

KernelScripting, important functions
(defined in @Fluid)

function fluidTable( var result:Real;

var phase:PhaseEnum;
arg1:Real; arg2:Real;
func:FuncEnum;
var fluidData:FluidData;
definedBy:CompositionDefinedByEnum ):Boolean; internal;
Calls a property table function (example: water/steam table) for a fluid defined in
fluidData

Macros, KernelScripting and Programmable component 21

KernelScripting, important functions
(defined in @Fluid)

function fluidTableWST( var result:Real;

var phase:PhaseEnum;
arg1:Real; arg2:Real;
func:FuncEnum ):Boolean; internal;
Directly calls the water/steam table

function fluidTableUser2Phase( var result:Real;

var phase:PhaseEnum;
arg1:Real; arg2:Real;
func:FuncEnum;
medium:Integer ):Boolean; internal;
Directly calls the „Refprop“ property table

function fluidNormalize( var fluidData:FluidData;

definedBy:CompositionDefinedByEnum;
var control : NormalizeControl ):Boolean; internal;
Normalizes a composition to 100 %

Macros, KernelScripting and Programmable component 22

KernelScripting, important datatypes
(defined in @Kernelscripting and @Fluid)

type Mode = (Initializing = 1, Calculating = 2, Finishing = 3 );

type PhysValue = (PhysValueP, PhysValueH, PhysValueM ); // kind of value on pipe

type FluidData = record

ncv : Real; // net calorific value [kJ/kg]
fluidType:FluidTypeEnum; // composition-type
fluidAnalysis : FluidAnalysis; // composition
fugit:Real; // fugitive portions (coal only)
rho:Real; // density
zfac:Real; // Z factor (oil only)
coalType:CoalTypeEnum; // coal type (coal only)
cpcorr:Real; // ash cp correction factor
medium:Integer; // media type (2-phase fluid only)
salt:Real; // salt content (salt water)
fkal:Integer; // media type of Kalina-fluid
xi:Real; // mass fraction of refrigerant
fluidExtension:smartptr FluidExtension; // may contain additional data
end;

Macros, KernelScripting and Programmable component 23

KernelScripting, important datatypes
(defined in @Kernelscripting and @Fluid)

type FluidAnalysis =
array [Substance_First .. Substance_Last] of Real;

Other datatypes (defined in @System) :

type FluidTypeEnum =
(
FluidTypeUndefined = -1, // undefined Value
FluidTypeSteam = 0, // No composition required
FluidTypeFluegas, // Fluegas or Air
FluidTypeGas, // Gas
FluidTypeCoal, // Coal
FluidTypeCrudegas, // Crudegas
FluidTypeOil, // Oil
FluidTypeUser, // User
FluidType2Phase, // 2phase
FluidTypeSaltwater, // Saltwater
FluidTypeBinaryMixture, // BinaryMixture
FluidTypeUniversalFluid, // UniversalFluid
FluidTypeThermoLiquid, // ThermoLiquid
FluidType_Size,
FluidType_UpperBound = FluidType_Size - 1,
);

Macros, KernelScripting and Programmable component 24

KernelScripting, important datatypes
(defined in @System)

type CompositionDefinedByEnum =
(
CompositionDefinedByNone = -1,
CompositionDefinedByMass,
CompositionDefinedByVolume,
CompositionDefinedByCoalRaw,
CompositionDefinedByCoalWaterAndAshFree,
CompositionDefinedByCoalWaterFree,
CompositionDefinedByCoalAshFree,
CompositionDefinedBy_Size,
CompositionDefinedBy_UpperBound = CompositionDefinedBy_Size - 1,
);

type CoalTypeEnum =
(
CoalTypeGeneral, // old mode
CoalTypeHard, // hard coal
CoalTypeBrown, // brown coal
CoalType_Size,
CoalType_UpperBound = CoalType_Size - 1,
);

Macros, KernelScripting and Programmable component 25

KernelScripting, important datatypes
(defined in @System)

type SubstanceEnum =
(
SubstanceNone, // no Substance
Substance_First=1, // first substance-index
SubstanceN2=1, // 1 Nitrogen (N2)
SubstanceO2, // 2 Oxygen (O2)
SubstanceCO2, // 3 Carbon dioxide (CO2)
SubstanceH2OG, // 4 Water (gaseous)
SubstanceSO2, // 5 Sulphur dioxide (SO2)
SubstanceAR, // 6 Argon (AR)
SubstanceCO, // 7 Carbon monoxide (CO)
SubstanceCOS, // 8 Carbon monoxide sulfide (COS)
SubstanceH2, // 9 Hydrogen (H2)
SubstanceH2S, // 10 Hydrogen sulphide (H2S)
SubstanceCH4, // 11 Methane (CH4)
SubstanceHCL, // 12 Hydrogen chloride (HCl)
SubstanceETH, // 13 Ethane (C2H6)
SubstancePROP, // 14 Propane (C3H8)
SubstanceBUT, // 15 Butane (C4H10)
SubstancePENT, // 16 Pentane
SubstanceHEX, // 17 Hexane
SubstanceHEPT, // 18 Heptane
SubstanceACET, // 19 Acetylene

… continued on next page Macros, KernelScripting and Programmable component 26

KernelScripting, wichtige Datentypen
(definiert in @System)

… continued from previous page

SubstanceBENZ, // 20 Benzole
SubstanceC, // 21 Elementary carbon (C)
SubstanceH, // 22 Elementary hydrogen (H)
SubstanceO, // 23 Elementary oxygen (O)
SubstanceN, // 24 Elementary nitrogen (N)
SubstanceS, // 25 Elementary sulphur (S)
SubstanceCL, // 26 Elementary chlorine (Cl)
SubstanceASH, // 27 Ash
SubstanceLIME, // 28 Lime
SubstanceH2OL, // 29 Water (liquid)
SubstanceH2OB, // 30 Water (chemical bound)
SubstanceASHG, // 31 Ash
SubstanceNO, // 32 NO
SubstanceNO2, // 33 NO2
SubstanceNH3G, // 34 NH3G
SubstanceNH3L, // 35 NH3L
SubstanceCO2L, // 36 CO2L
SubstanceMETHL, // 37 Methanol
Substance_Last = SubstanceMETHL,
Substance_Size,
Substance_UpperBound = Substance_Size - 1,
);
Macros, KernelScripting and Programmable component 27
KernelScripting, important datatypes
(defined in @System)

type FuncEnum = // fluid-table functions

(
FuncH_OF_PT=0, // Enthalpy from pressure and temperature
FuncS_OF_PT=1, // Entropy from pressure and temperature
FuncT_OF_PH=2, // Temperature from pressure and enthalpy
… + many (see @System)

type PhaseEnum = // phase of the fluid

(
PhaseNone,
PhaseFluid,
PhaseGas,
PhaseSuperCritical,
PhaseWetSteam,
Phase_Size,
Phase_UpperBound = Phase_Size - 1,
);

Macros, KernelScripting and Programmable component 28

KernelScripting, important datatypes
(defined in @System)

type NormalizeEnum = // enumeration Normalize

(
NormalizeFillUpSelected=0, //fill up selected items (additively)
NormalizeScaleTo100, //fill up items (multiplicatively)
NormalizeScaleTo100Selected, //fill up selected items (multiplicatively)
NormalizeScaleTo100NotSelected,//fill up not selected items(multiplicatively)
NormalizeMakePureFluid, //makes a pure fluid (or an evenly
//distributed mixture) of the selected items
Normalize_Size,
Normalize_UpperBound = Normalize_Size - 1,
);

Macros, KernelScripting and Programmable component 29

KernelScripting, Universalfluid
(defined in @System)

type UniversalSubstancePart =
record
substance : UniversalSubstanceEnum;
fraction : Real;
end;

type UniversalSubstanceEnum = // universal substances

(
UniversalSubstanceINVALID = 0,
UniversalSubstanceN2 = 1,
UniversalSubstanceO2 = 2,
UniversalSubstanceCO2 = 3,
UniversalSubstanceH2OG = 4,
UniversalSubstanceSO2 = 5,
UniversalSubstanceAR = 6,

… + many (see @System)

Macros, KernelScripting and Programmable component 30

KernelScripting, Universalfluid
(defined in @System)

type UniversalLibraryEnum = // libraries for universalfluid

(
UniversalLibraryLIBIF97 = 1,
UniversalLibraryIFC67 = 2,
UniversalLibraryFDBR = 3,
UniversalLibraryLIBIDGAS = 4,
UniversalLibraryLIBIDGASMIX = 5,
UniversalLibraryLIBHUGAS = 6,
UniversalLibraryLIBHUAIR = 7,
UniversalLibraryLIBCO2 = 8,
UniversalLibraryLIBNH3 = 9,
UniversalLibraryLIBH2 = 10,
UniversalLibraryLIBHE = 11,
UniversalLibraryLIBR134A = 12,
UniversalLibraryLIBBUTAN_N = 13,
UniversalLibraryLIBBUTAN_ISO= 14,
UniversalLibraryLIBPROPAN = 15,
UniversalLibraryLIBAMWA = 16,
UniversalLibraryLIBWALI = 17,
UniversalLibraryLIBSEAWA = 18,
UniversalLibrarySALTWATER = 19,
UniversalLibraryREFPROP = 20,
UniversalLibraryTHERMOLIQUID= 21,
UniversalLibrary_Size,
UniversalLibrary_UpperBound = UniversalLibrary_Size - 1,
);
Macros, KernelScripting and Programmable component 31
KernelScripting, Universalfluid
(defined in @System)

type UniversalCompositionDefinedByEnum = //Type of universal-fluid compos.

(
UniversalCompositionDefinedByNone = -1,
UniversalCompositionDefinedByMass,
UniversalCompositionDefinedByMole,
UniversalCompositionDefinedBy_Size,
UniversalCompositionDefinedBy_UpperBound =
UniversalCompositionDefinedBy_Size - 1,
);

Macros, KernelScripting and Programmable component 32

KernelScripting, exercise
KS_01.ebs

Create a KernelScripting (comp.93) :

• Split of inlet massflow (water) into 3 outlet massflows

• Cooling of outlet massflows

• Specification of splitting factors and cooling (delta T)

Macros, KernelScripting and Programmable component 33

KernelScripting, exercise
KS_02.ebs

Create a KernelScripting (comp.93) :

• Split of inlet massflow (fluegas) into 2 outlet massflows

• One outlet flow should consist of pure CO2 at the temperature of the inlet
massflow

• The other outlet flow should contain the remaining constituents of the
fluegas and of the CO2 which was not extracted

Macros, KernelScripting and Programmable component 34

Programmable component (component 65)

associated Source-code
(Programming language C/C++)

component 65

Macros, KernelScripting and Programmable component 35

Programmable component (component 65)

Component 65 can be used to integrate a program written in a programming

language different from EbsScript into Ebsilon. The program must have been
compiled into a DLL. For the creation of the DLL a programming environment
like Microsoft Visual Studio together with C/C++ compiler must be available.

When the DLL is called, data from the Ebsilon model is transferred to the DLL
where the data can be processed and then transferred back to the Ebsilon
model.

The path to the DLL can now be specified directly in component 65. Previously
only in the general settings of Ebsilon a path could be specified which then was
global for all Ebsilon models and all components 65. Therefore now it is
possible to use more than 1 DLL per model.

Macros, KernelScripting and Programmable component 36

Programmable component (component 65)

Example project provided together with Ebsilon :

Normally under :
C:\Programme\Ebsilon\EBSILONProfessional 10\Data\
Examples\Programmable or a similar path

Programmable.sln MS-VisualStudio Solution file

EbsUser.h Header file with predefined datatypes and prototypes
ebsuser.c Sourcecode example

It is recommended to copy the whole folder into a different directory.

Macros, KernelScripting and Programmable component 37

Programmable component (component 65)
exercise

Copy the Visual C/C++ example project into a different folder

Compile the project and generate the DLL

Open the Ebsilon example model “Component_65.ebs”

Insert the path to the DLL into component 65

Execute a simulation

Open the Visual C/C++ project (if you have MS Visual Studio)

Create an new source-code (example11 in ebsuser.c) which should differ from

example 1 insofar that the maximum pressure is written to the outlet pipes.

Generate the DLL

Execute the simulation. Check if the maximum pressure is written to the outlet
pipes.
Macros, KernelScripting and Programmable component 38
combination of macro, Kernelscripting
and Fluidtypes

Often it makes sense to embed a component 65 into a Macro

Inner view outer view

Macros, KernelScripting and Programmable component 39

KernelScripting, exercise
KS_04.ebs

Create a KernelScripting, which is embedded into a Macro :

• Splitting of inlet flow (steam) into 2 outlet flows

• Specification of split ratio as a specification value of the Macro. This

specification value should be transferred to the KernelScripting

• Specification of the outlet temperature as a specification value of the

Macro. This specification value should be transferred to the KernelScripting

• One outlet flow should have the temperature of the inlet massflow

• The other outlet flow should have the temperature given as specification
value

Macros, KernelScripting and Programmable component 40

Macros, KernelScripting and Programmable component 41