User Unit Operations 1

User Unit Operations

© 1999 AEA Technology plc - All Rights Reserved. 1

Extn 2.pdf
2 User Unit Operations

Introduction
User unit operations, just like unit operation extensions, allow the
HYSYS user to build a custom unit operation for their simulations. User
unit operations and unit operation extensions differ from each other in
several ways; the most important difference is the location of the
defining code.With a unit operation extension, the defining code exists
outside of the HYSYS simulation in a separate DLL; while the defining
code for a user unit operation is written and exists within the HYSYS
simulation.

User unit operations operate much like any other operation in HYSYS
with one important exception; with these operations, the user must
supply the code that will define their function.

Having the user enter the defining code means that user unit
operations can be used to model operations that are not available with
the normal HYSYS package. It also means that HYSYS users are virtually
unlimited in regards to the amount of customization that they can
introduce into a simulation.

Learning Objectives
By completing this module, you will learn:

• How to install and define a user unit operation.

• The purpose and function of each of the three main
subroutines in user unit operation code.

Prerequisites
Before beginning this module, you should have some experience with
writing VB compatible code in HYSYS, either with the MLE, user
variables, or user unit operations.

2

Because the defining code for
extensions is complied, it can
be freely distributed without
any risk of sharing proprietary
or confidential information.
User Unit Operations 3
Background
User unit operations and unit operation extensions both offer the
HYSYS user an opportunity to increase the functionality of the HYSYS
program through the addition of custom built unit operations.
It may seem that these two features would be in conflict as their
purposes are similar. However, they are not. These two features have
differences that direct them towards different areas of application.
User unit operations are often easier to construct and install than unit
operation extensions. For example, user unit operations do not have a
separate EDF file defining the views of the operation. Instead, a generic
interface is used for all user unit operations. The code of the operation
exists within the HYSYS simulation and is saved whenever the
simulation is saved. Although, user unit operations can be exported to a
separate file and imported into another simulation.
One disadvantage of the user unit operation is that the code is not in a
compiled form like it is for extensions. This means that the user unit
operation code can not be distributed without possibly distributing
confidential and proprietary information. Another limitation is that the
views for the user unit operation can not be modified and customized
like the views for extensions.
On the other hand, a major advantage of the user unit operation, is that
the use of a separate programming environment is not required. The
code is written within the HYSYS program so a separate compiler is not
needed. To write an unit operation extension you will need to use a
separate programming environment like VB or C++.
3
4 User Unit Operations

User Unit Operation Code

Whenever a new user unit operation type is created, HYSYS creates
three subroutines in the code for the operation. These three
subroutines are: Initialize, Execute, and StatusQuery. Each of these
subroutines has its own specialized function and responsibility; they
will all work together in a properly designed user unit operation.

The Initialize Subroutine

This subroutine is called only once for the life of the user unit
operation. It is called just prior to the first run of the Execute
subroutine. The purpose of this subroutine is to set up the operation.
Typically, this includes, but is not limited to, the following:

• Setting nozzles as "Active" or "Inactive" as required.

• Naming all valid nozzles.
• Creating any variables that need to be created, and giving
them initial values.

The Execute Subroutine

This subroutine is called whenever the operation is required to solve.
This can occur when a variable of the operation is changed, or when an
attached stream is recalculated by the program. Typically, this
subroutine will contain all of the code needed to perform the
operation’s calculations.

The Calculate method should be used in this subroutine (and only this
subroutine) to write calculated values back into the simulation. Any
values returned to the simulation via the Calculate method will appear
in black to the HYSYS user.

The StatusQuery Subroutine

This subroutine is called whenever HYSYS wishes to update the status
information for its objects. The primary functions of this subroutine
include the following:

• Provide warning and error messages.

• Display these messages in the HYSYS status window and in
the status bar at the bottom of the user unit operation’s view.

4
 User Unit Operations 5

Workshop
In this workshop, we will create and install a user unit operation that
will model a steam ejector vacuum pump.

The user can either specify information about the motive steam, or
about the suction stream, and the operation will calculate the
remaining parameters.

Creating a User Unit Operation

The process for creating a user unit operation and adding it to your
simulation is quite straight forward. User unit operations are added
much like any other unit operation in HYSYS.

To begin this Workshop complete the following steps.

1. Open the HYSYS case U_U_Op-Workshop.hsc located on the

Starter disk supplied with the course material. This case contains
a partially built Steam Ejector user unit operation.
2. Once the case is open, the debugger window will appear. This is
expected because of the missing lines of code. HYSYS recognizes
that there is a syntax error in the code and brings up the
debugging window. We do not wish to debug the code at this time
so close this window.

5
6 User Unit Operations

The Initialize Subroutine

As mentioned before, the Initialize subroutine serves to set up the
connections of the operation to match the required conditions. For this
operation, we need to have two material feed streams and one material
product stream. There are no energy streams for this operation. The
code for the Initialize subroutine has been partially written; however, it
is missing most of the important information.

3. Add the following two lines of code to the Initialize subroutine

(after the error handler) to change the labels for the first feed
stream and the product stream.

ActiveObject.Feeds1Name = "Inlet"
ActiveObject.Products1Name = "Outlet"

4. By default, only the first feed nozzle and the first product nozzle
are active. Before we can change the label of the second feed
stream, we need to activate it. Add the following two lines of code
immediately after the two lines entered for step 3.

ActiveObject.Feeds2Active = True
ActiveObject.Feeds2Name = "Motive Steam"

This completes the Initialize subroutine. As you can see, this

subroutine is relatively short, because it performs a very specialized
and simple task.

6
 User Unit Operations 7

The Execute Subroutine

The Execute subroutine is responsible for performing all calculations
necessary to solve the operation. It contains the code that will define
what this operation will do.

5. The first line of code that must be added will prevent the
subroutine from running if the HYSYS solver is in the middle of a
"forget" pass. Add the following line of code to the Execute
subroutine.

If MyEjector.SimulationCase.Solver.IsForgetting Then Exit Sub

6. The next step in this subroutine will set the stream variables to
reference the correct objects. Complete the partially written code
so that it looks like the following.

Set InStrm = MyEjector.Feeds1.Item(0)

Set OutStrm = MyEjector.Products1.Item(0)
Set StmStrm = MyEjector.Feeds2.Item(0)

7. In order for the operation to perform accurate calculations, the

motive steam stream must contain a certain amount of water. It is
necessary to check the composition of the steam in order to
assure that the calculations will be accurate. Add the following
lines of code to the subroutine in order to perform this task.

Dim Comps As Object

Set Comps = _
MyEjector.SimulationCase.BasisManager.FluidPackages(0).Components
H2O = Comps.index("H2O")
SSCMF = StmStrm.ComponentMassFraction.Values
If (SSCMF(H2O) > 0.95) Then OKH2O = True Else OKH2O = False

7
8 User Unit Operations

8. The Balance method of user unit operations can be used to

perform heat, mass, molar, or total balances over the operation.
Use the Object Browser to see how this method is used. Note how
many arguments this method requires and what each argument
does.

How many arguments does the Balance method require?

_____________
What does the first argument do? ________________
And the second? ________________
And the third?_______________

9. Add the following lines of code to perform a total balance on the

operation.

Dim strs(0 to 2) As Object

Set strs(0) = InStrm
Set strs(1) = StmStrm
Set strs(2) = OutStrm
MyEjector.Balance btTotalBalance, 2, strs

This completes the Execute subroutine; remember that most of the

code was written for you. In the Exercise portion of this module, you
will have the opportunity to write an Execute subroutine without any
starter code.

8
 User Unit Operations 9

The StatusQuery Subroutine

The StatusQuery subroutine is used to update the Status bar in HYSYS
with appropriate messages to help the user.

10. The first line of code that should be added will check to see if the
operation is set to be "ignored" and exit the subroutine if this is
the case. Add the following line of code to the subroutine.

If ActiveObject.IsIgnored Then Exit Sub

11. The code that will be entered here will add the following message
to the status bar: "Requires a Feed Stream." This message will be
displayed if there is no feed stream attached to the operation. Add
the following line of code to the subroutine.

Call ActiveObject.AddStatusCondition(slMissingRequiredInformation, 1, _
"Requires a Feed Stream")

12. This step will also print an error message into the status bar. This
time the message should read, "Requires a Motive Steam
Stream." Add the required code to the subroutine. Hint: it looks a
lot like the code for step #11, but the unique identifier in the line
above (the number 1) will have to be different for this error
message (use the number 2).
13. The code that will go here will add another warning message to
the status bar if the motive steam stream does not have enough
water in it. Add the following line of code to the subroutine.

Call ActiveObject.AddStatusCondition (slMissingOptionalInformation, 12, _

"Mass Frac H2O must be > 0.95 in Motive Steam Stream.")

This should complete the StatusQuery subroutine. All three

subroutines should now be able to run without error.

Return to the PFD view and force the operation to resolve by changing
one of the parameters in one of the feed streams. For example, change
the pressure in the steam stream to a different, but similar, value.

Does the operation solve properly? __________

If the operation did not solve properly, try to debug it using
some of the debugging tools available in the code
environment.

9
10 User Unit Operations

Exercise
In this exercise, you are asked to build a working user unit operation
without step-by-step guidance from the instructor.

The operation built here will be a Pressure doubler. Although it is

completely imaginary, this type of user unit operation is very easy to
construct.

Step-by-step instructor guidance will not be provided; there will be

some hints and suggestions given here to help you complete this
exercise.

Before starting this exercise, open the HYSYS case:

U_U_Op-Exercise.hsc located on the Starter disk supplied with the
course material. This case contains one fully defined material stream
that will be used as the feed stream to the user unit operation.

Adding the User Unit Operation

In order to add a user unit operation to your simulation, perform one of
the following procedures:

• Select Add Operation from the Flowsheet drop down menu,

and select User Unit Ops from the list that appears.
• Press the <F12> hot key, and select User Unit Ops from the
list that appears.
• Press the User Ops button on the Object Palette and add the
The User Ops button. operation to the PFD in the usual manner.

Completing one of the above options will bring up the Add User Unit
Operation window.

10
 User Unit Operations 11

If there have not been any user unit operations added (or imported) to
the simulation before this point, there will be only three options
available to the user: Cancel, Create Type, or Import Type. If a
previously exported user unit operation exists, it could now be
imported; however, we are going to create a new user unit operation
type so select the Create Type button. The following view will appear.

Type the name for the user unit operation here. It is always a good idea
to use a name that will somehow describe the function of the user unit
operation. In this case, enter P-Doubler for the type’s name, and press
the OK button. This will return you to the previous view and HYSYS will
display the newly created type’s name in the Available User Unit
Operations list.

In order to create a new user unit operation, highlight the name of the
newly created type and press the Add button. This will bring up the
User Unit Op view.

From this page you can access the code editor by selecting the Edit
button on the Code page.

The Initialize Subroutine

The code that should go here is very similar to the code that was put
into the Initialize subroutine in the Workshop section of this module,
with one very important exception. Rather than a second material feed
stream, we need an energy feed to be attached to this operation. Energy
feeds need to be activated just like secondary material streams.

If desired, you may wish to add an error handler to this subroutine,

which will help you find run time errors in the program.

11
12 User Unit Operations
Checking that both the mass
and molar flow of the feed
stream are known may seem
redundant; however, this is
one way to ensure that the
stream is fully defined.
12
The Execute Subroutine
The first line of this subroutine should be an If ... Then statement that
will check to see if the solver "IsForgetting" or not. Hint: see step #5 in
the Workshop section.
The next bit of code should be three local variable declarations for the
stream objects.
Following the variable declarations, the declared variables can be set to
reference their respective streams. If desired, you may wish to check if
there are streams attached before setting the reference, though this is
not mandatory.
Five items must be known before this operation will be able to solve.
These five items are:
• Feed stream - Molar Flow
• Feed stream - Mass Flow
• Feed stream - Pressure
• Feed stream - Temperature
• Energy stream - Heat Flow
Use the IsKnown property to determine if all of these items are defined.
If any one of the five is not defined, then exit the subroutine.
Next, use the Calculate method to set the outlet stream’s pressure at
twice the pressure value of the inlet stream.
Finally, use the Balance method of the operation to finalize the
calculations. Hint: See step #9 in the Workshop section.
Again, if desired, an error handler can be added to this subroutine in
order to catch any errors.
 User Unit Operations 13

The StatusQuery Subroutine

The first line in this subroutine will be an If ... Then statement that will
check to see if the "ActiveObject" is ignored or not. If it is ignored, this
subroutine should be bypassed. Hint: See step #10 in the Workshop
section of this module

Declare three local variables to represent the streams. Hint: see the
second paragraph of the Execute subroutine on the previous page, you
may cut-and-paste the code from there to here.

Next, set the declared variables to reference the proper streams. You
may wish to check to make sure that the streams are valid before you
set the reference.

Use three separate If ... Then statements to display status bar messages
to alert the user to missing streams. Hint: see step #11 in the Workshop
section of this module. Remember that the unique identifier must be
different for each message.

If desired, an error handler could be added to this subroutine to catch

any run time errors that may occur.

Running the Operation

After all of the code is entered into the operation, you can test its
functionality by attaching the feed stream, and creating and attaching
the product and energy streams to the operation.

Does the operation perform as desired? ________________

What is the pressure in the feed stream? ________________

What is the pressure in the product stream? _____________

13
14 User Unit Operations

Advanced Users

How is the temperature in the product stream calculated?

__________

As an additional exercise, use the Calculate method to set the

temperature of the product stream equal to twice the temperature of
the inlet stream.

How will this affect the balance performed at the end of the
Execute subroutine? __________

How will this affect the required information? Hint: Does

the heat flow still need to be known? _____________

Change the operation’s code to reflect these changes.

14