Example of Using the Excel Unit Op

CHEMCAD allows use of a custom unit operation model specified in Microsoft Excel.
Some customization of CHEMCAD files is required. The unit operation model must be
written in Visual Basic for Applications (VBA). This document is a tutorial that guides the
advanced user through the process of customizing CHEMCAD files and inserting VBA
code in the framework provided by Chemstations. The user is responsible for
developing their own VBA model of a unit operation.
Part 1: Mixer with no defined Pressure
The Excel Unit Op will be utilized to perform the task of a mixer in this example. First a new job is created
in CHEMCAD. Name the job Excel. Two feed streams and one outlet stream are connected to an Excel
Unit Op. No other unit ops are needed. Connect the flowsheet as shown, then double click the the Excel
Unit Op to open its dialog box.

Upon opening the dialog box, the File Paths screen will appear.

The first field displays the file name of the custom dialog box used by this unit. For the first part of this
example, this will be ignored. Custom dialog boxes will be addressed in the second part of the example.
This field can either be deleted or left with the default value. If it is left, an example dialog box will show
up upon closing this dialog box. The example dialog is not functional and can be ignored.
The second field displays the file name of the Excel workbook used by the Excel UnitOp. This is the file
that contains the Visual Basic Applications code. CHEMCAD automatically creates this file (as well as the

user added dialog box files) the first time you open the Excel Unit Op dialog box. Both files are created
in the job directory. To use a file in a different location, the full path must be specified in this dialog box.
The second page of the dialog box lists the macros that are pre-defined and built into the Excel Unit Op.
Any user added macros that are not listed must be added to this screen, once they are written. To
disable a macro, check the diable box on the right.

The OnEntry macro performs the function of bringing in all data of the streams from CHEMCAD to Excel
and the macros. The ExcelUop macro has skeleton programming code that will fit the need of most
users. The OnExit macro puts all the new or changed data back into CHEMCAD. The user can
customize any of these macros, but will normally customize only ExcelUop. The user can create
additional macros. If additional macros are created, they must be listed in this dialog box in order to be
run. The order in which the macro is listed in this dialog box is the order in which the macro will be
executed.
Click OK to close the Excel Unit Op dialog.
Now define some components for the Excel job. From the Thermophysical menu select Component
list to edit the jobs components. For this job, pentane, heptane and hexane are added to the component
list. Once a component list is defined, give values of components, temperature, and pressure for the two
feed streams. Feed stream one will be at 60 F and 15 psia. Feed stream two will be at 90 F and 10
psia. The amounts of each component can be seen in the picture below. All values were chosen
arbitrarily for the sake of the example.

Open Excel and then open the file created by CHEMCAD (here, Excel1.xls). This file is found in the job
folder of the current work directory (default: c:\cc5data).

Now open the Visual Basic Editor box. This can be done either by the Tools menu > Macros > Visual
Basic Editor on the tool bar, or by pressing [Alt]+[F11]. The code for each of the built in macros can be
seen in the Procedures box on the right. Jump to the ExcelUop sub by selecting it with the combo box in
the upper right corner of the project view window, as shown.

Now you are in the correct subroutine to add user code for a unit operation model. Scroll through the
code until you get to the line that states
' [your code goes here, get what you need through the above object handles].
The lines preceding this one are comments added for the users benefit which describe available
variables. The lines are listed below for explanation purposes. These variables were declared and
defined in the OnEntry macro.

'
'
'
'
'
'
'
'

nComp - number of components

nInlets - number of inlets
nOutlets - number of outlets
inletTempR() - temperature of inlets (base 1)
inletPresPsia() - pressure of inlets (base 1)
inletEnthBtu_Hr() - enthalpy of inlets (bass 1)
inletMoleVapFrac() - vapor fraction of inlets (base 1)
inletCompRatesLbmol_Hr(,) - component mole rates of inlets(stream index, base 1)

'
'
'
'
'
'

outletTempR() - temperature of outlets (base 1)

outletPresPsia() - pressure of outlets (base 1)
outletEnthBtu_Hr() - enthalpy of outlets (bass 1)
outletMoleVapFrac() - vapor fraction of inlets (base 1)
outletCompRatesLbmol_Hr(,) - component mole rates of outles(stream index, base 1)

The variable nComp has the number of components that are in the component list in CHEMCAD. The
variable nInlets has the number of inlet streams to the Excel Unit Op as the variable nOutlets has the
number of outlets from the Excel Unit Op.
The next group of variables which start with the word inlet have the properties of the inlet streams
stored in arrays. The last group of variables which start with the word outlet hold the properties of the
outlet streams. The values element i of the array pertains to the stream connected to inlet number i. For
example, inletTempR(2) holds the temperature of the stream connected to the second inlet.
If an inlet stream has defined values in CHEMCAD, the values will be stored in the inlet variables when
the OnEntry macro runs. The inlet variables can be called by the users code. When the OnExit macro
runs, it returns the values of the outlet arrays (outletTemp(I), etc) to CHEMCAD. The users VBA code, in
ExcelUop macro, determines the values of the outlet arrays.
Note that the units of the inlet and outlet arrays are Rankine, Psia, Btu/hr, and lbmol/hr. Different units
may be used for calculation, but the numbers returned to CHEMCAD via the outlet arrays are evaluated
in the listed units. The unit conversion methods available for VBA are discussed in the VBA services
manual.
In this section, type in your code. Below is the code for the mixer example. A detailed analysis follows the
code.

Dim X As Integer
Dim compLbmol_Hr(1 To SIZE_COMP_ARRAY) As Single, flashcompLbmol_Hr(1 To
SIZE_COMP_ARRAY) As Single
For X = 1 To nComp
outletCompRatesLbmol_Hr(1, X) = inletCompRatesLbmol_Hr(1, X) +
inletCompRatesLbmol_Hr(2, X)
compLbmol_Hr(X) = outletCompRatesLbmol_Hr(1, X)
Next X
outletEnthBtu_Hr(1) = inletEnthBtu_Hr(1) + inletEnthBtu_Hr(2)
If inletPresPsia(1) <= inletPresPsia(2) Then outletPresPsia(1) = inletPresPsia(1) Else outletPresPsia(1) =
inletPresPsia(2)
Dim tempR As Single, flashTempR As Single
Dim presPsia As Single, flashpresPsia As Single
Dim enthbtu_hr As Single, flashenthbtu_hr As Single
Dim flowrate As Single
presPsia = outletPresPsia(1)
enthbtu_hr = outletEnthBtu_Hr(1)

tempR = (inletTempR(1) + inletTempR(2)) / 2

'must define a stream before flashing it!
check = flash.DefineFeedStream(tempR, presPsia, enthbtu_hr, compLbmol_Hr)

check = flash.CalculateHPFlash(enthbtu_hr, presPsia)

outletMoleVapFrac(1) = flash.GetMoleVaporFraction
check = flash.GetVaporStream(flashTempR, flashpresPsia, flashenthbtu_hr, flowrate, f
lashcompLbmol_Hr)
If flashTempR = 0 Then
check = flash.GetLiquidStream(flashTempR, flashpresPsia, flashenthbtu_hr, flowrate,
flashcompLbmol_Hr)
End If
outletTempR(1) = flashTempR
A portion of this code is just used to define more variables that are not previously defined. The lines of
code that do this are seen below.

Dim X As Integer
Dim compLbmol_Hr(1 To SIZE_COMP_ARRAY) As Single, flashcompLbmol_Hr(1 To
SIZE_COMP_ARRAY) As Single

Dim tempR As Single, flashTempR As Single

Dim presPsia As Single, flashpresPsia As Single
Dim enthbtu_hr As Single, flashenthbtu_hr As Single
Dim flowrate As Single
The first section of code that performs a task would be to use predefined variables of the inlet and outlet
streams of the unit and combine the inlets to create the outlets. The For.Next section adds up each of
the component amounts from the two inlet streams and stores them into the outlet stream.
For X = 1 To nComp
outletCompRatesLbmol_Hr(1, X) = inletCompRatesLbmol_Hr(1, X) +
inletCompRatesLbmol_Hr(2, X)
compLbmol_Hr(X) = outletCompRatesLbmol_Hr(1, X)
Next X
The mixer in this example is adiabatic, so energy must be conserved.The next section of code add the
enthalpies of the two inlet stream and stores the value into the outlet stream enthalpy.
outletEnthBtu_Hr(1) = inletEnthBtu_Hr(1) + inletEnthBtu_Hr(2)
The next statement is an IfThenElse statement that sets the pressure for the outlet stream.
If inletPresPsia(1) <= inletPresPsia(2) Then outletPresPsia(1) = inletPresPsia(1) Else outletPresPsia(1) =
inletPresPsia(2)
In the second part of the example, the pressure will be input by the user via the customized dialog box.
For the first part of the example, the outlet pressure is fixed as the lower pressure of the two inlet streams.
The statement checks to see if the first inlet stream has a lower or equal pressure to that of the second
inlet pressure. If it does, the outlet pressure is set to the pressure of the first inlet stream. If it does not,
the outlet pressure is set to the pressure of the second inlet stream.

The next section of code (after variable declarations previously described) stores the new pressure,
enthalpy, and temperature into new variables.

presPsia = outletPresPsia(1)
enthbtu_hr = outletEnthBtu_Hr(1)
The temperature is arbitrarily set as the average of the inlet temperatures. This is done so the variable
tempR is not zero when it is used to define the stream.
tempR = (inletTempR(1) + inletTempR(2)) / 2
Next the stream to be flashed is defined with the pressure, enthalpy, and temperature from above
(presPSIA, enthbtu_hr, tempR).
check = flash.DefineFeedStream(tempR, presPsia, enthbtu_hr, compLbmol_Hr)
The next lines of code have CHEMCAD perform the flash calculation with the defined stream, and then
get the properties of the vapor stream for the flash calculation.
check = flash.CalculateHPFlash(enthbtu_hr, presPsia)

The flash is done with an HP flash since the enthalpy and pressure of the outlet stream is known. The
calculateHPflash method takes the defined overall composition and flashes the stream to the specified
enthalpy and pressure. The flash method uses the VLE model selected for the flowsheet in CHEMCAD.
Note that temperature, vapor fraction, and phase composition are the unknown variables which
CHEMCAD must find.
Once the stream is flashed, the temperature and vapor fraction of the flashed stream need to be returned
and stored for the outlet stream. The vapor fraction is stored directly to the outlet stream array.
outletMoleVapFrac(1) = flash.GetMoleVaporFraction
The temperature for the vapor portion of the flashed stream is obtained to return the value of the overall
temperature. Note that this method will set the specified variables equal to values for the vapor phase of
the defined and flashed stream. We do not wish to overwrite our variables, so new dummy variables are
used.
check = flash.GetVaporStream(flashTempR, flashpresPsia, flashenthbtu_hr, flowrate,
flashcompLbmol_Hr)
If there is no vapor in the stream, the vapor stream temperature (and other variables) will be zero. The
next line of code takesthe liquid temperature if there is no vapor. Again we use the dummy variables.
If flashTempR = 0 Then
check = flash.GetLiquidStream(flashTempR, flashpresPsia, flashenthbtu_hr, flowrate,
flashcompLbmol_Hr)
End If
The value for flashTempR is now the temperature calculated by the HPflash method. The outltet
temperature is set to this value.
outletTempR(1) = flashTempR
Now all properties for the outlet stream are known. Oultet enthalpy and flowrates were obtained by
observing conservation of mass and energy. Outlet pressure was obtained as the lower inlet pressure.
After calculating the flash for the outlet stream based on P, H, and composition, the vapor fraction was
obtained. The temperature (vapor and / or liquid) has been obtained from the results of the flash
calculation. The outlet arrays have been set to the calculated values.

All user coding is finished. The built in code in CHEMCAD will put the stream data just stored by the user
into the stream fields in CHEMCAD when OnExit runs. Save before closing the Visual Basic Editor.

Part 2: Defining The Pressure for the Mixer

In section one an Excel Unit Op which does not require user interaction was created. The next part of the
tutorial uses a customized user added dialog box to allow user specification of the operating pressure of
the mixer. This pressure is used for the flash calculation of the stream to obtain the stream properties.

The first step is to create the user added dialog box for the Excel Unit Op. The Excel1.MY file, which is
found in the job directory just as the Excel1.xls file was, must be opened with the CHEMCAD Screen
Builder program.

Use of the Screen Builder program is described in detail in the Screen Builder Help Document. If further
clarification is needed for the commands used in Screen Builder, please consult that document.
When the Excel1.MY file is opened, the screen should look as shown in the picture below.

Next choose Layout from the command menu, and then Edit from the Layout menu. Alternatively, press
[ctrl] + [E].

The screen should now look as below.

Click on the text label that reads You may use Screen Edit program to create custom dialog. Green
squares appear to highlight this field. Edit the text in the box to read Enter the output pressure.

Now click on the text labeled Example: and the same green box should appear. Delete this text box by
either using the delete button or from the toolbar choose Edit and the Cut. Repeat the same process to
remove the text labels Temperature and Heat duty. Use the same process to remove r the two white
boxes (EditDblBox1 and EditDblBox3) as well as the two [#] labels (TextVar1 and TextVar3) that are on
the same row as the Temperature and Heat duty text labels. All that should be left is the text labeled
Pressure , the enrtry field labeled EditDBLBox2, and the [#] across from it. The way the box looks has
been used for description here, but to read the entry field label, simply double click the box and the label
will be shown. For example, double click the white box across from the Pressure text and the lable will
be EditDblBox2. The screen should now look as seen below.

The next step is to change the code of the dialog box to correspond to CHEMCAD. Changing the
ValueID field for the EditDblBox2 screen does this. Double click the remaining white box on the screen
(EditDblBox2 next to the Pressure label) and scroll down the list of fields until ValueID appears. Change
this number by clicking on the Double002 to Double001.

Now close the Property Sheet window for EditDblBox2 and save the file. Then close the program. The
next file that needs to be changed is the Excel1.Map file. This is also found in the same directory as the
Excel1.My file and the Excel1.xls file previously opened with this example. This file is opened with
Notepad. The file will look similar to the one below.

The term Dictionary refers to the number of variables that will be present. This must be changed to one
instead of three. Only one variable will be present; the set pressure. The lines Temperature 1 Float
Temp and Heatduty 3 Float Qrate are deleted. The line Pressure will be left. The number must be
changed from 2 to 1, as Pressure is now the first (and only) variable assigned to this unitop. The file

should look as shown below. After making these changes, save and close the file.
The last file that needs to be customized for the dialog box is the Excel1.Lab file. The .lab files are used
by the reporting features of CHEMCAD (output >resulsts, output >reports, tools >specsheet). Reports are
made using the labels specified in the .lab file with the variable specified.
The Excel1.lab file is found in the job directory and is opened with Notepad just as Excel1.Map was. The
file will read as below.

This file must be edited in a similar manner to the Excel1.Map file. The Temperature and Heat
duty lines are deleted. The first number on the pressure line, 2, is changed to a 1. This instructs
CHEMCAD that the first variable should be labeled Pressure. The file should now look like the one
below. Save the file and then close.

The new dialog box is finished. To test, go back into CHEMCAD and open the Excel job. Double click
the Excel Unit Op and make sure Excel1 is in the first entry field of the dialog. This field will be empty if it
was deleted in the first part of the tuturial. Now click [OK] for the first dialog box with the file paths. The
second dialog box should come up with a Pressure field available to have data entered into it. Enter the
pressure of 20 psia and click [OK].

Now run specsheet for the unit op. This command is found under Tools on the menu bar. An Excel
spreadsheet should come up for the unit op. On the part of the spreadsheet labeled UNITOP DATA
FROM CHEMCAD are all the variables, parameters, units and values listed for the Excel Unit Op. The
only value that should be here is Pressure with a value of 20. The item to take note of here is the variable
number for Pressure. In this case it is 2. This will be needed for the visual basic code.
Close Specsheet.xls and open the Excel1.xls file. Open the Visual Basic code that was programmed in
part one of the example. Only one section of code needs to be changed.
' If inletPresPsia(1) <= inletPresPsia(2) Then outletPresPsia(1) = inletPresPsia(1) Else outletPresPsia(1) =
inletPresPsia(2)

If myUnitPar(2) <> 0 Then

outletPresPsia(1) = myUnitPar(2)
Else: If inletPresPsia(1) <= inletPresPsia(2) Then outletPresPsia(1) = inletPresPsia(1) Else
outletPresPsia(1) = inletPresPsia(2)
End If
myUnitPar is an array of the unit op specification variables, as seen on the specsheet report. The
nd
number 2 corresponds to the number noted of on the spec sheet. The 2 element of the myUnitPar array
is the pressure specification. Note that the first element of myUnitPar is reserved.
The first line shown is the line of code that needs to be changed. This line of code previously set the
pressure. Put an apostrophe in front of this line to make it a comment. Comment code is not executed
when the program runs.
Next, type in the second line above with the myUnitPar variable checks to see if a pressure is entered into
the created dialog box. If the pressure was specified in the dialog, it will will be stored as myUnitPar(2) .
nd
This is an array with all the unit op variables as seen on the spec sheet. The 2 element of myUnitPar()
nd
corresponds to the 2 parameter of the unit op. Viewing this unitop with specsheet, we confirmed that the
nd
2 parameter of this unitop is Pressure. This code will set the outlet stream pressure to the input value,
myunitPar(2). If that value equals zero then no number was entered into the dialog box and a default
pressure will be used as the outlet pressure. The default pressure is the lowest pressure of all the
incoming streams. The line of code for this corresponds to the same line of code for setting the outlet
pressure in section one of the tutorial. Save the file and exit. Run the Unit op in CHEMCAD.