HYSYS Automation Basics with Excel
HYSYS Automation Basics with Excel
Automation Introduction
1
© 2004 AspenTech - All Rights Reserved.
EA1000.32.02
12 Automation Introduction
2 Automation Introduction
Introduction
Automation is the ability to programmatically interact with an
application through objects exposed by that application.
Workshop
In this module you will review and begin to understand an Automation
front-end to the Turbo Expander case using Microsoft Excel.
Additionally a simple HYSYS User Variable will be created.
Learning Objectives
In this module, you will gain an understanding of the possibilities that
Automation access to HYSYS can bring. The examples given should give
a starting point for any further learning.
2
Automation Introduction 3
Prerequisites
No prior programming experience is assumed. However before
beginning this module, you should have a reasonable understanding of
the HYSYS program.
The benefits that you will see from HYSYS Automation will depend
entirely on what you use HYSYS for. If you find yourself performing the
same task or calculation several times during a project, writing a MLE
macro or a User Variable will save a lot of valuable project time. This will
be especially true if the calculation is complex or requires several
variables simultaneously.
3
4 Automation Introduction
Rather than typing a large amount of code into the Excel Visual Basic
Don’t worry if you haven’t Editor, in this Workshop you will review some prewritten code using
built the Turbo Expander
plant case. VBA's debugging tools.
The file
“ADV5_Spreads&CaseStud The instructor may choose that the class does this individually, or as a
_Soln.hsc” contains this group.
case.
Preparation
1. Open the Turbo Expander HYSYS case.
2. Open the Microsoft Excel file: “Adv Automation - [Link]”.
3. In order to use VBA macros in Excel you need to tell Excel to Enable
Macros.
Figure 1
In Excel 2000 you may need to change the Security setting to Medium
on the Tools... Macro... Security menu option, before you see this
window on opening the file.
The Excel spreadsheet has already been set up with some labels and
values.
4
Automation Introduction 5
Figure 2
5
6 Automation Introduction
Figure 3
6
Automation Introduction 7
Figure 4
VBA Basics
The intention of this section is to introduce the very basics of
manipulating VBA code rather than to teach the details of HYSYS VBA
programming.
The techniques described here will be used later when examining the
prewritten code.
Running Macros
To run a macro, place the cursor within the macro in the VBA Editor, and
click the Run Sub / UserForm toolbar button.
7
8 Automation Introduction
Figure 5
Macros can also be run within the VBA Editor, from the Run menu or by
pressing F5.
Figure 6
8
Automation Introduction 9
Next trigger the code as above. When VBA encounters the breakpoint
execution will stop and the code window will appear. The line of code
that is about to be processed is highlighted in yellow.
Figure 7
9
10 Automation Introduction
HYSYS Objects are organised into a tree: The object hierarchy. The
objects that will be accessed in this example are illustrated below:
Figure 8
is used. This sets up the object variable hyApp to refer to the HYSYS
application. The resulting object is of type Application.
10
Automation Introduction 11
To link to further objects within the tree, dot notation is used. For
example the Turbo Expander Excel interface uses the line:
i.e. to refer an object on the next layer down in the tree a full stop is
used.
Figure 9
The object browser window will appear. By default the object browser
will list the objects available in all the type libraries that are selected in
the References lists (Tools … References). In order to limit it to just
HYSYS objects change the <All Libraries> drop-down at the top left to
HYSYS.
11
12 Automation Introduction
Figure 10
Clicking on an object (or 'Class') in the left hand list then shows all the
members (objects or properties) that are associated with that object.
The Object Browser also allows searching.
It is good practice to declare When accessing HYSYS via Automation, an Object Variable can be used
all variables at the top of the in the code to link to a HYSYS object.
procedure.
12
Automation Introduction 13
Figure 11
Figure 12
If the variable is an object variable then it will appear with a '+' sign next
to it, clicking this will show any sub-objects and properties within the
object.
13
14 Automation Introduction
Figure 13
14
Automation Introduction 15
Figure 14
2. Add a breakpoint to the On Error line and start the code running. (If
you need to, you can refer back to page 8 for details of breakpoints,
and making the code run.) Make the Set hyApp … line execute.
Figure 15
3. Add a Watch for the hyApp variable, click the '+' sign next to the
variable to show the properties of this object, note that
ActiveDocument is one of them, and that it's type is SimulationCase.
15
16 Automation Introduction
4. Execute the next line of code, add a Watch for hyCase and note that
it shows the same information as the ActiveDocument property of
the hyApp object.
5. Use the object browser to view the HYSYS Application object. Note
again that the type of the ActiveDocument property is
SimulationCase.
Figure 16
The next section of code checks if there was a case open in HYSYS using
the VB 'Is Nothing' construction.
Figure 17
16
Automation Introduction 17
Try running the code with no case open. What happens now?
Figure 18
What is the type of this variable? Where in the Object Browser could this
object type be found?
17
18 Automation Introduction
Figure 19
8. Add a Watch for the hyStream object. Look at all the properties this
has. Note that the Type of this variable is ProcessStream.
9. Execute the [Link] = False line. In HYSYS the solver
is now turned off (Red Traffic light).
Now the temperature in the stream can be set using the two values that
were retrieved from the Excel spreadsheet earlier.
Figure 20
10. Execute this line - check that the value in the HYSYS case matches
that entered in Excel.
11. Look up the ProcessStream object in the Object Browser and find
the Temperature property. This is of type RealVariable.
18
Automation Introduction 19
Figure 21
RealVariables are special HYSYS objects that hold numerical values, but
also contain other information that is useful for the programmer.
19
20 Automation Introduction
The first parameter is the new value to be set, and the second is the unit
to set the value in. Note that the square brackets mean that the second
parameter is optional. If it is not supplied then HYSYS assumes the value
is being supplied in it's internal units. (°C in the case of temperature.)
Look at the Temperature in the Watch window. What are the values of some
of the properties listed above?
13. Execute the code down to the line just above where the HYSYS solver
is turned back on.
Figure 22
14. Add a Watch for the hyExpander object and look at some of the
properties it has.
20
Automation Introduction 21
15. Reposition the VBA editor window and the HYSYS window so that
both are visible.
16. Execute the line [Link] = True, and observe that
HYSYS resolves the case.
The next parts of the code retrieve various information from the newly
modified HYSYS case.
Figure 23
Flowsheets are referred to by their Tag (not their Name). This can be
found on the Connections tab.
21
22 Automation Introduction
Next a new stream is assigned to the hyStream variable, using the Item
property of the EnergyStreams collection of this new sub flowsheet
object. The EnergyStreams collection contains only the Energy streams
in the flowsheet.
Variables can be reused
when they are finished with. The ProcessStream object type can hold both Material and Energy
There is no need to declare
a different variable for each stream objects, however Energy streams have far fewer accessible
stream or operation that is properties. In this case the HeatFlow property is used.
accessed.
The GetValue method is then used. This is analogous to the SetValue
method except that it takes only one parameter: the required unit.
Similarly the compressor duty and LPG product mass flow are obtained.
Note that there is no need to obtain an object variable for a stream or
operation before running the GetValue method against one of it's
properties. However if the same object is to be used more than once it
makes sense to create an object variable for it.
Figure 24
22
Automation Introduction 23
The next section of the code retrieves some additional values from some
operations on the main flowsheet.
Figure 25
The final sections of the code deal with obtaining component specific
properties.
Figure 26
23
24 Automation Introduction
Note that each time execution reaches the Next IntCount line, it jumps
back up to Set hyCpt = … line. This is the first time a VB loop has been
used in this code. Each time the loop executes the value of the IntCount
variable is increased until it reaches the number of components minus
one.
All the HYSYS collections are “zero based” - The first term is at position
zero.
The result of this loop is that if Methane is present in the case then it's
position in the list of components will have been placed into the
IntCH4Idx variable.
Figure 27
24
Automation Introduction 25
All HYSYS values that contain arrays of data (e.g. component mass
fractions, or mole flows, or tray by tray data in a column) have a special
object type called RealFlexVariable.
What is the value in this array at the position held in the IntCH4Idx
variable? Does this agree with the Methane mole fraction displayed in
HYSYS?
Finally all the component mass fractions in the Product LPG stream are
to be reported.
25
26 Automation Introduction
Figure 29
Here the VarHyArray variant array is first filled with the names of all the
components and then the component mass fractions, and each are
written into the spreadsheet.
26. Examine the ProcessStream object in the Object Browser. Note that
each of the properties also has a corresponding …Value property.
(e.g. Temperature and TemperatureValue or Pressure and
PressureValue)
26
Automation Introduction 27
In each case the …Value property simply returns a value of type Double
(in the case of single valued properties like temperature), or Variant (in
the case of component properties), in the HYSYS internal calculation
units.
RealVariables and
RealFlexVariables also have
properties called Value and Rather than use the...Value properties of the ProcessStream object, it is
Values, which return generally better practice to use [Link](s) property of the
numbers in HYSYS internal Real(Flex)Variable.
units.
The final lines of the main code, clear all the object variables and then
instruct VBA to skip the error handler if no error has occurred.
Figure 30
27
28 Automation Introduction
The first two examples can be found in Section 5.7 of the Customization
Guide. In this exercise a User Variable will be implemented that relates
the heater pressure drop to the flow rate in one of the exchangers in the
Turbo Expander Case.
28
Automation Introduction 29
Object Location
Operations (except Logicals) Design tab... User Variables page
Streams Worksheet tab... User Variables page
Logical Operations User Variables tab
Flowsheet Flowsheet menu... Flowsheet User
Variables option
Simulation Case Simulation menu... Simulation Case
User Variables option
When any of these locations is opened the view will be similar. (Below is
the view for a stream).
Figure 31
29
30 Automation Introduction
To add a new User Variable, click the Create New User Variable icon. The
Create New User Variable dialog box then appears.
This window is the same for all types of user variables. The only
difference is the available macro types.
The only way to close the This choice sets when the code gets called. For Streams, Operations and
window and save any Flowsheets the choices are before and after the object does it's
changes made is to click the
OK button. calculations. Simulation Case user variables are only ever executed
when the user clicks the button on the User Variable window.
Before the User Variable code window can be closed (by clicking OK), a
name must be set for the User Variable.
30
Automation Introduction 31
The Show / Hide Variable Details icon (green triangle) in the top right
corner of this window is used to toggle the display of the User Variable
details tabs.
Show / Hide Variable
Details icon In order to edit an existing User Variable, click the Edit the Selected User
Variable icon on the User Variable page of the HYSYS object, or double-
click the user variable value cell.
Figure 33
Figure 34
31
32 Automation Introduction
Figure 35
There is also a built in Object Browser. Since the code is executed from
HYSYS there is no need to make a reference to the HYSYS type library -
this is already set internally.
The code that is written in the User Variable uses almost exactly the
same VBA syntax as when accessing HYSYS from Excel. The only
difference is how to connect into the HYSYS object hierarchy, and how
to interact with the displayed user variable value.
32
Automation Introduction 33
1. ActiveObject
• This returns on object for the owner of the code. The type of this
object depends on what kind of User Variable is using it:
• Stream User Variable = Returns a ProcessStream type object for
the stream containing the user variable.
• Operation User Variable = Returns an object for the operation
containing the user variable. (Type of object depends on the type
of operation.)
• Flowsheet User Variables = Flowsheet object for owner
flowsheet.
• Simulation Case User Variables = Not supported - use
ActiveCase object instead.
2. ActiveCase - Always returns a SimulationCase object for the case
containing the User Variable.
33
34 Automation Introduction
Figure 36
2. Select the User Variable to export then click the Export button.
3. On the file dialogue that appears set the file name of the required
User Variable export file (This will have a .huv extensions).
34
Automation Introduction 35
Parameter Value
Name Pressure Drop Calc
(Tag will automatically be set to the
same)
Type Real
Dimensions Scalar
Units Pressure Drop
Execution (Macro tab) PreExecute()
Activation (Attributes tab) User Enabled
Variable... Calculate Only (Security tab) Checked
35
36 Automation Introduction
4. Either type the code below into the code window, or paste it from
the supplied text file. (“Adv Automation - UV [Link]”)
Figure 37
36
Automation Introduction 37
Figure 38
5. Place a breakpoint on the Sub PreExecute() line, then make the code
run by changing the flow rate of the Feed Gas stream.
6. Step through the code and ensure that it is behaving as expected.
Note that the first time the code is called after the change is made, the
mass flow through the cooler is not known hence the code in the If
It’s best to trigger the User [Link]=True Then … End If section is not
Variable for debugging by executed.
changing a value in the
flowsheet, and hence
making HYSYS call the This is because when the solver performs steady state calculations there
code. are two solve passes which it performs: the forget pass and the calculate
pass. When the value of a variable changes, the solver first does one
If the code is triggered by solve pass with the value marked as unknown. This is the forget pass.
clicking the Start / Resume
toolbar button then any
This allows HYSYS to correctly propagate the effects of any change.
ActiveObject references will
not point to the correct 7. Export the User Variable and import it into another case. (You could
object. try one of the HYSYS sample cases, or one of the solution cases for
this course.)
Challenge
Try using this code in a similar User Variable for a Heater operation or a
Valve. Does it work? What modifications need to be made?
Try adapting the code to base the pressure drop on some other
parameter - for example the molar flow, or the density, or the
composition of a particular component.
37
38 Automation Introduction
38