Macros

With the "new" macro mechanism described here, you can assemble your own components from individual components, which can be built into models as a partial model or "black box".

• The number and type of inputs and outputs,
• specification and result values as well as
• EbsScripts, which are automatically called before and after a calculation,

can be defined. An independent namespace is used for these EbsScripts, so that no conflicts arise even if such a macro is used more than once.

Using Macros

Macros can be used like normal components. They can be moved, copied and pasted (multiple times in different models).

Double-click to open the properties window of the macro, in which the externally (externally) visible properties of the macro can be viewed and modified.

Which properties should be visible in the external view is defined in its internal view.

To change the internal properties of the macro, the macro must be opened. The internal view is then displayed in a new window.

Macros can be protected so that the inside view cannot be opened for protected macros.

Creating Macros

A new macro can be inserted in a model by using the menu command "Insert"à"Macro-Object". One can now position it and change its name and description. This description also appears as text on the macro display.

Editing Macros

If one clicks on the macro with the right mouse button, one can select the command "Open Macro-object" from the context menu to open the macro.

To open a macro for editing, the middle mouse button can also be used. A double click with the middle mouse button on the macro object opens the corresponding macro, a double click with the middle mouse button on the interface object inside the macro opens the corresponding parent instance in which the macro is contained.

The Macro-Properties Window (inside display)

The properties of the macro (intern) will be displayed on the following listed tabs:

• Ports      
• Specification-Values       
• Results
• Carlines            
• Result arrays
• Spec-Matrices
• Result-Matrices
• EbsScripts       
• Port-Positions
• Basic Properties
• View
• Calculation
• Layout                  

Depending on the type of macro some tabs may be empty.

Example: Macro : VW1_mit_NK
Basic Properties (external display) 

Opened Macro - inside display

Ports

In the tab "Ports" you can define which connections the macro should have to the outside.

By clicking into the field "Please click to insert..." you can define a new connection, by marking a line and pressing the "Delete" button you can remove a connection. If one clicks into a field of the 2nd column, a selection box appears, in which one can define the line type.

In the third column, a checkbox with the heading "none" can be activated for connections. In this case, the connection can be hidden by the user. The port will be hidden ONLY on the OUTSIDE of the macro - inside the macro it will always remain visible.

The fourth column defines whether it is a port where a fluid is going into the macro (entries are indicated by small white squares) or coming out of the macro (exits by small black squares ). The text entered in the "Short description" column appears as a description in the external properties window of the macro.

The representation in the circuit is a mirror image (see inside view of macro). If the macro is not rotated or mirrored and the port positions have not been defined manually (see below), the connections are at the top in the external representation. Input lines are shown as inputs and output lines as outputs.

In the internal view the connections are at the bottom. Input lines are shown here as outputs and output lines as inputs. So the macro symbol represents the "outside world" in this representation.

The modeling for the macro interior is connected to these connections coming from the outside world. This can be done in the usual way (as in the "outside world"). Macros can be nested, one can also insert further macros in the inner world of a macro. Since the macro has its own namespace, you are independent of the outside model when specifying names in the interior (so there can be a component in the macro that has the same name as another component in the exterior).

Port-Positions

The Port Positions and the minimal size of the macro-box can be defined in a tab of the internal macro properties window.

The width and height values play a decisive role in the aspect ratio and in the size of the macro in the final model.
If the positioning mode is set to "user-defined", the final macro rectangle can be made square, for example, or the minimum size of the macro rectangle can be set.

The minimum macro size changes simultaneously in the inside and outside view. 

After the pipe connections are defined, the Pipe-positions tab can be selected to move the pipe ports around. To move the positions of the connections, select the entry "user defined" from the Positioning Combobox.

Specification-Values

On the "Specification-Values" sheet of the internal macro properties window you can define specification values of the macro.

On the "Results" sheet of the internal macro properties window you can define result values of the macro.

The internal processing is possible through the macro EbsScripts. For example, one can copy a macro specification value to a specification value of a component inside the macro or (calculate and) assign a macro result value.

Identifier and description can be entered freely, the dimension (Quantity) of the specification value is to be selected from the selection box. These specification values then appear like this in the external properties window, where the user can enter the desired values.

A check mark at "Tooltip" causes this value to be displayed in the tooltip of the macro (if one points with the cursor to the "external view" of the macro).

If "Text" is selected as the quantity or dimension, the specification value is defined as text. The user can then enter a text instead of a numerical value.

For specification values and result values, it is possible to provide combo boxes for the quantity. In this case, you do not need to specify a number, but select an entry from the combo box (corresponds to a flag default value). These entries are defined in the macro by selecting "Combo entries" when defining the quantity (dimension) of the specification or result value. Afterwards, by clicking the button in the "Combo entries" column, a dialog can be opened in which one can define the displayed texts and the associated code numbers.

The selection "XUI Callback" as Quantity means that the selection of a quantity entry contained in the combo box is controlled by the XUI dll interface (see xui_dll.cpp in the example).

Specification values can be set to "Read only" for the user of the macro. With "Read only", these values are displayed on the Default values property sheet of a macro, but cannot be changed.

Furthermore, the "Visibility" can be set.

• displayed
• hidden
• grayed (value is changeable)
• XUI-Callback

The visibility "XUI callback" means that the visibility of such a value is controlled by the XUI dll interface (see xui_dll.cpp in the example).

A "category" can also be assigned: 

• default value
• default value only for design calculation
• preset value only for partial load calculation
• Nominal value
• EbsScript
• XUI callback

The category is only used in the display:
 Nominal values are displayed in blue (as for all components).
 Default values used only in design calculation are shown in purple.
 Values used in EbsScripts only are displayed in green.
 The category "XUI callback" means that the category of such a value is controlled by the XUI dll interface (see xui_dll.cpp in the example).

Grouping

Several specification and result values of a macro can be grouped, as it has already been done for some components. For this purpose entries have to be made in the column "Grouping":

• [ : Start of a group
• ] : end of a group
• Category : Assign a category to a group

Groups can be nested. Further details can be taken from the example below. The upper image shows the inner view of the macro (macro open), the lower one the outer view (all groups open).

Transfer automatically

Specification values defined in the macro can directly be coupled to specification values of components within the macro. This spares the user the allocation in the EbsScript. To do so, the desired specification value to which the value is to be transferred is entered into the column “Auto-Transfer“ (automati...) on the sheet “Specification values“ of the MacroInterface properties window. To allocate a macro specification value to several specification values within the macro, several specification values can be entered as well (separated by “;”).

Similarly, automatic linking of result values is also possible. Here, expressions can also be used in the "Auto-Transfer" column. Characteristic curves, result maps, matrices and result matrices can also be coupled in this way, but always only as a whole (by specifying the name of the characteristic curve/matrix).

If the input is incorrect, an error message with reference to the macro is displayed during a simulation.

Results

The result values can be defined in two tabs of the internal macro properties window. One tab allows the specification of individual result values. The other tab allows for the specification of result arrays. The name and the description can be entered freely, the quantity of the default value can be selected from the drop-down list. These default values then appear in the external properties window.  

The allocation of the result values must be done in an EbsScript inside the macro. The values entered here are then visible outside the macro after completing the calculation.

EbsScripts

The EbsScripts can be defined in a tab of the internal macro properties window.

If a calculation (simulation or validation) is started and macros are available in the model, the "EbsScript to run before calculation" is executed before calling the EBSILON^®Professional-computing core. In this EbsScript it is possible to enter the specification values in the components inside the macro. However, the pipe values are not available at this time, since the calculation has not yet been done.

After the calculation is done, the "EbsScript to run after calculation" is executed. All the pipe values are available in this EbsScript. It can be used to transfer the results from the inside of the macro to the result values visible outside the macro. 

On the specification page for EbsScripts there is a third entry for taking over nominal values. Here the behaviour of the macro can be defined by means of EbsScript function implementations for the functions ”hasNominalValues“ and ”TakeOverNominalValues“. The return value of “hasNominalValues“ defines whether the macro is to be displayed in the nominal value takeover dialog (provided that the user has not ruled this out in the general settings), and whether the function ”takeOverNominalValues“ is called. 

function hasNominalValues():boolean;
begin
       // return true to indicate that the component
       // has calculated new nominal values
       hasNominalValues:=false;
end;

procedure takeOverNominalValues(source_profile_id, real_target_profile_id : integer; full_specification:boolean);
begin
     // copy the nominal-values in this procedure
     // arguments reflect the selection from the user in the dialog after the calculation
     // (resp. the preselected options)
end;

Example model Makro_NominalValues.ebs:

The model represents a mixer with pressure loss. An adaptation of component 60 for mode P2 = min (P1, P3), where the direction of the pressure specification can be reversed and the pressure in the line with the higher pressure is calculated via a pressure loss, a component 2.
The model has four profiles

• Global interpretation
  
• Local interpretation
  
• Identification
  
• Simulation

In local and global design, the nominal values are taken over from the calculation result. 

You can also apply characteristic curves in macros. For this the macro has to contain the followings for each characteristic:

• brief description
• name
• the number of points
• description of the x values
• quantity of the x values
• description of the y values
• quantity of the y values
• a flag defining whether the characteristic should have a parameter (This parameter must be used in case of a bivariate table. In this case, Y is a function of X and the "parameter".  For each value of the parameter, the user must must specify a set of X and Y correlations).           
• description of the parameter if applicable and
• quantity of the parameter
• a flag defining if a vector array should be used. (Only Principal Diagonal)    
                 

Searching for objects in macros

To search for objects within macros activate the checkbox “Open Macros” in the Search window (binocular icon). This way objects within macros will be also included in the search.

QT diagrams for macros

By default, QT diagrams are drawn across macro limits, i.e. the heat exchangers contained in a macro will be displayed in the diagram exactly like the heat exchangers outside the macro.

It is possible to insert the macro as a whole into a QT diagram as an object. For this purpose, there is a new sheet “QT diagram” in the MakroInterface properties dialog where the interpretation of the macro connections for the diagram is to be entered.

At first, you can choose whether the macro is

• not a heat exchanger

• a simple heat exchanger without auxiliary condensate

• a simple heat exchanger with auxiliary condensate, or

• a duplex heat exchanger

Subsequently, it will be defined which pins are inlets and outlets for the hot and cold side respectively (and auxiliary condensate and second cold leg respectively if applicable).

EbsScript-Functions for macros only

There is the runEbsScript function specifically for macro objects. It enables the explicit execution of the macro ebsScripts "Before calculation", "After calculation" and "Transfer of nominal values".

Example script - executable in the example Block750.ebs:

var rc: ebsscriptstatusenum;
begin
   clrscr;
   rc := VW2_mit_NK::MacroInterface.runEbsScript(UserCodeTypeAfterCalculation);
   println (enumtostring(rc));
   rc := VW1_mit_NK::MacroInterface.runEbsScript(UserCodeTypeBeforeCalculation);
   println (enumtostring(rc));
end.

Output of the script:

EbsScriptStatusOk
EbsScriptStatusScriptNotFound

The method „getobjects(ebsobjecttype:string, includeChildContexts:boolean)" allows access to objects within a macro (filtered by type or whether objects from contained macros should also be included).

Example script - executable in the example Block750.ebs:

var eo: array of ebsobject;  ce:integer;
begin
    eo := VW2_mit_NK::MacroInterface.getObjects ("ebspipe", true);
    for ce := low (eo) to high (eo) do begin 
       println (eo[ce].name);
    end;
end.

Output of the script:

H2O_FLUESSIG_16
H2O_FLUESSIG_36
Dampf
Wasser_1
Wasser_2
Wasser_3