Getting Started with EbsOpen

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.

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://msdn.microsoft.com/en-us/library/d0kh9f4c.aspx

GettingStartedwithEbsOpen.docx 1
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 Visual Basic for Applications (VBA)

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:

GettingStartedwithEbsOpen.docx 2
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:

GettingStartedwithEbsOpen.docx 3
 Note that some methods, classes and properties may
have been deprecated. If so, use the alternative
suggested here

VBA Object Browser

GettingStartedwithEbsOpen.docx 4
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:

Sub GetModelInfo()
'Determines how many components and streams are in an EBSILON Model Using EbsOpen
Dim app As EbsOpen.Application
Dim Path As String
Dim model As EbsOpen.model
Dim prof As EbsOpen.profile
Dim iNumCmps, iNumStrms As Integer

'EbsOpen requires a valid EBSILON License. Create an Error Handler to

'Fail gracefully on any uncaught error, likely caused by trying to use EbsOpen
'without a valid license
On Error GoTo ErrHandler

'Create an EBSILON Instance

Set app = New EbsOpen.Application

'read the model path and name from the named range ModelPath
Path = Range("ModelPath").Value

'Open the model specified in ModelPath, returns Nothing if model can't be opened
Set model = app.Open(Path, True)

If model Is Nothing Then

MsgBox(Path & " could not be opened! Check the path and model name " & _
" and try again.")
Exit Sub
End If

Set prof = model.RootProfile 'Choose the Root Profile

prof.Activate 'Activate the profile

iNumCmps = model.ActiveProfile.Configuration.CalculationResult.NumberOfComponents
iNumStrms = model.ActiveProfile.Configuration.CalculationResult.NumberOfLines

MsgBox("Your model has: " & iNumCmps & " components and " & iNumStrms & " Streams.")

model.Close
Exit Sub

ErrHandler:
MsgBox("Unable to load EbsOpen. Please check your EBSILON License / Dongle.")

‘Ebislon-Instance will be terminated (since all references to it got released)

End Sub

GettingStartedwithEbsOpen.docx 5
See the EbsOpenDemo.xlsm and EbsOpen.xlsm files in the \Data\Examples subfolder 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 :

GettingStartedwithEbsOpen.docx 6
 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.

GettingStartedwithEbsOpen.docx 7
 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:

GettingStartedwithEbsOpen.docx 8
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 on the next page is from the sample
EbsOpenCSharpDemo project that you can find in the Data\Examples subfolder 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:

GettingStartedwithEbsOpen.docx 9
using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Windows.Forms;

namespace EbsOpenCSharpDemo
{
public partial class Form1 : Form
{
public Form1()
{
InitializeComponent();
}

OpenFileDialog ofd = new OpenFileDialog();

//make app and model variables static so they are not instantiated
//and terminated with each UI event
EbsOpen.Application app = new EbsOpen.Application();
EbsOpen.IModel model = null;

private void Form1_Load(object sender, EventArgs e)

{
}

private void button1_Click(object sender, EventArgs e)

{
try
{
//Open the model file selected by the user, return a null if model can't be opened
model = app.Open(ModelFileName.Text, true);
if (model == null)
{
MessageBox.Show("Unable to open the selected model. Please Try again.");
}
else
{
int numcmps, numstrms;
model.ActivateProfile("Design"); //Activate the design profile
//get the # of components
numcmps = model.ActiveProfile.Configuration.CalculationResult.NumberOfComponents;
//get the # of streams
numstrms = model.ActiveProfile.Configuration.CalculationResult.NumberOfLines;
MessageBox.Show("The selected model has " + numcmps + " components and " + numstrms + "
streams.");
model.Close();
}
}
catch
{
//A valid EBSILON License is needed to use EbsOpen. Catch unhandled exceptions from EbsOpen
//most likely caused by trying to use EbsOpen without a valid license
MessageBox.Show("Unhandled Exception Occurred. Please check your EBSILON License / Dongle.");
}
}

private void button2_Click(object sender, EventArgs e)

{
ofd.Filter = "Ebsilon Models |*.ebs";
if (ofd.ShowDialog() == DialogResult.OK)
{
ModelFileName.Text = ofd.FileName;
}
}
}
}

GettingStartedwithEbsOpen.docx 10
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.

GettingStartedwithEbsOpen.docx 11
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:

http://www.ebsilon.com/help/EN/webframe.html#UnitsOfMeasure.html

GettingStartedwithEbsOpen.docx 12
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.

Public Function ReadVar(model As EbsOpen.model, sProf As String, sObj As String, sVar

As String, eUOM As EbsOpen.EpUnit) As Object
'Function to read data from EBSILON variables via EbsOpen in user specified UOM
'acceptable eUOM values from EbsOpen.epUNIT enumeration

Dim eData As EbsOpen.Data

Dim eValue As EbsOpen.EbsValue
Dim ebsval As Object
Dim eProfile As EbsOpen.profile

ebsval = "NaN"

'make sure a valid model object was passed in

If model Is Nothing Then
MsgBox("Model Not Found! Please provide a valid Model Object.")
ReadVar = ebsval
Exit Function
End If

If model.GetProfile(sProf, eProfile) Then

eProfile.Activate

'Find the specified object. 2nd argument to the ObjectByContext method is

'True so that Nothing is returned if sObj does not exist

eData = model.ObjectByContext(sObj, True)

If eData Is Nothing Then

MsgBox("Unable to find object " & sObj & " in the model.")
Else
eValue = eData.EbsValues(sVar)
If eValue Is Nothing Then
MsgBox("Unable to find variable " & sVar & " in object " & sObj & ".")
Else
ebsval = eData.EbsValues(sVar).GetValueInUnit(eUOM)
End If
End If
Else
MsgBox("Profile " & sProf & " not found in model " & model.Name)
End If

ReadVar = ebsval

End Function

GettingStartedwithEbsOpen.docx 13
 Function WriteVar(model As EbsOpen.model, sProf As String, sObj As String, sVar As
String, eUOM As EbsOpen.EpUnit, vVal As Object, SaveFlg As Boolean) As Boolean
'Function to write data to EBSILON variables via EbsOpen in user specified UOM
'acceptable eUOM values from EbsOpen.epUNIT enumeration
'Returns True if writing succeeds and False if it fails

Dim bretval As Boolean

Dim eData As EbsOpen.Data
Dim eValue As EbsOpen.EbsValue
Dim eProfile As EbsOpen.profile

bretval = False

'make sure a valid model object was passed in

If model Is Nothing Then
MsgBox("Model Not Found! Please provide a valid Model Object.")
WriteVar = False
Exit Function
End If

If model.GetProfile(sProf, eProfile) Then

eProfile.Activate

'Find the specified object. 2nd argument to the ObjectByContext method is

'True so that Nothing is returned if sObj does not exist

eData = model.ObjectByContext(sObj, True)

If eData Is Nothing Then

MsgBox("Unable to find object " & sObj & " in the model.")
Else
eValue = eData.EbsValues(sVar)
If eValue Is Nothing Then
MsgBox("Unable to find variable " & sVar & " in object " & sObj & ".")
Else
bretval = eData.EbsValues(sVar).SetValueInUnit(vVal, eUOM)
End If
End If
Else
MsgBox("Profile " & sProf & " not found in model " & model.Name)
End If

'Save change to disk if successful & desired by user

If bretval And SaveFlg Then model.Save

WriteVar = bretval

End Function

GettingStartedwithEbsOpen.docx 14
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.

GettingStartedwithEbsOpen.docx 15
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:

Sub ReadWriteModelAndProfileVars()

Dim App As EbsOpen.Application

Dim model As EbsOpen.model
Dim profile As EbsOpen.profile
Dim mdlvar As Double
Dim profVar As Double

App = New EbsOpen.Application 'Create an EBSILON Instance

model = App.Open("C:\MyModels\MyModel.ebs", True)

If model Is Nothing Then

MsgBox("Model could not be opened!")
Exit Sub
End If

Call model.GetProfile("Design", profile)

'Read a model variable named MyMdlVar

mdlvar = model.Configuration.Variables.Item("MyMdlVar")

'Write a model variable

model.Configuration.Variables.Item("MyMdlVar") = 33.2
'follow with model.Save if you want change to myMdlVar to be permanent

'Read a profile variable named MyProfVar

profVar = profile.Configuration.Variables.Item("MyProfVar")

End Sub

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.

GettingStartedwithEbsOpen.docx 16