EbsOpen Introduction

EbsOpen is a comprehensive COM class library that offers access to all of the application, model, stream and component data in EBSILON Professional. It is a powerful tool for activities ranging from simulation, validation and what-if scenarios to parametric studies and automated calculations in operating power plants. The Excel Interface for EBSILON is an example of the type of integration that can be achieved with EbsOpen.

EbsOpen provides over 200 classes with 3,500 methods and properties that can be used to read, run, edit and interact with EBSILON and EBSILON models. It is suitable for integrating EBSILON Professional calculations and data with your software infrastructure. EbsOpen can be used with many common automation and programming environments such as Visual Studio.net (via VB, C++ or C#) or the Visual Basic for Applications (VBA) environment for MS Office products like Excel.

This section of the help file introduces EbsOpen and provides some examples of how to use it.

 

The COM interface "EbsOpen" of EBSILONProfessional can also be used from Python by means of the Python for Window Extensions "pywin32".
The Python module "EbsOpen.py" is not absolutely necessary for this, but it makes working with the EbsOpen interface easier because it contains Python classes for the individual COM interfaces and classes and definitions of the enumeration values. EbsOpen.py is located in the subdirectory data/python of the Ebsilon installation directory.

Look at EbsOpen Class Documentation for further details.

EbsOpen Overview       Using EbsOpen with VBA       Using EbsOpen with Visual Studio and C#       Reading and Writing Component, Stream & Macro Data with EbsOpen    

 

Reading and Writing model and profile variables    

 

EbsOpen Overview

The EbsOpen COM library is located in the folder you installed EBSILON Professional into. If you used the default destination folder when you installed EBSILON this will be either:

C:\Program Files\Ebsilon\EBSILONProfessional [version number]

or

C:\Program Files (x86)\Ebsilon\EBSILONProfessional [version number]

depending on your OS and which version (32 bit or 64 bit) of EBSILON you installed.

To use the EbsOpen library, you will need to make a reference to its type library file EbsOpen.tlb:

 

Examples of how to do this in VBA and C# are provided later. To explore the classes, methods and properties that EbsOpen provides, you can open the EbsOpen.tlb file using the Oleview program that comes with Microsoft Visual Studio: https://docs.microsoft.com/en-us/previous-versions/d0kh9f4c(v=vs.140)

 

If you do not have Microsoft Visual Studio a nice alternative open source viewer is OleWoo: http://www.benf.org/other/olewoo/

A view of some of the available properties (for Calculation Run Statuses) in OleWoo is shown below:

You can also use the Object Browser (more details below) in the VBA or Visual Studio environment to explore all of the EbsOpen classes, methods and properties to find what you need to integrate EBSILON and EBSILON models with your other systems and applications.

 

Using EbsOpen with VBA (Visual Basic for Applications)

This section will walk you through setting up and using EbsOpen with VBA in Excel. Some familiarity with VBA is assumed. To begin, start Microsoft Excel and create a new work book. Start the VBA Integrated Development Environment (IDE) by pressing Alt+F11:

Next Choose the References… Item from the Tools pull down menu as shown above and add a reference to the EbsOpen by pressing the Browse button on the References dialog shown below and selecting the EbsOpen.tlb file in the Add Reference dialog from the folder you installed EBSILON Professional into.

Once you have added a reference to the EbsOpen type library file in VBA, you can use the VBA object explorer to look at the available classes, methods and properties. To do this, choose the Object Browser item from the View menu or press F2 from within the VBA IDE:

 

With the steps above completed, you are ready to start using EbsOpen in your own VBA code. Here is a simple VBA subroutine that uses EbsOpen to determine how many components and streams there are in the model you specify in a named range called ModelPath in an Excel Workbook:

See the EbsOpenDemo.xlsm and EbsOpen.xlsm files in the \Data\Examples sub folder of the EBSILON installation folder for more examples of what can be done with EbsOpen.

NOTE: Depending on your operating system / user access control settings, and EBSILON installation folder, you may need to copy these workbooks to a non- system folder and update their EbsOpen.tlb reference in order for them to work.

 

Using EbsOpen with Visual Studio and C#

This section will walk you through setting up and using EbsOpen with C# in Visual Studio. Some familiarity with Visual Studio and C# is assumed. To begin, start Visual Studio and create a new project by following these steps:

1. Start Visual Studio and choose the New > Project… Item from the File pull down menu:

2. Select the Visual C# >Windows sub branch of the Templates branch and select the Windows Forms Application Template as shown below:

3. Add a reference to the EbsOpen library by right clicking on the References branch in the Solution Explorer tree and choosing the Add Reference… item as shown below:

4. Click Browse… and go to the Ebsilon Installation Folder and select EbsOpen.dll (this is a .net-optimized assembly-version of Ebsopen.tlb) in the Reference Manager dialog as shown below and then press OK.

5. If you have successfully added the EbsOpen Reference the Reference folder of your Solution Explorer tree will now have an EbsOpen branch as shown below:

6. Double clicking on the EbsOpen branch of your project’s References folder will open the Visual Studio Object browser shown below:

You can use the Object browser to explore the classes, methods and properties provided by EbsOpen. Once you have completed the steps above to start your C# project, you are ready to start coding your application that will use EbsOpen. The code shown below is from the sample EbsOpenCSharpDemo project that you can find in the Data\Examples sub folder of the EBSILON installation folder. The listed code is for a simple windows forms application that displays how many components and streams there are in a user selected model. The sample application includes additional code that will fill a dropdown list box with all the profiles in the selected model and a button that will run a simulation for any profile selected in the dropdown list box:

 

Reading and Writing Component, Stream & Macro Data with EbsOpen

EbsOpen has classes defined for every stream and component type within EBSILON Professional. The easiest way to read or write data to / from an EBSILON model is as follows:

1. Declare a variable using the type of component / stream you wish to read.

2. Use the objects and items properties / methods of the model class to set the variable defined in step 1 to the component / stream you wish to read.    

3. Read / write the desired parameter from EBSILON by appending the parameter name to the variable defined and set in steps 1 and 2 with a dot (.): EbsVariable.EbsParameterName

The procedure above presumes you have already declared and set valid EbsOpen.Application and EbsOpen.model objects in your code. Reading a variable into your code looks like this in VBA code:

Dim Efficiency_meter As EbsOpen.Comp32

Dim dsp As EbsOpen.Comp46

Set dsp = model.Objects.Item("DSP")

Set Efficiency_meter = model.Objects.Item("Efficiency_meter")

eff_max = Efficiency_meter.ETA //read parameter ETA from component Efficieny_Meter

dsp.MEASM = 590.0 //write flow rate of 590 kg/s into measuring point DSP

 

The procedure above is simple, but limited for the following reasons:

1. It does not deal with units of measure. Accessing variables in this manner will always return values in EBSILON’s native SI unit set (with the base units m, kg, sec, degC, bar, kJ, kW). If you need or want the values in another unit set you must handle that manually or with the SetValueInUnit and GetValueInUnit methods:

           bWriteSuccesful = dsp.MEASM.SetValueInUnit(1000, epUNIT_t_h)

           The Get/SetValueInUnit methods are described in more detail below and demonstrated in the sample code in the EbsOpenDemo.xlsm spreadsheet.

2. Declaring variables for each specific type of EBSILON component and stream is cumbersome and not really scalable for reading / writing lots of different parameters from lots of different models.

3. It won’t read / write components and streams that are inside of Macro objects.

Fortunately, the classes, methods and properties of EbsOpen are rich enough to construct a more generic way to read / write data. Study the code for the ReadVar and WriteVar VBA functions below to see how. This code is in the utilities module of the EbsOpenDemo.xlsm file in the Data\Examples sub folder of the EBSILON installation folder and can be exported and imported into your own VBA project.

By using the Model Class’ ObjectbyContext method, an object can be found by name and cast assigned to the more generic EbsOpen.Data class and its EbsValues property can be used to find any object parameter by name. Together, these classes, methods and properties can be used to construct a function that can read / write data based on string arguments for the names of the component, macro or stream and parameter to be read / written. As mentioned above, there are also unit of measure related methods (GetValueInUnit and SetValueInUnit) that will handle unit of measure conversions.

Using the unit of measure methods requires knowing the integer codes for the various units of measure supported by EBSILON. A list of these codes is found in the EpUnit enumeration that is part of EbsOpen. The following screen shot from a type library viewer shows a portion of the 493 unit of measure codes that are available:

You can also use the code completion feature in your IDE to determine the appropriate unit of measure code by typing EbsOpen.epUnit in a subroutine or function to get the list of possible values. This is what doing so looks like in VBA:

The EBSILON help file also has a list of unit of measure codes here: List with dimensions and units

NOTE: The EbsOpen.epUnit portion may be dropped if the text for the desired unit code is known, for example by using only epUNIT_lb_s for lb/sec. For dimensionless parameters like component methods, use epUNIT_NONE when using the ReadVar and epUNIT_INTEGRAL when using the WriteVar functions in the EbsOpenDemo.xlsm example. It may be necessary to look at the EbsValue item for the variable you wish to read or write in your debugger to determine the right unit of measure code. Use of the wrong unit of measure code can lead to read and write failures. Check the return values from the ReadVar and WriteVar functions to ensure that they succeed. ReadVar returns the string “NaN” when it fails and WriteVar returns False.

The following are some common examples for using the ReadVar function – the profile, component, stream and macro names shown should be changed as appropriate if this code is copied:

Read the enthalpy of a stream in Btu/lb from the Design profile:

ReadVar(model, "Design", "H2O_DAMPF", "H", EbsOpen.EpUnit.epUNIT_btu_lb)

Read an electric line in kW:

ReadVar(model, "Design", "Net_Electric", "Q", epUNIT_kW)

Read a specification value from a component in psia:

ReadVar(model, "Design", "Piping", "DP", epUNIT_psia)

Read a method value from a component, no unit of measure:

ReadVar(model, "Design", "Piping", "FMODE", epUNIT_NONE)

Read a value from a logic line in kW:

ReadVar(model, "Design", "HEAT", "Q", epUNIT_kW)

Read a value from a macro object:

ReadVar(model, "Design", "GSCND_1", "POPER", EbsOpen.EpUnit.epUNIT_psia)

Read a value from a component inside a macro object named GSCND_1. Note the syntax for going inside of the macro object:  MacroName::ComponentName

ReadVar(model, "OD", "GSCND_1::Measuring_point_1", "MEASM", epUNIT_lb_h)

Read a value from a logic line inside of a macro object named GSCND_1:

ReadVar(model, "Design", "GSCND_1::Logic_1", "Q", EbsOpen.EpUnit.epUNIT_kW)

 

WriteVar function sample code:

Write a Temperature in Degrees C to a Boundary Value component and save the change to disk:

WriteVar(model, "Design", "Boundary_value", "T", epUNIT_GrdC, 454.444444, True)

Write the Measurement Type for a Measuring Point component. Do not save the change to disk:

WriteVar(model, "Design", "MPoint1", "FTYP", EbsOpen.epUNIT_INTEGRAL, 34, False)

 

NOTE: If the model written to via the WriteVar function is open in another instance of EBSILON, setting the SaveFlg parameter to True will not change the model’s data permanently. If the SaveFlg is set to False or the model is already open when the SaveFlg is set to true, the WriteVar function will change only a temporary copy of the model loaded in memory and the change will not be permanent.

 

Reading and Writing model and profile variables

User defined model and profile variables (see Extras Model Options… Profile-Variables and Model-Variables) are handled differently than component, stream and macro variables. The sample ReadVar and WriteVar functions shown above cannot be used to read and write model and profile variables because they are not contained within the Objects class. Model and Profile variables are found within the configuration class for their respective objects. The VBA code snippet below shows how to read and write model and profile variables:

Model and profile variables do not have units of measure and can be Boolean, char, integer, real or string types. Keep this in mind and take the appropriate steps to account for this when reading / writing these variables via EbsOpen in your application.

 

Note:

- The method SaveCopyAs has been added to the interface EbsOpen.Model, where a copy of the model is saved under a different name, but the current model is retained.

- The methods SimulateNew and ValidateNew have been added to the interface EbsOpen.Model.
   In contrast to Simulate and Validate, these DO NOT require the CalculationErrors-parameter (facilitates the activation of .net-based languages).