PRO/II 8.

3
User-Added Subroutine User Guide
 PRO/II Version 8.3 The software described in this guide is furnished under a written
agreement and may be used only in accordance with the terms and
conditions of the license agreement under which you obtained it.

Thermodynamic Data Copyright © 2009 Invensys Systems, Inc. All rights reserved. The
Keyword Manual material protected by this copyright may be reproduced or utilized
Copyright Notice for the benefit and convenience of registered customers in the
course of utilizing the software. Any other user or reproduction is
prohibited in any form or by any means, electronic or mechanical,
including photocopying, recording, broadcasting, or by any infor-
mation storage and retrieval system, without permission in writing
from Invensys Systems, Inc.
The technical documentation is being delivered to you AS IS and
Invensys Systems, Inc. makes no warranty as to its accuracy or
use. Any use of the technical documentation or the information
contained therein is at the risk of the user. Documentation may
include technical or other inaccuracies or typographical errors.
Invensys Systems, Inc. reserves the right to make changes without
prior notice.
Trademarks PRO/II and Invensys SIMSCI-ESSCOR are trademarks of Inven-
sys plc, its subsidiaries and affiliates.
AMSIM is a trademark of DBR Schlumberger Canada Limited.
RATEFRAC®, BATCHFRAC®, and KOCH-GLITSCH are regis-
tered trademarks of Koch-Glitsch, LP.
Visual Fortran is a trademark of Intel Corporation.
Windows Vista, Windows 98, Windows ME, Windows NT, Win-
dows 2000, Windows XP, Windows 2003, and MS-DOS are trade-
marks of Microsoft Corporation.
Adobe, Acrobat, Exchange, and Reader are trademarks of Adobe
Systems, Inc.
All other trademarks noted herein are owned by their respective
companies.
U.S. GOVERNMENT RESTRICTED RIGHTS LEGEND
The Software and accompanying written materials are provided
with restricted rights. Use, duplication, or disclosure by the Gov-
ernment is subject to restrictions as set forth in subparagraph (c)
(1) (ii) of the Rights in Technical Data And Computer Software
clause at DFARS 252.227-7013 or in subparagraphs (c) (1) and (2)
of the Commercial Computer Software-Restricted Rights clause at
48 C.F.R. 52.227-19, as applicable. The Contractor/Manufacturer
is: Invensys Systems, Inc. (Invensys SIMSCI-ESSCOR) 26561
Rancho Parkway South, Suite 100, Lake Forest, CA 92630, USA.

Printed in the United States of America, February 2009.

 Contents
Chapter 1:
Modular UAS Introduction
General Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-1
User Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-6
Software Requirements for PRO/II UAS . . . . . . . . . . . . . . . . .1-7
Hardware Requirements for PRO/II UAS . . . . . . . . . . . . . . . . . .1-8
Program Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-9
Upgrading Legacy User-Added Subroutines . . . . . . . . . . . . .1-10
Source Code Changes for Intel Fortran: . . . . . . . . . . . . . . . . .1-13

Chapter 2:
Modular UAS Build Procedures
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1
User Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1
Developer Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-17

Chapter 3:
Modular Interface Software
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-1
Contexts in PRO/II . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-3
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-3
ISOLVE Return Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-4
Call-back Routines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-5

Chapter 4:
Modular Utility Subroutines
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-1
User Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-1
Developer Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-2
Definition of class_ UASOBJ.mod . . . . . . . . . . . . . . . . . . . . . .4-10
class_Fluid.mod and class_FluidPhase.mod . . . . . . . . . . . . . .4-30

Chapter 5:
Modular Unit Operations
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-1
Keyword Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-2

PRO/II User-Added Subroutine User Guide ToC - i

 User Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Developer Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13
Definition of class_ UAUOP.mod . . . . . . . . . . . . . . . . . . . . . . . 5-20

Chapter 6:
UAS Modular Fluids
Interface Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1
Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
User Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
Developer Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
Fluid Guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-21
class_Fluid.mod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-25
class_FluidPhase.mod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-34

Chapter 7:
User-Added Units of Measure
Overview of User Dimensional Units . . . . . . . . . . . . . . . . . . . . . 7-1
UAUTIL User Dimensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4
UAUOP User Dimensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5
Definition of class_DMUOM.mod . . . . . . . . . . . . . . . . . . . . . . . 7-6

Chapter 8:
UAUOP AutoGUI
Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1
Basic XML File Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
Associating an XML file with a UAUOP Unit Operation . . . . 8-3
XML Schema Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4
AutoGUI Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-16

Chapter 9:
UAUOP Icons
Icon Data File Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1
Associating an Icon Data File with a UAUOP Unit Operation9-2
Icon File Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3

Chapter 10:
UAUOP INI File
Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1
Keyword Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1
Input Description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-3
INI File Usage Information. . . . . . . . . . . . . . . . . . . . . . . . . . . 10-15

ToC - ii February 2009

 Chapter 11:
Interfacial Area Utility
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-1
Available Interfacial Area Data - Developers . . . . . . . . . . . . .11-1

Chapter 12:
Binary Mass Transfer Utility
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-1
Available Mass Transfer Data - Developers . . . . . . . . . . . . . .12-2

Chapter 13:
Heat Transfer Utility
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-1
Available Heat Transfer Data - Developers. . . . . . . . . . . . . . .13-2

Chapter 14:
Classic UAS Introduction
PRO/II User-Added Subroutines . . . . . . . . . . . . . . . . . . . . . . .14-1
Software Requirements for PRO/II UAS . . . . . . . . . . . . . . . .14-2
Hardware Requirements for PRO/II UAS . . . . . . . . . . . . . . . . .14-3
Program Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-4
Upgrading Legacy User-Added Subroutines . . . . . . . . . . . . .14-5
Build Procedure for Classic PRO/II UAS . . . . . . . . . . . . . . . .14-6
Customizing a UAS Data Entry Window . . . . . . . . . . . . . . . .14-8
Fortran Coding Standards . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-9
Fortran Programming Guidelines . . . . . . . . . . . . . . . . . . . . .14-10
Source Code Changes for Intel Fortran: . . . . . . . . . . . . . . . .14-11

Chapter 15:
Interfacing Software
Output and Reporting Routines . . . . . . . . . . . . . . . . . . . . . . .15-7
Stream Data Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-10
Flash Calculation Interfaces . . . . . . . . . . . . . . . . . . . . . . . . .15-16
Property Calculation Interfaces . . . . . . . . . . . . . . . . . . . . . . .15-29
Interfaces for Solids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-40
Component Order, Identification, and Data . . . . . . . . . . . . .15-42
User-Defined Data Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-48
Common Storage Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-49

PRO/II User-Added Subroutine User Guide ToC - iii

 Chapter 16:
User-Added Thermodynamic
Property Methods
Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-1
Communicating with PRO/II . . . . . . . . . . . . . . . . . . . . . . . . . . 16-3
Handling Water Decant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-11
Enthalpy and Entropy Calculations . . . . . . . . . . . . . . . . . . . 16-22
Density Calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-36

Chapter 17: Transport and Special Property Subroutines

User-Added Transport Property Subroutines . . . . . . . . . . . . 17-1
User-Added Special Property Subroutines . . . . . . . . . . . . . . 17-11

Chapter 18:
Classic Unit Operations
Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-1
User Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-2
Developer Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-9
User-Added Pipe Pressure Drop Utility Routines . . . . . . . . 18-32

Chapter 19:
Reaction Kinetic Subroutines
User Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-1
Developer Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-3
Example Problem—Allyl Chloride Production in a PFR . . 19-10

Chapter 20:
UAS Refinery Reactor Simulation
User Utility Subroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-1
Example Input File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-25
Example of PRO/II User-Added Subroutine . . . . . . . . . . . . 20-28
C *** Example of User’s Reactor Main Subroutine ***. . . . . . . . . . . . . 20-39

Chapter 21:
UAS Solid Components
Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-1
User Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-2
Developer Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-2

Chapter 22:
Pressure Drop Subroutines
PIPE Pressure Drop Subroutines. . . . . . . . . . . . . . . . . . . . . . . 22-1

ToC - iv February 2009

 Plug Flow Reactor Pressure Drop Subroutines . . . . . . . . . . .22-9

Appendix A:
Special Property Key Words . . . . . . . . . . . . . . . . . . . . . . . . A-1
Named Special Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1
Numbered Special Properties . . . . . . . . . . . . . . . . . . . . . . . . . . A-5

PRO/II User-Added Subroutine User Guide ToC - v

ToC - vi February 2009
 Chapter 1
Modular UAS Introduction
Beginning in PRO/II® version 7, new interfaces for user-added sub-
routines implement a completely new object-oriented design. This
was a significant departure from previous interfaces, which use a
procedural architecture. Starting with this chapter, the first part of
this manual describes the newer modular interfaces.
Modular interfaces offer new functionality, and using them to
implement user-added subroutines is significantly different from
past practice. However, they do not replace any older user-added
functionality in PRO/II. All the interfaces available in earlier ver-
sions of PRO/II still function in exactly the same manner as they
always have. SIMSCI® has no plans to abandon them, and contin-
ues development activities to extend their capabilities.

Note: Refer to Chapter 14, Classic UAS Introduction for informa-

tion about new enhancements to the older interfaces.

General Information
This section presents general introductory information about the
technologies and methodologies used in the modular user-added
interfaces. The next section in this chapter presents information for
end users who wish to use modular user-added subroutines when
running simulations in PRO/II. Instructions for developers imple-
menting modular user-added subroutines appears in separate chap-
ters.

Nomenclature
PRO/II categorizes modular user-added subroutines by function.
Below is a brief summary of some terms used in this manual.

UAS A generic term for any User-Added Subroutine entity. It

includes UAUOP and UAUTIL subroutines written by users.
It does not refer to INTERFACEs supplied by PRO/II.
UAUOP A User-Added Unit OPeration written by a user-
developer. Registered as a [UAUOP] in the P2UasReg.Ini
file. Called only from PRO/II.

PRO/II User-Added Subroutine User Guide 1-1

 UAUTIL A User-Added UTILity subroutine written by a user-
developer. Registered as one (or more) of the utility types
in the P2UasReg.Ini file. Called only from PRO/II.
INTERFACE Any of the software provided by SIMSCI that supports
data exchange between PRO/II and user-written sub-
routines. Older interfaces are available in UASLB.LIB. The
modular interfaces are available in USERLB6.LIB and in a
number of Fortran modules. Interfaces are intended to be
used within user-added subroutines.

Procedural Interfaces
The older user-added interfaces in PRO/II treat individual data
items as separate entities. Refer to Chapter 14, Classic UAS Intro-
duction. They typically include long lists of arguments in subrou-
tine calls. Enhancing them typically requires changing the number
and type of arguments in the call lists. To maintain backward com-
patibility, all versions of each interface must be supported. This
results in many variations of subroutines that basically perform the
same function, which can be confusing.
Procedural interfaces require changes to user-added routines before
they can use the newer versions of the interfaces. Code must be
rewritten and re-linked with PRO/II; then it must be tested and
debugged. From a maintenance perspective, this is inefficient and
undesirable. The newer user-added interfaces in PRO/II do not use
this paradigm.

Modular Interfaces
This is a short overview of object-oriented programming (OOP)
using Fortran 90. It defines the terminology used throughout the
rest of this manual to describe the modular interfaces in PRO/II. It
is not a tutorial of object-oriented practices, which is beyond the
scope of this manual.
Object-oriented programming treats data in sets. First, a storage
object is created and all related data entities are mapped into it. The
storage object may contain a mixture of scalar and array data of dif-
ferent intrinsic types, such as integer, real, character, and logical
data. Each data entity is a data member of the storage object. Data
members that are arrays typically have a dynamic size. They can be
adjusted to accommodate different amounts of data. In Fortran 90, a
data object having these characteristics is called a defined type.

1-2 Modular UAS Introduction February 2009

 Second, member methods are added to operate on the data in the
storage object. This ensures that basic functions for operating on the
data are always available with the data. Adding these methods
transforms the defined type into an Abstract Data Type, or ADT for
short.
Third, the ADT is transformed into a class by adding constructor
and destructor methods. These methods allow allocating and free-
ing computer resources to dynamically create one or more virtual
copies of the ADT in computer memory whenever required. Each
copy is called a class instance. PRO/II’s modular interfaces manage
each instance independently. Each instance always includes all the
data members of the ADT. The dynamic (array) data members in
each instance may have a size different from the analogous member
in other instances. For example, a single class can serve all the
needs of any modular user-added unit operation. Although each
type of unit operation has unique data requirements, they all use
class_UaUop.

In Fortran 90, each Class is encapsulated in it’s own module. A

module is the template that defines a class. The executable code
resides in a dynamic link library, or DLL. A module is the basic
building block for the inter-operation between PRO/II and user-
added subroutines. PRO/II interfaces provide a separate module for
each class. However, the executable code for all modules resides in
a single DLL. Together, all the modules and the DLL constitute the
new PRO/II modular interface.

Modular User-Added Subroutines

Modular user-added subroutines interact with PRO/II through the
modular interfaces. They include user-added unit operations and
user-added utilities. Later chapters present interfacing details.
To use modular UAS’s in PRO/II simulations, end-users must first
install and register them with PRO/II. Specific installation instruc-
tions must be obtained from the UAS developer, not from SIMSCI.
The registration process consists of editing the PRO/II registration
file to include essential access information, so PRO/II can call and
use the UAS. The registration file is divided into sections based on
the functionality of the UAS. Each UAS must be registered in the
proper section of the registration file. For example, a user-added
unit operation must be registered in the [UAUOP] section, while an
interfacial area utility must be registered in the [IFAREA] section.

PRO/II User-Added Subroutine User Guide 1-3

 Modular User-Added Unit Operations
UAUOP behavior is similar to that of native unit operations contained
in PRO/II. However, users first create and install them in their own
dynamic link libraries (DLL’s); then register them, so that PRO/II can
locate them.
PRO/II accepts input data for UAUOP’s through key words and PRO-
VISION™. In the course of solving a flowsheet, PRO/II calls out to
these routines to perform their own data cross-checks, perform cal-
culations, and to write reports of their results.
UAUOP’s have substantially different capabilities from user-added
utilities. For example, a UAUOP conceivably could call a UAUTIL, but
a UAUTIL should never call a UAUOP. Similarly, one UAUOP cannot
call another UAUOP. Generally, user-written subroutines cannot call
a UAUOP. A UAUOP can use any of the interfaces described in this
manual.
Modular User-Added Utilities
Certain PRO/II unit operations allow user-written subroutines to
perform specific calculations. This manual refers to those user-writ-
ten subroutines as user-added utilities, or UAUTIL.
Generally, a UAUTIL is a user-added subroutine that serves as
an alternative to an existing PRO/II method. For example, the
RATEFRAC models allow UAUTIL’s to calculate interfacial area, mass
transfer coefficients, and heat transfer coefficients. All of the exist-
ing procedural utilities, such as USKIN1 and PIPUS2, remain active
and do not have modular replacements.
PRO/II version 7.0 enhanced the RATEFRAC column model to sup-
port 3 new modular utilities. Only RATEFRAC supports them. They
are:
Interfacial Area methods. RATEFRAC allows a different subroutine
or method on each tray or in each packed section.
Binary Mass Transfer Coefficient methods. RATEFRAC allows
a different subroutine or method on each tray or in each packed
section.
Heat Transfer Coefficient methods. RATEFRAC allows a different
subroutine or method on each tray or in each packed section.
These types are discussed in detail in separate chapters later in this
manual. Additional chapters describe UAUOP’s.

1-4 Modular UAS Introduction February 2009

 Modular Interface Call-backs
Modular interface call-backs provide mechanisms for exchanging
data and calculation control between PRO/II and user-added sub-
routines. User-added subroutines call them to retrieve data or to
have PRO/II perform calculations for them. SIMSCI provides all
the call-backs available in PRO/II.
Calculation call-backs are called by user-added subroutines. They
perform PRO/II calculations at the request of the UAS. In a typical
scenario, PRO/II passes execution control to a user-added subrou-
tine by calling either a UAUOP or a UAUTIL. The UAS performs its own
calculations, which may or may not involve calling PRO/II calcula-
tion call-backs. For example, a UAUOP might call function flash_Fluid
to perform a flash calculation on a fluid object. Function flash_Fluid
returns it’s results to the UAS.
Data call-backs return data and other information from PRO/II
when they are called from a UAS. For example, function
GetFactor_DmUom returns factors for converting numerical values
between user-defined and internal PRO/II units of measure.

Compatibility with Procedural Interfaces

Generally, modular subroutines are not compatible with the older
procedural interfaces. In most other cases, mixing the two interfaces
is discouraged. The problems arise mostly from the different dimen-
sional units and different component ordering used for data
exchange.
Procedural user-added subroutines do not support modular data
storage objects. They should not attempt to access modular call-
backs that pass class objects in their argument lists. However, pro-
cedural subroutines may safely use the file-handling, error register,
and line printing routines from the modular interface. Other uses are
strongly discouraged.

PRO/II User-Added Subroutine User Guide 1-5

User Information
This section presents an overview of information that users need to
set up and use modular user-added subroutines with PRO/II. More
complete details are available in Chapter 2, Modular UAS Build
Procedures. Information for developers who author user-added sub-
routines appears in later chapters, not here.

Registering a Modular UAS with PRO/II

PRO/II maintains a “registry” file that includes a separate category
for each supported type of user-added utility. It also supports a sep-
arate category for registering unit operations. PRO/II cannot find a
UAS or its DLL unless it is properly registered. The procedure for
registering a UAUOP is different from the procedure for registering
a UAUTIL. Both procedures are simple, and fully described in
Chapter 2.

Locating User-Added DLL’s

Modular User-added dynamic link libraries (DLL’s) built for
PRO/II may be located anywhere on a network so long as PRO/II
can find and access them. This means the user-added DLL’s do not
need to be located in the same directory tree where PRO/II is
installed. These DLL’s could be located on a different disk drive, or
even a different computer. The operating system of the computer
that stores the DLL’s could be any operating system (such and Unix
or Linix) so long as it supports a Windows-compatible protocol for
calling DLL’s. The full path to the DLL (from PRO/II) must not
exceed 255 characters.
This is different from the requirements for procedural DLL’s dis-
cussed in Building with the Intel Visual Fortran Compiler in Chap-
ter 14.

Program Limits
Every new UAS must be registered with PRO/II before it can be
used. Some benefits of this approach are:
An almost unlimited number of UAUTIL’s and UAUOP’s may be
implemented in PRO/II.
No pre-defined subroutine names. Any subroutine name up to
31 characters is allowed.

1-6 Modular UAS Introduction February 2009

 Implementation is through Dynamic Link Libraries that may be
located anywhere on a computer network (so long as PRO/II
can navigate to them).
There are almost no restrictions on the names of modular
DLL’s (or the subroutines within them). This is possible
because users must “register” each user-added subroutine in a
simple text file. PRO/II dynamically finds and executes the
required subroutines in each DLL as needed, by looking them
up in the “registry” file.
Any number of UAS’s may be included in a single DLL, and any
number of DLL’s may be used. DLL’s all may reside in a single
directory or in separate directories, as the end user chooses.
The only restriction is that the fully justified path to the DLL
should require no more than 255 characters.
There are no limitations on number of components allowed in
new user-added subroutines. In fact, PRO/II passes the number
of components in each simulation to each interface routine in a
user-added DLL. If the DLL requires storage for component
data, it should dynamically allocate that storage based on the
number of components passed to it by PRO/II.

Software Requirements for PRO/II UAS

The hardware and software requirements of modular subroutines
generally are the same as for procedural routines. See Chapter 2,
Modular UAS Build Procedures, and Software Requirements for
PRO/II UAS in Chapter 14.

Compilers and Linkers

Developers integrate user-added subroutines written in Fortran into
PRO/II by creating a custom version of the dynamic link library
UASLB.DLL. To compile and link user-added subroutines into the cur-
rent PC version of PRO/II, use the following compiler:
Intel Visual Fortran version 10.1 or newer (standard or profes-
sional editions). This compiler is compatible with Net 2003 and
Net 2005 architectures.
Important: The Compaq Visual Fortran compiler no longer is com-
patible. Starting with version 8.2, PRO/II is built on the Net 2003
architecture. This change was required to continue delivering new
product versions on the current and future operating systems from
Microsoft Corporation.

PRO/II User-Added Subroutine User Guide 1-7

 Other legacy compilers, such as Lahey Fortran and MicroSoft Pow-
erStation Fortran, also are no longer compatible with current ver-
sions of PRO/II UAS because those compilers are incompatible
with the Net 2003 architecture.

While the recommended compiler is strongly preferred, other

compilers or languages may be used to create a user DLL. The only
real restrictions are:
The compiler must be based upon and compatible with the Net
2003 architecture from Microsoft Corporation. Other compilers
use different storage architectures that are incompatible with
PRO/II. The only sure way to determine compatibility is to try
them out.
The compiler and linker support Fortran 90 data types, modules,
and subroutine calling conventions.

Hardware Requirements for PRO/II UAS

PRO/II is built and certified on Microsoft Windows© operating sys-
tems (OS).
Starting with version 8.2, PRO/II is fully compatible with the
Windows Vista©, the preferred operation system.

Windows XP© and Windows 2000© should pose no problems,

but earlier versions of windows no longer are supported, since
they do not permit the Net 2003 architecture.
The ProVision Graphical User Interface (GUI) does not func-
tion properly on other operating systems, such as Unix.

Adequate dynamic memory is required. Windows Vista© rec-

ommends a minimum of 2 GB but strongly recommends 3 GB
of dynamic memory, which should be adequate to run PRO/II
successfully. PRO/II routinely may use 350 MB or more of
memory.
Hard disks should be no more than about 75% full, and always
should have 2 GB or more of free space to avoid excessive frag-
mentation of the Windows file system.

1-8 Modular UAS Introduction February 2009

Program Limits
Although PRO/II internally has no fixed limits on the number of
components, the classic user-added interface for PRO/II imposes
certain hard restrictions. The limitations shown in Table 1-1 apply.
Table 1-1: PRO/II UAS Limitations
Calculation/Model Component/Variable
Maximum
Classic User-Added 2500 Components in Flowsheet
Calculations1
Classic User-Added Unit IPARM (250)
Operations RPARM (500)
HEAT (10)
SUPPLE (10000)
User-Added Kinetic Models 50 Components in Flowsheet
IPARM (10)
RPARM (70)
SUPPLE (200)
Modular User-Added Dynamic allocation, no fixed
Calculations limits.
1) Except user-added kinetics

Note: For flow sheets containing more than 2500 components,

contact your SIMSCI representative to obtain a version of
PRO/II User-Added Subroutines with an increased compo-
nent maximum. (This is not required for modular user-
added applications.)
Note: For user-added thermodynamic and transport properties,
the TDATA array (and corresponding UDATA statement) is
limited to 2600 entries.
Note: These limits do not apply to the new modular user-added
subroutines described in the first chapters of this Guide.

PRO/II User-Added Subroutine User Guide 1-9

Upgrading Legacy User-Added Subroutines
Starting with version 8.2, PRO/II is based upon the Net 2003 archi-
tecture and no longer is compatible with any earlier versions. All
user-added projects created using PRO/II 8.1 and any earlier ver-
sion must be recompiled and re-built. This must be done using the
new Intel Fortran compiler, version 10.1 or newer, or another com-
piler compatible with the Net 2003 architecture. Follow the direc-
tions in Chapter 2, Modular UAS Build Procedures to perform the
rebuild.

Use of Common Blocks

Note: All newer modular user-added applications use Fortran mod-
ules that provide dynamic data objects to pass all data. No
common blocks are used in these implementations.
If your previous installation of UAS was built on a version earlier
than PRO/II 5.5, please contact your SIMSCI support representative
for information about upgrading your user-added subroutines.
Previous to PRO/II version 5.5, common block definitions were
specified directly in the source code. For example:
COMMON /FACTOR/ TCONVT, TFAC, . . .
Now you need to only specify the name of the INCLUDE file (with
its proper path) that contains the common block of interest. For the
common block /FACTOR/, it suffices to specify:
INCLUDE ‘FACTOR.CMN’
In order to maintain compatibility with the supplied INCLUDE files,
you should ensure that the original common variable names con-
tained in these common blocks have not been modified.
These INCLUDE files are supplied as part of the UAS/PDTS product
in the C:\SIMSCI\PROII82\USER\CMNS directory.
These changes facilitate the creation of DLL versions of user-added
subroutines. These source code modifications are required only
when using a MicroSoft Windows version of PRO/II. User-added
subroutines on other platforms do not require modification.

1-10 Modular UAS Introduction February 2009

 Replacement Source Code
Important: New Intel Visual Fortran solutions and projects replace
the older (now obsolete) workspaces and projects used formerly by
Compaq Visual Fortran. Table 1-2 shows the new solutions and
projects on the left with the corresponding workspaces and projects
they replace on the right.

Table 1-2: Replacement UAS Solutions and Projects

New Code for PROII 8.2 Replaced Obsolete Code

\User\Uas\Examples\IF8\ \User\Uas\Examples\VF6\
UasLb.sln uaslb.DSW
UasLb.vfproj UASLB.dsp

\User\Uas\Examples\Exam1\ \User\Uas\Examples\Exam1\
USER42_IF8.INP USER42.INP
USER42.FOR USER42.FOR
U42OUT_IF8.FOR U42OUT.FOR

\User\Uas\Examples\Exam2\ \User\Uas\Examples\Exam2\
UKHS4.INP identical
UKHS4.FOR identical

\User\Uas\Examples\Exam3\ \User\Uas\Examples\Exam3\
USKIN1.INP identical
USKIN1.FOR identical

\User\Uas\Examples\exam4\ \User\Uas\Examples\exam4\
UTRAN2.INP identical
UTRAN2.FOR identical

\User\Uas\Examples\Exam5\ \User\Uas\Examples\Exam5\
UKHS1.INP identical
UKHS1.FOR identical

\User\Uas\Examples\Exam6\ \User\Uas\Examples\Exam6\
UKHS3.INP identical
UKHS3.FOR identical

\User\Uas\Examples\Exam7\ New solids handling unit opera-

USER57.FOR tion example. No older code to
U57OUT.FOR
replace.

PRO/II User-Added Subroutine User Guide 1-11

 Table 1-2: Replacement UAS Solutions and Projects

New Code for PROII 8.2 Replaced Obsolete Code

\User\Uas\Examples\Exam8\ New example of user-added

ExUkhs7.INP method for water enthalpy. No
ExUkhs7.CHK older code to replace.
UKHS7.FOR

\User\Uas\UasF90\IVF\ \User\Uas\UasF90\VF6\
ExUasF90.sln ExUasF90.dsw
ExUasF90.vfproj ExUasF90.dsp
ExUop.sln ExUop.dsw
ExUop1.vfproj ExUop1.dsp

\User\Uas\UasF90\ \User\Uas\UasF90\
AreaMain.f90 identical RATEFRAC
AreaCalc.f90 identical Interfacial area
AreaRepo.f90 identical utility
MassMain.f90 identical RATEFRAC
MassCalc.f90 identical Mass Transfer
MassRepo.f90 identical utility
HeatMain.f90 identical RATEFRAC
HeatCalc.f90 identical Heat Transfer
HeatRepo.f90 identical utility
Uop1Main.f90 identical
Uop1Cros.f90 identical Modular
Uop1Calc.f90 identical User-Added
Uop1Repo.f90 identical Unit Operation
FluidOut.f90 identical source code
FluidRep.f90 identical
UdmRepo.f90 identical
Ex1Uop.ini identical Modular UaUop
Ex1UopIcon.dat identical configuration
Ex1Uop.xml identical files

1-12 Modular UAS Introduction February 2009

Source Code Changes for Intel Fortran:
PRO/II 8.3 is built with the Intel Fortran compiler. Fortran unit
numbers from a Compaq-compiled library cannot be used by the
executable libraries created by the Intel compiler. For example,
assume a file is opened by an Intel Fortran library using Logical
File unit 10. Then, that file unit number is passed to a subroutine
compiled using the Compaq Fortran compiler. A READ or WRITE
statement using that file unit will fail in the Compaq-compiled
library because the file unit numbers do not match. This is due to
architectural changes in the “.NET” platform (used by the Intel
compiler and PRO/II).
There are at least two cases where PRO/II opens a file and passes
the associated file unit number to a user-added subroutine.
PDTS application: the NFOUT argument returned from the
PAOPEN() subroutine
User-Added Subroutine: IDATA(6) of the USERnn unit operation
subroutine.
In both cases, PRO/II calls the intrinsic Fortran OPEN function, then
passes the unit number a user-added subroutine. Applications built
using the Intel Fortran compiler cannot directly use this Fortran unit
number in a WRITE statement. Instead, the utility subroutine PAWRITE
has been provided to allow your application to write output to the
file. The following code fragments illustrate the required changes:
Original PDTS example that may fail:
CHARACTER(LEN=16) :: NAME
INTEGER(4) :: NFOUT
. . .
CALL PAOPEN( NAME, " ", NFOUT, IRCODE )
1001 FORMAT( A )
WRITE( NFOUT, 1001 ) “This Write FAILS”

PDTS example modified for Intel Fortran inter-operation with

Compaq Fortran:
CHARACTER(LEN=16) :: NAME
INTEGER(4) :: NFOUT
CHARACTER(LEN=78) :: cLine
. . .
1001 FORMAT( A )
. . .
CALL PAOPEN (NAME, " ", NFOUT, IRCODE)

PRO/II User-Added Subroutine User Guide 1-13

 cLine = "This fixes the problem"
CALL PAWRITE( NFOUT, cLine )

Original UAS example that may fail:

SUBROUTINE USER42( IPARM, RPARM, SUPPLE,
& HEAT, IDATA, ISOLVE, ISTOP )
. . .
INTEGER(4), INTENT(IN) :: IDATA( 30 )
INTEGER(4) :: NFOUT
1001 FORMAT( A )
. . .
IOUT = IDATA(6)
WRITE( NFOUT, 1001 ) “This may FAIL”

UAS example modified for Intel Fortran inter-operation with

Compaq Fortran:
SUBROUTINE USER42( IPARM, RPARM, SUPPLE,
& HEAT, IDATA, ISOLVE, ISTOP )
. . .
INTEGER(4), INTENT(IN) :: IDATA( 30 )
CHARACTER(LEN=78) :: cLine
. . .
cLine = "This fixes the problem"
CALL PAWRITE( NFOUT, cLine )

Note: To open a file not used by PRO/II, call subroutine FIGETU

to obtain a Fortran unit number from PRO/II. Then call the
Fortran OPEN() function directly from the user-added sub-
routine. This approach eliminates the need for any code
changes to the READ or WRITE statements. The reason is that
the OPEN, READ, and WRITE calls are executed under the
same architecture, so the discontinuities discussed above
do not apply.

1-14 Modular UAS Introduction February 2009

 Chapter 2
Modular UAS Build Procedures
Overview
When PRO/II is installed by a user, the Setup Wizard provides an
option to install the sample user-added subroutines. When selected,
this option copies all the necessary source code and sample projects
to the hard drive of the computer. However, the sample modular
subroutines must be built and registered (by the user) before they
can be used by PRO/II.
A developer writes user-added subroutine code, builds executable
dynamic link libraries (DLL’s), and delivers them to users. Once
again, users are the ones who must install and register the subrou-
tines before they can be used by PRO/II.
In both of these scenarios, it is the responsibility of users to
install (or build) the DLL’s and register the modular subrou-
tines so PRO/II can use them.

User Information
This chapter explains the steps required to build, register, and use
modular subroutines in PRO/II. It uses a sample project that ships
with PRO/II to illustrate the procedures. Users are encouraged to
use the sample projects to develop their own modular subroutines.
Specific details of writing new user-added subroutines do not
appear here. That information is available elsewhere in this manual.
Separate chapters describe each individual type of UAUTIL and
UAUOP subroutine.

All the examples use Microsoft Visual Studio© for NET 2003 and
Intel Visual Fortran© version 10.1. Developers are expected to be
familiar with these tools; this manual does not describe them fur-
ther.
The procedure for building modular utility subroutines (UAUTIL) is
identical to the procedure for building modular unit operations
(UAUOP). In both cases, source code is processed to create a
dynamic link library. A single DLL may contain both types of user-
added subroutines.

PRO/II User-Added Subroutine User Guide 2-1

 Building A UAS DLL Using Visual Studio .NET 2003
Building a dynamic link library involves two major phases:
1. Compiling. The source code of all routines in the library is pro-
cessed to create relocatable binary object files.
2. Linking. The object files are passed into a linker that creates the
executable DLL.
Both of these functions are performed by using the Build command
in Microsoft Visual Studio for NET 2003.
The PRO/II Installation Disk includes a sample UAUTIL project that
includes subroutines for computing interfacial area, binary mass
transfer coefficients, and heat transfer. This discussion uses that
project to demonstrate the build process.

Note: These instructions assume the sample project was installed

in the default directory structure. For PRO/II version 8.3,
this directory is:
C:\SIMSCI\PROII82\USER\UAS\UASF90\IVF
The source code is located in:
C:\SIMSCI\PROII82\USER\UAS\UASF90\
Modify the paths for this example if the sample code was installed
in a different directory. To build other projects, modify the file
names as needed.
Start Intel Visual Fortran version 10.1 (or later version) by
opening Visual Studio .NET 2003.
Select File/Open Solution from the menu bar.
Select the file:
\SIMCI\PROII82\USER\UAS\UASF90\IVF\EXUASF90.SLN,
then click OK.
Be sure the Solution Explorer pane is open. If not, select View/
Solution Explorer from the menu bar.
Expand the Source Files directory under the ExUasF90 project in
the Solution Explorer pane. All the member files for the project
are listed in the Source Files directory, as shown in Figure 2-1.

2-2 Modular UAS Build Procedures February 2009

 Figure 2-1: Visual Studio Solution Explorer

To add files to the project, right-click the Source Files folder

icon to display a pop-up action menu; then select Add from the
action menu for more options. To view source code, simply
double-click any of the .f90 files in the list of source files.
Ensure the “active configuration” is Release on the standard
tool bar. See Figure 2-2, “Setting the Project Configuration to
Release.”
Figure 2-2: Setting the Project Configuration to Release.

PRO/II User-Added Subroutine User Guide 2-3

 Compile and link the entire project.
In the Solution Explorer, right-click the ExUasF90 project. From
the action menu that opens, highlight Project Only; then click
Rebuild Only Project, as shown in Figure 2-3.
Figure 2-3: Building A Project

When the “active configuration” is Release, the executable

DLL is created in:
\SIMSCI\PROII82\USER\UAS\UASF90\IVF\RELEASE\
When the “active configuration” is Debug, the executable DLL
is created in:
\SIMSCI\PROII82\USER\UAS\UASF90\IVF\DEBUG\
Note: PRO/II does not provide any debug libraries, so any debug-
ging activity is limited to the User-Added project.

2-4 Modular UAS Build Procedures February 2009

 Registering a UAS with PRO/II
Before PRO/II can use a modular user-added subroutine, it must be
registered so that PRO/II can access it. Registering subroutines
enables PRO/II to dynamically locate and call them on demand.
Only the newer modular user-added subroutines can be registered.
Because the older procedural subroutines are installed in pre-
defined locations, there is no need to register them.
Subroutine registration is a simple procedure that involves modify-
ing one plain-text file.

Editing the Registration File

The registration file named P2UasReg.ini is located in the SYSTEM
sub-directory where PRO/II is installed. For a default installation of
PRO/II, the full path to this file is:
C:\SIMSCI\PROII82\SYSTEM\P2UASREG.INI
This may be different on machines that installed PRO/II using some
of the custom installation options.

Syntax in P2UasReg
Note: When modifying the registration file to include a new user-
added subroutine, use only a plain-text editor, such as
Notepad or the Visual Studio editor. Do not use a word pro-
cessor which inserts hidden codes that invalidate the entire
registration file.
The P2UasReg.ini file is divided into sections based upon the func-
tional types of user-added subroutines supported by PRO/II.
Section headers are enclosed in square brackets; for example,
[UAUOP] is the header of the section where unit operations are
registered.
The various types of user-added subroutine must be registered
within the appropriate section of the file.
A semicolon (;) is a comment character. Everything to the right
of a semicolon is ignored by the processor.
A Tilde (~) is a place-holder that indicates no entry in a field.
Since entries on each line are position dependent, tildes are
required to indicate where an entry is omitted.
Entries that include embedded blanks must be enclosed in quo-
tation marks.

PRO/II User-Added Subroutine User Guide 2-5

 Character entries are not case-sensitive. For example, “EX1UOP”
and “Ex1uop” are equivalent.
Do not use “tabs” to space entries. Instead, use one or more
space characters to separate entries.
Each of the following sub-sections discusses one section of the reg-
istration file. Edited examples of parts of the P2UasReg.ini file illus-
trate correct usage. The actual file shipped with PRO/II includes
wider fields and additional comments not shown here.

Registering User-Added Utilities

PRO/II currently supports three types of user-added utility subrou-
tines: Interfacial Area, Mass Transfer, and Heat Transfer. When the
PRO/II setup program installs user-added subroutines, it includes
one example of each type of UAUTIL they are registered in different
sections of the P2UasReg.ini file. Table 2-1 shows the relationships of
the utility types to sections in the P2UasReg.ini file.
Table 2-1: Utility Type Sections in the Registration File
Utility type Register In Section
Interfacial Area [UAIFAREA]
Mass Transfer [UAMASSTR]
Heat Transfer [UAHEATTR]

As shown below, the registration file contains a separate section for

each supported type of UAUTIL subroutine. It is important to register
utility subroutines in the correct section so that PRO/II can locate
and call them.
;[UAIAREA] UOM
UAS identifier PathNo DLL name UAS routine System
; -------------- ------ -------------- ----------- ------
"IFAREAUas1" 4 "ExUasF90.dll" "AreaMain" Proii
;
[UAMASSTR] UOM
; UAS identifier PathNo DLL name UAS routine System
; -------------- ------ -------------- ----------- ------
"MassTranUas1" 4 "ExUasF90.dll" "MassMain" Proii
;
[UAHEATTR] UOM
; UAS identifier PathNo DLL name UAS routine System
; -------------- ------ -------------- ----------- ------
"HeatTranUas1" 4 "ExUasF90.dll" “HeatMain" Proii
where:

2-6 Modular UAS Build Procedures February 2009

 UAS Identifier Enter a text string that uniquely identifies the utility
subroutine. The identifier is a required entry, and must not
duplicate any other identifier in the same section. It may
contain up to 31 characters. The first character must be a
letter, A through Z. The sample above assigns “IFAREAUas1”
as the identifier of an interfacial area utility.
The UAS Identifier is used by keyword input and PROVISION to
select this utility. See “Using a User-Added Modular Utility in
PRO/II” on page 2-14 for examples of keyword usage.
PathNo This specifies the path to the directory where the DLL that
contains the subroutine is installed. Enter a path ID number
from the [UASPATH] section of the registration file. See
“Registering a Path to a User-Added DLL” on page 2-9 of
this chapter to learn about adding path entries.
DLL name The exact name of the dynamic link library that contains
the user-added utility subroutine. The access functions of
the operating system are case sensitive, so it is important
that the name of the DLL and this ID always exactly agree.
The recommended convention is to enter the DLL name
and the ID in all upper case characters. Each ID may con-
tain up to 31 characters.
UAS routineThe exact name of the interface subroutine that PRO/II
calls to access this utility. The interface routine must be in
the DLL specified by the DLL NAME entry. Each ID may
contain up to 31 characters.
UOM systemEnter one of the key words from Table 2-2 to specify
the system of dimensional units used for data transfer.
PRO/II delivers all input data in the specified dimensional
units system. It also expects all results to return using the
same system of dimensional units. No mixing of systems of
units is allowed.
Table 2-2: Systems of Dimensional Units for Data Transfer
Keyword System of Units
PROII PRO/II internal units
ENGLISH English units
METRIC Metric system units
SI System International

PRO/II User-Added Subroutine User Guide 2-7

 Refer to Table 4-1 of the PRO/II Keyword Manual for a list of
dimensional units used in each of these systems.

Example:
This example registers a Mass Transfer utility routine using the
identifier MyMassTr1. Assume the name of the callable interface
routine is MYMASS1, the DLL named MYUAS1.DLL is located in
directory E:\MYDRIVE\MYCODE\, and that this path already is reg-
istered as path 5 in the [UASPATH] section of the registration file.
Data transfer uses the SI system of units.
[UASPATH]
; PathNo Fully justified path (255 characters maximum)
; ------ ----------------------------------------------------
1 "%p2Install%\USER\UAS\EXAMPLES\"
2 "%p2Install%\USER\"
3 "%p2InstallPath%\SYSTEM\"
4 "%p2Install%\USER\UAS\F90\IVF\Debug\"
5 “E:\MYDRIVE\MYCODE\”
. . .
[UAMASSTR] UOM
; UAS identifier PathNo DLL name UAS routine System
; -------------- ------ -------------- ----------- ------
"MassTranUas1" 4 "ExUasF90.dll" "MassMain" Proii
“MyMassTr1” 5 “MYUAS1.DLL” “MYMASS1” SI

The procedure for registering other utility subroutines is analogous

to this example. Simply substitute the appropriate section of the
registration file for the type of utility. Register an Interfacial Area
utility in the [UAIFAREA] section instead of the [UAMASSTR] section.
Register a heat transfer utility in the [UAHEATTR] section.

2-8 Modular UAS Build Procedures February 2009

 Registering a Path to a User-Added DLL
A path allows PRO/II to access a user-added DLL anywhere on the
computer network. The [UASPATH] section declares the location of
all the directories that PRO/II uses to find user-added dynamic link
libraries. PRO/II pre-defines several paths that developers may use
to store their DLL’s, as shown.
[UASPATH]
; PathNo Fully justified path (255 char max)
; ------ ------------------------------------
1 "%p2Install%\USER\UAS\EXAMPLES\"
2 "%p2Install%\USER\"
3 "%p2InstallPath%\SYSTEM\"
4 "%p2Install%\USER\UAS\F90\VF6\Debug\"
where:
PathNo A unique integer number that identifies the path. The PathNo
entries in other sections refer to this to register user-added
utility routines. Numbering should be sequential, beginning
with the first available (unused) path number. This is a
required entry.
Path text The fully justified path to a directory used to store DLL’s.
Always enclose the path text in quotation marks to allow
embedded blanks. The path may contain as many as 255
characters, including embedded blanks.

Note: The path does not include the name of the DLL file. It ter-
minates with the name of the directory that contains the
DLL. Paths already registered during PRO/II installation
should not be deleted or altered in any manner.
“%p2Install%” is a parameter that expands to be the root directory
where PRO/II is installed. It is defined in the [P2Config] sec-
tion of the PRO/II configuration file PROII.INI.
The PROII.INI file is located in the installed USER directory. This
makes the parameter configurable by each end-user. In a
default installation of PRO/II version 8.3, the full path and file-
name of the PRO/II configuration file is:
C:\SIMSCI\PROII82\USER\PROII.INI
In this file, the parameter is defined as:
P2Install=D:\SIMSCI\PROII82\
Changing the value of the P2Install parameter in the PROII.INI file
dynamically changes the path of the%p2Install% expansion macro.

PRO/II User-Added Subroutine User Guide 2-9

 Use of this macro is optional. It could be replaced by the actual text
of the installed path.
The PathNo entries in other sections of the registration file refer to
entries in the [UASPATH] section. The PathNo entries for user-added
utilities (described earlier) refer to the paths in the [UASPATH] sec-
tion. To locate DLL’s elsewhere, a new path must be added to the
[UASPATH] section.

Note: Unit operations do not refer to the [UASPATH] section. Each

of them has its own configuration (INI) file that includes the
path declaration.

Example:
A developer wishes to add directory path “E:\MyDrive\MyCode” to
the registration file. Assuming the first four paths (shown
above) already exist in the registration file, the new path is
installed as path 5.
[UASPATH]
; PathNo Fully justified path (255 char max)
; ------ ------------------------------------
1 "%p2Install%\USER\UAS\EXAMPLES\"
2 "%p2Install%\USER\"
3 "%p2InstallPath%\SYSTEM\"
4 "%p2Install%\USER\UAS\F90\VF6\Debug\"
5 “E:\MYDRIVE\MYCODE\”

2-10 Modular UAS Build Procedures February 2009

 Registering [UAUOP] User-Added Unit Operations
Register all modular user-added unit operations in the [UAUOP] sec-
tion of the registration file. Entries in this section include:
; ============================================================
; Enter User-Added Unit Operations in the [UAUOP] section
[UAUOP]
; IdNo UATYPE INI File Name Help File Name Help Context
;------ ---------- -------------- --------------- ------------
1 “Ex1Uop” Ex1Uop.ini ~ ~
where:
IdNo This is a unique ID number that identifies the user-added unit
operation. It is a required entry, and must have a value in
the range of 1 through 9999. The sample above assigns a
value of 1.
UATYPE Enter a text string that uniquely identifies the unit opera-
tion. This identifier is a required entry, and must not dupli-
cate any other UATYPE entry in the [UAUOP] section. The
first character must be a letter, A through Z. The sample
code above assigns “Ex1Uop” in the UATYPE column. The
quotation marks are required when the identifier contains
embedded spaces. It usually is more reliable to avoid using
embedded spaces in the identifier itself.
This entry is used by keyword input and PROVISION‰ to
select this unit operation. For example, keyword input would
use the following statement to add this unit operation to a simu-
lation:
UAUOP( Ex1Uop ) UID= U1
This identifier (i.e., “Ex1Uop”) also appears in the list of available
user-added unit operations in PROVISION‰.
INI File Name This is the name of the initialization file that defines
the access and data content of the unit operation. Refer to
the Chapter 5, Modular Unit Operations, for information
about the INI file. While this entry is optional, omitting it
eliminates many powerful features, including the ability to
define the data structure, and the ability to relocate the
DLL.
Help File Name Optional, and not fully supported by PRO/II. For
now, always enter a tilde (~) for this entry.

PRO/II User-Added Subroutine User Guide 2-11

 Help Content Declares the “home” help topic in the user-added help
file. This is not supported in PRO/II version. For now,
always enter a tilde (~) for this entry.

Example:
When first installed, the [UAUOP] section contains only the
Ex1Uop entry, as shown above. Assume a developer wishes to
register a new user-added unit operation with an ID number of
123 and a UATYPE of ABC. Also assume it has an “INI” file named
“ABC.INI”. After registering this unit operation, the [UAUOP] sec-
tion would include the following information.
; ==============================================================
; Enter User-Added Unit Operations in the [UAUOP] section
[UAUOP]
; IdNo UATYPE INI File Name Help File Name Help Context
; ------ ---------- ------------- -------------- ------------
1 “Ex1Uop” Ex1Uop.ini ~ ~
123 “ABC” ABC.INI ~ ~

Reserved Sections - [P2UOP]

The [P2UOP] section is reserved for use by SIMSCI“. It typically
includes the following entries, but is not discussed further.
======================================================
; Invensys/SIMSCI User-Added Unit Ops. 3rd party
; developers should never alter the [P2UOP] section.
[P2UOP]
; IdNo UATYPE INI File Help File Help Topic
;------ --------- ----------- --------- ----------
10001 "FURNACE" FURNACE.INI ~ ~
10002 "ACE" ACE.INI ~ ~
10003 "PPUOP" PPUOP.INI ~ ~

Note: Users and third-party developers should never modify the

entries in this section.

2-12 Modular UAS Build Procedures February 2009

 Troubleshooting Registration Errors
PRO/II fails when attempting to call a user-added utility subroutine
not properly registered in the P2UasReg.ini file. In such cases, PRO/II
generates an error message that reports the failure. The message
reports the faulty path in the [UASPath] section.
To fix the problem, the user could correct the faulty entries in the
P2UasReg.ini file. The problem may be due to a faulty DLL path,
DLL name, or subroutine name. Alternatively, the user could move
the DLL or the subroutine name to match the P2UasReg.ini file.
Always ensure the UAS is registered in the correction section of the
registration file.
For example, assume the sample UAS project (shipped with
PRO/II) installs the DLL named EXUASF90.DLL in the path:
C:\SIMSCI\PROII71\USER\UAS\UASF90\IVF\RELEASE\
Assume the path and DLL name in the P2UasReg.ini file are erro-
neous, as in:
EXUBASF90.DLL (misspelled DLL name)
C:\SIMSCI\PROII82\USER\UAS\UASF90\IVF\RELEASE\
PRO/II fails when calling a subroutine in this DLL, and issues the
following error message:
*** ERROR *** Located but FAILED to load user-
supplied UAS DLL from path
C:\SIMSCI\PROII82\USER\UASF90\VF6\
RELEASE\EXUBASF90.DLL.
Please ensure the entry is correct in the
UAS registry (P2UasReg.ini).
The user should determine the actual location of the installed DLL
on the hard drive. Comparing the actual location and name with the
error message reveals the two errors (highlighted for emphasis). It
is then a simple matter to correct the P2UasReg.ini file.

PRO/II User-Added Subroutine User Guide 2-13

 Using a User-Added Modular Utility in PRO/II
This discussion assumes a user-added DLL is built and the callable
subroutines are properly registered in the PRO/II UAS registration
file, P2UasReg.ini. Refer to topics earlier in this chapter. A detailed
presentation of using the interfacial area utility is presented here.
Discussion of the mass transfer and heat transfer utilities is mini-
mal, since their usage is analogous to that of the interfacial area util-
ity.

Using An Interfacial Area Utility – End Users

This utility was first available in PRO/II version 7.1. It is used only
by the RATEFRAC algorithm of the COLUMN model in PRO/II.
Because PRO/II includes built-in correlations for computing inter-
facial area, use of this user-added feature always is optional. Refer
to Chapter 12.10 of the PRO/II Keyword Input Manual for informa-
tion about the RATEFRAC algorithm and the RFTRANSFER statement.
Before PRO/II can use a user-added interfacial area subroutine, the
subroutine must be installed and registered. Because third-party
developers supply the subroutines, SIMSCI has no control over
them, and cannot be responsible for ensuring their quality or com-
patibility with PRO/II. End users must install the user-added sub-
routine according to the directions supplied by the developer or
supplier. SIMSCI cannot offer further guidance concerning subrou-
tine installation.
After installation, the end user must register the subroutine in the
P2UasReg.ini file. Refer to Registering User-Added Utilities earlier in
this chapter for instructions.
The RFTRANSFER statement of the COLUMN model in PRO/II allows
users to select an interfacial area user-added subroutine. It has the
following form:
RFTRANSFER IASUB=
The argument iaSubID of the IASUB keyword specifies a user-added
subroutine that performs interfacial area calculations. Any subrou-
tine registered in the [UAIFAREA] section of the P2UasReg.ini file is
available as the argument for the IASUB keyword.

Using the Sample Interfacial Area Utility

As delivered, PRO/II includes a working sample of an interfacial
area utility that demonstrates a working interfacial area utility. The

2-14 Modular UAS Build Procedures February 2009

 correlations included in the sample utility are not adequate for all
column configurations supported by RATEFRAC.

Note: The sample code shipped with PRO/II is part of sample

projects that must be built before executing. Refer to
“Building A UAS DLL Using Visual Studio .NET 2003” in
this chapter to learn how to build and use sample projects.
A Fortran compiler and linker are required.
The following input listing includes an RFTRANSFER statement that
uses the sample code for computing interfacial area, binary mass
transfer coefficients, and heat transfer. It is a complete input file,
and should solve successfully.

TITLE PROJ=IFAreaUAS, PROB=SampleIFA1

DESC Demonstrate An Interfacial Area UAS Using RateFrac
DIMENSION ENGLISH
COMPONENT DATA
LIBID 1,METHANOL / 2,WATER / 3,ETHANOL / &
4,PROPANOL / 5,BUTANOL / 6,NITROGEN
THERMODYNAMIC DATA
METHOD SYSTEM=WILSON, TRANSPORT=PURE
STREAM DATA
PROP STRM=FEED, PHASE=L, PRES=15, RATE(WT)=1000 &
COMP(M)= 1,0.4/ 2,0.2/ 3,0.2/ 4,0.1/ 5,0.10/ 6,0.0
PROP STRM=GAS, TEMP=200, PRES=20, RATE(WT)=1000 &
COMP(M) = 6,1.0
UNIT OPERATIONS
COLUMN UID=T1, NAME=10 TRAY ABS
PARAM TRAY=10, RATEFRAC=15
FEED FEED,1 / GAS,10
TRATE SECTION(1)=1,4, CAP, DIAMETER(FT)=4, WEIR=2
TRATE SECTION(2)=5,7, CAP, DIAMETER(FT)=4, WEIR=2
TRATE SECTION(3)=8,10, CAP, DIAMETER(FT)=4, WEIR=2
PRODUCT OVHD(WT)=OVHD, 1000, BTMS(WT)=BTMS, 1000
TEMP 1, 175 / 10,200
PRES 1, 15.0 / 10,16.0

$ Comment the next 3 lines to use internal correlations

RFTRANSFER HTSUB=HeatTranUas1, SECTION=2, &

IASUB=IFAREAUas1, &
MTSUB= MassTranUas1

Notice in the input listing that the column includes three TRATE sec-
tions. The RFTRANSFER statement applies the user-added subrou-
tines only to TRATE section 2. Additional RFTRANSFER statements
may be added for each section in the column.

PRO/II User-Added Subroutine User Guide 2-15

 Also in the input listing above, the sample interfacial area subrou-
tine supplied by SIMSCI has the identifier IFAREAUas1. This can be
changed to any other desired identifier that is registered (“Register-
ing User-Added Utilities” on page 2-6.
Edit the ID entry in P2UasReg.ini (only the ID entry).
Change the RFTRANSFER IASUB=iaSubID entry in the input file so
that iaSubID matches the new identifier.
As long as the DLL path, DLL name, and subroutine entries remain
unchanged, the sample will run successfully.
The problem could be modified to use the built-in correlations in
PRO/II by deleting or commenting the three lines of code for the
RFTRANSFER statement. Comparing the results of the problem with
and without using the user-added subroutines should demonstrate
the two solutions agree to three or four significant digits.

Using A Mass Transfer Utility

Use of this utility is analogous to the usage of the interfacial area
utility. Because PRO/II includes built-in correlations for computing
the binary mass transfer coefficients, use of this user-added feature
is always optional. Refer to Chapter 12.10 of the PRO/II Keyword
Input Manual for information about the RATEFRAC algorithm and
the RFTRANSFER statement.
Using A Heat Transfer Utility
Use of this utility is analogous to the usage of the interfacial area
utility. Because PRO/II includes built-in correlations for computing
the heat transfer, use of this user-added feature always is optional.
Refer to Chapter 12.10 of the PRO/II Keyword Input Manual for
information about the RATEFRAC algorithm and the RFTRANSFER
statement.

2-16 Modular UAS Build Procedures February 2009

Developer Information
This section presents useful information to developers writing their
own modular user-added subroutines. The requirements and avail-
able resources for a utility calculation routine are different from
those of a unit operation. Separate outlines are presented for each of
them.

Contexts in PRO/II
PRO/II performs a variety of operations to successfully complete a
simulation. Related types of operations are grouped together in con-
texts. When PRO/II calls a user-added subroutine, it expects each
UAUTIL or UAUOP to perform actions appropriate to the current
context, as illustrated in Table 2-3. Yes indicates that PRO/II makes
a call to a UAUTIL or UAUOP. No indicates that PRO/II does not
attempt to call the UAUTIL or UAUOP in that context.

Table 2-3: Contexts in PRO/II

Context UAUTIL UAUOP Description Need
INPUT No No Initialize input data (file or Optional
GUI)
CROSSCHECK No Yes Input data verification Optional

CALCULATE Yes Yes Perform calculations Required

OPCALC No Yes Calculate after flowsheet solved Optional

REPORT No Yes Write results to output file Optional

The column of the table titled “Context” lists the exact text of the
context strings. PRO/II passes the context as data member %Context
in the data object argument of the subroutine call. (The context also is passed
as a separate argument in the call list of a UAUOP.) The portion of
the context string in bold type is the minimum character string to
use for testing the context. For example, the first five characters of
context could be tested against literal string CROSS to identify the
CROSSCHECK context; e.g.,

IF( DataObj%Context(1:5) .EQ. “CROSS” ) THEN

Optionally, up to all ten characters in the string could be tested; e.g.,
IF( DataObj%Context(1:10) .EQ. “CROSSCHECK” ) THEN
When performing tests on text strings, always use upper case char-
acters only. Note that Fortran 90 uses a percent sign ( % ) as the
“member selection” operator.

PRO/II User-Added Subroutine User Guide 2-17

 As shown in Table 2-3, PRO/II calls a UAUTIL only during the CAL-
CULATE context. In other words, the user-added utility code must
perform calculations on request. In contrast, PRO/II expects a user-
added unit operation to support all contexts except INPUT.
Note that the only code requirement is to return a valid ISOLVE flag
to PRO/II, even for the CALCULATE context. For example, returning
ISOLVE = 0 informs PRO/II that the UAS did not perform any
actions. In such cases, PRO/II executes alternative code, or issues
error messages, as appropriate.

ISOLVE Return Values

Whenever PRO/II calls a UAUTIL or UAUOP, it requires the called
routine to perform specific actions and to return specific data. This
is true regardless of the context in which PRO/II makes the call.
PRO/II does not always require return values from a utility routine
in every context. However, it always requires a valid return value
for ISOLVE. For example, a utility routine normally returns all results
in the array DataObj%RESULTS. However, these may be omitted if the
utility returns ISOLVE=0 or 3. Table 2-4 explains the valid return val-
ues that PRO/II accepts in every context.
Table 2-4: ISOLVE Values returned from a UAS
ISOLVE Description
Returns
0 UAS performed no action, PRO/II attempts to
continue. No returned results expected.
1 UAS successfully completed processing, PRO/II
continues normally. Returned results required.
2 UAS Failed – PRO/II continues flowsheet execution.
Returned results required.
3 UAS Failed – PRO/II terminates (flowsheet
execution). No returned results expected.

The “expected” return code in all contests is DATAOBJ%ISOLVE = 1.

Values of 2 or 3 always indicate an error condition. When a UAS
does not support a context, it should return DATAOBJ%ISOLVE = 0 to
indicate “no action taken”.
The meaning of ISOLVE codes 0 and 1 should be obvious. However,
the distinction between ISOLVE codes 2 and 3 is more subtle. Typi-
cally, a return value of DATAOBJ%ISOLVE = 2 indicates a convergence
problem. The UAS completes calculations and returns results, but
the results may not be converged within tolerance. For example,

2-18 Modular UAS Build Procedures February 2009

 this frequently occurs in early iterations of recycle problems that
require several cycles to build up flow rates to meet the overall con-
vergence criteria. An ISOLVE = 2 error is non-fatal if it occurs on any
pass through the UAS, except the last pass. It allows PRO/II to con-
tinue the (iterative) calculations. If the ISOLVE = 2 error occurs on the
last pass through the UAS, it causes PRO/II to report, “Solution not
reached.”

The ISOLVE = 3 error always is fatal. UAS developers should return

this code when the UAS encounters a problem that prevents it from
performing its calculations. Typically, these situations occur when
data is missing or invalid. When PRO/II receives this return code, it
immediately terminates all flowsheet calculations, and results in
“solution not reached”. Later chapters that discuss each specific util-
ity or unit operation may expand these definitions.

Writing A Modular Utility (UAUTIL)

Follow these steps to create a user-added utility calculation module
(UAUTIL). Examples of user-added utilities include Interfacial Area,
Binary Mass Transfer, and Heat Transfer subroutines. Do not use
this procedure for a user-added unit operation (UAUOP).
1. Read the appropriate chapter of this manual for the UAUTIL of
interest. Determine the input data available from PRO/II, and
the results that return to PRO/II in the RESULTS array. (not
required when building a sample project).
2. Use one of the sample interface routines (AreaMain.f90, Mass-
Main.f90, or HeatMain.f90) as a template for the interface routine.
Use class_ UASOBJ as the only argument in the call list.
3. Code the calculation algorithm in Fortran 90.
Access available PRO/II data from the class_UASOBJ storage
object.
Perform calculations.
Store the required results in the RESULTS array of the
class_UASOBJ storage object.
Set the ISOLVE flag in the class_UASOBJ storage object.
4. Compile and Link the DLL.

PRO/II User-Added Subroutine User Guide 2-19

 5. Register the subroutine and DLL in the PRO/II P2UasReg.ini file.
Remember that each type of UAUTIL must be registered in the
appropriate section of the registry file.
The UAS now should be ready for use by PRO/II.

Resources for Modular Utility Calculation Routines

Each type of user-added utility may require the use of a different set
of PRO/II interfaces. Any departures from the requirements listed
here are presented in later chapters that discuss specific types of
user-added utility routines. Generally, the various calculation utili-
ties require following PRO/II resources:
class_UASOBJ.mod A Fortran 90 module that contains the
explicit interface for the UAUTIL data storage object. All
available PRO/II data is passed to the utility as a single
argument in the call. Similarly, all results from the utility
are returned to PRO/II through the RESULTS array of this
module.

Writing a Modular Unit Operation (UAUOP)

Follow these steps to create a user-added unit operation (a
UAUOP). Do not use this for a user-added utility calculation sub-
routine (UAS).
1. Read the appropriate chapters of this manual that describes the
structure of a user-added unit operation.
2. Map out the data structure for the UAUOP, and create an “.INI”
file that defines this structure. Be sure to map storage for user
input data and for results in the INT, PAR, and DBL arrays.
3. Code the calculation algorithm in Fortran 90.
Access available PRO/II data using the available PRO/II
interface routines, including component, stream, and unit
operation data.
Perform calculations.
Store the required results in the appropriate members of the
data structure.
Set the ISOLVE flag in the data structure.
If desired, code other related subroutines, such as an “Out-
put Report” subroutine, a GUI routine for input processing,

2-20 Modular UAS Build Procedures February 2009

 a “Cross Check” routine for input data verification, and an
“Output Review” GUI window.
4. Compile and Link the DLL.
5. Add the DLL and subroutine access data to the “[Access Data]”
section of the “.INI” file.
6. Register the “.INI” in the “[UAUOP]” section of the PRO/II regis-
try file.
The UAUOP now should be ready for use by PRO/II.

Resources for Modular User-Added Unit Operations

class_UaUop.mod This Fortran 90 module contains the explicit
interface for the unit operation data storage object. The
majority of available PRO/II data is passed to the unit oper-
ation as one of the arguments in the call. Similarly, all
results from the unit operation return to PRO/II through the
INT, PAR, and DBL arrays of this module.

xxxx.INI The INI file of a UAUOP defines all the attributes of the
unit operation that are exposed to PRO/II. The developer of
the UAUOP must write this file. This process is described in
a separate chapter.
xxxxUOPIcon.DAT An optional file that defines the properties of
the icon used in the PROVISION‰ PFD window to repre-
sent the user-added unit operation. The developer of a user-
added unit operation also creates this file. It is described in
a separate chapter.
xxxx.XML An optional file that defines the properties and behavior
of a custom input window for the unit operation. It is used
in conjunction with the xxxxUOPIcon.DAT file. The devel-
oper of a user-added unit operation also creates this file.

PRO/II User-Added Subroutine User Guide 2-21

 Resources for All Modular User-Added Subroutines
class_Fluid.mod A Fortran 90 module that contains the explicit
interface for the user-accessible analog of a PRO/II stream.
This is used by class_UASOBJ.mod to store data for a single
stream. Access to data in this module normally is through
members of class_UASOBJ.
Class_FluidPhase.mod A Fortran 90 module that contains the
explicit interface for a single phase of a stream. This is used
by class_Fluid.mod. Access to data in this module normally is
through members of class_UASOBJ.
The modules listed above are required by the compiler when the
user compiles the source code for the UAS. These are provided to
you by PRO/II. The path to them must be included in the UAS
project.
UserLb6.LIB This is the “export library” for UserLb6.DLL, the
Dynamic Link Library (DLL) containing code for the mod-
ules listed above. It also contains the code for “callback
interfaces” used by modular user-added subroutines to call
PRO/II. This library is required by the linker when building
the UAS DLL project. In a default installation, it is avail-
able in the .\User\LIBS\ directory.

2-22 Modular UAS Build Procedures February 2009

 Compiler and Linker Project Settings
Projects that build user-added subroutines use resources installed
with PRO/II. The necessary Fortran modules and libraries must be
installed using the PRO/II installation (or Setup) program on the
PRO/II installation disk. Selecting the User-Added Subroutines
option will copy all the necessary files to directories in the PRO/II
directory tree.
The settings for the compiler and linker must include paths to the
directories that include these SIMSCI resource files. All the neces-
sary settings already are configured in the sample user-added
projects. However, developers who create their own projects must
include the proper paths to these resource files. This section dis-
cusses those settings.

Setting the Module Path for the Fortran Compiler

Fortran modules are templates that define the data structures and
interface routines available to modular user-added subroutines.
The include option specifies a directory to add to the path that is
searched for module files referenced in USE statements, in addition
to files referenced using INCLUDE statements. For all USE statements,
the directories searched are as follows, in this order:
1. The directory containing the first source file (assuming default
settings).
2. The current default directory where the compilation is taking
place.
3. If specified, the directories listed in the INCLUDE option.
The order of searching multiple directories occurs within
the specified list from left to right.
4. Directories indicated by the INCLUDE environment variable.
Follow these steps to set the module path in MicroSoft Visual
Studio. Refer to Figure 2-4
In the Solution Explorer, right click the project and select Prop-
erties from the action menu; then open the Fortran tab.

PRO/II User-Added Subroutine User Guide 2-23

Figure 2-4: Setting the Fortran USE Module Path

Click the down arrow of the Category: list box and highlight
PreProcessor in the list. Enter the following text in the Addi-
tional Include Directories text box:
C:\SIMSCI\PROII82\USER\CMNS
This is the absolute path from the project directory where the
modules are installed.
Click OK to confirm the setting.
When the project is in the default PRO/II install directory path,
a relative path may be used. Refer to Figure 2-4, “Setting the
Fortran USE Module Path”, on page 2-24.

Setting the Import Library Path for the Linker

USERLB6.LIB is an export library that includes the templates for all
the call-back functions that the user-added subroutine can call from
PRO/II. The linker needs it to successfully create a user-added
DLL. Follow these steps to set the library path in Microsoft Visual
In the Solution Explorer, right click the project and select Prop-
erties from the action menu; then open the Linker tab.
In the General tab, enter the following text in the Additional
Library Directories text box:

2-24 Modular UAS Build Procedures February 2009

 C:\SIMSCI\PROII82\USER\LIBS\
This is the absolute path from the project directory where the
modules are installed...
When the project is in the default PRO/II install directory path,
a relative path may be used. Refer to Figure 2-5, “Setting the
Linker Libraries Path”, on page 2-25.

Click OK to confirm the setting

Figure 2-5: Setting the Linker Libraries Path

Refer to the On-Line Help in Visual Studio and the Intel Visual For-
tran compiler for more information about using the build tools
effectively.

PRO/II User-Added Subroutine User Guide 2-25

2-26 Modular UAS Build Procedures February 2009
 Chapter 3
Modular Interface Software

Overview
This chapter discusses the interfaces available for communicating
between PRO/II and modular user-added subroutines. Table 3-1
shows how the data is organized in this manual.
Table 3-1: Interface Modules and Routines in UserLb6.lib
Name Description See page...

Output and Reporting Routines

HEAD Heads and numbers an output page 15-7
UAOUT Write a single line of text to the Report file,
3-5
History file, or display terminal.
UAWRITE Write a single line of text to any File Unit 3-7
UAERROR Records an Error, Warning, or Message in the
3-8
PRO/II error-handling subsystem.
Modular Utility Routines (UAUTIL)
class_UASOBJ Data transfer object and member functions for
Chapter 4
manipulating utility subroutine data
Modular Unit Operations (UAUOP)
class_UAUOP Data transfer object and member functions for
Chapter 5
manipulating unit operation data.
Fluid and Fluid Data Modules
class_Fluid Data transfer and member functions that
6-25
manipulate fluids, perform flashes, etc.
class_FluidPhase Data transfer and member functions to
6-34
manipulate data in each phase of a fluid.
Dimensional Units Module
class_DMUOM Class containing member functions that access
Chapter 7
dimensional units conversion factors.

PRO/II User-Added Subroutine User Guide 3-1

 PRO/II communicates with user-added subroutines through:
Data classes defined in Fortran modules.
Call-back routines provided in the PRO/II program.
Subroutine argument lists, including modular storage objects.

Modular Interface Data Classes

PRO/II organizes the data that it passes to user-added subroutines
into groups called classes. A separate Fortran module implements
each class. The classes often have a hierarchical structure, where
one class may include one or more other classes. For example, a
UAUOP includes the Fluid class. The available base classes are
described in chapters 4 through 7.

Modular Call-back Routines

Modular call-back routines allow modular user-added subroutines
to call PRO/II to retrieve and store data, or to perform calculations
on demand. Several call-back functions and subroutines are general
purpose and not members of the data classes. These routines are
described in this chapter.
Other call-back routines are “member functions” of the data classes.
Table 3-1, ”Interface Modules and Routines in UserLb6.lib”, pro-
vides cross-references to the chapters that describe the data classes
and all their member functions.

Subroutine Argument Lists

When PRO/II calls a UAUOP or a UAUTIL, it passes data and execu-
tion control to them. Arguments in the call list include a data object
and execution control flags. The data object is specific to the
type of modular UAS being called. Control variables include a
CONTEXT flag and a solution flag, ISOLVE. The CONTEXT flag tells
the UAS what PRO/II expects. ISOLVE informs PRO/II whether or
not the UAS succeeded.

3-2 Modular Interface Software February 2009

Contexts in PRO/II
During any simulation, PRO/II performs a variety of operations to
orchestrate the successful execution of the flowsheet. During these
operations, PRO/II may or may not call a UAUTIL or UAUOP to
perform its own processing. PRO/II defines several execution con-
texts, as illustrated in Table 3-2. Yes indicates PRO/II makes a call
to the subroutine. No indicates that PRO/II does not attempt to call
the subroutine in that context.

Table 3-2: Contexts in PRO/II

Context UAUTIL UAUOP Description Need

INPUT No No Process input data (Keywords Optional
or AutoGUI)
CROSS- No Yes Validate Input data Optional
CHECK

CALCULATE Yes Yes Flowsheet calculations Required

OPCALC No Yes Post flowsheet calculations Optional

REPORT No Yes Write final results Optional

The left-most column of the table lists the exact text of the context
strings passed in from PRO/II in data member DataObj%Context. The
portion of the context string in bold type is the minimum character
string to use for testing the context. For example, the first five char-
acters of context could be tested against literal string CROSS to iden-
tify the CROSSCHECK context; e.g.,
IF( DataObj%Context(1:5) .EQ. “CROSS” ) THEN
Optionally, up to all ten characters in the string could be tested; i.e.,
IF( DataObj%Context(1:10) .EQ. “CROSSCHECK” ) THEN
When performing tests on text strings, always use upper case char-
acters only. Note that Fortran 90 uses a percent sign ( % ) as the
member access operator.

PRO/II User-Added Subroutine User Guide 3-3

ISOLVE Return Values
Whenever PRO/II calls a UAUTIL or UAUOP, it expects the called
routine to perform specific actions based on the call context. PRO/II
does not require calculation results to return from a user-added sub-
routine in every context. However, it always requires a valid return
value for ISOLVE. For example, a utility routine normally returns
all results in the array DataObj%RESULTS. However, these may be
omitted if the utility returns ISOLVE=0 or 3. Table 3-3 defines the
valid return values for ISOLVE.

Table 3-3: ISOLVE Values Used By User-Added Subroutines

ISOLVE
Description
Returns

0 UAS performed no action, PRO/II attempts to

continue. No returned results expected.

1 UAS successfully completed processing, PRO/II

continues normally. Returned results required.

2 UAS Failed – PRO/II continues flowsheet execution.

Returned results required.

3 UAS Failed – PRO/II terminates (flowsheet

execution). No returned results expected.

The “expected” return code in all contests is DATAOBJ%ISOLVE = 1.

Values of 2 or 3 always indicate an error condition. When a UAS
does not support a context, it should return DATAOBJ%ISOLVE = 0 to
indicate “no action taken”.
The meaning of ISOLVE codes 0 and 1 should be obvious. However,
the distinction between ISOLVE codes 2 and 3 is more subtle. Typi-
cally, a return value of DATAOBJ%ISOLVE = 2 indicates a convergence
problem. The UAS completes calculations and returns results, but
the results may not be converged within tolerance. For example,
this frequently occurs in early iterations of recycle problems that
require several cycles to build up flow rates to meet the overall con-
vergence criteria. An ISOLVE = 2 error is non-fatal, if it occurs on any
pass through the UAS, except the last pass. It allows PRO/II to con-
tinue the (iterative) calculations. If the ISOLVE = 2 error occurs on the
last pass through the UAS, it causes PRO/II to report, “Solution not
reached.”

The ISOLVE = 3 error always is fatal. UAS developers should return

this code when the UAS encounters a problem that prevents it from

3-4 Modular Interface Software February 2009

 performing its calculations. Typically, these situations occur when
data is missing or invalid. When PRO/II receives this return code, it
immediately terminates all flowsheet calculations, and results in
“solution not reached”. Later chapters that discuss each specific utility
or unit operation may expand these definitions.

Call-back Routines
In addition to the data modules used to communicate with user-
added subroutines, PRO/II provides additional subroutines and
functions that may be useful to developers. Call-back routines are
used inside user-added subroutines to request data or calculations
from PRO/II. This section describes those routines.

Output and Reporting

UAOUT
Purpose: Write a single line of text to selected PRO/II output files.
Calling sequence:
SUBROUTINE UAOUT( cFile, cAct, cText )
where:
cFile This option flag selects the files that receive the output data. It
is a character string that may have one of the following values.
Normal Displays the output on the user display terminal,
and writes the data in the PRO/II history file.
Terminal Displays data on the user display terminal only.
History Writes the output to the PRO/II history file only.
Report Writes the output in the PRO/II output report file.
The value of cFile may be truncated to only the first character
of the values listed above (N, T, H, or R).
cAct An option flag that controls line spacing when writing the
output. The character string may have one of the following
values.
Single Single space; simply write the line of output.
Double Double space; write a blank line, then write the
output.
Page Start a new page, then write the output.
This option is active only when writing to the Report file. The
value of cAct may be truncated to only the first character of
the values listed above (S, D, or P).

PRO/II User-Added Subroutine User Guide 3-5

 cText A character string or variable containing the actual text to
output.

The cFile option should be set to “Report” only when the user-
added Context also is “Report”. Note that the output report file
normally constrains each line of output to no more than 78 charac-
ters. Using the PRINT WIDTH = 80 or PRINT WIDTH = 120
option extends the output width to include the specified number of
characters. Refer to the PRINT WIDTH option in chapter 5, “Gen-
eral Data”, of the “PRO/II Keyword Input Manual”.
During calculations, when the user-added context is CALCULATION,
use the NORMAL, TERMINAL, or HISTORY option. All these options dis-
regard the cAct flag. They also discard all lines of output that are
completely blank. At the end of execution, PRO/II merges the his-
tory file into the report file to save the calculation history. Any data
written to a display terminal is lost after being displayed. UAOUT
does not write output to any other files.
The following sample code illustrates the proper use of UAOUT.
CHARACTER :: cLine*78
605 FORMAT( " ", A, 1P, 3E13.4 )
. . .
WRITE(cLine, * ) &
" _________ Test Results from UAS MassReport _________"
CALL UAOUT( "REPORT", "DOUBLE", cLine )
WRITE(cLine, * ) &
" ___________________ Column Data ___________________"
CALL UAOUT( "REPORT", "DOUBLE", cLine )
WRITE(cLine,605) " Cross-sectional area = ", MTobj%DS1( 1 )
CALL UAOUT( "REPORT", "SINGLE", cLine )
WRITE(cLine,605) " Weir Height = ", MTobj%DS1( 2 )
CALL UAOUT( "REPORT", "SINGLE", cLine )
WRITE(cLine,605) " Downcomer area = ", MTobj%DS1( 3 )
CALL UAOUT( "REPORT", "SINGLE", cLine )

The ExUasF90 and ExUOP sample projects that ship with PRO/II
include output report subroutines that make extensive use of UAOUT.
Refer to the source code for subroutines in files HEATREPO.f90,
MASSREPO.f90 and AREAREPO.f90 of that project.

3-6 Modular Interface Software February 2009

 UAWRITE
This routine writes a single record of pre-formatted text to any Log-
ical File Unit (LFU) open for writing formatted sequential data. To
use it, create a string variable and format it as desired. Obtain the
Logical File (LFU) of the target file. Call UAWRITE, passing the LFU
and the string variable (or quoted literal) as the arguments of the
call.
Calling sequence:
UAWRITE( LFU, cLine )
where:

LFU Input Integer Logical File Unit of a sequential formatted

file with WRITE permission.
cLine Input character string or variable containing a single line
of formatted text or data.

Example:
This sample code snippet demonstrates declaring the character vari-
able, populating it with text and numerical values, obtaining a file
unit in variable LFU using FIGETU, and calling UAWRITE.
INTEGER(4) :: LFU, Ival
REAL(8) :: Rval
CHARACTER(LEN=133) :: cLine
. . .
CALL FIGETU( 1, LFU )
Rval = 23.4
Ival = 3
cLIne = “The value of RVAL( ) is:”
WRITE( cline(19,21), “( I3 )” ) Ival
WRITE( cLine(29:39), “(F9.4)” ) Rval
CALL UAWRITE( LFU, TRIM(cLine) )
The single line of output would be:
The value of RVAL( 3) is : 23.4000

Note: Modular unit operations (UAUOP) include variable LFUout

for writing to the standard PRO/II output file. Assuming the
UaUop data object is named UopObj in the user-written unit opera-
tion, the following example writes cLine to the PRO/II standard
output file:
CALL UAWRITE( UopObj%LFUout, TRIM( cLine ) )

PRO/II User-Added Subroutine User Guide 3-7

 UAERROR
Purpose: Register an error, warning, or message in the PRO/II error
subsystem. Also write a user-defined message to a standard output
file.
Calling sequence:
UAERROR( cELevel, IUNO, MESSAGE )
Where:

cELevel Required input single character that acts as an option for

the error level to record. Allowed values include:
“E” Severe error, calculations failed. The message may
describe the error.
“W” Warning, calculations hampered, results may be
suspect. The message describes the situation.
“M” Message, no error, calculations succeeded. This is
merely information for the user.
IUNO Required scalar input. The internal order number of a unit
operation. This may be a UAUOP that calls UAERROR; or
a unit operations that calls a user-added utility that calls
UAERROR. A value of zero omits IUNO from the message.
MESSAGE Required character input. This is the text of the error
message to display or print. It may contain up to 200
characters of text.

The error level specified by cELevel indicates the severity of the

reported problem. In most cases, a user-added subroutine is either a
unit operation or a utility called from a unit operation. In either
case, the error behaves as if it were generated by a unit operation.
An Error terminates flowsheet calculations when registered outside
a flowsheet recycle loop. When registered inside a recycle loop, an
Error fails the current loop iteration but may allow additional itera-
tions of the loop.
A Warning does not halt calculations, but informs users that a prob-
lem exists. Normally, warnings indicate a situation or condition that
compromises the calculated results. For example, “Warning -
supplied data is not monotonic” may indicate a problem
with supplied data that could compromise the integrity of calculated
results.
A Message is informational only, and never influences the calcula-
tions in PRO/II. For example, assume a user-added subroutine

3-8 Modular Interface Software February 2009

 allows the user to enter a calculation option but the user neglects to
supply it. A Message may be appropriate to inform users that a
“default” method is being used. If no default is allowed, then a
Warning or an Error may be more appropriate. Since messages are
processed by the error processing subsystem, normal progress mes-
sages should be generated by calling UAOUT, not UAERROR.
Argument IUNO is an integer that identifies the parent unit operation
that encountered the error. For a user-added unit operation it is
available in member %UasIdNo of the UAUOP data object. For a user-
added utility, IUNO is available in member %UasIdNo of the UASOBJ
data object.
Argument MESSAGE is the text of the error. It may be a quoted lit-
eral string or a CHARACTER string variable. It does not need to
include the error level (error, warning, etc.) or a unit operation
identifier.

Example:
Consider the following utility called from unit operation Ex1Uop:
SUBROUTINE MyUAUtil( ObjUtil )
TYPE( UASOBJ ) :: ObjUtil
INTEGER(4) :: IUNO
CHARACTER(LEN=78) :: Message
IUNO = ObjUtil%UasIdNo
IF( ObjUtil%INTdata( 1 ) .LE. 0 ) THEN
Message = “Default method used when“ &
// “INTdata( 1 ) = 0”
CALL UAERROR( “M”, IUNO, Message )
END IF
The call to UAERROR generates the following message:
** MESSAGE ** In Unit 'EXUOP1',
Default method used when INTData( 1 ) = 0
UAERROR performs all the formatting automatically. In particular,
the “** MESSAGE **” clause in the example corresponds to the
error level specified in the first argument (cELevel). The clause “In
Unit 'EXUOP1'” is an automatic expansion of the second argu-
ment (IUNO). The text of the message is wrapped when it is too long
to fit on a single line. Also, whenever two or more contiguous
blanks appear in the text, they are compressed to a single space.

PRO/II User-Added Subroutine User Guide 3-9

 class_UASOBJ.mod
This is the base class used to create modular Utility subroutines. It
contains a data structure and accessor functions to access the data.
The data structure is populated and passed from PRO/II in the argu-
ment list in each call to a modular user-added utility.
See Chapter 4, Modular Utility Subroutines for detailed informa-
tion about using this module and its members.

class_UAUOP.mod
This is the base class used to create modular Unit Operations. It
contains a data structure and accessor functions to access the data.
The data structure is populated and passed from PRO/II in the argu-
ment list in each call to a modular user-added unit operation.
See Chapter 5, Modular Unit Operations for extensive information
about using this module and its members.

class_Fluid.mod
This module makes Fluid data objects available to within modular
user-added subroutines. Modular Utilities such as IFAREA include
fluids within their data structures. Modular unit operations only
identify their feed and product streams and do not provide pre-built
fluids. Member methods of class_Fluid.mod, such as load_fluid, pro-
vide developers the necessary tool to instantiate, manipulate, and
destroy fluid object at will.
See Chapter 6, UAS Modular Fluids for comprehensive informa-
tion about using this module and its members.

class_DMUOM.mod
This module defines a class that provides dimensional units to mod-
ular user-added subroutines. Currently it provides a single user-call-
able function, GetFactor_DmUom, that returns factors to convert
between user-units and PRO/II internal units.
Chapter 7, User-Added Units of Measure, defines the module, its
member functions, and data structure. See Chapter 6, UAS Modular
Fluids for information and examples that use this module and its
members.

3-10 Modular Interface Software February 2009

 Chapter 4
Modular Utility Subroutines

Overview
User-added utilities perform specific calculations and return spe-
cific, pre-defined results when called from PRO/II. They serve as
alternatives to existing PRO/II methods.
The first section in this chapter present user information that
describes using modular utilities in PRO/II simulations. The
remainder of the chapter presents developer information that
includes coding requirements, a full description of class_UASOBJ,
and an extensive example of an implementation.

User Information
The RATEFRAC column model in PRO/II is the only unit operation
that supports modular utilities. The following are the only sup-
ported modular utilities.
Interfacial Area methods. RATEFRAC allows a different subroutine
or method on each tray or in each packed section.
Binary Mass Transfer Coefficient methods. RATEFRAC allows
a different subroutine or method on each tray or in each packed
section.
Heat Transfer Coefficient methods. RATEFRAC allows a different
subroutine or method on each tray or in each packed section.

Keyword Summary
RFTRANSFERSECTION = idno,
MTCORR = DEFAULT, or
MTSUBROUTINE = user-added subroutine-name,

HTCORR = CHILTON, or
HTSUBROUTINE = user-added subroutine-name,

IACORR=DEFAULT or ONDA or BRAVO or SCHEFFE, or

IASUBROUTINE = user-added subroutine-name
Use the MTSUB, HTSUB, and IASUB entries to use user-added utility
routines. Refer to Chapter 12.10 of the PRO/II Keyword Manual for
more information.

PRO/II User-Added Subroutine User Guide 4-1

 Utility Input Data Requirements
Utility routines currently do not accept input data values.

Utility Output Reports

PRO/II does not call user-added utility routines to report results.
Because utility calculations are an intrinsic part of unit operations,
the effects of the utility calculations are implicit in the solved
results of the unit operations. However, developers may add code to
write intermediate results when their utilities are called. Interface
routine UAOUT may be used by them for this purpose.

Utility Installation and Registration

It is the user’s responsibility to install and register the user-added
utilities before attempting to use them from PRO/II. Users must
obtain specific installation instructions from the developer of each
utility subroutine; not from SIMSCI. See “Registering User-Added
Utilities” on page 2-6 of Chapter 2 in this manual to learn about
registering modular utilities.
See “Using a User-Added Modular Utility in PRO/II” on page 2-14
of Chapter 2 for an example of using these utilities in PRO/II simu-
lations.

Developer Information
The remainder of this chapter is intended for developers of user-
added utilities. Users who merely use pre-built modular utilities in
PRO/II simulations may find some of the material interesting.

Data Exchange Between PRO/II and Utility Routines

Each sub-class of user-added utility routine performs a specific type
of calculation. For each utility type, PRO/II passes in a limited, pre-
defined set of data that is available for use by the user-added utility.
The data requirements and the data supplied for each utility type
may differ, but the basic mechanism for data transfer to and from
PRO/II are consistent. PRO/II uses the class_UASOBJ module to
pass all input data to the utility interface routine.
Using the input data, the user-added utility interface routine calls
the utility calculation routine. The calculation routine computes a
pre-defined result or set of results. It must store the results in the
RESULTS array of the class_UASOBJ data object. Before returning
control to PRO/II, the utility must set the return code in the ISOLVE
member of the class_UASOBJ data object.

4-2 Modular Utility Subroutines February 2009

 Refer to individual chapters later in this manual for listings of the
data available to each specific type of utility subroutine. Refer to
Chapter 11, ”Interfacial Area Utility” for interfacial area subrou-
tines; Chapter 12, ”Binary Mass Transfer Utility” for mass transfer
subroutines, and Chapter 13, ”Heat Transfer Utility” for heat trans-
fer subroutines.

Coding Guidelines
Each user-added calculation utility requires an interface routine
written in Fortran 90. This is because PRO/II passes a reference to a
data class in the argument list when it calls the user-added subrou-
tine. A Fortran 90 module is required to “instantiate” the data class,
so data can be accessed from it. Instantiating the class also allows
the user-added routine to store its results in the data class. Earlier
versions for Fortran, such as Fortran 77 or Fortran 66, do not sup-
port this feature.
All PRO/II interfaces conform to the Fortran 90 standard as much
as possible. However, dynamic calls to external DLL’s are outside
the strict domain of the Fortran standard. PRO/II uses extensions to
the Fortran 90 language to accomplish this. In the examples in this
manual, the extensions of Compaq Visual Fortran version 6.6b are
illustrated. These probably will be different if other compilers are
used.
Modern programming practice typically implements “modular cod-
ing” to isolate the call interface from the rest of the code (such as a
calculation algorithm). In addition, “modular coding” typically
“encapsulates” unrelated functionality in different subroutines or
functions. In PRO/II, the interface routine is the single entry and
exit point for a UAS. PRO/II calls the interface routine, and in turn,
it calls appropriate subroutines to perform the desired computa-
tions. When calculations are complete, the calculation routines
return control to the interface routine, which in turn serves as the
return point to PRO/II.
When implementing more than one UAS in a single DLL, the sim-
plest and most intuitive approach probably would be to code a sepa-
rate interface routine for each UAS. Keep in mind that a single UAS
can include more than one subroutine. The examples presented in
this manual all use separate subroutines for the call interface, the
calculation algorithm, the report writer, and other supported func-
tionality. The sample code in Figure 4-1 illustrates the basics of this
approach.

PRO/II User-Added Subroutine User Guide 4-3

 Contexts in Utility Subroutines
PRO/II uses several execution contexts that perform a variety of
operations to solve a simulation. "Contexts in PRO/II" on page 3-3
defines them. As shown in Table 4-1, PRO/II calls a UAUTIL only in
the CALCULATE context.

Table 4-1: Contexts in PRO/II

Context UAUTIL Description

INPUT No Input simulation data

CROSS No Validate input data

CALC Yes Perform calculations

OPCALC No Post-flowsheet calculations

REPORT No Write final results

PRO/II expects the user-added utility to perform calculations on

request. Support for all other contexts is not currently implemented
for user-added utilities.

ISOLVE Return Values

PRO/II requires each user-added utility to return the ISOLVE flag
each time it is called. See "ISOLVE Return Values" on page 3-4.
The “expected” return code is DATAOBJ%ISOLVE = 1. Values of 2
or 3 always indicate an error condition. When a UAS does not sup-
port a context, it should return DATAOBJ%ISOLVE = 0 to indicate
“no action taken”.

Results Return Values

PRO/II expects each user-added utility routine to return a complete
set of valid results when the subroutine returns control to PRO/II.
The Results member of the UASOBJ data structure is the mechanism
that performs this function. Different types of user-added utilities
return completely different sets of results.
For example, an interfacial area utility returns a single value repre-
senting the (specific) interfacial area of a stage. For a packed stage,
this is dimensionless (actually, interfacial area per unit area of pack-
ing). For a stage with trays, the dimensional units are inverse length
(actually, interfacial area per unit of tray volume). In both cases,

4-4 Modular Utility Subroutines February 2009

 this single value returns in the first element of the results array,
Results(1,1).

In contrast, a mass transfer coefficient utility returns a set of binary

mass transfer coefficients that includes a value for each binary pair
of components in a simulation. This requires a two dimensional
array. For NOC components, the number of results is NOC*NOC, and
the results array has two dimensions, each of NOC elements. The
declaration for the size is Results(NOC,NOC). Each value has units of
mole-rate (wt-moles/time). For a simulation containing five compo-
nents, the mass transfer coefficient routine has a results array
dimensioned Results(5,5), and PRO/II expects the subroutine to
return all 25 values.

Dimensional Units
Each user-added utility subroutine exchanges data with PRO/II in a
consistent set of dimensional units. The subroutine developer
chooses one of several sets provided by PRO/II. The developer
must inform the end-user of the correct set of units. The end-user
must declare the developer’s set of units when registering the sub-
routine with PRO/II. See “Registering User-Added Utilities” on
page 2-6 of Chapter 2 for a description of the registration process.
The registered set of dimensional units applies to all data exchanged
between PRO/II and a user-added subroutine. This is independent
of the units used for input data in a simulation. Refer to Chapter 7,
”User-Added Units of Measure”, for lists of the available sets of
units, including all dimensional classes. It includes the exact unit of
measure used by each class for each available set of units. PRO/II
does not support changing the unit of measure in each class of a sys-
tem of units for a utility routine.

PRO/II User-Added Subroutine User Guide 4-5

 Coding A Utility Interface Routine
Each user-added utility requires a standard interface routine so
PRO/II can call it. The interface routine must conform exactly to
the requirements presented here. Using a separate interface routine
removes the PRO/II constraints from the calculation routine.
Figure 4-1 illustrates the essentials of a basic interface subroutine.
Figure 4-1: Sample Interface Routine Called by PRO/II
1 SUBROUTINE UASMAIN( DataObj )
2 !DEC$ ATTRIBUTES DLLEXPORT:: UASMAIN ! Export UASMain
3 !___________________________________________________________
4 ! |
5 ! Variables in Argument list |
6 ! Name Type I/O Brief Description |
7 ! -------- ------ --- ------------------------------------- |
8 ! DataObj UasObj I/O UAS Data object (all input/output data|
9 !___________________________________________________________|
10 !
11 USE class_UASOBJ ! Interface DataObj as a UASOBJ class
12 !
13 IMPLICIT NONE ! Require explicit variable declarations
14 !
15 TYPE(UASOBJ), INTENT(INOUT) :: DataObj ! Instantiate Obj
16 !
17 CHARACTER :: context*12 ! local character variable
18 !
19 ! --------------------- Code Begins here --------------------
20 !
21 context = TRIM( UASOBJ%Context ) Evaluate Context flag
22 !
23 IF( context(1:4) .EQ. "CALC" ) THEN
24 CALL UasCalc( DataObj ) ! Perform calculations
25 ELSE IF( context(1:6) .EQ. "REPORT" ) THEN
26 CALL UasReport( DataObj ) ! Generate report
27 ELSE ! Handle unsupported contexts
28 UasObj%ISOLVE = 0 ! Set ISOLVE to “Never Solved”
29 ENDIF
30 END SUBROUTINE UASMAIN

Notes about Figure 4-1:

Line 1 illustrates the interface that PRO/II calls. It includes a single
argument in the dummy argument list – DataObj.
Line 2 is the Compaq Visual Fortran compiler directive that exports
UASMAIN from the DLL and exposes it to PRO/II, or other external
applications that may call it. The routine that PRO/II calls always

4-6 Modular Utility Subroutines February 2009

 must be exported from the DLL; otherwise, PRO/II cannot find it. It
is not necessary to export routines (such as the calculation routine)
that are not called from outside the DLL.
Lines 3 through 10, and 18 through 20, are simply documentation
comments (a good coding practice).
Line 11 is the Fortran 90 command that invokes the explicit inter-
face in Fortran 90 module class_UASOBJ.mod. This statement must be
included for the routine to compile properly. It exposes member
functions in the module for use in the interface subroutine.
Line 13, IMPLICIT NONE, requires explicit type declarations for all
variables in the subroutine (another good coding practice). Note
that data members of DataObj do not need to be declared, since class_
UASOBJ always explicitly declares all of its data members (see line
11).
Line 15 locally “instantiates” variable DataObj as a UASOBJ class
object. This exposes all the “public” data and member functions in
DataObj for local access inside the encompassing subroutine.

Line 17 declares variable context as a local string containing up to

12 characters.
Line 21 accesses the context flag from DataObj and copies it into
local string context. Bringing this item into local storage is a mere
convenience, but illustrates the mechanism for accessing data mem-
bers in DataObj.
Lines 23 through 29 constitute an IF-THEN-ELSE construct that han-
dles all functionality that the UAS supports. Different subroutines
are called depending upon the value of variable context. Line 23
compares the first four characters of variable context to the literal
string “CALC”, a pre-defined context string set up by PRO/II. If this
test evaluates to TRUE, the subroutine containing the calculation
algorithm is called at line 24. If it evaluates to FALSE, control passes
to line 25.
Line 25 tests the first six characters of variable context against literal
string “REPORT” (always all upper-case). A test that evaluates to
TRUE calls routine UasReport at line 26. This illustrates the modular
separation of functionality, wherein the calculation algorithm is
coded in one subroutine, while the code to generate a report is
coded in different subroutine. If the test at line 25 evaluates FALSE,
control passes to lines 27 and 28.

PRO/II User-Added Subroutine User Guide 4-7

 Line 27 is the default clause of the “IF” construct. If none of the pre-
ceding clauses evaluate TRUE, control passes to here. In this exam-
ple, this handles all other contexts not supported by the UAS.
Line 28 sets the ISOLVE flag directly in the DataObj data structure.
Since this value needs to be returned through DataObj, there is no
advantage to creating a local variable for it.
Finally, line 30 ends the subroutine. When control reaches this line,
the subroutine exits and returns to PRO/II. Note the omission of a
Fortran 77 RETURN statement. It is not required by Fortran 90.
This basic subroutine is suitable for use in any UAS that requires a
single call-list argument of TYPE(UASOBJ). The sample code of
Figure 4-1 supports only two contexts: CALCULATE and REPORT. All
others return ISOLVE = 0, indicating “no action taken”. Developers
should expand the IF-THEN-ELSE construct to handle other PRO/II
contexts that the UAS supports.

4-8 Modular Utility Subroutines February 2009

 Coding A Utility Calculation Routine
Typically, the calculation code should appear in a routine separate
from the utility interface routine. In this approach, PRO/II only calls
the interface routine, and the interface routine is the only routine
that calls the calculation routine. This provides the most flexibility
for writing the code and modularizing the functionality. There are
two approaches for coding the call from the interface to the calcula-
tion routine.
The interface routine performs all access to the class_ UASOBJ
data object. It could extract all input data into local variables
and arrays, then pass all the local data as arguments in the call
to the calculation routine. The call to the calculation routine
would include an array that returns the results to the interface
routine. After calculations complete, the interface routine
stores the (returned) results in the class_ UASOBJ structure, and
sets the ISOLVE member. This approach allows the calculation
routine to be completely self-contained, independent of
PRO/II, and portable for use in other applications.
The interface routine calls the calculation routine with few or
no arguments. The calculation routine would “USE class_
UASOBJ” and directly extract the input data from that data struc-
ture. This simplifies the call between the interface and calcula-
tion routines. It also allows the calculation routine to work
directly with the input data and results in a straightforward
manner. However, this requires the calculation routine to
depend upon the availability of the class_ UASOBJ class. Using
this approach, the calculation routine could be used only when
called by PRO/II, and would not be portable for use in other
applications.
Either approach is equally valid; the choice of implementation is
left to the developer. Refer to the topic “Accessing Data of
class_UASOBJ” later in this chapter to learn how to implement and
use class_UASOBJ in a user-added subroutine.

PRO/II User-Added Subroutine User Guide 4-9

Definition of class_ UASOBJ.mod
This module makes class_ UASOBJ available to user-added subrou-
tines. The class includes a data structure and member methods. For
user-added utility subroutines, a UASOBJ instance is the only argu-
ment in the call list of the subroutine. PRO/II does not support using
UASOBJ with user-added unit operations.

This section describes the proper usage of class_UASOBJ mod. It also

describes all the data in the UASOBJ base class. Remember that only
a sub-set of the data described here is available to any specific type
of user-added subroutine.

Usage of class_ UASOBJ

PRO/II passes the data object of this class to each user-added utility
subroutine that it calls. To use the data structure, the user-added
subroutine code must perform several operations.
Include the UASOBJ instance as the only item in the subroutine
argument list. This allows data in the data object to pass
between PRO/II and the user-added subroutine.
USE the class_UASOBJ module. This brings in the definition of
the data structure, and makes the accessor functions of the class
available to the subroutine.
Declare the UASOBJ argument variable as a UASOBJ instance.
This makes the local instance of UASOBJ accessible by within
the subroutine.
The following code sample illustrates these three operations.
SUBROUTINE MASSMAIN( MTobj )
USE class_UASOBJ
TYPE(UASOBJ), INTENT(INOUT) :: MtObj
Notes:
1. MTobj is the mass transfer class. It is a sub-type of the UASOBJ
class.
2. The statement USE class_UASOBJ brings the module
class_UASOBJ into the user-added subroutine. This defines the
class used in the following TYPE statement. This allows access
to member methods in the module.
3. The TYPE statement applies the definition of the UASOBJ class to
MtObj. This allows access to the data and methods in MtObj.

4-10 Modular Utility Subroutines February 2009

 All data items in the UASOBJ data structure are “members” of
that data structure. There are two methods available to access
the members:
Direct member addressing
Indirect accessor routines
The following sections discuss both data access methods.

Direct Member Addressing in class_UASOBJ

Direct member addressing accesses data by direct reference to the
data member. Fortran 90 defines the percent symbol % as the
access operator. Consider the following data structure as an analog
of UASOBJ:
TYPE CHARGE
INTEGER :: PARTS(40)
REAL(8) :: LABOR
REAL(8) :: MILEAGE
END TYPE CHARGE
Now assume a subroutine includes the following declaration:

TYPE(CHARGE) MONTH
This declares MONTH as a CHARGE structure.
Some valid array references for this type follows:
MONTH%PARTS(I) ! An integer array element
MONTH%PARTS(I:K) ! An integer array section
MONTH%LABOR ! A double precision scalar
The “parent % member” construct is extensible to any level in the data
structure. For example, some instances of UASOBJ include a FLUID
structure named FLVAPOR. Each FLUID (including FLVAPOR) has a
member named TEMP for the temperature. The FLVAPOR fluid also
contains an FLPHASE structure named VAPOR.
Finally, the VAPOR phase data structure contains a member array
named XFracM that is dimensioned to NOC, the number of compo-
nents in the simulation. XFracM contains the mole fraction of each
component “i”. To obtain the mole fraction of component 6 from
XFracM, the following code could be used:

SUBROUTINE MASSMAIN( MTobj )

USE class_UASOBJ
TYPE(UASOBJ), INTENT(INOUT) :: MtObj
INTEGER(4) :: idx

PRO/II User-Added Subroutine User Guide 4-11

 REAL(8) :: Xfrac6, TempVap
. . .
idx = 6
Xfrac6 = MtObj%FLVAPOR%VAPOR%XFracM(idx)
To obtain the temperature from the storage TEMP member of
FLVAPOR, use:

TempVap = MtObj%FLVAPOR%TEMP
It is possible to access any data member in any sub-structure of
UASOBJ in this manner. Table 4-2 on page 4-19 lists all data mem-
bers that might be available in the UASOBJ data structure. The first
column, labeled “Member”, is the name of the data member to use
for direct member addressing.

Indirect Accessor Routines in class_UASOBJ

This is a more traditional access method, quite similar to Fortran 77.
In addition to defining the UASOBJ data structure, class_UASOBJ.mod
also provides accessor functions to retrieve data from UASOBJ. No
functions to store data in UASOBJ are provided.

Note: The accessor routines discussed in this section are available

only when using class_UASOBJ.mod in a subroutine.
Many (but not all) data members of UASOBJ have keywords
assigned to them to enable indirect access. Table 4-2 lists these key-
words in the last column, labeled “Keyword”. The accessor func-
tions are described below.

4-12 Modular Utility Subroutines February 2009

 GETUASVAL
This function retrieves data from the UASOBJ storage object. It is
an alternative to using direct accessing of data members. It supports
several different types of argument variables, depending upon the
type of data being retrieved.

Named Integer Scalar Data

Calling sequence:
FUNCTION GETUASVAL( kwIn, ObjIn, Ivalue ) &
RESULT(iErr)
This form of the function retrieves a scalar integer member of array
IS1.

kwIn A keyword for an element of the IS1 array. These key-

words are not listed in Table 4-2 because the data in DS1
may be different for each type of user-added subroutine.
Refer to the data tables in the chapters that describe indi-
vidual types of user-added subroutine. For example, see
Table 12-1 for keywords of data available in a mass trans-
fer coefficient utility subroutine.
ObjIn The data object declared as TYPE(UASOBJ). The data to
retrieve must be a member of this data structure.
Ivalue The returned scalar integer value.
iErr An error code returned as the value of the function. A
value of 0 indicates successful retrieval (no errors). Any
negative value indicates an error.
Example: In an interfacial area calculation subroutine, determine
whether the current stage has packing or trays. If packed,
retrieve the packing type and packing arrangement. If the stage
has trays, retrieve the tray type.
Use Table 11-1 on page 11-2 (for an Interfacial Area subrou-
tine) to find:
Stage Type stored in IS1(1) with access keyword COLTYPE.
Packing type stored in IS1(2) with access keyword PTYPE.
Packing arrangement stored in IS1(3), access keyword PAR-
RANGE.
Tray type stored in IS1(6) with access keyword TTYPE.
With this information, the following code is valid:

PRO/II User-Added Subroutine User Guide 4-13

 SUBROUTINE ABC( IfObj )
USE class_UASOBJ
TYPE( UASOBJ ) :: IfObj
INTEGER(4) :: ierr, StageType
INTEGER(4) :: PackType, PackArr
INTEGER(4) :: TrayType
!
ierr = GETUASVAL("COLTYPE", IfObj, StageType)
!
! For a stage with packing
IF( StageType .EQ. 1 ) THEN
ierr = GETUASVAL("PTYPE", IfObj, PackType)
ierr = GETUASVAL("PARRANGE", IfObj, PackArr )
! For a stage with trays
ELSE IF( StageType .EQ. 2 ) THEN
ierr = GETUASVAL("TTYPE", IfObj, TrayType )
ENDIF
The values mapped to these flags for an interfacial area object are
listed in Table 11-1 on page 11-2. For example, Table 11-1 explains
that StageType represents the value of IfObj%IS1(1), a flag for the
column type, where StageType = 1 indicates a packed stage and
StageType = 2 indicates the stage has trays. The error code returns
in variable ierr. A negative value indicates an error.

Integer Array Elements

Calling sequence:
FUNCTION GETUASVAL(kwIn, Obj, IValue, ix1, ix2) &
RESULT(iErr)
This form of the function retrieves a scalar value from any inte-
ger array available in the UASOBJ data object. The only integer
array currently supported is IS1. Use of this form is discour-
aged for data retrieval from array IS1.
kwIn A keyword for an integer array. Currently, this is always
“IS1”.
ObjIn The name of the data object declared as
TYPE(UASOBJ). The data to retrieve must be a member
of this data structure.
Ivalue The returned scalar integer value.
ix1 The first dimension element (column) of the item in the
array referenced by kwIn.
ix2 The second dimension element (row) of the item in the
array referenced by kwIn. Currently, this always is 1.

4-14 Modular Utility Subroutines February 2009

 Ierr An error code returned as the value of the function. A
value of 0 indicates successful retrieval (no errors). Any
negative value indicates an error.
Example: In an interfacial area calculation subroutine, determine
whether the current stage has packing or trays. If packed,
retrieve the packing type and packing arrangement. If
the stage has trays, retrieve the tray type. This is the
same example as above, but now uses this alternative
form of the GETUASVAL accessor routine.
Use Table 11-1 (for an interfacial area subroutine) to find:
Stage Type stored in IS1(1) with access keyword COLTYPE.
Packing type stored in IS1(2) with access keyword PTYPE.
Packing arrangement stored in IS1(3), using access keyword
PARRANGE.
Tray type stored in IS1(6) with access keyword TTYPE.
Array IS1 is a single-dimension array, so the second dimension,
ix2 (the row) must always be 1. With this information, the fol-
lowing code is valid:
SUBROUTINE ABC( IfObj )
USE class_UASOBJ
TYPE( UASOBJ ) :: IfObj
INTEGER(4) :: ierr, StageType, ix1, ix2
INTEGER(4) :: TrayType, PackType, PackArr
!
ix2 = 1 ! always = 1 to access array IS1
ix1 = 1 ! offset to "COLTYPE"
ierr = GETUASVAL("IS1", IfObj, StageType, &
ix1, ix2 )
! For a stage with packing
IF( StageType .EQ. 1 ) THEN
ix1 = 2 ! offset to packing type
ierr = GETUASVAL("IS1", IfObj, PackType, &
ix1, ix2 )
ix1 = 3
ierr = GETUASVAL("IS1", IfObj, PackArr,&
ix1, ix2 )
! For a stage with trays
ELSE IF( StageType .EQ. 2 ) THEN
Ix1 = 6 ! offset to tray type
ierr = GETUASVAL("IS1", IfObj, TrayType, &
ix1, ix 2)
ENDIF

PRO/II User-Added Subroutine User Guide 4-15

 Double Precision Named Array Element
Calling sequence:
FUNCTION GETUASVAL( kwIn, ObjIn, DValue ) &
RESULT( iErr )
This form of the function retrieves one double precision value
from array DS1.
kwIn A keyword for an element of the DS1 array. These key-
words are not listed in Table 4-2, because the data in
DS1 may be different for each type of user-added utility
data object. Refer to the data tables in the chapters that
describe individual types of user-added subroutine. For
example, see Table 12-1 for keywords of data available
in a mass transfer coefficient utility subroutine.
ObjIn The name of the data object declared as
TYPE(UASOBJ). The data to retrieve must be a member
of this data structure.
Dvalue The returned scalar double precision value.
iErr An error code returned as the value of the function. A
value of 0 indicates successful retrieval (no errors). Any
negative value indicates an error.
Example: In an interfacial area calculation subroutine, retrieve the
stage weir height. Table 11-1 (for an interfacial area sub-
routine) lists the weir height in DS1( 2 ). It also shows that
the keyword for this member is HTWIER. With this infor-
mation, the following code is valid:
SUBROUTINE ABC( IfObj )
USE class_UASOBJ
TYPE( UASOBJ ) :: IfObj
INTEGER(4) :: ierr
REAL(8) :: WeirHeight
ierr = GETUASVAL( "HTWIER", IfObj, WeirHeight )
The value for the height of the weir returns in variable
WeirHeight. The error code returns in variable ierr.

4-16 Modular Utility Subroutines February 2009

 Double Precision Unnamed Array Element
FUNCTION GETUASVAL( kwIn, Obj, DValue, ix1, ix2
& RESULT(iErr)
This form of the function retrieves a scalar value from any dou-
ble precision array available in the UASOBJ data object.
kwIn A keyword for a double precision array. These keywords
are not listed in Table 4-2, because the data in DS1 may
be different for each type of user-added subroutine.
Refer to the data tables in the chapters that describe indi-
vidual types of user-added subroutine. For example,
Table 13-1 on page 13-2 defines the double precision
arrays DS1, DA2, and DA3 that are available in a heat
transfer coefficient utility subroutine.
ObjIn The name of the data object declared as TYPE(UASOBJ).
The data must be a member of this data structure.
Dvalue The returned scalar double precision value.
ix1 The first dimension element (column) of the item in the
array referenced by kwIn.
ix2 The second dimension element (row) of the item in the
array referenced by kwIn.
iErr An error code returned as the value of the function. A
value of 0 indicates successful retrieval (no errors). Any
negative value indicates an error.
Example: In a heat transfer coefficient utility subroutine, retrieve
the mass transfer coefficient and the diffusion coefficient
of the binary pair for components 3 and 6.
For an HTC subroutine, use Table 13-1 to find the diffusion
coefficient array is DS2 with the keyword DIFFCO. In addition,
notice the mass transfer coefficient array is DS3, with the key-
word MASSCO. With this information, the following code is
valid:
SUBROUTINE BCD( HtObj )
USE class_UASOBJ
TYPE( UASOBJ ) :: HtObj
INTEGER(4) :: ierr, ix1, ix2
REAL(8) :: Diff36, Mass36
ix1 = 3
ix2 = 6

PRO/II User-Added Subroutine User Guide 4-17

 ierr = GETUASVAL ("DIFFCO", HtObj, Diff36, &
ix1, ix2 )
ierr = GETUASVAL ("MASSCO", HtObj, Mass36, &
ix1, ix2 )
The value for the diffusion coefficient returns in variable
Diff36.

The value for the mass transfer coefficient returns in variable

Mass36.

The error code returns in variable ierr.

Named Character Data

Calling sequence:
FUNCTION UasGetChar( kwIn ) RESULT( cValue )
This function retrieves a limited number of character data. This rou-
tine is most useful to developers rather than end users of user-added
subroutines. The only character data currently supported are the
module type and version of class_UASOBJ.mod. Developers may wish
to access that data during the debugging stage of development to
verify that the object passed from PRO/II is the correct one.
kwIn A keyword for a character member in Table 4-2.
cValue The returned data string of up to 40 characters.
Example: Retrieve the module type and module version of UASOBJ.
CHARACTER(LEN=40) :: mType, mVersion
mType = UasGetChar( "MODT" )
mVersion = UasGetChar( "MODV" )

4-18 Modular Utility Subroutines February 2009

 Data Structure of class_UASOBJ
Table 4-2 describes the data structure of the UASOBJ data structure
in the base class. It is presented for the convenience of engineers
who develop user-added subroutines. The complete base class never
is passed to a user-added subroutine. However, describing it here
provides a single source of information about data that is passed to
two or more types of user-added subroutine. Table 6-11 on page 6-
35 lists the data structure of “fluid phase” members of UASOBJ.

Table 4-2: class_UASOBJ Data Member

Module Data
Member Type Description
UasType C 12 Identifies the type of utility subroutine being
called
UasPath C 256 Path to DLL directory from P2UasReg.ini
UasName C 32 Actual name of subroutine called, from
P2UasReg.ini
UasID C 32 PRO/II ID of the called UAS, from
P2UasReg.ini
UasVersion C 12 Version of the UAS set by the developer of the
UAS.
General Data
Member Type Description
ThermoFl I4 Thermodynamic method set flag, not yet
supported.
DiagnosticFl I4 Diagnostic flag, for use only by the UAS
developer.
UomSystem I4 UOM system flag
1 = PRO/II internal 2 = English
3 = Metric 4 = SI
Context C 12 Context flag
1 INPUT 2 CROSSCHECK
3 CALCULATION 4 OPCALC
5 REPORT
iContext I4 Integer version of Context flag
1 INPUT 2 CROSSCHECK
3 CALCULATION 4 OPCALC
5 REPORT

PRO/II User-Added Subroutine User Guide 4-19

 Table 4-2: class_UASOBJ Data Member
UASOBJ Data Members
Member Type Description
Phase I4 Fluid Phase of interest (for calculations)
0 = Phase does not apply
1 = Vapor
2 = Liquid
CallerID C 12 ID of calling Unit Operation
Exist L4 Logical. True if UASOBJ contains valid data.

Component Data
Member Type Description
NOC I4 Total number of components in problem
CompIndex(i) I4 Internal component numbers, in input order. I =
1, NOC
Fluid Data
Member Type Description
FlVapor Fluid Vapor phase fluid data object
FlLiquid Fluid Liquid phase fluid data object
FlIface Fluid Interface phase fluid data object
FlFeed Fluid Liquid phase fluid data object
FlProd Fluid Interface phase fluid data object
The following members are validation flags for the fluid data
members immediately above. They take the following values:
1 = Array is allocated and populated with valid data.
0 = allocated but empty.
-1 = missing.
ValidFlVapor I4 Validation flag for fluid FlVapor
ValidFlLiquid I4 Validation flag for fluid FlLiquid
ValidFlIface I4 Validation flag for fluid FlIface
ValidFlIFeed I4 Validation flag for fluid FlFeed
ValidFlProd I4 Validation flag for fluid FlProd
Subroutine-specific Data
Member Type Description
IS1 I4 An array containing scalar integer data. Contents
may change for each type of utility subroutine.

4-20 Modular Utility Subroutines February 2009

 Table 4-2: class_UASOBJ Data Member
IA2 DP An array for integer array data. Contents may
change.
IA3 DP Another array for integer array data. Contents
may change.
DS1 DP An array of double precision floating-point
data. Contents may change for each type of
utility subroutine.
DA2 DP An array for floating point array data. Often
contains binary diffusion coefficients. Contents
may change.
DA3 DP An array for floating point array data. Often
contains binary mass transfer coefficients.
Contents may change.
DA4 DP An array for floating point array data. Contents
may change.
DA5 DP An array for floating point array data. Contents
may change.
The following validation flags take the following values:
1 = Array is allocated and populated with valid data.
0 = allocated but empty.
-1 = missing.
ValidIS1 I4 Validation flag for array IS1
ValidIA2 I4 Validation flag for array IA2
ValidIA3 I4 Validation flag for array IA3
ValidDS1 I4 Validation flag for array DS1
ValidDA2 I4 Validation flag for array DA2
ValidDA3 I4 Validation flag for array DA3
ValidDA4 I4 Validation flag for array DA4
ValidDA5 I4 Validation flag for array DA5
Output Data to Return
Member Type Description
Results DP Calculated Results returned to PRO/II. Number
of elements and dimensional units are different
for each type of user-added subroutine.

PRO/II User-Added Subroutine User Guide 4-21

 Table 4-2: class_UASOBJ Data Member
ISOLVE I4 Solution flag to return UAS
0 = no processing took place
1 = solved successfully (expected value)
2 = errors encountered, but results returned
3 = failed, stop calculations
SizeR1 I4 First extent of Results vector (1), not a return
value
SizeR2 I4 Second extent of Results vector (1), not a return
value
ValidResults I4 Validation flag for Results array.
1 = Results array passed in containing valid
data.
0 = Results array passed in empty, but allocated.
-1 = Results array is absent.
User-defined Data
Member Type Description
LenINT I4 Size of INTdata array
LenPAR I4 Size of PARdata array
LenDBL I4 Size of DBLdata array
INTdata I4 User-supplied integer data
PARdata I4 User-supplied PARAMETER data
DBLdata I4 User-supplied supplementary data
Logical File Units
Member Type Description
LfuInput I4 A logical file unit to be used for data input
LfuData I4 A logical file unit to be used for intermediate
data storage
LfuOutput I4 A logical file unit to be used for writing results
The MEMBER column lists the exact name of each member. These names are
used for direct access to the data from within the data object; e.g.
IAObj%NOC

4-22 Modular Utility Subroutines February 2009

 Table 4-2: class_UASOBJ Data Member
The Type column indicates the data type declared for each entry
C nnn Character string containing up to nnn characters
I4 Integer(4) integer scalar value (one 4 byte word)
L4 Logical(4) logical scalar variable (one 4 byte word) The only
possible values are TRUE or FALSE.
DP A REAL(8) double precision floating point scalar value

Module Identification Data

The data in this section is available to verify the identity of a user-
added subroutine that PRO/II calls. This data is useful when PRO/II
fails to find a called user-added subroutine.
Module User-Added Subroutines must be registered in the PRO/II
user-added subroutine registration file. The end user must acquire
the UasType and UasName from the developer of the subroutine. See
“Registering a UAS with PRO/II” on page 2-5 for an extensive dis-
cussion of the registration process.
The UasPath depends upon where the end-user installs the user-
added direct link library. Normally, this may be anywhere on a com-
puter or a network that PRO/II is able to access. (Subroutine devel-
opers may place constraints on the installed location.)
The UasID must be unique among all the ID’s in the specific section
of the P2UasReg.ini file (where the subroutine is registered). The end
user may choose any desired identifier, subject to any constraints
imposed by the subroutine developer.
The UasVersion typically is of little interest to an end user, but may be
quite important to a subroutine developer.

UasType Identifies the type of utility subroutine being called,

including:
UAIFAREA Interfacial Area subroutine.
UAMASSTR Mass transfer coefficient subroutine.
UAHEATTR Heat transfer Coefficient subroutine.
These types correspond to the sections in the P2UasReg.ini
file for the types of user-added subroutines supported by
PRO/II. SIMSCI defines these types.

PRO/II User-Added Subroutine User Guide 4-23

 UasPath Registered path to the directory that contains the DLL
containing the UAUTIL currently being called. Not used
by any UAUOP. PRO/II looks up this member and
extracts it from the [UASPATH] section of the P2UasReg.ini
file.
UasName Actual name of the interface subroutine that PRO/II calls.
It is the entry in the column labeled UAS routine name in
the section identified by the UasType member (above) in
the P2UasReg.ini file.
UasID Registered ID of the called UAS. It is an entry in the UAS
identifier column in the section identified by the UasType
member (above) in the P2UasReg.ini file.
UasVersion Version of the UAS set by the developer of the UAS.

General Data
Data in this section is important, because it includes various flags
that inform the subroutine what PRO/II expects it to do.

ThermoFl Thermodynamic method set flag. This is the ID number

of the Thermodynamic Method Set that PRO/II used to
compute component and fluid properties. Currently, no
user-added subroutines need to compute these properties,
since all available data passes in from PRO/II.
Consequently, this member is not needed.
DiagnosticFl Diagnostic flag, for use only by the UAS developer.
PRO/II does not allow the user to enter a value for this
member, so it cannot be used. However, during subroutine
implementation, the developer could set this value in the
code of the user-added subroutine. This could be useful
for writing diagnostic messages from the routine under
development. The Developer has the responsibility of
defining values for this flag.
UomSystem UOM system flag
1 = PRO/II internal
2 = English
3 = Metric
4 = SI
This member is read from the P2UasReg.ini file. The user
needs to enter this when registering the subroutine.

4-24 Modular Utility Subroutines February 2009

 Context Context flag (a character string)
INPUT
CROSSCHECK
CALCULATION
OPCALC post convergence
REPORT
iContext Integer version of the Context flag.
1 INPUT
2 CROSSCHECK
3 CALCULATION
4 OPCALC
5 REPORT
The context flag is essential, because it informs the user-
added subroutine what PRO/II expects it to do. In the
CALCULATION context, the subroutine must return a
complete set of valid values in the Results member of
UASOBJ. PRO/II does not expect results in any other
context. In addition, it should return ISOLVE=1.
Developers may use either the character Context or the
integer iContext to perform logical branching in the code.
Phase Phase of interest (PRO/II applies the results to this phase)
0 = Calculations are not phase-dependent
1 = Vapor
2 = Liquid
Some utility subroutines compute results that apply to a
specific fluid phase; others do not. The Phase flag
indicates which phase is requested, if any. Currently,
PRO/II only requests bulk liquid and bulk vapor results.
CallerID ID of calling Unit Operation. This may be useful when
generating error messages from the user-added
subroutine.
Exist Logical TRUE if the UASOBJ object is populated with
valid data. Normally, testing this member in the user-
added code is not necessary. It may be useful to
developers during code development.

Component Data
The component data members in Table 4-2 are generic, since the
same data set is passed to all types of utility routine supported by
PRO/II.
NOC Total number of components in problem

PRO/II User-Added Subroutine User Guide 4-25

 CompIndex(i) Internal component numbers, in input order. i
= 1, NOC.
Components and component data delivered to a utility subroutine
are always sorted in their order of appearance in the input data of
the simulation. In keyword input, the COMPONENT DATA section of
input declares all components and assigns them ordinal numbers.
However, PRO/II internally reorders the components to gain calcu-
lation efficiency. The CompIndex(i) array contains the internal compo-
nent number for each component.
For example, assume the input file contains three components:

COMPONENT DATA
LIBID 1,EBENZENE / 3, H2
POLY 2,PS
PRO/II internally orders the components as:
1, H2 / 2, EBENZENE / 3, PS
The following table shows the relationship of CompIndex elements to
input order and internal order.
Input Internal
Order Component CompIndex Order
1 EBENZENE (1) = 2
2 PS (2) = 3
3 H2 (3) = 1

Fluid Data
A fluid is the user-added analog of a PRO/II material flow stream.
See “Data Structure of class_Fluid” on page 6-27 for a list of all
available data in each fluid.
Each type of user-added utility subroutine defines its own set of flu-
ids. For example, the interfacial area subroutine includes three sepa-
rate fluids, while an HTC subroutine has none at all. Refer to the
chapters that describe individual types of utility subroutines for the
fluid members available in each specific type of utility routine. The
following discussion lists all fluids supported by the UASOBJ data
object. A typical user-added subroutine does not include every fluid
listed here.
FlVapor A fluid object that contains the data for the stage
bulk vapor phase. It supports data for the total fluid
and for the bulk vapor phase. Since the fluid is all

4-26 Modular Utility Subroutines February 2009

 vapor, the data for the total fluid and the vapor phase
are identical.
FlLiquid A fluid object that contains the data for the stage
bulk liquid phase. It supports data for the total fluid
and for the bulk liquid phase. Since the fluid is all
liquid, the data for the total fluid and bulk liquid
phase are identical. It does not include any data for
possible liquid sub-phases.
FlIface A fluid object that contains data for the Total fluid,
bulk vapor phase, and bulk liquid phase. It does not
include data for any possible liquid sub-phases.
FlFeed A fluid object that contains data for the combined
feed stream of a simulation object. Currently, none of
the utility subroutines allow a feed stream. An
FlFeed fluid contains phase members for total
fluid, bulk vapor phase, and bulk liquid phase. It
does not include data for any possible liquid sub-
phases, solids, or electrolyte phases.
FlProd A fluid object that contains data for the combined
product stream of a simulation object. Currently,
none of the utility subroutines allow an FlProd
stream. An FlProd fluid contains phase members
for total fluid, bulk vapor phase, and bulk liquid
phase. It does not include data for any possible liquid
sub-phases, solids, or electrolyte phases.
The variables listed below are validation flags that correspond to
the fluids listed above. They allow user-added subroutine code to
determine which fluids are present and contain data from PRO/II.

ValidFlVapor Validation flag for fluid FlVapor

ValidFlLiqui Validation flag for fluid FlLiquid
d
ValidFlIface Validation flag for fluid FlIface
ValidFlIFeed Validation flag for fluid FlIFeed
ValidFlProd Validation flag for fluid FlProd

Each flag may have any of the following values.

Values of Validation Flags

PRO/II User-Added Subroutine User Guide 4-27

 Value Description
1 Array is allocated and populated with valid data
0 Array is allocated but empty. Do not use data from the array
-1 Array is not allocated. Do not attempt to use the array

Developers should test the appropriate validation flag before using

the data from a particular fluid. Do not use data from a fluid when
the validation flag is less than one.

Subroutine-specific Data
Each type of utility subroutine has its own unique data require-
ments. To provide storage for different data, the UASOBJ data
structure contains several generic arrays that PRO/II resizes and
fills before each call to a user-added utility subroutine. Refer to the
chapters that describe individual types of utility subroutines for list-
ings of available data.
IS1 A one-dimension array containing scalar integer data.
Contents defined by each UAS.
IA2 A two-dimension array for integer array data. Contents
defined by each UAS.
IA3 Another two-dimension array for integer array data.
Contents defined by each UAS.
DS1 A one-dimension array of double precision floating-point
data. Contents defined by each UAS.
DA2 A two-dimension array for floating point array data.
Often contains binary diffusion coefficients. Contents
defined by each UAS.
DA3 A two-dimension array for floating point array data.
Often contains binary mass transfer coefficients. Contents
defined by each UAS.
DA4 A two-dimension array for floating point array data.
Contents defined by each UAS.
DA5 A two-dimension array for floating point array data.
Contents defined by each UAS.

The size and data content for each array are different for each type
of subroutine. Developers should refer to the data listings in the
chapter that describes the particular type of subroutine under devel-
opment. For example, refer to See “Interfacial Area Data Mem-
bers” on page 11-2, when developing an Interfacial Area utility
subroutine.

4-28 Modular Utility Subroutines February 2009

 The variables listed below are validation flags that allow user-added
subroutines to determine which arrays were populated by PRO/II.

ValidIS1 Validation flag for array IS1

ValidIA2 Validation flag for array IA2
ValidIA3 Validation flag for array IA3
ValidDS1 Validation flag for array DS1
ValidDA2 Validation flag for array DA2
ValidDA3 Validation flag for array DA3
ValidDA4 Validation flag for array DA4
ValidDA5 Validation flag for array DA5
Each flag may have any of the following values.

Values of Validation Flags

Value Description
1 Array is allocated and populated with valid data.
0 Array is allocated but empty. Do not retrieve data from the
array.
-1 Array is not allocated. Do not attempt to use the array.

Developers should test the appropriate validation flag before using

the data from a particular array. A value of “1” indicates the data in
an array is available for use. Do not use data from an array when the
validation flag is less than one.

Returned Results (required)

The interfacial area calculation subroutine must return two values to
PRO/II:
ISOLVE Required integer scalar returned solution flag. Use a
value for ISOLVE from Table 2-4 on page 2-18. Always
return ISOLVE= 1 when returning reasonable values in
the Results array. See “ISOLVE Return Values” on
page 2-18 for more information.
Results(1,1) Returned calculated values. Different types of utility
subroutines return different values. This is a two-
dimension array, even when returning a single value.
See “Results Return Values” on page 4-4. Also, refer
to the chapters that describe each utility type for the
specific return values that PRO/II requires.

PRO/II User-Added Subroutine User Guide 4-29

 The following two data members are not return values, but are
included here to complete the documentation.

SizeR1 First dimension of the Results array. The value always is 1.

SizeR2 Second dimension of the Results array. The value always is 1.
The class_UASOBJ constructor sizes the Results array as
Results(SizeR1,SizeR2).

Logical File Units

Developers of utility subroutines may wish to read or write data to
files outside the control of PRO/II. The file units described here
are provided to ensure that the external file units used by a subrou-
tine do not conflict with file units used by PRO/II. No utility sub-
routines currently supported by PRO/II have access to this feature.

LfuInput A logical file unit to be used for data input. Not available.
LfuData A logical file unit to be used for intermediate data
storage. Not available.
LfuOutput A logical file unit to be used for writing results outside
the PRO/II output report. Not available.

class_Fluid.mod and class_FluidPhase.mod

These modules make fluid and phase data objects available to user-
added subroutines. The number of fluids in the UASOBJ object of a
utility subroutine may be different in each type of user-added sub-
routine. Each fluid object may contain one or more PHASE objects,
depending upon the phase state that the fluid represents.
See Chapter 6, UAS Modular Fluids for thorough information about
class_Fluid and class_FluidPhase.

4-30 Modular Utility Subroutines February 2009

 Chapter 5
Modular Unit Operations

Overview
Modular user-added unit operations (UAUOP) allow users and other
independent developers to extend PRO/II with their own unit opera-
tions. User-added unit operations are fully integrated into PRO/II,
so their execution is indistinguishable from that of the internal unit
operation models.
Developers define their own data structures using an information
(INI) file associated with each model. Supported data types include
integer, double precision, and character data. The data structures
allow scalar data and single-dimension arrays of almost any reason-
able size. Developers may assign names and units of measure in the
data definition.
PRO/II does not call user-added subroutines during input process-
ing, but UAUOP input processing is based on the data structure
defined by the developer. Both the PRO/II keyword input facilities
and PROVISION support these features. PROVISION provides
basic minimal data entry windows that support all the input data
allowed by key words.
The XML-based AutoGUI allows developers to create a custom
interactive Graphical Interface for each UAUOP. When AutoGUI is
used, PROVISION displays the AutoGUI DEW’s instead of the
default windows. It is much more powerful than the custom inter-
face available for the older procedural user-added unit operations.
In the course of a simulation, PRO/II calls modular user-added unit
operations to perform the following functions.
Validate input data during CROSSCHECK execution.
Perform calculations during the CALCUATION phase, as part of
the flowsheet solution.
Perform post-convergence calculations in the OPASS phase
(after the simulation flowsheet has converged).
Write final results during the REPORT phase of a simulation.
The first section of this chapter present useful information to users
running simulations that include user-added unit operations. Later
sections are intended for developers who create and implement the
user-added unit operation models.

PRO/II User-Added Subroutine User Guide 5-1

Keyword Summary
Unit Identification (required)
UAUOP( <uoptype> ), UID=<uid> {, NAME=<text>, PRINT= 1, &
BYPASS= 1, PLOT, DIAGNOSTIC= 1}, &
CALOPTION( CALC or OUT )= 1

Sides, Feeds and Products (required)

SIDE( sideid ) FEED=sid {, sid, ... }, PROD=sid {, sid, ..., ) &
METHOD=setid

Annotations (optional)
NOTE TEXT= <text>

User-supplied Data (conditional)

Integer Data
INT( name or seqno ) intval1 {, intval2, .... }

Parameter Data
PAR( name or seqno ) parval1 {, parval2, .... }

Double Data
DBL( name or seqno ) dblval1 {, dblval2, .... }

Text Data
TEXT( name or idno {, elno}) txtval1 {, txtval2, .... }

Exporting Scalar Parameters (optional)

DEFINE <parname> AS <uauoptype>=<uid>, PAR( seqno ) &
{,<op>, <ref>}

Importing Scalar Parameters (optional)

DEFINE PAR( seqno ) AS <uoptype>=<uid>, <param> &
{,<op>, <ref>}
or
DEFINE PAR( seqno ) AS STREAM=<sid>, <prop> &
{, <op>, <ref> }

5-2 Modular Unit Operations February 2009

User Information
Keyword Input
Data for modular unit operations is entered in the UNIT OPERA-
TION section of a keyword input file. The input conventions
described here generally agree with those in Chapter 10.2,”Unit
Operation Input” of the PRO/II Keyword Input Manual. Any varia-
tions from the normal input conventions are presented here.

Unit Identification (required)

UAUOP( <uoptype> ), UID=<uid> {, NAME=<text>, PRINT= 1,&
BYPASS= 1, PLOT, DIAGNOSTIC= 1},&
CALOPTION( CALC or OUT )= 1
This card is required as the first card of input for each user-added
unit operation.
UAUOP( <uoptype> ) The <uoptype> qualifier specifies the type
of user-added unit operation. It is the identifier regis-
tered in the [UAUOP] section of the UASREG.INI file.
UID=<uid> A standard entry required by PRO/II. <uid> is a charac-
ter string of up to 12 characters that uniquely identifies a
specific instance of the UAUOP in the flowsheet.
NAME=<text> A standard optional PRO/II entry. <text> is descrip-
tive text up to 40 characters.
BYPASS Specifies the calculation contexts in which PRO/II calls
the unit. Table 5-1 defines the available values.
Table 5-1: Bypass Options
Bypass Value Description
1 CALCULATE context during flowsheet convergence only.
This is the default.
2 OPASS context after flowsheet convergence only
3 Both CALC and OPASS contexts during and after flow
sheet convergence.

When the BYPASS keyword or it’s argument is missing,

PRO/II assumes BYPASS=1. The bypass flag does not affect
other contexts. The unit operation always is called for CROSS-
CHECK and REPORT contexts. The developer may implement
the PRINT option to control output in the REPORT context.
The following entry definitions merely describe the intended pur-
pose of the keyword. The actual significance is defined by the
developer of the model. These options may or may not be supported

PRO/II User-Added Subroutine User Guide 5-3

 in any specific user-added unit operation. The limitations that are
listed are imposed by PRO/II. Any specific UAUOP may impose
more stringent constraints. Users must obtain the input require-
ments from the model developer, not from SIMSCI.
PRINT=ival An optional flag that developers may implement to
allow users to control report generation. Variable PrintFL
assumes the value of ival. When this keyword is miss-
ing, PrintFL = 0. When the keyword is present without
an argument value, PrintFL=1.
PLOT An optional logical flag that does not accept an argu-
ment. Presence of the keyword sets the PlotFL variable
to TRUE to request any available plots. When omitted,
the value is FALSE.
CALOPT( qual )=ival A compound flag for controlling calcula-
tions. Entering CALCULATE for qual sets variable
CalOpContext = 1, indicating an option during flowsheet
convergence. Setting qual to OPASS sets CalOpFlag=2,
indicating OPASS context. CALCULATE is the default
when the keyword is present without a qualifier value.
CalOpValue = 0 when the keyword is missing.
The numeric argument was originally intended to spec-
ify the number of zones in heat exchanger zones analysis
calculations. However, the significance may be rede-
fined by the developer, or not implemented. It has a
default value of 5 and a range between 1 and 50.
DIAGNOSTIC Requests intermediate results or trace back reports.
The numeric argument may be any integer value. PRO/II
assigns a value of 1 when the keyword is present but the
argument is missing.

Sides, Feeds and Products (required)

Sides partition unit operations into sections. Many unit operations
have a single side; for example, a pump or a flash drum. Other units
are multi-sided, such as heat exchangers that have a shell side and a
tube side. PRO/II allows each UAUOP to have up to 10 sides.
Each SIDE statement declares information for one side of the
model. Developers of the model determine the total number of
sides, which are required, which are optional, and which feeds and
products are required or optional. Usually, user-added unit opera-
tions require at least one side, typically side number 1.
To be included in flowsheet calculations, each unit operation must
have at least one feed stream. If it has no feeds, it will be skipped.
This is a requirement of the PRO/II calculation sequencer. No feeds

5-4 Modular Unit Operations February 2009

 are required for units that perform calculations only in the OPASS
context (i.e., when BYPASS=2). PRO/II allows each side to have
between zero and 10 feeds.
Products are always optional. PRO/II allows each side to have
between zero and 10 products.
SIDE( sideid or sideno ) FEED=sid {, sid, ... }, &
PROD=sid {, sid, ..., ), METHOD=setid
sideid An identifier of up to 32 characters, assigned by the
developer, that uniquely identifies the side. The first
character of the sideid must be a letter (A -Z). Since each
side implicitly has an integer sequence number, the side
number (sideno) may be used instead of the sideid.
FEED Specifies the feed streams to the side. When this key-
word is present, it requires at least one stream identifier.
Up to 10 feeds are allowed by PRO/II.

Note: At least one side must have at least one FEED. If this
requirement is not satisfied, the unit will be skipped during flow-
sheet convergence calculations.
PROD When this keyword is present, it requires at least one
stream identifier.Products always are optional. Omit this
keyword on sides that do not have products.
METHOD This declares the thermodynamic METHOD set used by
the side. Each side in the unit operation may have a dif-
ferent METHOD. The METHOD must be declared in the
THERMODYNAMIC DATA section of the input file. If
this entry is missing, PRO/II assigns the DEFAULT
METHOD to the side.

User-supplied Data (conditional)

The data types INT, PAR, and DBL allow both scalar and array data.
Arrays are all single dimension.
Every user-supplied input data item has an ordinal sequence num-
ber (seqno) assigned to it by the developer. Optionally, it also may
have an assigned name (name). The keyword input statements
described here allow users to identify data items using either the
(seqno) or the (name).

Integer Data
INT( name or seqno ) intval1 {, intval2, .... }

PRO/II User-Added Subroutine User Guide 5-5

 Parameter Data
PAR( name or seqno ) parval1 {, parval2, .... }

Double Data
DBL( name or seqno ) parval1 {, parval2, .... }
Any number of INT, PAR, and DBL statements may appear in an
input file. Data for more than one variable may appear in each
statement. All data for an array should appear in order on a single
statement.
Numeric Data Example:
Consider the following (partial) data storage definition.
Table 5-2: Sample Numeric Data Definition
Type seqno ID Name Size Value
PAR 1 First 1 1.0
PAR 2 Second 3 2.1
3 2.2
4 2.3
PAR 5 Third 2 3.1
6 3.2
7 Fourth 1 4.0

All the data in Table 5-2 may be entered on a single PAR state-
ment:
PAR( First ) 1.1, 2.1, 2.2, 2.3, 3.1. 3.2, 4.0
Alternatively, several PAR statements could be used:
PAR( First ) 1.1
PAR( Second ) 2.1, 2.2, 2.3
PAR( Third ) 3.1, 3.2
PAR( Fourth ) 4.0
Statements may use sequence numbers instead of ID names.
PAR( 1 ) 1.1
PAR( 2 ) 2.1, 2.2, 2.3
PAR( 5 ) 3.1, 3.2
PAR( 7 ) 4.0
Enter all values of an array in order on a single statement. Val-
ues for single elements of arrays should not be entered. For
example, it is invalid to input only element 2 of PAR( 2 ) :
PAR( Second ) , 2.2 ! This is invalid.
However, the following is valid

5-6 Modular Unit Operations February 2009

 PAR( 3 ) 2.2 (Where 3 is the sequence number of element 2 of
array Second.)
All the strategies demonstrated in the preceding examples also
apply to INT, DBL, and TEXT data.

Text Data
TEXT( name or idno {, elno}) txtval1 {, txtval2, .... }
TEXT statements behave differently than the INT, PAR, and DBL
statements. Text statements use an ID number or name in conjunc-
tion with an element number to identify the first data entry on the
statement.
name or The name of the TEXT variable or array.
idno The unique ID number assigned to the TEXT variable or
array. One or the other must be the first qualifier in the
parenthesis.
elno A TEXT array element number that stores the first data
value. Subsequent data values are stored sequentially in
the next storage elements. This entry is not applicable
for a scalar text item. Element 1 is the default when elno
is omitted for an array item.
Text Data Example:
Consider the following (partial) data storage definition.
Table 5-3: Sample Text Data Definition
Type idno ID Name Size elno Value
TEXT 1 First 1 1 A1
TEXT 2 Tarray 3 1 B2.1
- 2 B2.2
- 3 B2.3
TEXT 3 Third 2 1 C3

All the data in Table 5-3 may be entered on a single TEXT

statement:
TEXT( First ) “A1”, “B2.1”,”B2.2”,“B2.3”, “C3”
Alternatively, several PAR statements could be used:
TEXT( First ) “A1”
TEXT( Tarray ) “B2.1”, ”B2.2”, “B2.3”
TEXT( Third ) “C3”
Statements may use ID numbers instead of ID names.
TEXT( 1 ) 1.1

PRO/II User-Added Subroutine User Guide 5-7

 TEXT( 2 ) 2.1, 2.2, 2.3
TEXT( 3 ) 3.1, 3.2
Values for single elements of arrays also may be entered using
element numbers. For example, enter data for Tarray (3) as:
TEXT( Tarray, 3 ) “B2.3”
or
TEXT( Tarray, 1 ) “B2.1”, “B2.2”

Where 1 is the element of Tarray used to store the first value.

The second value “B2.2” is stored in Tarray(2).
Each text variable has a limit (imposed by the developer) on the
number of characters it may contain. The limit applies to each ele-
ment in a TEXT array. Text strings that contain embedded blanks or
commas must be enclosed in quotation marks.

Exporting Scalar Parameters

DEFINE <parname> AS <uauoptype>=<uid>, PAR( seqno ) &
{,<op>, <ref>}
This statement is used in other unit operations (such as controllers
and optimizers) to import PAR data from a UAUOP. The UAUOP
exports a scalar value to the importing unit operation. Refer to
Chapter 10.5, Define, in the “PRO/II Keyword Manual”. The first
100 PAR values are available for this usage.
<parname> Identifies the item that receives the value in the import-
ing unit operation. When the importing unit is another
UAUOP, <parname> must have the form: PAR(seqno).
<uauoptype> This element specifies the type of user-added unit
operation that will supply the data. It is the identifier reg-
istered in the [UAUOP] section of the UASREG.INI file.
<uid> A standard entry required by PRO/II. Keyword UID is
required. <uid> is a character string of up to 12 charac-
ters that uniquely identifies a specific instance of the
UAUOP in the flowsheet.

PAR( seqno ) The PAR keyword is required. The seqno qualifier is

the sequence number of one scalar PAR value in the
UAUOP. Only scalar PAR values may be accessed; how-
ever, it may be an element of a PAR array. Using the
name of the PAR is not supported. It must be accessed
using the sequence number.

5-8 Modular Unit Operations February 2009

 Importing Scalar Parameters
DEFINE PAR( seqno ) AS <uoptype>=<uid>, <param> &
{,<op>, <ref>}
or
DEFINE PAR( seqno ) AS STREAM=<sid>, <prop> &
{, <op>, <ref> }
The DEFINE statements for importing PAR values are part of the
input for a UAUOP. Each DEFINE imports a single scalar value
from other unit operations and flowsheet streams. Their usage is
described in Chapter 10.5, Define, in the “PRO/II Keyword Man-
ual”.
PAR( seqno ) This entry identifies the PAR element that receives
the value in the UAUOP. The first 100 PAR values are
available for use. The ( seqno ) qualifier is the sequence
number. Using the name of the PAR is not supported.
<uoptype> This qualifier is required to identify the type of unit
operation that supplies the data value. It may be any unit
operation in the flowsheet, including another user-added
unit operation.
<param> Identifies the data item to import from the source unit
operation. When the source unit operation is another
UAUOP, this entry must take the form PAR( seqno ). For
example,
UAUOP(Ex1Uop) UID=myUaUop1
DEFINE PAR(2) AS STREAM=S2, TEMPERATURE(K)
DEFINE PAR(3) AS FLASH=FLA1, PRES
Keep in mind that the UAUOP developer defines the data in the
PAR array. This includes declaring units of measure. The examples
immediately above assume that PAR(2) has temperature units and
PAR(3) has pressure units. This is important when importing or
exporting parameter values, since the PRO/II DEFINE subsystem
applies numeric conversions to data having dimensional units of
measure.
PRO/II provides an extensive slate of unit operation parameters and
stream properties that are accessible through the DEFINE sub-
system. Refer to Chapter 10.3, Flowsheet Parameters, in the “PRO/
II Keyword Manual” for more information.

PRO/II User-Added Subroutine User Guide 5-9

 PROVISION Input
Figure 5-1: UAUOP Icon on PFD Palette
.When user-added unit operations are registered in
the P2UasReg.ini file, PROVISION automatically
adds icons to the PFD palette so users can select
them. This is shown in Figure 5-1.
The new icon is separate from the “User-added
Unit” icon (that allows selection of the procedural
unit operations described in Chapter 18, “Classic
Unit Operations”).
To add a UAUOP to a simulation, simply click the
icon to select it. Move the mouse cursor to the
main “Flowsheet” window and left-click the
mouse. A UAUOP icon appears at the position
of the cursor. This is exactly the same procedure
used to add any other unit operation to the
simulation.
To enter or edit input data, right-click the UAUOP icon in the main
“Flowsheet” window. This opens the pop-up “action menu”. Click
the “Data Entry...” menu item shown in Figure 5-2.
Figure 5-2: Opening a UAUOP Date Entry Window

PROVISION includes generic Data Entry Windows that allow

users to enter data for a UAUOP. The generic DEW supports input
for all data declared in the INI file associated with the UAUOP.
However, the layout is extremely simple.
By using the optional AutoGui in PRO/II, the developer of the
UAUOP can create a much more sophisticated DEW that organizes

5-10 Modular Unit Operations February 2009

 user input in a more user-friendly format. Figure 5-3 shows part of a
fairly simple example of a custom AutoGui DEW.
Figure 5-3: Sample Custom AutoGui DEW

Clicking the tabs near the top of the window display additional data
input dialog boxes. Notice the data have been grouped and have
labels. It is even possible to change the units of measure. Chapter 8,
“UAUOP AutoGUI” explains how to create and use AutoGui win-
dows.

PRO/II User-Added Subroutine User Guide 5-11

 UAUOP User Options

Calculation Options
PRO/II provides a CALOPTION flag on the UAUOP statement of
keyword input that allows simulation users to control optional cal-
culations in a UAUOP. Developers may or may not choose to imple-
ment this in their models.

Final Reports
PRO/II calls each UAUOP during the REPORT context to allow it
to generate a report of its results. Interface routine UAOUT may be
used for this purpose. When the UAUOP does not include report-
writing code, PRO/II can write a default report for it. The UAUOP
developer controls whether or not PRO/II writes a default report by
returning an appropriate code in the ISOLVE variable.

Optional Reports
The UAUOP keyword statement provides several flags that devel-
opers may implement to control optional output. Developers should
inform users of any options they implement for the following flags.
DIAGNOSTIC=ival This flag is intended to allow simulation users
to control the generation of trace back and debugging
information. The ival argument accepts any integer
value. The default is ival=0.
PRINT=ival A flag intended to control optional or additional
reports. Typical uses include controlling intermediate
output during calculations, or extended output in the
final report. The ival argument accepts any integer
value. The default is ival=0.
PLOT PRO/II provides a PLOT flag on the UAUOP statement
of keyword input that allows simulation users to control
the generation of plotted results. Developers may or may
not choose to implement this in their models.

UAUOP Installation and Registration

It is the user’s responsibility to install and register user-added unit
operations before attempting to use them from PRO/II. Users must
obtain specific installation instructions from the developer of each
UAUOP; not from SIMSCI. See “Registering [UAUOP] User-
Added Unit Operations” on page 2-11 of Chapter 2 in this manual
to learn about the registration procedure.

5-12 Modular Unit Operations February 2009

Developer Information
The remainder of this chapter is intended for developers of user-
added unit operations. This material is not essential for users who
only use pre-built modular utilities in PRO/II simulations; but they
may find some of the material informative.

Data Exchange between PRO/II and UAUOP Routines

Almost all unit operation data is encapsulated in a UAUOP data
object that is an argument in the subroutine call list. The syntax of
the call to a UAUOP always has the following form:
CALL myUaUop( CONTEXT, UopObj, ISOLVE )
Where:
myUaUop The name of the interface subroutine called by PRO/II.
The developer replaces myUaUop with an actual subrou-
tine name and registers it in the [UAUOP] section of the
P2UasReg.INI file along with other information.

CONTEXT This input variable is a flag that tells the UAUOP what
actions PRO/II expects it to perform. A short summary
of these options appears on page 5-13 of this chapter. A
more complete explanation is available in “Contexts in
PRO/II” on page 2-17 of Chapter 2, “Modular UAS
Build Procedures”.
UopObj This argument is the UAUOP data structure that passes
in all unit operation input data and returns all calculated
values. It is discussed extensively in the remainder of
this chapter.
ISOLVE This output variable is the only information PRO/II
requires a UAUOP to return. See “ISOLVE Return Val-
ues” on page 2-18 of Chapter 2, “Modular UAS Build
Procedures”.
Other types of data are accessed through interface classes, such as
class_Fluid (Chapter 6) and class_DMUOM (Chapter 7).

Contexts Involving a UAUOP

PRO/II defines several contexts that perform different types of
operations during a simulation. Table 5-4 lists the contexts in which
PRO/II makes calls to user-added unit operations.
Table 5-4: Contexts for a UAUOP in PRO/II
Context UAUOP AutoGui Description

PRO/II User-Added Subroutine User Guide 5-13

 Table 5-4: Contexts for a UAUOP in PRO/II

INPUT Not Called Read and Store input data

called

CROSS- Called Not Verify input data

CHECK called

CALCULATE Called Not Perform calculations

called

OPASS Called Not Perform calculations

called

REPORT Called Not Generate final output report

called

Contexts are more fully defined in Chapter 2. See “Contexts in

PRO/II” on page 2-17. PRO/II expects each UAUOP to support all
the contexts. If an optional AutoGui Data Entry Window is imple-
mented, PRO/II calls it only during the INPUT context.

ISOLVE Return Values from a UAUOP

Whenever PRO/II calls a UAUOP, it expects the UAS to perform
specific actions. PRO/II requires the UAUOP to return a valid value
for ISOLVE after each call. Table 5-5 lists the valid return values
that PRO/II accepts from a user-added unit operation..
Table 5-5: ISOLVE Values returned from a Utility
ISOLVE
Description
Returns
0 UAS performed no action, PRO/II attempts to
continue. No other returned results expected.
1 UAS successfully completed processing, PRO/II
continues normally. Other returned results expected.
2 UAS Failed – PRO/II continues flowsheet execution.
Other returned results expected.
3 UAS Failed – PRO/II terminates (flowsheet
execution). No other returned results expected.

The “expected” return value in all contests is ISOLVE = 1. Values of

2 or 3 always indicate an error condition. When a UAUOP does not
support a context, it should return ISOLVE = 0 to indicate “no action
taken”.
In a UAUOP call, ISOLVE is an argument in the subroutine call list.
Always set the ISOLVE variable in the argument list. The UAUOP
data object also passes in a copy of ISOLVE as one of its members.

5-14 Modular Unit Operations February 2009

 It is not used by PRO/II; however, it is a safe practice to set ISOLVE
both in the call argument variable and in the UAUOP object.

Example Setting ISOLVE:

The following code sample illustrates setting both instances of
ISOLVE in the interface subroutine.
SUBROUTINE myUOP( CONTEXT, UOPOBJ, ISOLVE )
CHARACTER(10) :: CONTEXT
TYPE(UAUOP) :: UOPOBJ
INTEGER(4) :: ISOLVE, iErr
IF( CONTEXT(1:4) .EQ. “CALC” ) THEN
ISOLVE = 2 ! assume failure
CALL myCalcs( UAUOP, iErr )
IF( iErr .EQ. 0 ) ISOLVE = 1 ! success
ELSE
ISOLVE = 0 ! all other contexts
END IF
UOPOBJ%ISOLVE = ISOLVE ! sets the copy
The branching logic is based on the CONTEXT flag passed in
from PRO/II. For the CALCULATION context only, subroutine
myCalcs is called. If no error occurred, myCalcs returns iErr =
0, and ISOLVE is set to 1; otherwise it returns an error value of
2. In all other contexts, ISOLVE returns zero indicating “no
action performed”. See “ISOLVE Return Values” on page 2-18
of Chapter 2 for more general information.

Results Return Values

Other than the ISOLVE argument variable, PRO/II does not require
any specific results to be returned from a UAUOP. There are two
mechanisms that allow a UAUOP to return results to PRO/II.
Calculated UAUOP results return in the IntValue, ParValue,
DblValue, and TxtValue members of the UAUOP data object.
PRO/II always stores these arrays upon return from the user-
added unit operation.
Fluid data is stored in PRO/II streams by the user-added unit
operation. It does not return through the argument list of the
subroutine.
Storage for calculated results must be defined in the INI file associ-
ate with the UAUOP. Any values stored by the UAUOP are available
in all subsequent calls to the UAUOP from PRO/II. Values stored in
the first 100 elements of the PARVALUE array are available for
use throughout the flowsheet by using the DEFINE subsystem.

PRO/II User-Added Subroutine User Guide 5-15

 Dimensional Units
Each user-added unit operation exchanges data with PRO/II in a
consistent set of dimensional units. The UOM’s are defined by the
developer in the INI file that defines the data storage of the UAUOP.
The developer chooses one of several UOM sets provided by
PRO/II. Additionally, specific units of measure may be assigned to
each dimensional class in the set of dimensional units. These defini-
tions are described later in this chapter in the discussion of the INI
file.
When calling the UAUOP, PRO/II ensures all data are converted to
the units of measure declared in the INI file. This is independent of
the UOM’s used by users to supply input data.
Users writing a keyword input file need to know which data use
which dimensional units. In contrast, a properly constructed
AutoGui window will display the UOM’s. Either way, it is good
practice for developers to inform users of the correct set of units in
their installation and usage instructions.
Refer to Chapter 7, “User-Added Units of Measure”, for lists of the
available sets of units, including all dimensional classes. The lists
include the exact unit of measure used by each class for each avail-
able set of units.

Coding Guidelines
Each user-added unit operation should have its own interface rou-
tine written in Fortran 90. The interface subroutine is called directly
from PRO/II. It includes the branching logic needed to implement
all the different contexts that PRO/II requires it to support. This
facilitates implementing the calculation code, cross-check code, and
report code in separate subroutines. This approach can greatly sim-
plify the coding effort. It also can enhance the portability of the
code by concentrating many (or all) dependencies on PRO/II in the
interface routine. The examples presented in this manual all use
separate subroutines for the call interface, the calculation algorithm,
the report writer, and other supported functionality.
PRO/II passes an instance of the UAUOP data class through the
argument list when it calls a user-added unit operation. This elimi-
nates the need for long argument lists in subroutine call.
A user-added unit operation must “instantiate” the data class so data
can be retrieved and stored. Earlier versions for Fortran, such as
Fortran 77 or Fortran 66, do not provide this capability.
All PRO/II modular interfaces conform to the Fortran 90 standard
as much as possible. However, dynamic calls to external DLL’s are
outside the strict domain of the Fortran standards. PRO/II uses

5-16 Modular Unit Operations February 2009

 extensions to the Fortran 90 language to accomplish this. In the
examples in this manual, the extensions are illustrated using
Compaq Visual Fortran version 6.6b. They will be different if other
compilers are used.

Coding A UAUOP Interface Routine

Each user-added unit operation requires a standard interface routine
so PRO/II can call it. The interface routine must conform exactly to
the requirements presented here. Using a separate interface routine
removes the PRO/II constraints from the calculation routine.
Figure 5-4 illustrates the essentials of a basic interface subroutine.
Figure 5-4: Sample Interface Routine Called by PRO/II
1 SUBROUTINE UOP1MAIN( CONTEXT, UopObj, iSolve )
2 !DEC$ ATTRIBUTES DLLEXPORT:: UOP1MAIN ! Export UOP1Main
3 !___________________________________________________________
4 ! |
5 ! Variables in Argument list |
6 ! Name Type I/O Brief Description |
7 ! -------- ------ --- ------------------------------------- |
8 ! CONTEXT C*10 I Type of Action requested by PRO/II !
9 ! "CROSSCHECK" - Verify input data !
10 ! "CALCULATE" - calculate a solution !
11 ! "OPASS" - Post flowsheet calcs !
12 ! "REPORT" - Write final report !
13 ! UopObj UaUop I/O UaUOp Data object instance !
14 ! ISOLVE INT O Required return status flag !
15 !___________________________________________________________|
16 !
17 USE class_UAUOP ! Interface module for a UAUOP
18 !
19 IMPLICIT NONE
20 CHARACTER(LEN=*), INTENT(IN) :: CONTEXT
21 TYPE(UAUOP), INTENT(INOUT) :: UopObj ! define dataobj !
22 INTEGER(4), INTENT(OUT) :: iSolve
23 !
24 IF( CONTEXT(1:9) .EQ. "CALCULATE" ) THEN
25 CALL Uop1Calc( UopObj, iSolve )
26 ELSE IF( CONTEXT(1:10) .EQ. "CROSSCHECK" ) THEN
27 CALL Uop1Cros( UopObj, iSolve )
28 ELSE IF( CONTEXT(1:5) .EQ. "OPASS" ) THEN
29 iSolve = 0 ! not supported in this example
30 ELSE IF( CONTEXT(1:6) .EQ. "REPORT" ) THEN
31 CALL Uop1Repo( UopObj, iSolve )
32 ELSE
33 iSolve = 0
34 ENDIF
35 !
36 UopObj%ISOLVE = ISOLVE
37 END SUBROUTINE UASMAIN

PRO/II User-Added Subroutine User Guide 5-17

 Notes about Figure 5-4:
Line 1 illustrates the exact argument list that PRO/II requires. Argu-
ment UopObj is an instance of the UAUOP class.
Line 2 is the Compaq Visual Fortran compiler directive that exports
UOP1MAIN from the DLL so PRO/II can call it.

Lines 3 through 16 simply document the call argument variables.

Line 17 makes class_UAUOP available in the subroutine.
Line 19, IMPLICIT NONE, requires explicit type declarations for all
variables in the subroutine (a good coding practice). Note that data
members of DataObj do not need to be declared; since class_ UAUOP
always explicitly declares all of its data members.
Line 21 declares variable UopObj as an instance of class_UAUOP.
This makes the “public” data and member functions in UopObj avail-
able for use within the subroutine.
Lines 24 through 34 constitute an IF-THEN-ELSE construct that
branches to different subroutines based on the context.
Line 23 compares the first nine characters of variable CONTEXT to
the literal string “CALCULATE” (always all upper-case), a pre-defined
context string used by PRO/II. If this test evaluates to TRUE, subrou-
tine UOP1CALC is called to perform the main calculations of the
unit operation. If it evaluates to FALSE, control passes to line 26.
Line 26 tests the first ten characters of variable context against literal
string “CROSSCHECK” (always all upper-case). If TRUE, line 27 calls
subroutine UOP1CROS to perform input data validation tests. This
illustrates the modular separation of functionality, where the calcu-
lation algorithm is coded in one subroutine, while the crosscheck
code is in a different subroutine. If the test at line 26 evaluates
FALSE, control passes to lines 28.

Line 28 tests for the OPASS context, branching in the same manner
as the previous IF clauses. This example does not support OPASS
calculations, and sets ISOLVE = 0 to indicate this.
Line 30 follows the same pattern, branching on the REPORT
context.
Lines 32 and 33 are the default clause of the “IF” construct. If none
of the preceding clauses evaluate TRUE, control passes to line 33. In
this case, the subroutine does nothing except set the ISOLVE return
variable to 0 to indicate the subroutine did nothing.
Line 36 sets the ISOLVE member of UopObj data structure to match
the ISOLVE variable. This is not required, but is a safe practice.

5-18 Modular Unit Operations February 2009

 Finally, line 37 ends the subroutine. When control reaches this line,
the subroutine exits and returns to PRO/II. Note the omission of a
Fortran 77 RETURN statement. It is not required by Fortran 90.
With simple modifications, the sample code of Figure 5-4 is suit-
able for use by any UAUOP. For example, to support OPASS calcu-
lations, simply replace line 29 with a call to an appropriate
subroutine. To disable one of the supported contexts, replace
the subroutine call with ISOLVE = 0 at line 25, 27, or 31, as
appropriate.

Coding A Unit Operation Calculation Routine

Typically, the calculation code should appear in a routine separate
from the interface routine. In this approach, PRO/II only calls the
interface routine, and the interface is the only routine that calls the
calculation routine. This provides the most flexibility for writing
the code and modularizing the functionality. There are two primary
approaches for coding the call from the interface to the calculation
routine.
1. The interface routine performs all access to class_ UAUOP. It
extracts all necessary input data from UopObj into local vari-
ables and arrays; then passes all the local data as arguments in
the call to the calculation routine. The call to the calculation
routine would include arguments that return all calculated
results to the interface routine. After returning from the calcula-
tion routine, the interface routine stores the (returned) results in
UopObj and sets ISOLVE. This approach allows the calculation
routine to be completely self-contained, independent of PRO/
II, and portable for use in other applications.
2. The interface routine calls the calculation routine with few
arguments, but passes UopObj in the call. This option is demon-
strated in the sample code of Figure 5-4. The calculation rou-
tine would use “class_ UAUOP” and directly extract the input
data from that data structure. This simplifies the call between
the interface and calculation routines. It also allows the calcula-
tion routine to work directly with the input data and store
results in a straightforward manner. However, this creates a
dependency of the calculation routine on class_ UAUOP. Using
this approach, the calculation routine could be used only when
called by PRO/II, and would not be readily available for use in
other applications.
Either approach is equally valid; the choice is left to the developer.
Refer to the topic “Direct Member Addressing in class_UAUOP”
on page 5-20 to learn more about using class_UAUOP.

PRO/II User-Added Subroutine User Guide 5-19

Definition of class_ UAUOP.mod
This module makes class_ UAUOP available in modular user-added
unit operations. The class includes a data structure that is passed as
an argument in the subroutine call list. This section describes all the
data in the UAUOP data structure. It also describes the proper usage
of the class. PRO/II does not support using class_ UAUOP in user-
added utility (UAUTIL) subroutines.

Usage of class_ UAUOP

PRO/II passes an instance of the UAUOP data object to each user-
added unit operation that it calls. Before using the data structure, the
user-added subroutine code must make several declarations.
Calling Sequence:
SUBROUTINE myUop( CONTEXT, UopObj, ISOLVE )
!DEC$ ATTRIBUTES DLLEXPORT :: myUop
USE class_UAUOP
TYPE(UAUOP) UopObj
INTEGER(4), INTENT(IN) :: CONTEXT
INTEGER(4), INTENT(OUT) :: ISOLVE
The second argument in the subroutine call list is the variable
to declare as a UAUOP instance. This allows data in the data
object to pass between PRO/II and the user-added subroutine.
See “Coding A UAUOP Interface Routine” on page 5-17.
Be sure to export the subroutine from the DLL. Use either the
!DEC$ ATTRIBRUTES statement shown above, or an external
“.DEF” export file.
USE class_UAUOP Include this statement to bring in the defi-
nition of the UAUOP data structure.
TYPE(UAUOP) UopObj This statement declares the UopObj
argument variable as a UAUOP instance. This makes the local
instance of UAUOP accessible by within the subroutine.
Two common methods of accessing the data in a module are:
Direct member addressing is fully supported in class_UAUOP.
Indirect accessor routines (using member accessor routines) is
not supported by class_UAUOP.
The following sections discuss both data access methods.

Direct Member Addressing in class_UAUOP

Direct member addressing accesses data by direct reference to the
data member. Fortran 90 defines the percent symbol % as the mem-

5-20 Modular Unit Operations February 2009

 ber selection operator. Consider the following data structure as an
analog of a UAUOP data structure.
TYPE ONESIDE
INTEGER(4) :: FeedCount
INTEGER(4) :: FeedNo( 20 )
CHARACTER(LEN=lszIdChar) :: FeedID( 20 )
END TYPE ONESIDE

TYPE UAUOP
INTEGER(4) :: NOC
REAL(8), DIMENSION(30) :: ParValue
INTEGER(4) :: SideCount
CHARACTER(LEN=32) :: SideName( 3 )
TYPE( OneSide ), DIMENSION(3) :: Side
END TYPE UAUOP
TYPE ONESIDE defines one side of a UAUOP, while TYPE
UAUOP defines a UAUOP data structure that allows up to 3 sides.

Each user-added unit operation subroutine contains the following

statements:
SUBROUTINE myUop( CONTEXT, UopObj, ISOLVE )
USE class_UAUOP
TYPE(UAUOP) UopObj
The TYPE(UAUOP) statement declares variable UopObj as a UAUOP
structure that includes the 3 sides. Some valid references in the
user-added unit operation subroutine might be:
numComps = UopObj%NOC ! Number of components
numSides = UopObj%SideCount ! Actual number of sides
The above statements retrieve scalar data from the UopObj storage
object. Array data is accessed in the same manner.
cNameSide= UopObj%SideName( 2 ) ! Name of Side 2
UserPar3 = UopObj%ParValue( 3 ) ! Element 3 of PAR
The “parent % member” paradigm is extensible to any level in the data
structure. For example,
nFeed3 = UopObj%Side(3)%FeedCount
cFeed = UopObj%Side(3)%FeedID( nFeed3 )
Local variable nFeed3 retrieves the actual number of feeds to side
3. Character variable cFeed retrieves the name of the last feed to
side 3. It is possible to access any data member in any sub-structure
of UAUOP in this manner.
Table 5-6 lists all data members available in the UAUOP data struc-
ture. The first column, labeled “Member”, is the exact name of the
data member to use for direct member addressing.

PRO/II User-Added Subroutine User Guide 5-21

 Indirect Access in class_UAUOP
The module class_UAUOP does not provide any accessor functions
at this time. All data is accessed using direct member addressing, as
described in the previous topic.

Data Structure of class_UAUOP

Table 5-6 defines the data structure in class_UAUOP. Table 5-6 lists
the data structure of one SIDE member of UAUOP. The member
DMUOM is itself another class object that is defined in Chapter 7.
Table 5-6: class_UAUOP Data Members
Member Type Description
Module Data
ModType C 12 Identifies the class_UAUOP module as
“UAUOP“. Set only by PRO/II.
ModVersion C 12 Version of class_UAUOP, typically “8.0".
Set only by PRO/II. (setting is not reliable.)
ProgID C 64 Program ID of a COM object. Not applicable
in a UAUOP. Set in the INI file.

UAUOP Identification and Access Data

UasType C 32 Identifies the type of this UAUOP
subroutine. Set in the INI file.
UasVersion C 12 Version of the UAUOP. May be set by the
developer by the UAUOP subroutine code.
UasRoutine C 64 Name of the interface routine called by PRO/
II to access this particular UAUOP model.
Set in the INI file.
UasFile C 40 File name of the DLL that contains this
UAUOP. Set in the INI file.
UasPath C 256 Path to directory where the DLL file resides.
Set in the INI file.
UasID C 12 PRO/II UID of this instance of the UAUOP
in each simulation. User input.
UasIdNo I4 PRO/II sequence number of this instance of
the unit operation in a simulation. Set by
PRO/II.
UasName C 40 Descriptive name of the model. User input.
CallerID C12 ID of the PRO/II routine that called the
UAUOP.

5-22 Modular Unit Operations February 2009

 Table 5-6: class_UAUOP Data Members
Member Type Description
General Data
Context C 12 PRO/II Context flag “INPUT”
“CROSSCHECK” “CALCULATION”
“OPASS” “REPORT”
iContext I4 Integer version of Context flag
1 INPUT 2 CROSSCHECK
3 CALCULATION 4 OPASS
5 REPORT
BypassFl I4 Calculation bypass flag, user input. Refer to
the UAUOP statement of Keyword Input
earlier in this chapter.
CalOpContext I4 Calculation context option flag. See the
UAUOP statement of Keyword Input.
CalOpValue I4 Calculation Option argument value. Defined
by the developer.
DiagnosticFl I4 Diagnostic flag, user input. Refer to the
UAUOP statement of Keyword Input earlier
in this chapter.
LFUout I4 Logical File unit for standard PRO/II output
PlotFl I4 Plot option flag, user input. Refer to the
UAUOP statement of Keyword Input.
PrintFl I4 Print option flag, user input. Refer to the
UAUOP statement of Keyword Input.
Exist L4 Logical TRUE if UAUOP contains valid data
Component Data
NOC I4 Total number of components in the
simulation
NOCMW I4 Number of molecular weight components
CompIndex( I4 Internal component numbers, in input order.
n) n = 1, NOC
Dimensional Units of Measure
Factors DMUOM Data object containing UOM data and
conversion factors. See Chapter 7.
Side Data
SideCount I4 Number of sides in the UAUOP. User input.
Side( ns ) Side Array of side-data objects. ns = 1, SideCount
See Table 5-8.

PRO/II User-Added Subroutine User Guide 5-23

 Table 5-6: class_UAUOP Data Members
Member Type Description
INT Input and Results Data
IntExtent I4 Total INT storage available (32 bit words)
IntCount I4 Number of defined INT variables
IntValue( n ) I4 Values of every element of every INT
variable
n = 1, IntExtent
IntSize( i ) I4 Number of elements in each INT
i = 1, IntCount
IntMapNo( i ) I4 Offset to first element of each INT variable.
i = 1, IntCountt.
IntLower( i ) I4 Lower bound limit of each INT variable.
i = 1, IntCountt
IntUpper( i ) I4 Upper bound limit of each INT variable.
i = 1, IntCountt.
IntName( i ) C 32 Name of every INT variable.
i = 1, IntCountt.
IntMinName( i ) I4 Number of characters in each INT name that
makes the name unique. i = 1, IntCountt
PAR Input and Results Data
ParExtent I4 Total PAR storage available. (64 bit words),
from INI file.
ParCount I4 Number of defined PAR variables, from INI
file.
ParValue(i) I4 Values of every element of every PAR
variable. i = 1, ParExtent.
ParSize( i ) I4 Number of elements in each PAR array, from
INI file. i = 1, ParCount.
ParMapNo( i ) I4 Offset to first element of each PAR variable.
i = 1, ParCount.
ParUomClass( i ) I4 Unit of measure class (temp, pres, etc.) of
each PAR variable, from INI file.
i = 1, ParCount.
ParLower( i ) I4 Lower bound limit of each PAR variable,
from INI file. i = 1, ParCount
ParUpper( i ) I4 Upper bound limit of each PAR variable,
from INI file. i = 1, ParCount.
ParName( i ) C 32 Name of every PAR variable, from INI file.
i = 1, ParCount.
ParMinName( i ) I4 Number of characters in each PAR name that
makes the name unique. i = 1, ParCount.

5-24 Modular Unit Operations February 2009

 Table 5-6: class_UAUOP Data Members
Member Type Description
DBL Input and Results Data
DblExtent I4 Total DBL storage available. (64 bit words),
from INI file.
DblCount I4 Number of defined DBL variables, from INI
file.
DblValue( i ) I4 Values of every element of every DBL
variable.
i = 1, DblExtent
DblSize( i ) I4 Number of elements in each DBL array i, from
INI file. i = 1, DblCount
DblMapNo( i ) I4 Offset to first element of each DBL variable.
i = 1, DblCount.
DblUomClass( i ) I4 Unit of measure class (temp, pres, etc.) of
each DBL variable i, from INI file.
i = 1, DblCount
DblLower( i ) I4 Lower bound limit of each DBL variable,
from INI file. i = 1, DblCount
DblUpper( i ) I4 Upper bound limit of each DBL variable,
from INI file. i = 1, DblCount.
DblName( i ) C 32 Name of every DBL variable, from INI file.
i = 1, DblCount
DblMinName( i ) I4 Number of characters in each DBL name that
makes the name unique. i = 1, DblCount
TEXT Input and Results Data
TxtExtent I4 Total TXT storage available. (Char*4 words)
from INI file.
TxtCount I4 Number of defined TXT variables from INI
file.
TxtMaxChr I4 Maximum characters allowed in any element
of any TXT variable. Computed from TEXT
definitions in the INI file.
TxtValue( i ) I4 Values of every element of every TXT
variable
i = 1, TxtExtent
TxtMapNo( i ) I4 Offset to first element of each TXT variable.
i = 1, TxtCount.
TxtSize( i ) I4 Number of elements in each TXT array, from
INI file. i = 1, TxtCount

PRO/II User-Added Subroutine User Guide 5-25

 Table 5-6: class_UAUOP Data Members
Member Type Description
TxtWidth( i ) I4 Maximum characters allowed in each
element of each TXT variable, from INI file.
i = 1, TxtCount
TxtName( i ) C 32 Name of every TXT variable, from INI file.
i = 1, TxtCount.
TxtMinName( i ) I4 Number of characters in each TXT name that
makes the name unique. i = 1, TxtCount.
Output Data
ISOLVE I4 Solution flag to return UAS.
0 = no processing took place
1 = solved successfully (expected value)
2 = errors encountered, but results returned
3 = failed, stop calculations
The MEMBER column lists the exact name of each member. These
names are used for direct access to the data from within the data object;
e.g. UopObj%NOC
The Type column indicates the data type declared for each entry
C nnn Character string containing up to nnn characters
I4 Integer scalar value (one 4 byte word)
L4 Logical scalar variable (one 4 byte word) The possible
values are .TRUE. and .FALSE.
DP A Real(8) double precision floating point scalar value

Module Data
The data in this section allows developers to determine the version
of the UAUOP module being used.
ModType Always identifies the module as “UAUOP’.

ModVersion The version of the module that changes whenever

changes are made to the module itself. This may include
adding or modifying the data structure or any accessor
functions. The current version is “8.0”.
ProgID This is used only by COM objects in PRO/II and is not
generally meaningful for a UAUOP. The ProgID is used
to register a COM object in the Windows® operating
system.

UAUOP Identification and Access Data

The variables in this section allow developers to add their own iden-
tification information and make it available inside the user-added

5-26 Modular Unit Operations February 2009

 subroutine. It includes information registered in the P2UasReg.ini
file by the user and used by PRO/II to access the UAUOP during a
simulation run.
UasType This is the text string that uniquely identifies the
UAUOP to PRO/II. Developers define it using the
UATYPE=UasType entry in the [Access] section of the
INI file. Users register it as the UATYPE entry in the
[UAUOP] section of the P2UasReg.ini file.
In keyword input, users declare the exact same string
on each UAUOP statement of UNIT OP input. For
example, UAUOP( Ex1Uop ) UID=U1, where Ex1Uop is
the registered UasType.
UasVersion Version of the UAS set by the developer of the UAS.
The code to set this must be implemented in a routine
written by the UAUOP developer. PRO/II simply
saves the data in the storage of the UAUOP in each
simulation.
UasRoutine The exact name of the interface routine called by PRO/
II for this UAUOP. The developer defines this name as
the ROUTINE=UasName entry in the [Access] section of
the INI file.
UasFile The complete name of the library file that contains the
user-written code of the UAUOP. This name includes
the DLL suffix. It does not contain any directory or
path information. The developer defines this name as
the DLL=Uasfile.DLL entry in the [Access] section of the
INI file.
UasPath The complete path to the directory that contains the
UasFile DLL. It should end with a back-slashes (\), and
does not include the UasFile name. The developer
defines this using the PATH=UasPath entry in the
[Access] section of the INI file.
UasID This is the 12 character identifier of one specific
instance of the UAUOP in a simulation.
In keyword input, the user declares a different UasID
on each UAUOP statement of UNIT OP input. For
example, UAUOP( Ex1Uop ) UID=U1, where U1 is the
UasID. of that specific unit operation.
UasIdNo Integer unit sequence number of the UAUOP in a
simulation. Every unit operation in a PRO/II
simulation is assigned a sequence number (seqno)
during input data processing. UasIdNo is the seqno
currently assigned to the current UAUOP.

PRO/II User-Added Subroutine User Guide 5-27

 UasName An optional 40 character descriptive name for a
specific instance of the UAUOP in a simulation. It may
be any text and does not need to be unique.
In keyword input, users may declare this using the
NAME keyword on the UAUOP statement; e.g,
UAUOP(Ex1Uop) UID=U1, NAME=MyName, where
MyName is the UasName.
CallerID 12 character ID of the PRO/II routine that called the
unit operation. Typically this is routine UAUOP_CA in
all contexts. Intended as a debugging aid, this variable
probably is not too useful.

General Data
Data in this section includes various flags that inform the subroutine
what actions PRO/II expects it to perform.
Context Context flag (See “Contexts Involving a UAUOP”
on page 5-13 of this chapter.)
“ INPUT” “ CROSSCHECK”
“CALCULATION” “OPASS”
“REPORT”
iContext Integer version of the Context flag. (See“Contexts
Involving a UAUOP” on page 5-13 of this chapter.)
1 = INPUT 2 = CROSSCHECK
3 = CALCULATION 4 = OPASS
5 = REPORT
BypassFL The calculation bypass flag on the UAUOP statement of
keyword input. Refer to Table 5-1, ”Bypass Options,”
on page 3 of this chapter.
CalOpContext An integer flag for the context qualifier of the
CalOption entry on the UAUOP statement of keyword
input. For example,
UAUOP(Ex1Uop) UID-U2, CALOP(Context)=ival
when Context = CALC, CalOpContext = 1
Context = OUT, CalOpContext = 2
CalOpValue An integer flag for the value of the ival argument to the
CalOption entry on the UAUOP statement of keyword
input. For example,
UAUOP(Ex1Uop) UID-U2, CALOP(Context)=ival
where ival is the value of CalOpValue. Developers
define the significance of CalOpValue (if any).

5-28 Modular Unit Operations February 2009

 DiagnosticFl A flag that lets developers request diagnostic reports
during a simulation through keyword input. An
example of keyword usage is:
UAUOP( EX1UOP), UID=U2, DIAGNOSTIC=2
This sample input sets DiagnosticFL = 2. Developers
define values for this flag.
LFUout This is the Logical File Unit used by PRO/II to
generate primary output reporting. The file may
change depending on the execution context. See
“Output and Reporting” on page 5 of Chapter 3.
PrintFl The integer value of the Print option on the UAUOP
statement. An example of keyword usage is:
UAUOP( EX1UOP), UID=U2, PRINT=2
This sample input sets PrintFL = 2. Developers define
values they support for this flag.
PlotFL The integer value of the PLOT flag option on the
UAUOP statement. The PLOT option does not accept an
argument value. An example of keyword usage is:
UAUOP( EX1UOP), UID=U2, PLOT
The example sets PlotFL = 1. PlotFL values have the
following meaning.
0 = No PLOT entry (on the UAUOP statement).
1 = PLOT entry specified by user input.
Exist Logical TRUE when the UAUOP object contains valid
data. If for some reason the UAUOP data structure has
not been initialized, this flag is FALSE. Normally,
testing this member in the user-added code is not
necessary. It may be useful to developers during code
development.

Component Data
NOC Total number of components in a simulation
NOCMW Number of molecular weight components in a
simulation. NMWSolids are excluded. When no
NMWSolids are in the simulation, NOCMW = NOC.
CompIndex(i) Internal component numbers, in input order.
i = 1, NOC.

Components and component data delivered to a UAUOP are always

sorted in their order of appearance in the input data of the simula-
tion. In keyword input, the COMPONENT DATA section of input
declares all components and assigns them ordinal numbers. This
define the component Input Order. However, PRO/II reorders the

PRO/II User-Added Subroutine User Guide 5-29

 components into Internal Order to gain calculation efficiency. See
“Internal Component Order vs. Print Order” on page 40 of Chapter
15.
All component data exchanged between a UAUOP and PRO/II are
in Input Order. The CompIndex array contains the internal compo-
nent number for each component. Developers should not have too
much need to directly manipulate the CompIndex array. It is used
mainly as an argument in call-back routines that provide data
exchange between a UAUOP and PRO/II.
For example, assume the input file contains three components:
COMPONENT DATA
LIBID 1,EBENZENE / 3, H2
POLY 2,PS
PRO/II internally orders the components as:
1, H2 / 2, EBENZENE / 3, PS
Table 5-7 shows the relationship of CompIndex elements to input
order and internal order.
Table 5-7: Input versus PRO/II Internal Component Ordering
Input Order Component CompIndex Internal Order
1 EBENZENE (1) 2
2 PS (2) 3
3 H2 (3) 1

Dimensional Units of Measure Data

Dimensional units handling is handled in class_DMUOM. Refer to
Chapter 7 for an extensive discussion of units of measure in any
modular user-added subroutine, including UAUOP..
Factors This is a DMUOM object that contains conversion
factors and UOM accessor functions for converting
data between USER and P2Internal units of measure
in a UAUOP. Refer to Chapter 7.

Side Data
Every UAUOP always contains at least one SIDE. See “Data Struc-
ture of One Side” on page 5-38. The SIDE concept allows logical
partitioning of the functionality and data storage in a unit operation
model. Some information, such as the number of sides, applies to
all the sides as an aggregate. The data members listed here are
members of the UAUOP itself.

5-30 Modular Unit Operations February 2009

 SideCount The number of sides that the UAUOP contains. This is
defined using the MAXSides entry in the [Sides] section of
the associated INI file. Note: some sides may not require
input data in every simulation.
Sides( ns ) An array of SIDE objects, with one member for each
SIDE in the UAUOP. Index ns ranges from 1 to
SideCount.

Integer User Data and Calculated Results

All integer data values for a UAUOP are stored in a single array.
Additional arrays provide auxiliary information useful to
developers.
IntExtent A scalar integer that allocates the total storage available
for integer data. It is set using the TOTINT entry in the
[Data Definition] section of the INI file of the UAUOP.
Storage is counted using 32-bit integer words.
IntCount The number of INT variables and arrays allowed to be
defined on INT statements in the [Data Definition] section
of the INI file. IntCount is defined using the MAXINT
entry in the [Data Definition] section of the INI file of the
UAUOP. Each array and each scalar is a single count.

IntValue(n) Array of integer values, including all user input and all
calculated results. Individual INT variables and arrays
are mapped into this array using the IntMapNo array
described below. Index n varies from 1 to IntExtent. In
keyword input, users use INT statements to provide
actual data values. The size of this array is declared by:
INTEGER(4) IntValue( IntExtent )
IntSize(i) The number of 32-bit integer words used to store each
INT member. The sizes are defined on INT statements in
the [Data Definition] section of the INI file of the UAUOP.
Index i varies from 1 to IntCount.
IntMapNo(i) Each element i contains the starting storage address of
an INT variable or array in the IntValue array. Index i var-
ies from 1 to IntCount. The value of element i is n, the
position of the data value in IntValue(n). This is gener-
ated from data in the [Data Definition] section of the INI
file.
IntLower(i) The lower limit value of any element of INT scalar or
array i. Limits are defined on INT statements in the INI
file. PRO/II uses this to validate user input data. It

PRO/II User-Added Subroutine User Guide 5-31

 applies to each element of an array. Index i varies from 1
to IntCount.
IntUpper(i) The lower limit value of any element of INT scalar or
array i. Limits are defined on INT statements in the INI
file. PRO/II uses this to validate user input data. It
applies to each element of an array. Index i varies from 1
to IntCount.
IntName(i) A character string name of up to 32 characters for each
integer scalar or array i. It is defined on INT statements
in the [Data Definition] section of the INI file of the
UAUOP. Index i varies from 1 to IntCount.

IntMinName(n) The minimum number of characters that makes

IntName(i) unique among all names of INT variables and
arrays. It is defined on INT statements in the [Data Defi-
nition] section of the INI file Index i varies from 1 to
IntCount.

Example: Using Integer Data

The following code fragment demonstrates accessing Integer data
from UAUOP storage. Assume the UAUOP data object is named
UopObj; INT(3) is a scalar and INT(4) is a 4 element array.
iLoc3 = UopObj%IntMapNo(3)! locate INT(3) value
iVal3 = UopObj%IntValue( iLoc3 ) ! get INT(3) value
cNam3 = UopObj%IntName( 3 ) ! get name of INT(3)
LimLo = UopObj%IntLower(3 ) ! get lower bound
LimHi = UopObj%IntUpper(3 ) ! get upper bound
IF( iVal3 .LT. LimLo ) THEN
UopObj%IntValue( iLoc3 ) = LimLo ! Set IVAL(3)
ELSE IF( iVal3 .GT. LimHi ) THEN
UopObj%IntValue( iLoc3 ) = LimHi ! Set IVAL(3)
END IF
! Work with element 2 of array INT(4)
iLoc4 = UopObj%IntMapNo(4 ) ! first INT(4) location
iSize = UopObj%IntSize( 4 ) ! get size of INT(4)
IF( iSize .GE. 2 ) THEN ! test size of INT(4)
iVal4el2 = IntValue( iLoc4 + 1) ! get element 2
!
! Test value of element 2 of INT(4) against the upper limit
! and reset it to upper limit if out of range
!
IF( iVal4El2 .GT. UopObj%IntUpper(4) THEN
IntValue( iLoc4 + 1) = UopObj%IntUpper(4)
END IF
cNam4 = UopObj%IntName( 4 ) ! get name of INT(4)

5-32 Modular Unit Operations February 2009

 PARAMETER User Data and Calculated Results
Parameter data are double precision values. In keyword input, the
PAR statements provide user-supplied values. Calculated results
also may be stored here, although the DBL data arrays are preferred
for this purpose.
PAR data are the only UAUOP data available to the PRO/II SPEC/
VARY/DEFINE subsystems. See “Exporting Scalar Parameters” on
page 5-8 and “Importing Scalar Parameters” on page 5-9 earlier in
this chapter. The SPEC/VARY/DEFINE subsystems support only
scalar values stored in the first 100 elements of the ParValue array.
ParExtent A scalar integer that allocates the total storage available
for double precision PAR data. It is set by developers
using the TOTPAR entry in the [Data Definition] section
of the INI file of the UAUOP. Storage is counted using
64-bit words.
ParCount A scalar integer value defined using the MAXPAR entry
in the [Data Definition] section of the INI file of the
UAUOP. ParCount is the number of PAR variables and
arrays allowed on PAR statements in the INI file. Each
array and each scalar is a single count.
ParValue(n) Array of all PAR data values, including all user input
and all calculated results. Individual PAR variables and
arrays are mapped into this array by the ParMapNo array
described below. Index n varies from 1 to ParExtent. In
keyword input, users use PAR statements to provide
actual data values. The size of this array is declared by:
Real(8) ParValue( ParExtent )
ParUomClass(i) An integer value that identifies the units of mea-
sure class of a PAR member. The class applies to all ele-
ments of a PAR array. The actual dimensional unit is the
user unit declared for the UOM class in the [UOM] sec-
tion of the INI file. Index i varies from 1 to ParCount.
ParSize(i) The number of 64-bit floating-point words used to store
each PAR member. The sizes are defined on PAR state-
ments in the [Data Definition] section of the INI file of the
UAUOP. Index i varies from 1 to ParCount.

ParMapNo(i) Each element i contains the starting storage address of

a PAR variable or array in the ParValue array. This is
generated from data in the [Data Definition] section of the
INI file. Index i varies from 1 to ParCount.

PRO/II User-Added Subroutine User Guide 5-33

 ParLower(i) The lower limit value of a PAR scalar or any element
of PAR array i. Limits are defined on PAR statements in
the INI file. PRO/II uses this to validate user input data.
Index i varies from 1 to ParCount.
ParUpper(i) The upper limit value of a PAR scalar or any element
of PAR array i. Limits are defined on PAR statements in
the INI file. PRO/II uses this to validate user input data.
Index i varies from 1 to ParCount.
ParName(i) A character string name of up to 32 characters for each
PAR scalar or array i. It is defined on PAR statements in
the [Data Definition] section of the INI file of the UAUOP.
Index i varies from 1 to ParCount.
ParMinName(n) The minimum number of characters that makes
ParName(i) unique among all names of PAR variables
and arrays. It is defined on PAR statements in the [Data
Definition] section of the INI file. Index i varies from 1 to
ParCount.

Example: Using PAR Data

The following code fragment demonstrates accessing PAR data
from UAUOP storage. The accessing strategy is analogous to
accessing INT data (demonstrated above). Assume the UAUOP data
object is named UopObj; PAR(3) is a scalar and PAR(4) is a 4 ele-
ment array.
iLoc3 = UopObj%ParMapNo(3) ! locate PAR(3) value
Val3 = UopObj%ParValue( iLoc3 ) ! get PAR(3) value
cNam3 = UopObj%ParName( 3 ) ! get name of PAR(3)
boundLo = UopObj%ParLower(3 ) ! get lower bound
boundHi = UopObj%ParUpper(3 ) ! get upper bound
IF( Val3 .LT. BoundLo ) THEN
UopObj%ParValue( iLoc3 ) = BoundLo ! Set PAR(3)
ELSE IF( Val3 .GT. BoundHi ) THEN
UopObj%ParValue( iLoc3 ) = BoundHi ! Set PAR(3)
END IF
! Work with last element of array Par(4)
iSize = UopObj%ParSize( 4 ) ! get size of PAR(4)
IF( iSize .GE. 1 ) THEN ! test size of PAR(4)
!
! get value from last element of PAR(4)
!
iLoc4 = UopObj%ParMapNo(4) ! first PAR(4) location
Val4n = ParValue( iLoc4 + iSize - 1 )
!
! Test value of last element of PAR(4) against the upper limit
! and reset it to upper limit if out of range
!
IF( Val4n .GT. UopObj%ParUpper( 4 ) THEN

5-34 Modular Unit Operations February 2009

 ParValue( iLoc4 + 1) = UopObj%IntUpper(4)
END IF
!
! Get name of array PAR(4)
!
cNam4 = UopObj%IntName( 4 ) ! get name of PAR(4)

Double Precision User Data and Calculated Results

DBL data are double precision values. In keyword input, the DBL
statements allow user-supplied DBL data. Calculated results are
stored here, usually after user input values.
DBL data are not available to the PRO/II SPEC/VARY/DEFINE sub-
systems. In most other respects, they behave analogously to PAR
data.
DblExtent A scalar integer that allocates the total storage available
for double precision DBL data. It is set using the TOT-
DBL entry in the [Data Definition] section of the INI file
of the UAUOP. Storage is counted using 64-bit words.
DblCount A scalar integer value defined using the MAXDBL entry
in the [Data Definition] section of the INI file of the
UAUOP. DblCount is the number of DBL variables and
arrays allowed on DBL statements in the INI file. Each
array and each scalar is a single count.
DblValue(n) Array of all DBL data values, including all user input
and all calculated results. Individual DBL variables and
arrays are mapped into this array by the DblMapNo array
described below. Index n varies from 1 to DblExtent. In
keyword input, users use DBL statements to provide
actual data values. The size of this array is declared by:
Real(8) DblValue( DblExtent )
DblUomClass(i) An integer value that identifies the units of mea-
sure class of a DBL member. The class applies to all ele-
ments of a DBL array. The actual dimensional unit is the
user unit declared for the UOM class in the [UOM] sec-
tion of the INI file. Index i varies from 1 to DblCount.
DblSize(i) The number of 64-bit floating-point words used to store
each DBL member. The sizes are defined on DBL state-
ments in the [Data Definition] section of the INI file of the
UAUOP. Index i varies from 1 to DblCount.

DblMapNo(i) Each element i contains the starting storage address of

a DBL variable or array in the DblValue array. This is

PRO/II User-Added Subroutine User Guide 5-35

 generated from data in the [Data Definition] section of the
INI file. Index i varies from 1 to DblCount.

DblLower(i) The lower limit value of a DBL scalar or any element

of DBL array i. Limits are defined on DBL statements in
the INI file. PRO/II uses this to validate user input data.
Index i varies from 1 to DblCount.
DblUpper(i) The upper limit value of a DBL scalar or any element
of DBL array i. Limits are defined on DBL statements in
the INI file. PRO/II uses this to validate user input data.
Index i varies from 1 to DblCount.
DblName(i) A character string name of up to 32 characters for each
DBL scalar or array i. It is defined on DBL statements in
the [Data Definition] section of the INI file of the UAUOP.
Index i varies from 1 to DblCount.
DblMinName(n) The minimum number of characters that makes
DblName(i) unique among all names of DBL variables
and arrays. Index i varies from 1 to DblCount.
accessing DBL data is completely analogous to accessing PAR data.
Refer to the sample (above) for using PAR data.

Text User Data and Calculated Results

Text data are strings containing a maximum number of characters as
defined in the INI file. In keyword input, TEXT statements allow
user-supplied text data. Calculated results may be stored here, typi-
cally after user input values.
Because of the variable size of each value, the input and processing
requirements of TEXT data differs from INT, PAR, and DBL data.
TxtExtent A scalar integer that allocates the total storage available
for all TEXT data. It is set using the TOTTEX entry in the
[Data Definition] section of the INI file of the UAUOP.
Storage is counted in words that contain 4 characters per
word.
TxtCount A scalar integer value defined using the MAXTEX entry
in the [Data Definition] section of the INI file. TxtCount is
the number of TEXT variables and arrays allowed on
TEXT statements in the INI file. Each array and each sca-
lar is a single count.
TxtMaxChr This scalar integer is the maximum number of charac-
ters allowed in any TEXT scalar or any element of a
TEXT array. It is computed as the largest width defined

5-36 Modular Unit Operations February 2009

 on any TEXT statement in the INI file. For example, local
variable cText dimensioned
CHARACTER(LEN=Uopobj%TxtMaxChr) :: cText
will be sized adequately to contain one TEXT scalar or
one element of any TEXT array defined in the INI file.
TxtValue(n) Array of all TEXT data values, including all user input
and all calculated results. Individual TEXT variables and
arrays are mapped into this array by the TxtMapNo array
described below. Index n varies from 1 to TxtExtent. In
keyword input, users use DBL statements to provide
actual data values. The size of this array is declared by:
Real(8) DblValue( DblExtent )
TxtSize(i) The number of 64-bit floating-point words used to store
each DBL member. The sizes are defined on DBL state-
ments in the [Data Definition] section of the INI file of the
UAUOP. Index i varies from 1 to DblCount.

TxtWidth(i) The maximum number of characters allowed in one

element of TEXT member n. This limit applies to each
element in a TEXT array.
TxtMapNo(i) Each element i contains the starting storage address of
a TEXT variable or array in the TxtValue array. This is
generated from TEXT data in the [Data Definition] sec-
tion of the INI file. Index i varies from 1 to TxtCount.
TxtLower(i) The lower limit value of a DBL scalar or any element
of DBL array i. Limits are defined on DBL statements in
the INI file. PRO/II uses this to validate user input data.
Index i varies from 1 to DblCount.
TxtUpper(i) The upper limit value of a DBL scalar or any element
of DBL array i. Limits are defined on DBL statements in
the INI file. PRO/II uses this to validate user input data.
Index i varies from 1 to DblCount.
TxtName(i) A character string name of up to 32 characters for each
DBL scalar or array i. It is defined on DBL statements in
the [Data Definition] section of the INI file of the UAUOP.
Index i varies from 1 to DblCount.
TxtMinName(n) The minimum number of characters that makes
DblName(i) unique among all names of DBL variables
and arrays. Index i varies from 1 to DblCount.

PRO/II User-Added Subroutine User Guide 5-37

 Example: Using TEXT data
The following code fragment illustrates using text data. Assume the
UAUOP data object is named UopObj.

Data Structure of One Side

Each user-added unit operation includes an array of SIDE data
structures. The number of SIDEs in a UAUOP is defined by the
developer in the [SIDES] section of the INI file of the user-added
unit operation. Data specific to each individual SIDE is stored its
own data structure (which is one of the members of the SIDE array).
Table 5-8 defines the data in each SIDE.
Table 5-8: Side Data Members
Member Type Description
Identification
Name C 32 Descriptive name of the Side
Exist L4 Logical side validity flag. TRUE= valid data
Feed Data
MaxFeed I4 Maximum feeds allowed to this side
FeedCount I4 Number of feed streams to this side
FeedNo(n) I4 Array of feed stream sequence numbers
FeedID(n) C 16 Array of feed stream identifiers
Product Data
MaxProd I4 Maximum products allowed from this side
ProdCount I4 Number of product streams from this side
ProdNo(n) I4 Array of product stream sequence numbers
ProdID(n) C 16 Array of product stream identifiers
Thermodynamic METHOD Set
TherSetID C 16 Thermodynamic METHOD Set identifier
TherSetNo I4 Thermodynamic METHOD Set number

Name The name of the side, defined on each SIDE statement in

the [Sides] section of the associated INI file. The name
may include up to 32 characters.
Exist This logical flag indicates whether or not the SIDE con-
tains valid data. When Exist = TRUE, the data in the
SIDE object is valid. Do not attempt to use other data

5-38 Modular Unit Operations February 2009

 from this SIDE when Exist = FALSE. This flag should be
tested before accessing data from a SIDE that is optional.
MaxFeed The maximum number of feeds allowed by this SIDE.
MaxFeed is set by developers on each SIDE statement in
the [Sides] section of the INI file that configures the
UAUOP.

FeedCount The total number of feed streams to this side in a simu-

lation. This is the number of stream ID’s appearing as
arguments of the FEED keyword on the SIDE card of a
UAUOP in keyword input. In PROVISION, FeedCount
is the number of streams connected as feed streams to
this SIDE of the UAUOP icon in the PFD window. The
FeedCount cannot exceed MaxFeed.

FeedNo(n) This array contains the stream numbers of all the feeds
to the SIDE. Index n is an integer that may vary from 1
to FeedCount.
FeedID(n) An array of stream identifiers for the FEED streams to
this SIDE. Index n is an integer that may vary from 1 to
FeedCount.

MaxProd The maximum number of products allowed by this

SIDE. MaxProd is set by developers on each SIDE state-
ment in the [Sides] section of the INI file that configures
the UAUOP.
ProdCount The total number of product streams from this side in a
simulation. This is the number of stream ID’s appearing
as arguments of the PROD keyword on the SIDE card of
a UAUOP in keyword input. In PROVISION, ProdCount
is the number of streams connected as products of this
SIDE of the UAUOP icon in the PFD window. The Prod-
Count cannot exceed MaxProd.

ProdNo(n) This array contains the stream numbers of all the prod-
ucts of the SIDE. Index n is an integer that may vary
from 1 to ProdCount.
FeedID(n) An array of stream identifiers for the PROD streams to
this SIDE. Index n is an integer that may vary from 1 to
ProdCount.

TherSetID The identifier of the Thermodynamic METHOD set

assigned to the SIDE. It is the setid argument of the
METHOD=setid on the SIDE statement of keyword
input.

PRO/II User-Added Subroutine User Guide 5-39

 TherSetNo The set number of the Thermodynamic METHOD set
assigned to the SIDE. It refers to the same METHOD set
as TherSetID.

5-40 Modular Unit Operations February 2009

 Chapter 6
UAS Modular Fluids
Interface Software
This section discusses the facilities available for manipulating fluids
in user-added subroutines. All interfacing functions listed in Table
6-1 are available in class_Fluid.mod. This module is part of dynamic
link library USERLB6.DLL.
Table 6-1: Interface Software for Fluids
class_Fluid.mod
Function Calculation Routines See . . .
flash_Fluid Calculates the thermodynamic state of a fluid 6-3
Kcalc_Fluid Computes K-values, dK/dT, fugacity 6-11
coefficients, liquid activities, and
compressibility.
Fluid Manipulation Functions
create_Fluid Instantiates a fluid 6-14
load_Fluid Fills a fluid with data from a PRO/II stream 6-16
copy_Fluid Copies all data from one fluid to another 6-17
store_Fluid Stores partial fluid data in a PRO/II stream 6-18
free_Fluid Destroys a fluid by releasing all resources 6-19
Data Storage Structures
TYPE FLUID Primary fluid data storage 6-25

Interfaces listed in Table 6-2 are members of class_FluidPhase.mod,

which is part of dynamic link library USERLB6.DLL.
Table 6-2: Interface Software for Phases
class_FluidPhase.mod
Function Phase Manipulation Functions See . . .
zero_FluidPhase Sets all data in one phase to zero 6-20
Data Storage Structures
TYPE Secondary fluid data storage. Each phase in a 6-34
FluidPhase fluid is stored in a separate FluidPhase

PRO/II User-Added Subroutine User Guide 6-1

 Note: The create_Fluid function returns an instance of a fluid as its
returned value. All the other functions include at least one fluid
object in their argument lists.

Overview
Fluids are modular analogs of PRO/II material streams. They are an
enhanced successor of the older user-added streams. Being object-
oriented constructs, they are compatible with modular utilities and
modular unit operations. They are not generally compatible with the
older procedural user-added subroutines.

User Information
Users do not directly interact with modular fluids when they run
simulations using PRO/II. They still manipulate PRO/II streams as
they always have. Users who merely use pre-built modular utilities
in PRO/II simulations may find some of the material interesting.
However, developers of new modular user-added subroutines use
fluids extensively.

Fluid Input Data Requirements

There is no direct user interaction with modular fluids when running
simulations. PRO/II dynamically populates the fluids passed to
user-added subroutines with data extracted from flowsheet streams.

Fluid Output Reports

PRO/II does not directly provide any output reports of fluids. User-
added subroutines may extract data from streams, manipulate the
fluids, and store fluid data back into streams. In this indirect man-
ner, the standard PRO/II stream report generators provide all avail-
able fluid reports.

Developer Information
The remainder of this chapter is intended for developers of user-
added utilities. The first section that follow describe the interface
routines that use fluids to communicate with PRO/II. This is fol-
lowed by some guidelines that should be helpful in creating fully
functional modular utilities and unit operations. Next is an extensive

6-2 UAS Modular Fluids February 2009

 description of the storage objects that store stream and phase data.
The chapter ends with a short example.

Calculation Subroutines

flash_Fluid
The flash_Fluid function computes essential thermodynamic proper-
ties that determine the equilibrium state of a fluid. All flash condi-
tions are entered in the fluid object (passed in the argument list)
before calling the function. Results return in the same fluid object.
Calling sequence:
iRet = flash_Fluid( cTypeIn, cSrIdIn, FLObj, iErr)
where:
cTypeIn Required input character string indicating the type of
flash calculation requested. Table 6-3 lists the available
flash types.
Table 6-3: Flash types Supported By Function flash_Fluid
cTypeIn Flash Type and Description
“ISO” Temperature and Pressure specified
“TADIA” Adiabatic flash at specified temperature
“PADIA” Adiabatic flash at specified pressure
“TDEW” Dew point flash at specified temperature
“PDEW” Dew point flash at specified pressure
“TBUB” Bubble point flash at specified temperature
“PBUB” Bubble point flash at specified pressure
“TISEN” Isentropic flash at specified temperature and
entropy. See examples below.
“PISEN” Isentropic flash at specified pressure and
entropy. See examples below.
“TWDEW” Water dew point flash at specified temperature
“PWDEW” Water dew point flash at specified pressure
“THCDEW” Hydrocarbon dew point flash at specified
temperature (as opposed to water dew point).
“PHCDEW” Hydrocarbon dew point flash at specified
pressure (as opposed to water dew point).
“TDUTY” Duty (i.e., enthalpy change) flash at specified
temperature and enthalpy change.

PRO/II User-Added Subroutine User Guide 6-3

 Table 6-3: Flash types Supported By Function flash_Fluid
“PDUTY” Duty (i.e., enthalpy change) flash at specified
pressure and enthalpy change.

cSrIdIn Optional input. This is the identifier of a PRO/II stream

to be updated when performing the flash. In a user-added
unit operation, it is typically the identifier of one of the
product streams from the UAUOP. User-added utility
subroutines typically use only their member fluids and
have no access to PRO/II streams; so set cSrIdIn to a
blank.
When this argument is blank, no PRO/II streams are
updated with results from the flash. To enter a blank, use
the blank quoted literal string “ ” as the argument value.
See examples below.
FLObj Required input. This is a Fluid data object of the fluid to
flash. Refer to See “Data Structure of class_Fluid” on
page 6-27 of this chapter. Before calling flash_Fluid, the
calling routine must set all required flash information in
this object. Refer to the discussion and examples that fol-
low.
iRet, iErr Output status flags, both integers. iRet is the primary
return flag. iErr often returns additional information when
iRet indicates an error, as shown in Table 6-4.
Table 6-4: Return Codes from flash_Fluid
iRet iErr Description
+3 n/a Success, VLE + Decant flash performed
+2 n/a Success, rigorous VLLE flash performed
+1 n/a Success, VLE (no DECANT) flash performed
0 +1 Success, VLE flash data not stored in stream
0 +2 Success, VLLE flash data not stored in stream
0 +3 Success, DECANT data not stored in stream
0 +4 Success, returned values based on fluid flowrate
of 1 kg-mole per second.
-1 -1 Failure, Stream specified in cSrIdIn not found
-1 -7 Failure, invalid flash type in cTypeIn
-1 -8 Failure during attempt to use dummy stream
-1 -9 Failure, corrupt data, data conversion failed

6-4 UAS Modular Fluids February 2009

 Table 6-4: Return Codes from flash_Fluid
iRet iErr Description
-2 n/a Failure, internal invalid phase requests
-3 n/a Failure, unidentified internal error
-4 n/a Failure, invalid number of components in fluid
-5 n/a Failure, invalid UOM system in fluid
-6 -1 Failed converting fluid data to PRO/II UOM’s
-6 -2 Failed converting results to USER UOM’s
-7 iType Flash calculations failed to converge
-8 n/a Failure while filling stream with fluid data
-10 -1 Failed, invalid fluid temperature
-10 -2 Failed, invalid fluid pressure
-10 -13 Failed, invalid duty (too large)
-10 -14 Failed, invalid entropy (too large)

Usage Notes
The flash_Fluid function requires a fully populated Fluid data object as
an input argument. See function "load_Fluid" on page 6-16 to learn
about initializing a fluid from a PRO/II stream.

Equilibrium Models
The thermodynamic METHOD set of the fluid determines the equilib-
rium model used by flash_Fluid. Equilibrium models in PRO/II
include VLE, VLE with DECANT, and VLLE. The thermodynamic
set is specified in member TherSetNo of the fluid object. It is set
whenever a fluid is loaded (using load_Fluid) from a PRO/II stream
or is copied from another fluid (using copy_Fluid).
Upon successful completion, the function value of flash_Fluid indi-
cates the equilibrium model used in the calculations. Refer to iRet in
Table 6-4.

Flash Types
In PRO/II, a flash calculation has NOC + 3 state variables, where
NOC is the number of components in the simulation. The compo-
nent compositions in the Total phase always are used for NOC of these
state variables. Specifying two additional state variables essentially
reduces the problem to one degree of freedom with one unknown
and one equation. Set these variables directly in the fluid data object

PRO/II User-Added Subroutine User Guide 6-5

 before calling flash_Fluid. In the following discussion of flash types,
assume the fluid object is named FLOBJ.

ISO Flash
An “ISO” flash specifies both temperature and pressure. Set both tem-
perature and pressure before calling flash_Fluid. For example:
FLOBJ%TEMP = 100.0
FLOBJ%PRES = 15.5
iRet = flash_Fluid( “ISO”, “ “, FLOBJ, iERR )
All other flash types specify either temperature or pressure, plus
one other variable.

TADIA, PADIA Flashes

These are adiabatic flashes where the total fluid enthalpy is held
constant at its existing value. Either temperature or pressure is spec-
ified and the other is calculated. For example:
FLOBJ%TEMP = 100.0
iRet = flash_Fluid( “TADIA”, “ “, FLOBJ, iERR)
Temperature is held at the specified value, total enthalpy is held
constant, and the calculated pressure returns in FLOBJ%PRES.
or
FLOBJ%PRES = 15.0
iRet = flash_Fluid(“PADIA”, “ “, FLOBJ, iERR)
Pressure is held at the specified value, total enthalpy is held
constant, and FLOBJ%TEMP returns the calculated temperature.
Total fluid molar enthalpy may be specified along with temperature
or pressure. This is not recommended, but here is an example.
FLOBJ%TOTAL%SpEnthM = 12321.0
FLOBJ%PRES = 15.0
iRet = flash_Fluid(“PADIA”, “ “, FLOBJ, iERR)
Total enthalpy and pressure are held at the specified values.
Calculated temperature is returned in FLOBJ%TEMP.
Instead of setting the enthalpy in the manner, use a DUTY flash to
incrementally change the enthalpy (see next).

TDUTY, PDUTY Flashes

These flashes apply a change to the total enthalpy of the fluid. A
special variable in the fluid data object, DUTY, allows the calling rou-
tine to set the amount of enthalpy change on a total-stream basis. As

6-6 UAS Modular Fluids February 2009

 usual, also set either the temperature or pressure to complete the
specification for these flashes. For example:

FLOBJ%DUTY = 2468531.0
FLOBJ%PRES = 15.0
iRet = flash_Fluid(“PDUTY”, “ “, FLOBJ, iERR)
or
FLOBJ%DUTY = 2468531.0
FLOBJ%TEMP = 15.0
iRet = flash_Fluid(“TDUTY”, “ “, FLOBJ, iERR)
The DUTY is applied to the total enthalpy of the fluid and the speci-
fied temperature or pressure is held constant.

Note: Setting FLOBJ%DUTY = 0.0 in a DUTY flash is equivalent to

performing an adiabatic (TADIA or PADIA) flash.

TBUB, PBUB Flashes

Specify only temperature or pressure for these flashes. The second
state variable is inherent in the flash type. The resulting fluid is all
liquid at the temperature and pressure at which the first vapor mole-
cules condense. For example:
FLOBJ%TEMP = 100.0
iRet = flash_Fluid(“TBUB”, “ “, FLOBJ, iERR)
The calculated bubble point pressure returns in FLOBJ%PRES.
or
FLOBJ%PRES = 15.0
iRet = flash_Fluid(“PBUB”, “ “, FLOBJ, iERR)
Data member FLOBJ%TEMP returns the calculated bubble point
temperature.

TDEW, PDEW Flashes

Specify only temperature or pressure for these flashes. The second
state variable is implied by the flash type. The resulting fluid is all
vapor at the temperature and pressure at which the first vapor mole-
cules begin to condense to a liquid. For example:
FLOBJ%PRES = 15.0
iRet = flash_Fluid(“PDEW”, “ ”, FLOBJ, iERR)
The calculated dew point temperature returns in FLOBJ%TEMP.
or
FLOBJ%TEMP = 100.0
iRet = flash_Fluid(“TDEW”, “ ”, FLOBJ, iERR)

PRO/II User-Added Subroutine User Guide 6-7

 The calculated dew point pressure returns in FLOBJ%PRES.

TWDEW, PWDET
These flashes compute the conditions at which the first water mole-
cules begin to condense to liquid. In non-rigorous VLE with
DECANT, this is where the DECANT liquid phase first begins to
condense. In rigorous VLLE systems, this is where the L2 (heavy)
liquid sub-phase first begins to condense. The L2 liquid sub-phase
has a flowrate of zero. The resulting fluid may be all vapor, or vapor
with some L1 (hydrocarbon) liquid. Specify only temperature or
pressure for these flashes. The second state variable is implied by
the flash type. For example:
FLOBJ%PRES = 15.0
iRet = flash_Fluid(“PWDEW”,“ ”, FLOBJ, iERR)
The calculated temperature returns in FLOBJ%TEMP.
or
FLOBJ%TEMP = 100.0
iRet = flash_Fluid(“TWDEW”,“ ”, FLOBJ, iERR)
The calculated pressure returns in FLOBJ%PRES.

THCDEW, PHCDEW
These flashes compute the conditions at which the first hydrocarbon
molecules begin to condense to liquid. In non-rigorous VLE with
DECANT, this is where the non-DECANT liquid phase first begins
to condense. In rigorous VLLE systems, this is where the L1 (light)
liquid sub-phase first begins to condense. The L1 liquid sub-phase
has a flowrate of zero. The resulting fluid may be all vapor, or vapor
with some L2 (water, DECANT) liquid. Specify only temperature
or pressure for these flashes. The second state variable is implied by
the flash type. For example:
FLOBJ%PRES = 15.0
iRet = flash_Fluid(“PHCDEW”, “ ”,FLOBJ,iERR)
The calculated temperature returns in FLOBJ%TEMP.
or
FLOBJ%TEMP = 100.0
iRet = flash_Fluid(“THCDEW”, “ ”,FLOBJ, iERR)
The calculated pressure returns in FLOBJ%PRES.

TISEN, PISEN Flashes

These types perform isentropic flashes on a fluid. They are entropy
analogs of the TADIA and PADIA flash types described earlier. The
calling routine first sets the total fluid entropy, then calls one of

6-8 UAS Modular Fluids February 2009

 these flashes. A special variable in the fluid data object, Entropy,
allows the calling routine to set the entropy on a total-fluid basis.
Also, set either the temperature or pressure to complete the specifi-
cation for these flashes. For example:
FLOBJ%ENTROPY = 97531.0
FLOBJ%PRES = 15.0
iRet = flash_Fluid(“PISEN”, “ ”,FLOBJ, iERR)
The calculated temperature is available in FLOBJ%TEMP.
or
FLOBJ%ENTROPY = 97531.0
FLOBJ%TEMP = 15.0
iRet = flash_Fluid(“TISEN”, “ ”,FLOBJ, iERR)
The calculated pressure is available in FLOBJ%PRES.

Using Temperature and Pressure Estimates

Flash calculations can be computationally expensive, especially if
they are repeatedly executed in large iterative loops. Routine
flash_Fluid allows the calling UAS to provide temperature and pres-
sure estimates to start calculations near the solution values. The
dimensional units of the estimates are the same user units used
throughout the UAS. Available estimates are:
EstTemp Specifies the temperature used to start flash calculations.

EstPres Specifies the pressure used to start flash calculations.

Estimates are declared in the fluid object (FLOBJ in this discussion)
before calling flash_Fluid. They are cleared after each flash, so they
must be initialized before each call to flash_Fluid.

Example:
A fluid initially is ISO-flashed at specified temperature and pressure.
Duty is added that is expected to raise the temperature by 10
degrees. The pressure is incremented by 1.2 pressure units. The new
fluid state is determined by a subsequent DUTY flash. A temperature
estimate is applied before starting the DUTY flash.
FLOBJ%TEMP = 100.0D+0
FLOBJ%PRES = 15.0D+0
iRet = flash_Fluid( “ISO”, “ “, FLOBJ, iErr )
. . .
FLOBJ%DUTY = 1234.5D+0
FLOBJ%EstTEMP = FLOBJ&TEMP + 10.0D+0
FLOBJ%PRES = FLOBJ%PRES + 1.2D+0
iRet = flash_Fluid( “DUTY”, “ “, FLOBJ, iErr )

PRO/II User-Added Subroutine User Guide 6-9

 Retrieving Flash Results
After successfully completing its calculations, function flash_Fluid
returns all fluid results in the fluid data object passed through the
argument list of the call. All data for each phase and sub-phase are
stored in the fluid Phase objects that are members of the fluid.
Returned data is complete, including transport properties, K-values,
vapor fugacities, and either liquid fugacities or liquid activity coeffi-
cients, as appropriate, depending upon thermodynamic METHOD.
Some phases may not exist after completing a flash. The phases that
flash_Fluid returns depends on the thermodynamics model used to
perform the flash. The TherSetNo member of the fluid object speci-
fies a METHOD set declared in the simulation, which in turn deter-
mines the equilibrium model. Table 6-5 lists the phase objects
populated by flash_Fluid for each equilibrium model.
Table 6-5: Fluid Phases Returned from flash_Fluid
Equilibrium Model
iRet = 1 iRet = 2 iRet = 3
Phase Name VLE Rigorous VLLE VLE + Decant
Total Yes Yes Yes
Vapor Yes Yes Yes
Liquid Yes Yes Yes
L1 No L1 Non-Decant
L2 No L2 Decant
Solid Molec wt solids Molec wt solids Molec wt solids
NMWSolid No No No

For example, any DEW-point flash results in an all-vapor fluid. The

Total and Vapor phases are fully populated, but none of the liquid
phases contain data.
Retrieve calculated results directly from the returned fluid object
and its constituent phase objects. The following code snippet
retrieves the weight fraction of component 3 from the Total, Vapor,
(bulk) Liquid, and L2 phases of fluid FLOBJ.
x3Tot = FLOBJ%TOTAL%XFracWt(3)
x3Tot = FLOBJ%VAPOR%XFracWt(3)
x3Tot = FLOBJ%LIQUID%XFracWt(3)
x3Tot = FLOBJ%L2%XFracWt(3)

6-10 UAS Modular Fluids February 2009

 Kcalc_Fluid
In some situations, it may be desirable to obtain K-values, dK/dT’s,
vapor fugacities, liquid fugacities, or liquid activity coefficients
without performing a flash. Function kcalc_Fluid provides this
capability.
Purpose: Compute K values, dK/dT, Fugacities or Liquid Activity
coefficients, and compressibility (Z). Call PRO/II to per-
form the calculations. All data in and results out are in
the Fluid Object.
Calling sequence:
iRet = Kcalc_Fluid( cPhase, cDeriv, cComp, &
FLObj, ieStat )
Where:
cPhase Phases of interest. This is a keyword entry input as a
quoted literal string. Available options are:
“BULK” or “LIQU” requests bulk liquid properties and
vapor phase fugacities.
“SUBL” or “LSUB” requests liquid sub-phase (L1 and L2)
properties and vapor fugacities.
cDeriv Input option to compute K-value derivatives with respect
to time. Available keywords are:
“NONE” Omit K-value derivatives. This is the default
when this argument is blank.
“DKDT” Compute and return K-value derivatives.

cComp Composition dependency flag. Input as a quoted literal

keyword. Available options are:
“COMP” Use the mole fraction compositions supplied in
the FLOBJ phase objects. This is the default when the
entry is blank. Mole fractions must be pre-loaded in the
following phase arrays:
FLOBJ%VAPOR%XFracM() Always required.
FLOBJ%LIQUID%XFracM() Required for cPhase = “BULK”
FLOBJ%L1%XFracM() Required for cPhase = “SUBL”
FLOBJ%L2%XFracM() Required for cPhase = “SUBL”
“NOCOMP” Compute properties from special code with-
out using composition data. Valid only when using
SRK.

PRO/II User-Added Subroutine User Guide 6-11

 FlObj This is a fluid object that contains the composition data
required by the cPhase and cComp arguments. It returns
all the calculated results.
ieStat An output integer that returns information about calcula-
tion results. It is used in conjunction with iRet to return
additional information about any errors (see below).
iRet A local scalar integer variable that accepts the returned
function value. It is the primary status flag that indicates
success or failure of the calculations. It is used in con-
junction with argument iErr when errors occur. Table 6-6
defines the returned values.
Table 6-6: Return Codes from Kcalc_Fluid
iRet iErr Description
+2 n/a Success, returned vapor, L1, L2 phase results
+1 n/a Success, returned vapor, and bulk liquid results
0 n/a Success (this value is never returned)
0, 1, 2 -1 Invalid cPhase, returned bulk liquid values
0, 1, 2 -2 Invalid cPhase, returned L1, L2 values
0, 1, 2 -3 Missing XFracM data - dK/dT values omitted
-1 n/a Invalid temperature
-2 n/a Invalid pressure
-3 -1 Invalid vapor fraction
-3 -2 Invalid (bulk) liquid fraction
-3 -3 Invalid L1 fraction
-3 -4 Invalid L2 fraction
-4 -1 Vapor fugacity calculations failed
-4 -2 Bulk liquid calculations failed
-4 -3 L1 calculations failed
-4 -4 L2 calculations failed

Retrieving Results
After successfully completing its calculations, function Kcalc_Fluid
returns all results in the fluid data object passed through the argu-
ment list of the call.
Returned data includes K-values, dK/dT values, vapor fugacities,
and either liquid fugacities or liquid activity coefficients, as appro-

6-12 UAS Modular Fluids February 2009

 priate, depending upon equilibrium model. See “Equilibrium Mod-
els” on page 6-5 of this chapter for more information.
The phases that Kcalc_Fluid populates depends on the cPhase input
argument. Table 6-7 illustrates the data that may be returned in each
phase.
Table 6-7: Results Returned by Kcalc_Fluid
Summary of Data Returned from Kcalc_Flash
Phases that Return Data for Various Equilibria
Property Rigorous VLLE VLE VLE + DECANT
EOS LACT EOS LACT EOS LACT
KVal( NOC ) L1, L2 L1, L2 L L L L
dKdT ( NOC ) L1, L2 L1, L2 L L L L
V V V V V V
ZKval
L1, L2 L1, L2 L L L L
V V V V V V
XFug( NOC )
L1, L2 L L
XLact( NOC ) L1, L2 L L
L = Bulk liquid, L1 = Non-decant (light) liquid sub-phase, NOC = number of
L2 = DECANT (heavy) liquid sub-phase components
EOS = Equation of State, LACT = Liquid Activity method

Example:
The following illustrates calling Kcalc_Fluid to compute and
retrieve some of the calculated properties. Assume the fluid is the
fluid data object. The blank arguments use the default setting “NONE”
for argument cDeriv and “COMP” for argument cComp.
1 iRet = Kcalc_Fluid(“BULK”, “ “, “ “, &
2 FLOBJ, iErr )
3 . . .
4 Vcompress = FLOBJ%VAPOR%ZKval
5 Comp3FugV = FLOBJ%VAPOR%XFug( 3 )
6 Comp3BulkKval = FLOBJ%LIQUID%KVal( 3 )
7 Comp3BulkdKdT = FLOBJ%LIQUID%dKdT( 3 )

Line 4 retrieves the calculated compressibility of the vapor

Line 5 retrieves the vapor phase fugacity of component 3.
Lines 6 and 7 retrieve the K value and its derivative for compo-
nent 3 in the bulk liquid phase.
All the retrieved properties were computed by Kcalc_Fluid.

PRO/II User-Added Subroutine User Guide 6-13

 Fluid Manipulation Functions
The functions described in this section allow user-added subroutines
to manipulate fluid objects in user-added subroutines. All are mem-
bers of class_Fluid or class_FluidPhase. To access the fluid func-
tions, the class_Fluid module must be declared with a USE
statement in each user-added subroutine that uses fluids. See “Sub-
routine Coding Requirements” on page 6-21.

create_Fluid
This function allows user-added subroutines to erect instances of
fluids. It dynamically allocates all arrays and computer resources
needed by a fluid. Call this function before attempting to use the
fluid in any other way. It is intended for use in unit operation sub-
routines. Using it in utility subroutines is possible but more difficult,
since the required FacObj (that defines the user-defined dimensional
units) is not available in a UASOBJ data structure.

Note: Do not use this function with a pre-defined fluid that is a

member of a UASOBJ instance. Pre-defined fluids have already
been created and loaded with data.
Calling sequence:
FLObj = create_FLUID( newID, NOC, FacObj, ieStat )

Where:
FLObj The new fluid object returned as the value of the func-
tion. It contains all supported phases, including Total,
Vapor, Liquid, L1, L2, Solid, and NMWSolid. However,
almost all data members are initialized to zero. Before
being used here, FLObj must appear in a TYPE( FLUID )
statement.
newID An identifier assigned to the new fluid instance. It is a
required input character string containing up to 12 char-
acters. The first character should be an upper or lower-
case letter (A-Z). The ID should be unique among all
fluid instances in the subroutine.
NOC The total number of components in the current simula-
tion. It is a required integer input argument. This should
be retrieved from the NOC member of a UAUOP or
UASOBJ data structure.

6-14 UAS Modular Fluids February 2009

 FacObj A fully populated dimensional units object created by
class_DMUOM. It is a required input argument. The
most convenient way to obtain this object is to use the
Factors member from a UAUOP data structure.

ieStat A scalar integer output variable that returns the status

code of the calculations. Negative values indicate errors
that cause the calculations to fail. Returned values are:
+1 = success, created fluid
0 = success (should never return)
-1 = Failed, missing newID
-2 = Failed, missing NOC

Example of Using create_Fluid:

The following sample demonstrates proper usage of the func-
tion to dynamically create a fluid in a unit operation subroutine.
Only code related to using create_Fluid is shown.
1 SUBROUTINE MyUOP( CONTEXT, UopObj, iSolve )
2 !
3 USE class_UaUop
4 USE class_Fluid ! required
5 !
6 TYPE( UAUOP ), INTENT(INOUT) :: UopObj
7 CHARACTER(LEN=*), INTENT(IN) :: CONTEXT
8 INTEGER(4), INTENT(OUT) :: iSolve
9 INTEGER(4) :: ieStat
10 !
11 TYPE( FLUID ) :: myFluid ! required
12 !
13 myFluid = create_Fluid( “myID”, &
14 UopObj%NOC, UopObj%Factors, ieStat )

Line 4 makes class_Fluid available in the subroutine, so func-

tion create_fluid can be used.
Line 11 declares variable myFluid as a fluid data structure, but
does not allocate any dynamic resources for it.
Lines 13 and 14 call create_Fluid to instantiate myFluid. The
second argument (UopObj%NOC) uses the NOC member
of the UAUOP object for the number of components.
The third argument (UopObj%Factors) is the dimen-
sional units data structure that is a member of the
UAUOP object.

PRO/II User-Added Subroutine User Guide 6-15

 load_Fluid
This function populates a fluid with data from a PRO/II stream. The
fluid already must exist. It may be a pre-defined fluid from a
UASOBJ object or one that was locally created. Use "create_Fluid"
on page 6-14 to create a fluid locally in a subroutine.
Calling sequence:
iRet = load_Fluid( cSrIdIn, FLObj )
Where:
cSrIdIn The identifier of the PRO/II stream from which data is
extracted. This is the same ID used to identify the stream
in PRO/II keyword input and in the flowsheet (PFD)
window of PROVISION.
FLObj The fluid object that receives data from the stream.
iRet A local integer scalar variable that receives the status
flag returned as the function value. Returned values are:

+1 Success, the fluid is loaded with stream data.

0 Success (never returned).
-1 Failure, could not load data into the fluid.

When called, load_Fluid fully populates the fluid with as much data
as possible. This includes generated properties that it derives from
the data in the PRO/II stream. However, when the stream data is not
complete, the resulting fluid data also will be incomplete. Any pre-
existing data in the fluid is overwritten during loading.
During the loading process, load_Fluid associates the fluid with the
PRO/II stream. The ID of the associated stream is stored in data
member P2StreamID of the fluid. For example, for a fluid named
FLObj, access the associated stream ID using FLObj%P2StreamID.

The most common method of finding a PRO/II stream is to use one

of the feeds to a user-added unit operation. File UOP1CALC.f90 in
sample project ExUOP.DSW demonstrates this approach.

6-16 UAS Modular Fluids February 2009

 copy_Fluid
Data from one fluid are copied to a second fluid by this function.
Fluid identification information is not copied. All other data in the
source fluid and its phases are copied to the target fluid. If the
source fluid has an associated PRO/II stream, the target fluid also
becomes associated with that stream.
Calling sequence:
iRet = copy_Fluid( FLin, FLout, ieStat )
Where:
iRet Returned status flag, a local scalar integer variable. Pos-
sible returned values are:

+1 Success, all phases copied, ieStat does not apply.

0 Success, some phases not copied, See ieStat.
-1 Failure, source fluid FLin is invalid (FLin%Exist=.FALSE.).
-2 Failure, target fluid FLout invalid (FLout%Exist=.FALSE.).

FLin The source FLUID object containing the data to copy.

FLout The target FLUID object that receives the copied data.
ieStat Returned scalar integer status flag indicating the status of
copying individual phases. Set only when iRet = 0 (con-
ditional success). It contains packed digits, with each
digit being a flag for a specific phase. The number of
digits indicates the number of phases not copied. The
value of each digit indicates a phase that did not copy:

Value Phase that did not copy

0 Complete success, all phases copied.
1 Total phase did not copy.
2 Vapor phase did not copy.
3 Bulk Liquid phase did not copy.
4 L1 liquid sub-phase did not copy.
5 L2 liquid sub-phase did not copy.
6 Solid phase did not copy.
7 NMWSolid phase did not copy.

PRO/II User-Added Subroutine User Guide 6-17

 store_Fluid
Use this function to store FLUID data in a PRO/II stream. Because
fluids are virtual objects, they cannot persist their data themselves.
PRO/II user-added unit operations usually compute the state of their
product streams. This function allows user-added subroutines to use
fluids for all calculations; then store the fluids in the product
streams. Data stored in a stream is available throughout the simula-
tion flowsheet.
Calling sequence:
iRet = store_Fluid( cSrIdIn, FLObj )
Where:
cSrIdIn The identifier of the PRO/II stream in which data is
stored. This is the same ID used to identify the stream in
PRO/II keyword input and in the flowsheet (PFD) win-
dow of PROVISION.
FLObj The fluid object from which data is copied.
iRet Returned status flag, a local scalar integer variable. Pos-
sible returned values are:

+1 Success, all data stored successfully.

0 Success (never returned).
-1 Failure, cSrIdIn is invalid.
-2 Failure, some fluid phase objects are invalid.
-3 Failure, unspecified reasons.
-4 Failure, invalid number of components (in FLObj).
-5 Failure, invalid conversion factors in FLObj%Factors.
-6 Failure, could not convert data from User to P2 UOM’s.

Note: Many fluid properties are derived values that streams do

not store. For example, fluid data includes many properties on
both a mole and weight basis. PRO/II streams usually store only
molar properties and molecular weight. The weight-based proper-
ties are easily computed from the molar properties.
The safest strategy for generating complete fluid properties is to
flash the fluid before storing it in a PRO/II stream.

6-18 UAS Modular Fluids February 2009

 free_Fluid
This function destroys an instance of a fluid by de-allocating and
releasing all the dynamic computer resources used by the fluid. This
function should be used only for fluids instantiated by using
create_fluid in a user-added subroutine. It never should be applied to
a pre-defined fluid that is a member of a UASOBJ passed from
PRO/II through the subroutine call list.
Calling sequence:
iRet = free_FLUID( FLObj )
Where:
FLObj The instance of a fluid to be freed.
iRet Returned status flag, a local scalar integer variable. Pos-
sible returned values are:

+1 Success, all resources successfully released.

0 Success, all resources successfully released.
-1 Failure, unspecified resources were not released.

The static members of the fluid remain available after calling

free_fluid. These are listed in Table 6-8 on page 27. For example,
all the member phase objects are destroyed, but the phase validation
flags remain available.
There is no real need to test the iRet status variable. There are no
further actions the user-added subroutine can perform to release the
fluid. Developers may wish to test iRet and issue a message or
warning (see "UAERROR" on page 3-8) during development for
debugging purposes. This is a non-fatal condition that does not need
to be reported in a release version. Normal exit from the subroutine
usually releases unneeded resources through the close-out proce-
dures that automatically are performed when running Fortran
applications.

PRO/II User-Added Subroutine User Guide 6-19

 zero_FluidPhase
Purpose: Reset all data members of a fluid phase object to values of
zero or missing. Only floating point data is processed.
Calling sequence:
iRet = zero_FluidPhase( NOC, PhObj )
Where:
NOC The total number of components in the simulation.
PhObj The fluid phase object to be reset.
iRet Returned status flag, a local scalar integer variable. Pos-
sible returned values are:

+1 Success, all phase data set to a value of zero or missing.

0 Never returned.
-1 Never returned.
-2 Failure, PhObj is not allocated (PhObj%Exist = FALSE).
-3 Failure, NOC is invalid (less than 1 or greater than 10000).

Fluid phases are members of fluids, and the fluid manipulation

functions initialize phase data when appropriate. Usually, there is
little need to call this function. However, here is an example that
uses zero_phase to reset phase Vapor in a fluid named myFluid:
iRet = zero_FluidPhase(myFluid%NOC,myFluid%Vapor)
This function operates on the floating-point phase properties listed
in Table 6-8 on page 27 of this chapter. It does not alter any integer
or character data. The following data members are set to zero.

RateM RateV FracM FMDecant ZKval

RateWt RateVstd FracWt FWDecant XFracM

All other floating-point properties in Table 6-8 are set to “missing”.

Module class_DMUOM defines this value as parameter DUAMISS.
It is a large negative value (-1.5D35). Another parameter available
in class_DMUOM is DUATEST with a value of -1.0D-35. To deter-
mine when a value is set to missing, use the following:
IF( myFluid%myPhase%property .LT. DUATEST ) THEN
the value is missing. Refer to Chapter 7 for more information.

6-20 UAS Modular Fluids February 2009

Fluid Guidelines
Project Requirements
Any user-added project that uses fluid objects must be configured to
satisfy the following two requirements:
The project compiler settings must include the path to file
class_Fluid.mod. See “Setting the Module Path for the Fortran
Compiler” on page 2-23 of Chapter 2, ”Modular UAS Build
Procedures”.
The project linker settings must include the path to file
UserLb6.lib. See “Setting the Import Library Path for the
Linker” on page 2-24 of Chapter 2, ”Modular UAS Build Pro-
cedures”.

Subroutine Coding Requirements

User-added subroutines that use fluids must be declared module
class_Fluid in a USE statement. The two scenarios of most interest
are discussed here.

Declaring Fluids in Utility Subroutines (UAUTIL)

PRO/II passes an instance of class_UASOBJ to each utility subrou-
tine through the argument list. This class already includes fluid
objects as members, so using class_UASOBJ automatically pro-
vides access to class_Fluid. This eliminates the need for a specific
USE statement for class_Fluid. Similarly, every fluid contains fluid-
Phase objects, so using class_Fluid automatically provides access to
class_FluidPhase. The following code fragment illustrates this.

SUBROUTINE MYUAUTIL( UAUTIL )

USE class_UASOBJ
TYPE(UASOBJ) :: UAUTIL
REAL(8) :: TempV, DensityL
!
! Retrieve temperature of fluid FlVapor, a member of UAUTIL
!
TempV = UAUTIL%FlVapor%TEMP
!
! Retrieve the density of the bulk liquid sub-phase of this fluid
!
DensityL = UAUTIL%FlLiquid%Liquid%Density

PRO/II User-Added Subroutine User Guide 6-21

 Declaring Fluids in Unit Operations (UAUOP)
User-added unit operations are based on class_UAUOP, which does
not provide automatic access to the class_Fluid module. Therefore,
an explicit USE statement is needed. Also, explicit TYPE statements
are required to declare variables as fluid objects. Since all fluids
include fluidPhase objects, no additional USE statement is required
to access class_FluidPhase. The following annotated code extract
demonstrates the construction of two fluids.
SUBROUTINE MYUAUOP( UOPOBJ )
USE class_UAUOP
USE class_Fluid ! required to use fluids
!
TYPE(UAUOP) :: UOPOBJ
INTEGER(4) :: iRet, NOC
!
! Declare 2 local variables as fluid objects
TYPE( FLUID ) :: Fluid1, Fluid2
!
NOC = UOPOBJ%NOC ! number of components
!
! Allocate resources for the two fluid objects
iRet = create_Fluid(“F1”, NOC, Fluid1, iRet)
iRet = create_Fluid(“F1”, NOC, Fluid1, iRet)

Usage of class_Fluid
After the basic fluid declarations described above are complete, the
fluids are available for use. The basic steps for working with fluids
are:
1. Create Instances of Fluids. Fluids were designed to be created
within UAUOP subroutines. Use function "create_Fluid" on
page 6-14 to allocate the computer resources needed by these
virtual constructs. This step is not required when developing a
UAUTIL subroutine that uses only the fluids that are members of
UASOBJ data structures passed as arguments in the call list.
2. Populate Fluid Instances with Data. The subroutine may ini-
tially populate each fluid in a number of ways:
Use the direct-access method of coding to store data in the
data members. Typically, PRO/II requires the temperature
and pressure in the encompassing fluid object. It also
requires the Total phase molar flowrate in Total%RateM and
molar compositions in array Total%XFracM.

6-22 UAS Modular Fluids February 2009

 Use function "load_Fluid" on page 6-16 to fully populate a
fluid with data from a PRO/II stream.
3. Use Fluids to Perform Tasks. Make copies of fluids (see func-
tion "copy_Fluid" on page 6-17), Use the calculation routines to
flash fluids and compute other properties. Refer to the section
titled "Calculation Subroutines" on page 6-3.
4. Store Fluid Data. When the subroutine has access to PRO/II
streams, a subset of the fluid data can be stored in a stream.
Refer to function "store_Fluid" on page 6-18.
5. Free Fluid Resources. All fluids use computer resources, and
it is good practice to release them before leaving the subroutine.
See function "free_Fluid" on page 6-19.
Developers should adhere to the following guidelines when writing
code.
Projects that create user-added subroutines must include mod-
ule class_Fluid.mod. It is required for class_UASOBJ to build
properly. Using the sample user-added projects installed with
PRO/II satisfies this requirement.
Pre-defined FLUID structures are available only as members of
a UASOBJ instance that is passed to a UAUTIL subroutine. The
UAUOP object passed to user-added unit operations does not
contain pre-defined fluids.
A user-added utility subroutine does not need to “USE”
class_Fluid. Class_UASOBJ automatically makes the module
available. Unit operation subroutines must “USE” class_Fluid.
Pre-defined fluids in UASOBJ have specific names assigned by
PRO/II. Refer to the chapters that describe individual utility
subroutines to determine exactly which fluids the subroutine
supports.
All references to data in pre-defined fluids must be in the form
of calls to data members of UASOBJ. This includes access to
any data in the fluid phases. Fluids instantiated using the
create_Fluid function are referenced as independent entities
(i.e., not as members of UASOBJ).
Only direct member addressing is available for accessing fluid
data. The class_Fluid module does not implement accessor
functions, so indirect addressing is not available.

PRO/II User-Added Subroutine User Guide 6-23

 Dimensional Units
Fluids use the dimensional units of measure in effect in the unit
operation or utility subroutine. The end-user must declare the devel-
oper’s set of units when registering the subroutine with PRO/II. See
“Registering a UAS with PRO/II” on page 2-5 of Chapter 2 for a
description of the registration process.
The registered set of dimensional units applies to all data exchanged
between PRO/II and a user-added subroutine. This is independent of
the units used for input data in a simulation. Refer to Chapter 7,
”User-Added Units of Measure”, for lists of the available sets of
units, including all dimensional classes.

Support for Solids-Forming Components

Module class_Fluid supports molecular weight solids in the Solid
phase. This includes all the member functions as well as the data
storage object.

Note: Non-Molecular weight solids are not supported in

class_Fluid. Member phase NMWSolid provides storage, and the
manipulation functions (create_fluid, load_Fluid, copy_Fluid,
store_fluid, and free_Fluid) handle the data properly. However,
calculation function flash_Fluid will return invalid results when
NMWSolid components are present in the fluid.

6-24 UAS Modular Fluids February 2009

class_Fluid.mod
This module makes fluid data objects available to the UASOBJ data
structure in user-added utility subroutines. It provides the
create_Fluid and free_Fluid functions that allow user-added unit
operations to instantiate instances of fluids. Additional manipula-
tion functions and calculation functions facilitate using fluids.
Each FLUID contains one or more FluidPhase objects. Each Fluid-
Phase member may or may not contain meaningful data, depending
upon the equilibrium state of the fluid. "class_FluidPhase.mod" on
page 6-34 describes the phase object.
This section describes the proper usage of class_Fluid mod. It also
describes all the data in the FLUID base class. Remember that pre-
defined fluids are available as members of UASOBJ only in UAUTIL
subroutines. UAUOP subroutines must instantiate and manage fluids
using the manipulation functions described earlier in this chapter.

Direct Member Access in class_Fluid

Direct member addressing accesses data by direct reference to the
data member. Fortran 90 defines the percent symbol % as the access
operator.
Direct member addressing takes the form: “parent % member”. The
“parent % member” construct is extensible to any level in the data
structure. Consider the following contrived example (line numbers
added for clarity):
1 SUBROUTINE MYSUB( FluidObj )
2 USE class_Fluid
3 TYPE( FLUID ) :: FluidObj
4 REAL(8) :: Temp, Pres, RmoleTot, RmoleV
5 REAL(8) :: c6MFTot, c6MFVap, Ratec6
6 INTEGER(4) :: iRet, Ncomps
7 !
8 Ncomps = FluidObj%NOC
9 Temp = FluidObj%Temp
10 Pres = FluidObj%Pres
11 !
12 IF( FluidObj%Status .GE. 1 ) THEN
13 RmoleTot = FluidObj%Total%RateM
14 c6MFTot = FluidObj%Total%XFracM( 6 )
15 !
16 IF( FluidObj%VapStatus .GE. 1 .AND. &
17 FluidObj%L1Status .GE. 1 ) THEN
18 c6MFVap = FluidObj%Vapor%XFracM( 6 )

PRO/II User-Added Subroutine User Guide 6-25

 19 RmoleV = FluidObj%Vapor%RateM
20 Ratec6 = RmoleV * c6MFVap
21 FluidObj%Vapor%XFracM( 6 ) = 0.0D+0
22 RmoleV = RmoleV - Ratec6
22 FluidObj%Vapor%RateM = RmoleV
23 FluidObj%Vapor%FracM = &
24 RmoleV / RmoleTot
25 FluidObj%Total%RateM = &
26 RmoleTot - Ratec6
27 END IF
28 END IF

Line 1 brings in a fluid object as the only argument in the call list.
Line 2 “uses” the fluid class module to make fluids available.
Line 3 declares the argument FluidObj as a FLUID.
Lines 4-6 simply declare some local variables in the subroutine.
Referring to Table 6-8 on page 27 of this chapter, note the fluid con-
tains members NOC (number of components), Temp, and Pres
(fluid temperature and pressure).
Lines 8, 9, and 10 retrieve these data values from the fluid storage.
Again from Table 6-8, note each Fluid contains FluidPhase objects
named Total, Vapor, Liquid, L1, and L2. The fluid also includes valid-
ity flags for each phase. (Members Status, VapStatus, and L1Status
are the validity flags for the Total, Vapor, and L1 phases, respec-
tively.)
Line 12 test the status flag for the Total phase in an IF statement.
Now look at Table 6-11 to identify the data members in a Fluid-
Phase object. Among the many properties, each phase has members
named RateM and XFracM. RateM is the total mole rate of the phase.
XFracM is an array containing the component mole fractions in the
phase. It contains NOC elements; one for each component in the
simulation. With this information, we continue interpreting the code
in the example.
Lines 13 and 14 retrieve RateM and the mole fraction of component
6 from the Total fluid phase.
Lines 16 and 17 test for valid data in the Vapor and L1 phases.
Lines 18 and 19 extracts vapor RateM and the mole fraction of com-
ponent 6 from the Vapor phase.
Line 20 computes the mole rate of component 6 in the vapor phase.
Line 21 zeroes the mole fraction of component 6.

6-26 UAS Modular Fluids February 2009

 Line 22 adjust the vapor rate to remove component 6.
Lines 23 and 24 adjust the fraction of vapor in the fluid.
Lines 25 and 26 subtracts the vapor rate of component 6 from the
total phase rate, removing component 6 from the fluid.
This demonstrates the power of the direct access method to access
data in any fluid. Developers should test for the existence of a fluid
before attempting to access data from it (refer to lines 12, 16, and
17).

Indirect Member Addressing in class_Fluid

The class_Fluid module does not implement accessor functions. For
this reason, indirect member addressing is not supported for data in
fluids.

Data Structure of class_Fluid

Table 6-8 lists all the member data in a fluid. Several fluid phases
are members of the fluid. All the phases are always created when
the fluid is allocated using function create_Fluid. Pre-defined fluids
that are members of the UASOBJ class do not include all the phases.
In pre-defined fluids, the Total phase always is present. Other phases
may be missing, depending upon the phase state of the fluid. For
example, the pre-defined FLVapor fluid does not include a Liquid,
L1, or L2 phase. Before attempting to access data in fluid phase
members, developers should test the phase validation flags to ensure
the phase is valid.
Table 6-8: class_Fluid Data Members
Member Type Description
Fluid Identification
ID C12 Identifies the fluid, typically “Vapor”, “Liquid”,
or “Iface”.
IdNo I4 An ID number assigned to the Fluid. Typically,
1 = Vapor – an all vapor stream
2 = Liquid – an all liquid stream
3 = L1 liquid sub phase (not available)
4 = L2 liquid sub-phase (not available)
5 = Total phase (always present)
Name C40 A name for the Fluid, typically “Vapor Fluid”,
“Liquid Fluid”, or “Interface Fluid”.
P2StreamID C20 Identifier of associated PRO/II stream
General Data

PRO/II User-Added Subroutine User Guide 6-27

 Table 6-8: class_Fluid Data Members
DiagnosticFl I4 Diagnostic print flag for code debugging
Dimensional Units Conversion Factors
UomSystem I4 Identification number of dimensional units
system
Factors DMUOM data object. See Chapter 7.
Thermodynamic Method Identification
TherSetNo I4 Thermodynamic METHOD set number
TherSetID C16 Thermodynamic METHOD set identifier
Component Data
NOC I4 Total number of components in problem.
NOCMW I4 Number of Molecular weight components in a
simulation (excludes NMW Solids components).
CompIndex(i) I4 Internal component numbers, in input order. i =
1, NOC
Fluid Properties
TEMP DP Temperature of the fluid
PRES DP Pressure of the fluid
FMDecant DP Mole fraction DECANT component in total
stream
FWDecant DP Weight fraction DECANT component in total
stream
Flash Control Flags and Estimates
EstTemp DP Temperature estimate
EstPres DP Pressure Estimate
DUTY DP Enthalpy change applied by a DUTY flash
Entropy DP Total stream entropy for a PISEN or TISEN
flash
EstKValues I4 Flag for flash to reuse previous K values
Phase Members
Total FluidPhase Total Fluid phase object (always present)
Vapor FluidPhase Vapor phase
Liquid FluidPhase Bulk Liquid phase
L1 FluidPhase Light (non-decant) liquid sub-phase
L2 FluidPhase Heavy (Decant) liquid sub-phase

6-28 UAS Modular Fluids February 2009

 Table 6-8: class_Fluid Data Members
Solid FluidPhase Molecular-weight Solids phase
NMWSolid FluidPhase Non-Molecular-weight Solids phase
Validation Flags (always present)
Exist L4 Fluid existence flag. Always.TRUE. if fluid
exists.
Status L4 Status flag. .TRUE. if Total phase exists.
VapStatus L4 Status flag. .TRUE. if Vapor phase exists.
LiqStatus L4 Status flag. .TRUE. if Bulk Liquid phase exists.
L1Status L4 Status flag. .TRUE. if L1 sub-phase exists.
L2Status L4 Status flag. .TRUE. if L2 sub-phase exists.
SolidStatus L4 Status flag. .TRUE. if Solid phase exists.
NMWStatus L4 Status flag. .TRUE. if NMWSolid phase exists.

Fluid Identification
The data in this section identifies the fluid. PRO/II automatically
generates this information when it creates a UASOBJ. Users cannot
modify or access this information. Developers may find it useful
during the debugging stages of subroutine implementation.

Component Data
Each fluid includes basic information about the components in a
simulation. Since fluids typically are members of a UASOBJ data
structure, the component data of a fluid duplicates the component
data of the parent UASOBJ. Developers usually retrieve component
data from UASOBJ, in which case retrieving component data from
a fluid is not necessary.

NOC Total number of components in the simulation,

including NMWSolids.
NOCMW Number of molecular weight components, including
molecular weight Solids. NMWSolids are excluded.
CompIndex(i) Internal component numbers, in input order. i=1, NOC

PRO/II User-Added Subroutine User Guide 6-29

 Fluid Properties
A few properties are so useful that they have storage members
directly in the main fluid structure. Most properties are stored in the
fluid phase members.

Temp Temperature of the fluid.

Pres Pressure of the fluid.
FMDecant Mole fraction of DECANT phase in the total fluid.
FWDecant Weight fraction of DECANT phase in the total fluid.

The following code extract illustrates retrieval of properties from

the pre-defined fluid named Liquid that is a member of a UASOBJ
structure named UaUtil.
SUBROUTINE EFG( UaUtil )
USE class_UASOBJ
TYPE(UASOBJ), INTENT(INOUT) :: UaUtil
REAL(8):: TempI, PresI, RateI, FvapI, FliqI
. . .
TempI = UaUtil%Liquid%TEMP
PresI = UaUtil%Liquid%PRES
RateI = UaUtil%Liquid%FMDecant
FvapI = UaUtil%Liquid%FWDecant

Thermodynamic Method Set Identification

PRO/II simulations may contain several METHOD sets. The entries
in this section identify the thermodynamic METHOD set assigned to
a fluid and all its phases.
TherSetNo The integer number of the METHOD set assigned to
the fluid. This value is used in PRO/II call-back routines
to perform calculations.
TherSetID The character identifier of the METHOD set assigned
to the fluid. It contains up to 16 characters. TherSetID is
not used by PRO/II call-back routines; TherSetNo is
used instead. TherSetID may be useful when writing
reports from user-added subroutines. It has no effect on
any calculations.
The following fluid functions propagate TherSetNO and TherSetID
in the following ways:
create_Fluid assigned the DEFAULT METHOD when it instanti-
ates a fluid.

6-30 UAS Modular Fluids February 2009

 load_Fluid assigns the PRO/II stream METHOD to the fluid dur-
ing the data loading process.
store_Fluid assigns the fluid METHOD to the PRO/II stream
that stores the fluid data.
copy_Fluid assigns the source fluid METHOD to the target fluid
during the copy operations.
flash_fluid uses the fluid METHOD to perform the flash calcula-
tions. If a PRO/II stream is specified for the flash, the fluid
METHOD is assigned to the specified stream.

Phase Members
Fluids store most of their data in member data structures that repre-
sent different fluid phases. The Total phase stores most of the proper-
ties of the fluid as a whole. Other phase members, Vapor and Liquid in
particular, store properties of each phase present in the fluid.
Fluids created in a user-added subroutine using the create_Fluid
function always include all the phases listed in Table 6-9. This
includes all fluids created in user-added unit operation subroutines.
Table 6-10 does not apply to these fluids.
.
Table 6-9: Phases Available in a Fluid
Total Properties of the overall fluid; i.e., the Total phase. This
phase always is present in a fluid.
Vapor Properties of the Vapor phase of a fluid. This phase may or
may not be present.
Liquid Properties of the bulk Liquid phase in a fluid. This phase
may or may not be present.
L1 Properties of the L1 liquid sub-phase. This phase may or
may not be present.
L2 Properties of the L2 liquid sub-phase. This phase may or
may not be present.
Solid Properties of the molecular-weight solids phase. This
phase may or may not be present.
NMWSolid Properties of the non-molecular-weight solids phase. This
phase is not yet fully supported by PRO/II.

PRO/II User-Added Subroutine User Guide 6-31

 Table 6-10 lists the phases that may be present in each pre-defined
fluid member of a UASOBJ data structure. Currently, none of the
pre-defined fluids support the L1 or L2 phase.
Table 6-10: Phases in Pre-defined Fluids of a UASOBJ Data Structure
Phases Present in a Fluid
Fluid Name Total Vapor Liquid L1 L2
Vapor Yes Yes - - -
Liquid Yes - Yes - -
Iface Yes Yes Yes - -

Validation Flags
Fluid validation flags allow developers to test for the existence and
availability of data in a fluid object and its phase members. The
flags should be tested before attempting to access data from fluid
objects.

Exist Fluid existence flag, a logical variable. Always TRUE if

fluid exists. Do not attempt to use data from the fluid if
this flag is FALSE. Test this variable first, before
attempting to access any other data in the fluid.
For all the phase flags listed below, a value of +1 indicates data
has been loaded in the phase member of the fluid. Do not
attempt to use data when the value is 0 or -1.
Status Status flag for the entire fluid. When the value = 1, the
overall fluid and the Total fluid phase are present and
valid. This includes data for Fluid Identification, the
Validation Flags, Component Data, and the Fluid
Properties. The phase members must be tested
individually using the flags listed below.
VapStatus Vapor phase status flag. When this flag has a value =1,
data in the Vapor phase is available for use.
LiqStatus Liquid phase status flag. When this flag has a value =1,
data in the Liquid phase is available for use.
L1Status Status flag for L1 liquid sub-phase. When this flag has a
value =1, data in the L1 sub-phase is available for use.
L2Status Status flag for L2 liquid sub-phase. When this flag has a
value =1, data in the L2 sub-phase is available for use.
SolidStatus Status flag for the (molecular-weight) solids phase. When
this flag has a value =1, data in the Solid phase is available
for use.

6-32 UAS Modular Fluids February 2009

 NMWSolid Status flag for the Non-Molecular-Weight solids phase.
When this flag has a value =1, data in the NMWSolid phase
is available for use.

The following sample code illustrates one of many possible ways to

use the fluid validation flags. The only intent is to illustrate the logic
branching in Fortran code. The example is not intended to execute
successfully without further development.
SUBROUTINE EFG( Obj )
USE class_UASOBJ
TYPE(UASOBJ), INTENT(INOUT) :: Obj
INTEGER(4) :: IfErrFl, IfErrT, IfErrV, IfErrL
! Test for existence of Interface Fluid
IF( Obj%Iface%Exist ) THEN
IfErrFl = 0 ! Fluid Exists.
!
! Test validity of Total phase.
IF( Obj%Iface%Status .EQ. 1 ) THEN

IfErrT = 0 ! Total fluid data is valid

ELSE
IfErrT = 1 ! Error – invalid total fluid.
ENDIF
!
! Test validity of vapor phase.
IF(Obj%Iface%VapStatus .EQ. 1 ) THEN

IfErrT = 0 ! Vapor phase is valid.

ELSE
IfErrT = 1 ! Error – invalid vapor phase.
ENDIF
!
! Test validity of Liquid phase.
IF(Obj%Iface%LiqStatus .EQ. 1 ) THEN

IfErrT = 0 ! Liquid phase is valid.

ELSE
IfErrT = 1 ! Error – invalid liquid phase.
ENDIF
!
! Error – fluid dies not exist.
ELSE
IfErrFl = 1 ! Error – invalid fluid
ENDIF

PRO/II User-Added Subroutine User Guide 6-33

class_FluidPhase.mod
This module makes FluidPhase data objects available to fluids in
user-added subroutines. Pre-defined fluids in a UASOBJ data struc-
ture do not include all the defined phases. However, fluids instanti-
ated using create_Fluid always allocate all the supported phases.
This section describes the proper usage of class_FluidPhase.mod. It
also defines all the data in a fluidPhase data object. Remember that
phases always are members of fluids. User-added subroutines typi-
cally do not directly instantiate phase objects.

Usage of class_FluidPhase
FluidPhase data structures are available only as members of
fluids. Developers should adhere to the following guidelines
when writing code to access data from a FluidPhase object.
User-added subroutines do not need a USE statement for
class_FluidPhase, since Class_Fluid automatically does this.
All fluidPhase objects in a fluid have pre-defined names.
Tables 6-9 and 6-10 includes the names of all possible phases
that a fluid might contain.
All references to FluidPhase data should access the phase
as a member of a fluid (e.g., Fluid%Phase%prop).
Only direct member addressing is available for accessing
phase data. The class_FluidPhase module does not implement
accessor functions, so indirect addressing is not available.
Sample code that demonstrates accessing phase data appears in
the section "Fluid Phase Example" on page 6-36.

Direct Member Addressing in class_FluidPhase

Direct member addressing of phase data is an inherent part of
accessing fluid data. This is described by "Direct Member Access in
class_Fluid" on page 6-25.

Indirect Member Addressing in class_FluidPhase

The class_FluidPhase module does not implement accessor func-
tions. For this reason, indirect member addressing is not supported
for data in phases.

6-34 UAS Modular Fluids February 2009

 Data Structure of class_FluidPhase
Table 6-11 lists all the data members in a FluidPhase storage struc-
ture.
Table 6-11: class_FluidPhase Data Members
Phase Identification (always present)
ID C12 Identifies the phase, typically “Total”, “Vapor”, or
“Liquid”.
IdNo I4 An ID number assigned to the phase. Typically,
1 = Vapor phase
2 = Bulk Liquid phase
3 = L1 liquid sub-phase (not available)
4 = L2 liquid sub-phase (not available)
5 = Total phase (always present)
Name C40 A name for the phase, typically “Total Fluid”,
“Vapor Phase”, or “Liquid Phase”.
Validation Flag (always present)
Exist L4 .TRUE. when phase has been instantiated.
Phase Properties (always present)
RateM DP Mole rate, wt*moles / time
RateWt DP Weight rate, wt / time
RateV DP Volumetric rate, vol / time
RateVstd DP Standard volumetric rate, vol / time
MolecWt DP Average molecular weight of phase
Density DP Density, wt / vol
DensStd DP Standard density, wt / vol
Acentric DP Acentric factor
SpVolM DP Specific mole volume, vol / wt*mole
SpVolMSt DP Standard specific mole volume, vol / wt*mole
d
SpVolWt DP Specific weight volume, vol / wt
SpEnthM DP Specific mole enthalpy, 1000’s energy / wt*mole
SpEnthWt DP Specific weight enthalpy, 1000’s energy units / wt
SpEntroM DP Specific mole entropy, 1000’s energy / wt*mole
SpEntroW DP Specific weight entropy, 1000’s energy / wt
t
CpM DP Average Specific Heat of phase, energy / wt-mole

PRO/II User-Added Subroutine User Guide 6-35

 Table 6-11: class_FluidPhase Data Members
CpWt DP Average Specific Heat of phase, energy /weight
FracM DP Mole fraction of the phase in the total fluid
FracWt DP Weight fraction of the phase in the total fluid
FMDecant DP Mole fraction of decant component in the phase
FWDecant DP Weight fraction of decant component in the phase
ZDens DP Phase compressibility (from density)
ThCond DP Average phase thermal conductivity
Viscosity DP Average phase viscosity
SurfTens DP Average phase surface tension (Liquid phase only)
XFracM(i) DP Component mole fractions, wt*mole(i)/total phase wt
XFracWt(i) DP Component weight fractions, wt(i) / total phase wt
XConcM(i) DP Component concentrations, weight*mole/volume
XLact(i) DP Component liquid activities, i = 1, NOC
XFug(i) DP Component Fugacities, i = 1, NOC
KVal(i) DP Component K-values, i = 1, NOC
dKdT(i) DP Component K-value derivatives with respect to
temperature, i = 1, NOC

Fluid Phase Example

As an example of accessing phase data, consider the following. An
Iface fluid contains three phase members: Total, Vapor, and Liq-
uid. The sample code (below) retrieves the following data:
Mole fraction of vapor in the fluid.
Mole fraction of component 5 in the vapor phase.
Mole fraction of bulk liquid in the fluid.
Mole fraction of component 5 in the bulk liquid phase.
Mole rate of the total fluid.
Mole fraction of component 5 in the total fluid.

SUBROUTINE JKL( Obj )

USE class_UASOBJ
TYPE(UASOBJ), INTENT(INOUT) :: Obj
INTEGER(4) :: idx
REAL(8) :: FracMvap, FracM5vap
REAL(8) :: FracMliq, FracM5liq

6-36 UAS Modular Fluids February 2009

 REAL(8) :: RateMtot, FracM5tot
. . .
idx = 5
! vapor phase properties
FracMvap = Obj%Iface%Vapor%FracM
FracM5vap = Obj%Iface%Vapor%XFracM( idx )
!
! liquid phase properties
FracMliq = Obj%Iface%Liquid%FracM
FracM5liq = Obj%Iface%Liquid%XFracM( idx )
!
! total fluid properties
RateMtot = Obj%Iface%Total%RateM
FracM5tot = Obj%Iface%Total%XFracM( idx )

The sample code (above) retrieves the total fluid mole rate from the
Total phase of the fluid.

PRO/II User-Added Subroutine User Guide 6-37

6-38 UAS Modular Fluids February 2009
 Chapter 7
User-Added Units of Measure

Overview of User Dimensional Units

All data exchanged between PRO/II and any user-added subroutine
are passed using the dimensional units requested by the developer.
This is regardless of the units used for data input or output reporting
in a simulation. The dimensional units may be different for each
type of user-added subroutine, but every instance of a particular
type of UAS uses the same set of dimensional units. This chapter
refers to these UOM’s as User Dimensions.
Each UAUTIL declares its system of user dimensions in the
P2UasReg.ini file. In contrast, each UAUOP declares its UOM’s in
its associated INI file. User-added unit operations allow more flexi-
bility in choosing UOM’s than do user-added utility routines. The
following sections discuss these two categories of UAS separately.
The final sections in this chapter describe class_DMUOM.mod, a
module that provides dimensional units conversion factors to user-
added unit operations. The module is not available in user-added
utility routines.

Base Systems of Units of Measure

PRO/II provides four systems of dimensional units that are avail-
able for use in all modular user-added subroutines. Table 7-1 Lists
the keywords that identify these systems.
Table 7-1: Base Systems of Dimensional Units
System
Keyword Description
ENGLISH Common system used in the United States

METRIC Traditional KMS Metric system

SI International System of Measurements

PROII PRO/II Internal System of Measurement

PRO/II User-Added Subroutine User Guide 7-1

 Dimensional Classes in the Base System of Units
The registered set of dimensional units applies to all data exchanged
between PRO/II and a user-added subroutine. Table 7-2 lists the
keywords for the units of all dimensional classes in each of the
dimensional units systems. It includes the exact unit of measure
used by each class for each dimensional class.

Table 7-2: Base Sets of Dimensional Units of Measure

UOM Keywords
Class Description English Metric SI PRO/II
TEMP Temperature F C K K
TDIF Temperature change
PRES Pressure PSIA KG/CM KPA KPA
PDIF Pressure change PSI KG/CM KPA KPA
WT Weight LB KG KG KG
TIME Time HR HR HR SEC
LENG Length FT Meter Meter Meter
FLEN Fine Length INch MM MM Meter
AREA Area FT2 M2 M2 M2
FAREA Fine Area IN2 MM2 MM2 M2
VELO Velocity, LENG/TIME FT/S M/S M/S M/S
CAKE
LIQV Liquid Volume FT3 M3 M3 M3
VAPV Vapor Volume FT3 M3 M3 M3
EQVO Equivalent Volume, LIQV/ FT3/F M3/M M3/M M3/M
LENG
LDEN Liq. Density, WT/LIQV LB/FT KG/M KG/M KG/M
VDEN Vap. Dens., WT/VAPV LB/FT KG/M KG/M KG/M
XDEN Petro Density, WT/LIQV LB/FT KG/M KG/M KG/M
SPVO Specific Volume, LIQV/WT- FT3/LB M3/KG M3/KG M3/KG
mole
ENER Energy BTU KCAL KJ KJ
WORK Work, ENER/TIME HP KW KW KJ/S
DUTY Duty, ENER/TIME * 1.0e6 BTU/HR KC/HR KJ/HR KJ/S
ENTH Enthalpy, ENER/WT BTU/LB KC/KG KJ/KG KJ/KG

7-2 User-Added Units of Measure February 2009

Table 7-2: Base Sets of Dimensional Units of Measure
UOM Keywords
Class Description English Metric SI PRO/II
ENTR Entropy, ENER/ BTU/LB KC/KG KJ/KG KJ/KG
(WT*TEMP)
CP Heat Capacity, ENER/ BTU/LB KC/KG KJ/KG KJ/KG
(WT*TEMP)
MRAT Mole Rate, (WT*mole) / LBM/HR KGM/HR KGM/HR KGM/S
TIME
WTRA Weight Rate, WT/TIME LB/HR KG/HR KG/HR KG/S
LVRA Liquid Volume Rate, LIQV/ FT3/HR M3/HR M3/HR M3/S
TIME
GVRA Gas Volume Rate, VAPV/ FT3/HR M3/HR M3/HR M3/S
TIME
COND Thermal Conductivity BTU/HR KC/HR W/MK W/MK
VISC Viscosity CP CP PAS PAS
KINE Kinematic Viscosity CST CST CST CST
SURF Surface Tension D/CM D/CM N/M N/M

HTCO Heat Transfer, ENER/ BTU/HR KC/HR KW/MK KW/MK

(TIME*AREA*TEMP)
FOUL Fouling Coefficient HFF/B HMC/K MK/KW MK/KW
UA U*A value, ENER/ BTU/HF KC/HC KW/K KW/K
(TIME*TEMP)
SPHT Specific Heat, ENER/ BTU/LB KC/KG KJ/KG KJ/KG
(WT*TEMP)
FRAC Fraction FRAC FRAC FRAC FRAC
PCT Percentage PCT PCT PCT PCT
PPM Parts per million PPM PPM PPM PPM
ANGL Angle RAD RAD RAD RAD
DIPO Dipole Moment DEB DEB DEB DEB
HVAL Heating Value, ENER/ BTU/FT3 KC/M3 KJ/M3 KJ/M3
VAPV
RUA Radial U*A coefficient

PRO/II User-Added Subroutine User Guide 7-3

UAUTIL User Dimensions
PRO/II calls each UAUTIL subroutine with a single argument in the
call list. The argument is a data object of TYPE(UASOBJ). All data in
the UASOBJ structure are passed in already converted to user dimen-
sions. Refer to Chapter 4, “Modular Utility Subroutines” for a gen-
eral introduction to the UASOBJ module.
The developer of a user-added utility may choose any one of the
systems listed in Table 7-1 as the set of user dimensions for the rou-
tine. A UAUTIL does not allow changing the units of individual
classes in the chosen system. The developer must inform the end-
users of the correct set of units.
The end-user must declare the set of units when registering the util-
ity subroutine in PRO/II’s P2UasReg.INI file. See “Chapter 2, “Reg-
istering User-Added Utilities” for a description of the registration
process.
For example, the following code segment in the P2UasReg.INI file
registers two interfacial area utilities that are identical except for the
UOM’s used to exchange data with PRO/II. It also registers a mass
transfer utility that uses English units.
;[UAIAREA] UOM
; UAS ID Path DLL name routine System
; ---------- ---- ---------- --------- -------
"myIFENG" 4 "myUA.dll" "IFENGL" ENGLISH
"myIFMET" 4 "myUA.dll" "IFMETR" METRIC
“muMassE” 4 “myUA.dll” “IMAENG” ENGLISH

In the "myIFENG" entry, note the keyword ENGLISH entered for

the “UOM System” entry. All instances of this UAUTIL call sub-
routine “IFENGL”, which expects data in the UASOBJ of the argu-
ment list to be in English units (column 3 of Table 7-2). The
"myIFMET" utility on the last line uses the METRIC UOM system.

While the structure and data content in the UASOBJ’s are identical
for both IFAREA utilities, the numeric values are in different units.
For instance, pressure values in English units are psia, but pressure
in metric units are kg/cm2. Developers and users can be confident
that these conventions apply to every instance of each of these two
utility routines.

Similarly, a UASOBJ passed to instances of mass transfer utility

“muMassE” contains different data than a UASOBJ passed to either
interfacial area utility. However, both objects use the same set of
user dimensions (English). Thus, for example, any pressure data in
either UASOBJ is passed using units of psia.

7-4 User-Added Units of Measure February 2009

 Note: For information specific to each type of utility routine refer
to Chapter 11, “Interfacial Area Utility”, Chapter 12, “Binary
Mass Transfer Utility”, and Chapter 13, “Heat Transfer Utility”.

UAUOP User Dimensions

User-added unit operations do not register their units of measure in
the P2UasReg.ini file. Instead, they allow specifying dimensional
units for individual classes in their “ini” files.
A developer first declares a pre-defined system of units using a
BASE statement and a UOM system keyword from column 1 of
Table 7-1. Subsequent statements may “override” the base units
used by individual classes in the system. The selected base system,
together with all the individual class overrides collectively are
known as a system of “user dimensions”.
User-added unit operations (UAUOP) include a member named
%Factors that is an instance of class_DMUOM. User-added utilities
cannot access this class.
Usage of class_DMUOM in a UAUOP
Each UAUOP data object includes a member named %Factors
which is an instance of class_DMUOM. All units of measure data
are initialized and available in the %Factors member.
Never attempt to alter the data in the DMUOM data structure.
The data in the DMUOM structure allow converting data values
between user units and PRO/II internal units of measure. Two sets
of factors are available: one to convert from user units to PRO/II
and the other to convert back from PRO/II to user units. The format
for using both sets of conversion is the same:
Value to = Value from * Factor
Because temperature and pressure allow relative values (e.g., F, C,
psi, barg), conversion of these classes additionally requires use of a
translation factor. For example, to convert temperature or pressure,
use:

Value to = Value from * Factor + Offset

Use accessor function GetFactor_DmUom( ), described below, to

obtain the desired conversion Factor and (when required) Offset.

PRO/II User-Added Subroutine User Guide 7-5

Definition of class_DMUOM.mod
This section describes the proper usage of class_DMUOM mod in a
modular user-added unit operation. The class includes a data struc-
ture and member methods for accessing and using dimensional
units data and conversion factors. The module is available only in
modular user-added unit operations. Modular utility routines do not
permit access to this module, since the data in class_DMUOM are
not initialized when PRO/II calls a UAUTIL.

Data Structure of class_DMUOM

The data structure included in class_DMUOM is a derived-type of
object assigned the type name DMUOM. It contains the conversion
factor data necessary to convert between defined USER dimen-
sional units (used by the user-added subroutine) and internal PRO/II
units of measure.
Data in the data structure should be accessed using the accessor
member functions of class_DMUOM, so it is not documented here.
However, a status flag is available to test the availability of data in
the object.
Status A flag indicating the state of the data structure; an inte-
ger variable.
-1 = not allocated, no data storage available
0 = Allocated, no data
+1 = Allocated, data valid

Accessor Functions

GetFactor_DmUom( )
This function retrieves one scaling factor and its associated transla-
tion factor to perform a dimensional units conversion. This accessor
function is a member of class_DMUOM. The input arguments spec-
ify which factor to retrieve.
Calling sequence:
iStat = GetFactor_DmUom( cSysIn, cClassIn, &
UomObj, FacOut, OffOut, cIdOut )
Where:
cSysIn Input character keyword that specifies the system of
units from which to convert. Valid entries are:
“USER” Requests a factor to convert from a user unit to a
PRO/II internal unit. May be abbreviated as “U”.

7-6 User-Added Units of Measure February 2009

 “P2” Requests a factor to convert from a PRO/II internal unit
to a user unit. May be abbreviated as “P”.
cClassIn Input character keyword that identifies the class of the
requested conversion factor. This keyword may be any
entry listed in the left-most column of Table 7-2.
UomObj An instance of a DMUOM data object. Currently, this
should be the %Factors member of the UAUOP structure
passed through the argument list in calls to a user-added
unit operation. This is an input argument.
FacOut Returned scalar double precision conversion factor.
OffOut Returned scalar double precision translation factor asso-
ciated with FacOut. This argument is used only when the
requested conversion is for temperature or pressure.
When cClassIn specifies any other dimensional class,
OffOut always returns a value of zero.

cIdOut Returned 16 character variable containing the keyword

identifier of the dimensional unit specified by cSysIn
and cClassIn. Note: This is the “from” unit. A fairly
comprehensive listing of all available dimensional key-
words appears in Table 4-2 of the “PRO/II Keyword
Manual”.
iStat Returned status flag indicating success of failure of the
call. Possible values include:
>=1 Success, no error, returns class ID number.
0 Failure, cClassIn is invalid.
-3 Failure, cSysIn is invalid.
Any other negative value - Failure, unspecified reasons.

cGetID_DMUOM( )
This function returns the keyword identifier for the units of measure
of a specified dimensional class and system. It is a member function
of class_DMUOM. It supports only PRO/II internal units and user
units.
Calling sequence:

cIDout = cGetID_DMUOM( cSysIn, cClassIn, &

UomObj )

Where:
cSysIn Input character keyword that specifies the system of
units from which to convert. Valid entries are:

PRO/II User-Added Subroutine User Guide 7-7

 “USER” Requests an identifier from the user system of units
May be abbreviated as “U”.
“P2” Requests an identifier from the PRO/II internal system
of units. My be abbreviated as “P”.
When cSystem specifies an unrecognized system of units,
cGetID_DMUOM returns the identifier of the user unit.

cClassIn Input character keyword that identifies the dimensional

class of the requested identifier. This keyword may be
any entry listed in the left-most column of Table 7-2.
UomObj An instance of a DMUOM data object. Currently, this
should be the %Factors member of the UAUOP structure
passed through the argument list in calls to a user-added
unit operation. This is an input argument.
cIDout A local character variable that accepts the identifier
returned from cGetID_DMUOM. If argument cClassIn is
invalid, cIDout returns the string “INVALID”. If the call
failed due to an internal error, cIDout returns a blank
string.

Examples
The following illustrates the proper usage for class_DMUOM using
the recommended accessor functions. The sample code represents a
subroutine within a user-added unit operation model where a
UAUOP object is passed in through the argument list.

Example 16-1
Subroutine MyCode( Context, UaUopObj, ISOLVE )
USE class_UAUOP
CHARACTER(LEN=*) :: Context
TYPE(UAUOP) :: MyUop
INTEGER(4), INTENT(OUT) :: ISOLVE

REAL(8) :: PresUA, TempUA, WorkUA, &

PresP2, TempP2, WorkP2, &
FacUA, OffUA, FacP2, OffP2
INTEGER(4) :: iStat
CHARACTER(LEN=16) :: cIdUomUA, cIdUomP2
!
ISOLVE = 1
!
! Convert a temperature, a pressure, and work
! from user units to PRO/II internal units
!
PresUA = 14.6959D+0 ! assume psia
!
iStat = GetFactor_DmUom( “USER”, “PRES”, &

7-8 User-Added Units of Measure February 2009

 myUop%Factors, FacUA, OffUA, cIdUomUA )
!
IF( iStat .GE. 1 ) THEN
!
PresP2 = PresUA * FacUA + OffUA ! Eqn 1
!
cIdUomP2 = cGetID_DMUOM( “P2”, “PRES”, &
myUop%Factors )
END IF
End Subroutine MyCode

Notes:
The statement “TYPE(UAUOP): MyUop“ declares the UAUOP data
object which includes “myUop%Factors“, an instance of
class_DMUOM.

Local variable PresUA is set to any value (here, 14.6959). All cal-
culations are assumed to be in user units, so PresUA is user units.
The call to GetFactor_DmUom retrieves the factor and offset to
convert pressure from user units to PRO/II internal units. The con-
version factor returns in variable FacUA with the associated transla-
tion factor returned in OffUA. The unit identifier returned in
cIdUomUA is the user unit for pressure.

Equation 1 applies the returned conversion terms to PresUA, result-

ing in variable PresP2 having the pressure value in internal PRO/II
units.
Finally, the call to “cIdUomP2 = cGetID_DMUOM( “P2”, “PRES”,”
returns the identifier for the PRO/II internal pressure units.

PRO/II User-Added Subroutine User Guide 7-9

7-10 User-Added Units of Measure February 2009
 Chapter 8
UAUOP AutoGUI

Overview
Each modular user-added unit operation allows developers to create
a custom data entry window (DEW). Simulation users use the win-
dow to enter and modify input data for the UAUOP. The window is a
dialog box with one or more tabs. Users click a tab to display a pane
of data. The infrastructure in PRO/II that provides this support is
called the AutoGUI.
The AutoGUI reads an XML text file that specifies the unit operation
data to display in the tabbed dialog box. The AutoGUI tool then cre-
ates and positions the data in the tabbed dialog box. Simple interac-
tions can be specified in the XML file, with no GUI programming
required.
This chapter provides details about using the AutoGUI to create
tabbed data entry dialog boxes for PRO/II UAUOP units. It specifies
the syntax of the XML used for creating the dialog boxes, and
shows some sample screens using AutoGUI.

Notation Used in this Chapter

To clarify the explanations, the following conventions are used in
this chapter.
Many XML tokens are enclosed in chevrons, e.g., <Spec>. The
chevrons are part of the token. In use, they usually have separate
start and end forms that encloses member elements; for example,
<Spec attributes> members </Spec>.

Bold font is for emphasis only.

XML tokens are case sensitive. For example, <SPEC> and <Spec>
represent different XML elements.
XML elements in monospaced font are exact tokens or names
that should be used exactly as they appear. For example,
Name=”AutoGUI” is the exact element that should be used as
shown, including the quotation marks.
Italicized text indicates generic placeholders that should be replaced
with appropriate data. For example, HelpFile=”filename.hlp”

PRO/II User-Added Subroutine User Guide 8-1

 indicates that the developer should replace filename with an actual
file name.
All quotation marks shown in the XML samples are required.

Basic XML File Structure

Table 8-1 shows the basic structure of an AutoGUI XML file
Table 8-1: Basic Structure of an AutoGui XML file
<SpecList Name="AutoGUIUop" HelpFile="filename.hlp">
<Spec Name="Tab 1 name" Type="Normal" UseNewSchema="1">
<!-- Specify Individual controls for this tab here. -->
</Spec>
<Spec Name="Tab 2 name" Type="Normal" UseNewSchema="1">
<!-- Specify Individual controls for this tab here. -->
</Spec>
</SpecList>

The AutoGUI XML file has a single <SpecList> XML element

that contains everything else in the file
Inside the <SpecList> element are one or more <Spec> ele-
ments.
Each <Spec> element defines the contents of one tab in the dia-
log box.
Inside each <Spec> element are additional elements that iden-
tify the specific UAUOP attributes to be displayed in that tab.
The sections below present specific information and examples of
displaying different types of attributes.

8-2 UAUOP AutoGUI February 2009

Associating an XML file with a UAUOP Unit Operation
The files listed in Table 8-2 are required for a UAUOP unit opera-
tion to implement AutoGui windows in PRO/II.
Table 8-2: AutoGui Files Associated with a UAUOP
File name Location Description
myUaUop.dll %P2Install%\Bin DLL containing runtime code for
UAUOP unit operation XXX
myUaUop.ini %P2Install%\System Data Definition file
myUaUopIcon.dat %P2Install%\System Definition file for the icon to
display on the PFD icon palette
and in the PFD flowsheet. See
Chapter 9, UAUOP Icons.
myUaUop.xml %P2Install%\System AutoGUI XML definition file.

Note: %P2Install% refers to the installation directory, such as

C:\simsci\proii82. See "Registering a Path to a User-Added DLL"
on page 2-9 for information about specifying the PRO/II installa-
tion path.
Before using an AutoGUI.XML file with a UAUOP unit operation, it
must be associated with the UAUOP. This linkage is accomplished
by modifying the myUaUopIcon.dat file:
GROUP 420001 "AutoGUI Test" "UAUOP" 1 "AutoGUIUOP"
ICON "AutoGUI Test" 60 0 20.0 "AG%d" 1 0
FORM P2GenericUnit.dll myUaUop.xml
Specifically, the FORM line must specify P2GenericUnit.dll as
the first argument and the name of your XML file as the second
argument.

PRO/II User-Added Subroutine User Guide 8-3

XML Schema Reference
The list of XML elements and attributes for the XML-based tabbed
dialog box is specified in Table 8-3. Detailed explanation of key ele-
ments are provided after the table. Specific examples appear later in
this chapter.
In Table 8-3, “AutoGUI XML Schema in PRO/II,” on page 4:
(R) refers to an XML element or attribute which is required.
A number in parenthesis specifies the number of elements
required or allowed.
In column 4, “Text Value”, the terms used are:
none – The attribute/element does not accept a text value.
String – The attribute/element accepts any unquoted string
value.
“string” – The attribute/element accepts any character string
enclosed in quotation marks.
"xxx" – A text value in quotes means that the text value must
be specified exactly as shown, where xxx is the exact text and
the quotation marks are required.
Integer – The text value must be a numeric integer value.
monospaced font – An exact entry to use as shown.

Table 8-3: AutoGUI XML Schema in PRO/II

Attribute of Text Value
XML Child Elements of of Element
XML Element Element XML Element or Attribute
<SpecList> None
Name= (R) “String”
<Spec> (1 or more) None
<Spec> None
Name= (R) “String”
Type= (R) “Normal”
<Group> (0 or more) None
<Parameter> None
(0 or more)
<Variable> None
(0 or more)

8-4 UAUOP AutoGUI February 2009

 Table 8-3: AutoGUI XML Schema in PRO/II
Attribute of Text Value
XML Child Elements of of Element
XML Element Element XML Element or Attribute
<Constraint> None
(0 or more)
<Group> None
Name= (R) “String”
Type= (R) “Normal”,
“Weak”,
“Strong”
<Count> (0 or 1) Integer
<Desc> (0 or 1) String
<ShowTitleHeader> String or
(0 or 1) false
<NoLabel> true or
(0 or 1) false
<Group> (0 or more) None
<Parameter> None
(0 or more)
<Variable> None
(0 or more)
<Constraint> None
(0 or more)

PRO/II User-Added Subroutine User Guide 8-5

 Table 8-3: AutoGUI XML Schema in PRO/II
Attribute of Text Value
XML Child Elements of of Element
XML Element Element XML Element or Attribute
<Parameter> None
Name= (R) “String”
Type= (R) “Choice”,
“Option”,
“Selection”
“Real”,
“Integer”,
“String”
<Desc> (0 or 1) String
<ValueDomain> String
(0 or 1)
<ReadOnly> (0 or 1) True or
false
<Required> (0 or 1) Req or
opt or
none
<NoLabel> (0 or 1) True or
false
<Count> (0 or 1) Integer
<CreateSideBySide> True or
(0 or 1) false
<ToolTip> (0 or 1) String
<ShowTitleHeader> String or
(0 or 1) “false”
<Variable> None
Name= (R) “String”
<Desc> (0 or 1) String
<ReadOnly> (0 or 1) True or
false
<Required> (0 or 1) Req or
opt or
none
<NoLabel> (0 or 1) True or
false
<Count> (0 or 1) Integer
<CreateSideBySide> True or
(0 or 1) false

8-6 UAUOP AutoGUI February 2009

 Table 8-3: AutoGUI XML Schema in PRO/II
Attribute of Text Value
XML Child Elements of of Element
XML Element Element XML Element or Attribute
<Variable> <MilanoAttribute> I or
(0 or 1) L
<ShowTitleHeader> String or
(0 or 1) false
<ToolTip> (0 or 1) String
<Value> None
Name= (R) “String”
Type= “Real”,
“Integer”,
“String”
<Desc> (0 or 1) String
<DependentGroup> “Name” of
(0 or more) Group element
<Constraint> None
<Desc> (exactly 1) String
<CreateSideBySide> True or
(0 or 1) false
<Image> None
Name= (R) String
<FileName> String
(exactly 1)
<Client> (0 or 1) True or
false
<Height> (0 or 1) Integer
<Width> (0 or 1) Integer
Miscellaneous Elements that are Children of Other Elements
<Count> Integer
<CreateSideBySide> True or
false
<Desc> String
<NoLabel> True or
false
<MilanoAttribute> I or L
<ReadOnly> True or
false

PRO/II User-Added Subroutine User Guide 8-7

 Table 8-3: AutoGUI XML Schema in PRO/II
Attribute of Text Value
XML Child Elements of of Element
XML Element Element XML Element or Attribute
<Required> Req or
opt or
none
<ShowTitleHeader> String or
false
<ToolTip> String
<ValueDomain> String
<SpecList> None
Name= (R) “String”
<Spec> (1 or more) None

Notes

Client
The <Client> element is a child element of <Image>. Refer to the
topic "Image" on page 8-10 for details.

Constraint
The <Constraint> element is used to display static text on the tab.
The <Desc> child element specifies the text to display.

Count
The <Count> element is a child of <Parameter> or <Variable>.
When used as a child element of a vector variable or vector parame-
ter, it defines the number of rows to display. When used as a child
element of a scalar variable or scalar parameter, it defines the width
(approximate number of characters) to display.

CreateSideBySide
The <CreateSideBySide> child element is used to modify the
default positioning of a control. Normally, controls are stacked ver-
tically in the tabbed dialog box. In some cases however, it is more
intuitive to place two controls side-by-side. For example, if a check
box is used to enable/disable a single edit control, the <NoLabel>
and <CreateSideBySide> elements can be used to place the edit
control next to the controlling check box.

8-8 UAUOP AutoGUI February 2009

 Desc
The <Desc> element specifies the actual text to display in the
tabbed dialog box of the parent XML element.

DependentGroup
The <DependentGroup> element is a child of the <Value> element
and is used to specify interactions between controls. See the
<Value> element for a detailed description.

FileName
The <FileName> element is a child element of <Image>. Refer to
the topic "Image" on page 8-10 for details.

Group
The <Group> element is used to group one or more items for pur-
poses of display or control. A group can be displayed in a group box
or grid. A group can also be enabled (or shown) based on the state
of a parent control (a check box, radio button, or drop-down list
box). The <Group> element supports the following attributes.
Name= This attribute specifies the text identifier for the group.
This text identifier is used in the <DependentGroup>
child element to associate the parent control (such as a
check box) with this dependent group of controls.
Type= This attribute specifies the type of display to be used for
the group and can have the following values:
“Weak” Displays the controls normally (without a
group box or a grid).
“Normal” Creates a group box around the controls speci-
fied as child elements of this <Group> element.
The text of the <Desc> child element is dis-
played as group box title.
“Strong” Creates the child controls in a grid. The child
controls must be one of the following types:
Scalar Variables: The grid is row-based; each
variable is displayed in its own row.
Scalar Parameters: The grid is row-based;
each parameter is displayed in its own row.

PRO/II User-Added Subroutine User Guide 8-9

 Note: Scalar variables and scalar parameters can be combined in
one strong group.
Vector Variables: The grid is column-based;
each vector variable is displayed in a sepa-
rate column, each element of the vector
variable is displayed in its own row. This
implies that the number of elements for
each vector variable must be the same.
Vector Parameters: The grid is column-based;
each vector parameter is displayed in a sep-
arate column, each element of the vector
parameter is displayed in its own row. This
implies that the number of elements for
each vector parameter must be the same.
Height The <Height> element is a child element of <Image>.
See “Image” (below) for details.

Image
The <Image> element is used to display image files in the tabbed
dialog box. The image formats supported are BMP, JPEG, and GIF.
The <FileName> child element specifies file name of the image file.
The <Client> child element specifies whether the file is located in
the client side; for PRO/II, this element. If <Client> is not
specified, the file location is considered to be a Server.
The image file should be located in \simsci\proiiNN\resource. The
display size of the image also can be specified through the <Height>
and <Width> child elements. If not specified, the image will be dis-
played in its actual size.

MilanoAttribute
The <MilanoAttribute> element is a child of the <Variable> element.
The text value of this element can be:
I (Capital I) If the <MilanoAttribute> element is not
present, or the text value is I, then the user input value of
the parent variable element will be displayed in the
tabbed dialog box.

8-10 UAUOP AutoGUI February 2009

 L If the text value is L (“level”, or calculated value), then
the calculated value of the variable is displayed.

NoLabel
The <NoLabel> element can be used to suppress the display of the
text label in front of the edit control. This element is typically used
with the <CreateSideBySide> element in an interaction scenario.
For example, to configure a check box to enable/disable a target edit
field,
1. Create the edit field in a <Group> element, so the group name
can be specified as the dependent group of the check box.
2. In the edit field, include the elements <CreateSideBySide> and
<NoLabel> with values of true to display the edit field next to
the controlling check box.

Parameter
The <Parameter> element is used to create a check box, radio but-
ton, combo box, or edit field, depending on the type. A vector
parameter will automatically be created as a grid, with each element
of the vector appearing in its own row. Attributes include:
Name= The name of the PRO/II database attribute associated
with this parameter element is specified using the
Name= attribute. See “Variable and Parameter Names”
on page 14 for more details.
Type= The type of parameter is specified using the Type=
attribute. The valid parameter types are:
“Choice” Creates a check box. The PRO/II database
attribute must be an integer (INT) value. By
default, a value of 0 means unchecked and a value
of 1 means checked.
This element can contain one or more <Value>
child elements which can be used to control the
show/hide or enable/disabled status of dependent
groups of controls. Control groups are defined
using the <Group> element. There can be only one
dependent group which will be enabled if the check
box is checked and disabled if unchecked.

PRO/II User-Added Subroutine User Guide 8-11

 If no <Value> child elements are provided, the
default values are used to control checked/
unchecked status.
“Option” Creates two or more radio buttons. The PRO/II
database attribute must be an integer (INT) value.
Each radio button is associated with a specific data-
base value using a <Value> child element.
“Selection” Creates a drop-down list box. The PRO/II
database attribute must be an integer (INT) value.
Each item in the drop-down list box is associated
with a specific database value using a <Value>
child element.
“String” or Each of these creates and edit field. The
“Real” or PRO/II database attribute may be an
“Integer” integer value (INT), a double value (DBL),
or a text value (TEXT).
The child elements <CreateSideBySide>, <Required>, <NoLabel>,
and <ReadOnly> may be used to specify additional characteristics.

ReadOnly
The <ReadOnly> element can be used to display information while
preventing the user from modifying it. Set the text value of this ele-
ment to true to create a read-only control.

Required
The <Required> element sets the required/optional state of the con-
trol. The valid values are
req Indicates that an input user value is required. If the user
does not supply a value, the border will be red.
opt Indicates that an input user value is optional. If the user
does not supply a value, the border will be green.
none Indicates that no border color will be used.

ShowTitleHeader
The <ShowTitleHeader> element specifies text to be displayed in
cell (0,0) of a grid when displaying an array parameter or an array
variable.

8-12 UAUOP AutoGUI February 2009

 Spec
Each <Spec> element in the XML document denotes a single tab in
the tabbed dialog box.

Note: For PRO/II, each <Spec> element must include the

Type=”Normal” attribute.

Type=“Normal” The Type= attribute of the <Spec> node must have

the value “Normal”. Normal tabs are displayed when
the user double-clicks on the unit operation icon in the
flowsheet.
Desc= This attribute (if specified) or the Name= attribute will
be displayed as the tab name.

SpecList
The <SpecList> element is the top-level element in the XML file.
There is only one <SpecList> element in an AutoGUI XML file.
This element will contain one or more <Spec> elements.

ToolTip
The <ToolTip> element specifies the text to be displayed as a tooltip
when the mouse hovers over the control. Tooltips are not supported
in a grid.

Value
One or more <Value> elements may be specified as a child element
of a <Parameter> element if its Type= attribute is “Choice”,
“Option”, or “Selection”. The purposes of the <Value> element are:

1. Associate a database attribute value to a human-readable

description. The Name= attribute of the <Value> element iden-
tifies the database value for which the information in the
<Value> element will apply. The <Desc> child element contains
the text that will be displayed to the user when the database
value matches the Type= attribute.
2. Control the enable/disable (or show/hide) state of a dependent
group of controls. The Name= attribute of the <Value> element
identifies the database value for which the information in the
<Value> element will apply. The <DependentGroup> child ele-
ment identifies the name of the <Group> element containing the
controls that are enabled (or shown) when the database value
matches the Type= attribute.

PRO/II User-Added Subroutine User Guide 8-13

 ValueDomain
The <ValueDomain> element is currently used only to display a list
of Thermodynamic METHOD sets in a drop-down list box, where
the parent element is a <Parameter> element whose Type= attribute
is “Selection”. The text value of this element must be THERMOSETS.
See Example 5 below for an example of defining a drop-down list
box to choose a thermodynamic METHOD set.

Variable
The <Variable> element creates a double precision edit field that
supports the PRO/II DEFINE construct. The PRO/II database
attribute must be a parameter (PAR) value. A vector variable will
automatically be created as a grid, with each element of the vector
appearing in its own row. The name of the PRO/II database attribute
associated with this variable element is specified using the Name=
attribute. See “Variable and Parameter Names” (below) for more
detail.
The child elements <Required>, <NoLabel>, <ReadOnly>,
and <CreateSideBySide> may be used to specify additional
characteristics.

Variable and Parameter Names

AutoGUI XML files use PRO/II database attributes. For a modular
User-Added Unit Operation (UAUOP), the attribute names are
defined in a configuration (INI) file. For demonstration purposes,
Figure 8-1 shows part of the data definition in a UAUOP INI file.
Figure 8-1: Sample UAUOP INI File Data Definition
INT 1 "MyScalarINT" 1 None -2111111111 -2111111111 -2111111111
INT 2 "MyVectorInt" 10 None -2111111111 -2111111111 -2111111111
PAR 1 "MyScalarPAR" 1 None -1.5E35 -1.5E35 -1.5E35
PAR 2 "MyVectorPAR" 10 None -1.5E35 -1.5E35 -1.5E35
DBL 1 "MyScalarDBL" 1 None -1.5E35 -1.5E35 -1.5E35
DBL 2 "MyVectorDBL" 10 None -1.5E35 -1.5E35 -1.5E35
TEX 1 "MyScalarTEX" 1 5 11
TEX 2 "MyVectorTEX" 10 5 11

Table 8-4 shows the proper Name= syntax for referring to the
UAUOP data attributes declared in Figure 8-1.

8-14 UAUOP AutoGUI February 2009

 Table 8-4: AutoGUI XML Access to PRO/II UAUOP Attributes
Name= Description of UAUOP data
Name=“MyScalarINT” Name for a scalar INT value (INT 1, a
scalar integer)
Name=“MyVectorINT[0]” Name for one element (the first) of
an integer array (INT 2)
Name=“MyVectorINT” Name for an entire INT array (INT
2)
Name=“MyScalarPAR” Name for a scalar parameter value
(PAR 1)
Name=“MyVectorPAR[4]” Name for one element (the fifth) of
a parameter array (element 5 of PAR
2)
Name=“MyVectorPAR” Name for an entire parameter array
(PAR 2)
Name=“MyScalarDBL” Name for a scalar parameter value
(DBL 1)
Name=“MyVectorDBL[9]” Name for one element (the tenth) of
a DBL array (element 10 of DBL 2)
Name=“MyVectorDBL” Name for an entire DBL array
(DBL 2)
Name=“MyScalarTEX” Name for a scalar text value
(TEX 1)
Name=“MyVectorTEX[0]” Name for one element (the first) of
a text array (element 10 of TEX 2)
Name=“MyVectorTEX” Name for an entire text array
(TEX 2)
Note: Use square brackets to declare subscripts,
e.g.,”MyVectorDBL[9]”

Width
The <Width> element is a child element of <Image>. Refer to the
topic "Image" on page 8-10 for details.

PRO/II User-Added Subroutine User Guide 8-15

AutoGUI Examples
This section contains various AutoGUI examples. Each example
shows the relevant portion of a UAUOP data definition *.INI file, the
source XML file, and the resulting GUI image.

Example 1: Display Scalar Edit Fields

This demonstrates the basic setup required to display scalar values
in float, integer, and text edit fields.

.ini file
[Data Definition]
MAXINT = 1
TOTINT = 1
MAXPAR = 1
TOTPAR = 1
MAXDBL = 1
TOTDBL = 1
MAXTEX = 1
TOTTEX = 2

INT 1 “ScalarINT” 1 None -2111111111 -2111111111 -2111111111

PAR 1 “ScalarPAR” 1 TEMP -1.5E35 -1.5E35 -1.5E35
DBL 1 “ScalarDBL” 1 None -1.5E35 -1.5E35 -1.5E35
TEX 1 “ScalarTXT” 1 8 9

.xml file
<SpecList Name=”AutoGUI Ex01">

<Spec Name=”Edit Fields” Type=”Normal”>

<Parameter Name=”ScalarINT” Type=”Integer”>

<Desc>Scalar Integer:</Desc>
<Required>none</Required>
</Parameter>

<Variable Name=”ScalarPAR”>
<Desc>Scalar Parameter:</Desc>
<Required>req</Required>
</Variable>

<Parameter Name=”ScalarDBL” Type=”Real”>

<Desc>Scalar Double:</Desc>
<Required>opt</Required>
</Parameter>

<Parameter Name=”ScalarTXT” Type=”String”>

<Desc>Scalar Text:</Desc>
<Required>none</Required>
</Parameter>

8-16 UAUOP AutoGUI February 2009

 </Spec>

</SpecList>
The <Variable> element is used to display the PAR attribute Scrap-
per (PAR 1 in the INI file listing). The 3 <Parameter> elements are
used to display INT, DBL, and TEXT attributes. If the unit-of-mea-
sure is specified for a PAR or DBL attribute (see PAR 1 in the INI file
listing), it will be used in the tabbed dialog box. The <Required>
element is used to specify the border color convention for missing
data.

Result
The resulting AutoGUI display is shown in Figure 8-2.
Figure 8-2: Example 1 AutoGUI Display

PRO/II User-Added Subroutine User Guide 8-17

 Example 2: Display Vector Edit Fields
This demonstrates the basic setup required to display vector values
in grids.

.ini file
[Data Definition]
MAXINT = 1
TOTINT = 10
MAXPAR = 1
TOTPAR = 10
MAXDBL = 0
TOTDBL = 0
MAXTEX = 0
TOTTEX = 0

INT 1 “ArrayINT” 10 None -2111111111 -2111111111 -2111111111

PAR 1 “ArrayPAR” 10 TEMP -1.5E35 -1.5E35 -1.5E35

.xml file
<SpecList Name=”AutoGUI Ex02”>

<Spec Name=”Arrays 1" Type=”Normal”>

<Parameter Name=”ArrayINT” Type=”Integer”>

<Desc>Array Integer:</Desc>
</Parameter>

<Variable Name=”ArrayPAR”>
<Desc>Array Parameter:</Desc>
</Variable>

</Spec>

<Spec Name=”Arrays 2" Type=”Normal”>

<Group Name=”Group1” Type=”Strong”>

<Desc>Both Arrays in same Grid</Desc>
<ShowTitleHeader>Index</ShowTitleHeader>
<Count>11</Count>

<Parameter Name=”ArrayINT” Type=”Integer”>

<Desc>Array Integer:</Desc>
</Parameter>

<Variable Name=”ArrayPAR”>
<Desc>Array Parameter:</Desc>
</Variable>

</Group>

</Spec>
</SpecList>

8-18 UAUOP AutoGUI February 2009

 Result
The first tab displays the two arrays in separate grids, as shown in
Figure 8-3.
Figure 8-3: First AutoGUI Tab of Example 2

Fields bordered in red indicate required but missing data that the
user must supply.

PRO/II User-Added Subroutine User Guide 8-19

 The second tab uses the <Group> element to combine the two vec-
tors into a “strong” group. As illustrated in Figure 8-4, this causes
the arrays to be displayed as two columns a single grid.
Figure 8-4: Second AutoGUI Tab of Example 2

The <ShowTitleHeader>Index</ShowTitleHeader> element speci-

fies the text “Index” displayed in the upper left corner cell of the
grid. The <Count>11</Count> element defines the approximate
number of rows to display.

8-20 UAUOP AutoGUI February 2009

 Example 3: Display Check box, Radio Button, List Box Controls
This demonstrates the basic setup required to display integer values
using check box, radio button, and drop-down list box controls.

.ini file
[Data Definition]
MAXINT = 3
TOTINT = 3
MAXPAR = 0
TOTPAR = 0
MAXDBL = 0
TOTDBL = 0
MAXTEX = 0
TOTTEX = 0
INT 1 “CheckINT” 1 None -2111111111 -2111111111 -2111111111
INT 2 “RadioINT” 1 None -2111111111 -2111111111 -2111111111
INT 3 “LBoxINT” 1 None -2111111111 -2111111111 -2111111111

.xml file
<SpecList Name=”AutoGUI Ex03">
<Spec Name=”Integers” Type=”Normal”>
<Parameter Name=”CheckINT” Type=”Choice”>
<Desc>Checkbox:</Desc>
</Parameter>
<Parameter Name="RadioINT" Type="Option">
<Desc>Radio Buttons:</Desc>
<Value Name="0" Type="Integer">
<Desc>Option 0</Desc>
</Value>
<Value Name="1" Type="Integer">
<Desc>Option 1</Desc>
</Value>
</Parameter>

<Parameter Name="LBoxINT" Type="Selection">

<Desc>Listbox:</Desc>
<Value Name="1" Type="Integer">
<Desc>Option 1</Desc>
</Value>
<Value Name="2" Type="Integer">
<Desc>Option 2</Desc>
</Value>
<Value Name="3" Type="Integer">
<Desc>Option 3</Desc>
</Value>
</Parameter>
</Spec>
</SpecList>

PRO/II User-Added Subroutine User Guide 8-21

 The <Value> element is used for the radio button and the drop-down
list box to associate a database value with a readable string.

Result
Figure 8-5: AutoGUI Tab of Example 3

Example 4: Implementing automated interactions

This demonstrates the setup required to implement interactions for
check box, radio button, and drop-down list box controls.

.ini file
[Data Definition]
MAXINT = 4
TOTINT = 4
MAXPAR = 4
TOTPAR = 8
MAXDBL = 0
TOTDBL = 0
MAXTEX = 0
TOTTEX = 0

INT 1 "CheckINT" 1 None -2111111111 -2111111111 -2111111111

INT 2 "RadioINT" 1 None -2111111111 -2111111111 -2111111111
INT 3 "LBoxINT" 1 None -2111111111 -2111111111 -2111111111
INT 4 "CheckINT2" 1 None -2111111111 -2111111111 -2111111111
PAR 1 "CheckPAR" 1 TEMP -1.5E35 -1.5E35 -1.5E35
PAR 2 "RadioPAR" 1 PRES -1.5E35 -1.5E35 -1.5E35
PAR 3 "LBoxPAR1" 1 PRES -1.5E35 -1.5E35 -1.5E35
PAR 4 "LBoxPAR2" 5 WTRA -1.5E35 -1.5E35 -1.5E35

.xml file
<SpecList Name="AutoGUI Ex04">

8-22 UAUOP AutoGUI February 2009

 <Spec Name="Interactions 1" Type="Normal">
<Parameter Name="CheckINT" Type="Choice">
<Desc>Checkbox:</Desc>
<Value Name="1" Type="Integer">
<DependentGroup>CheckINTGroup</DependentGroup>
</Value>
</Parameter>
<Group Name="CheckINTGroup" Type="Weak">
<Variable Name="CheckPAR">
<CreateSideBySide>true</CreateSideBySide>
<NoLabel>true</NoLabel>
</Variable>
</Group>
</Spec>

<Spec Name="Interactions 2" Type="Normal">

<Parameter Name="RadioINT" Type="Option">
<Desc>Radio Buttons:</Desc>
<Value Name="0" Type="Integer">
<Desc>Option 0</Desc>
</Value>
<Value Name="1" Type="Integer">
<Desc>Option 1 with value</Desc>
<DependentGroup>RadioINTGroup
</DependentGroup>
</Value>
</Parameter>
<Group Name="RadioINTGroup" Type="Weak">
<Variable Name="RadioPAR">
<CreateSideBySide>true
</CreateSideBySide>
<NoLabel>true</NoLabel>
</Variable>
</Group>
</Spec>

<Spec Name="Interactions 3" Type="Normal">

<Parameter Name="LBoxINT" Type="Selection">
<Desc>Listbox:</Desc>
<Value Name="1" Type="Integer">
<Desc>Option 1</Desc>
</Value>
<Value Name="2" Type="Integer">
<Desc>Option 2</Desc>
<DependentGroup>LBoxGroup2
</DependentGroup>
</Value>
<Value Name="3" Type="Integer">
<Desc>Option 3</Desc>
<DependentGroup>LBoxGroup3
</DependentGroup>
</Value>
<Value Name="4" Type="Integer">

PRO/II User-Added Subroutine User Guide 8-23

 <Desc>Option 4</Desc>
<DependentGroup>LBoxGroup4
</DependentGroup>
</Value>
</Parameter>

<Group Name="LBoxGroup2" Type="Weak">

<Parameter Name="CheckINT2" Type="Choice">
<Desc>Dependent Checkbox</Desc>
</Parameter>
</Group>
<Group Name="LBoxGroup3" Type="Weak">
<Variable Name="LBoxPAR1">
<Desc>Dependent Scalar PAR</Desc>
</Variable>
</Group>

<Group Name="LBoxGroup4" Type="Weak">

<Variable Name="LBoxPAR2">
<Desc>Dependent Vector PAR</Desc>
</Variable>
</Group>
</Spec>
</SpecList>

The <Group> element encloses one or more controls that will be

dependent on the value of the controlling check box, radio button, or
drop-down list box. The <Value> element in the controlling widget
has a child element <DependentGroup> which identifies the spe-
cific <Group> to be affected. For example, when the user selects
Option 4 in the drop-down list box, the dependent group
“LBoxGroup4” will be shown; the dependent groups for the other
options in the list box will be hidden.
Also notice that the elements <CreateSideBySide> and <NoLabel>
are used for the <Variable> elements in the “CheckINTGroup” and
“RadioINTGroup” groups so that these edit fields are displayed
adjacent to the controlling widget.

Result
The first tab demonstrates interaction with a check box. If the check
box is checked, then the dependent edit field is enabled.

8-24 UAUOP AutoGUI February 2009

 Figure 8-6: First AutoGUI Tab of Example 4

The second tab demonstrates interaction with radio buttons. The

selected radio button will enable the dependent edit field.
Figure 8-7: Second AutoGUI Tab of Example 4

The third tab demonstrates interactions with a drop-down list box.

The selected entry in the list box shows the dependent controls. The
controls associated with the other options in the list box are hidden.
Figure 8-8: Third AutoGui Tab of Example 4.

PRO/II User-Added Subroutine User Guide 8-25

 Example 5: Assigning Thermodynamic METHOD Sets to Sides
This demonstrates the setup required to allow the user to select a
Thermodynamic Set for one or more “sides” in the unit operation.
The example defines a unit containing two sides.

.ini file
[Sides]
MAXSides = 2
SIDE 1 Side_1 1 1 1 1
SIDE 2 Side_2 1 1 1 1

[Data Definition]
MAXINT = 1
TOTINT = 1
MAXPAR = 0
TOTPAR = 0
MAXDBL = 0
TOTDBL = 0
MAXTEX = 0
TOTTEX = 0

INT 1 "ScalarINT" 1 None -2111111111 -2111111111 -2111111111

.xml file
<SpecList Name="AutoGUI Ex04">
<Spec Name="Thermodynamics" Type="Normal">
<Parameter Name="MethodData[0]" Type="Selection">
<Desc>Thermodynamic Set Side 1</Desc>
<ValueDomain>THERMOSETS</ValueDomain>
</Parameter>

<Parameter Name="MethodData[1]" Type="Selection">

<Desc>Thermodynamic Set Side 2</Desc>
<ValueDomain>THERMOSETS</ValueDomain>
</Parameter>
</Spec>
</SpecList>

The <ValueDomain> element is used to load the drop-down list box

with the list of all available thermodynamic METHOD sets. The text
value of the element must be THERMOSETS. The name of the
<Parameter> element must be "MethodData[0]" for side 1,
“MethodData[1]” for side 2, and similar if additional sides must
be defined. (MethodData is the internal name of the array that con-
tains the thermodynamic set names assigned for each side in the unit
operation.)

8-26 UAUOP AutoGUI February 2009

 Result
Figure 8-9: AutoGUI Tab of Example 5

PRO/II User-Added Subroutine User Guide 8-27

8-28 UAUOP AutoGUI February 2009
 Chapter 9
UAUOP Icons
Each modular user-added unit operation allows developers to create
a custom image for display on the PRO/II icon palette and flow-
sheet. The image specification contains information on the appear-
ance and the stream connections.

Icon Data File Structure

The structure of an Icon data file is shown in Table 9-1.
Table 9-1: Basic Structure of an Icon Data File
GROUP 420001 "MyUAUOPName" "UaUOP" 1 "MYUAUOP"
ICON "MyUAUOPName" 60 0 20.0 "UOP%d" 1 0
FORM P2GenericUnit.dll myUaUop.xml
shape ...
DATA ...
PORT ...
DATA ...
PLIN ...
DATA ...
ID -1 -1 -1 -1 -1 -1
DATA ...
The icon file contains the following statements:
The first statement is the GROUP statement which defines the
display name of the UAUOP and associates it with the data def-
inition (*.INI) file.
The second statement is the ICON statement which defines the
display name and the auto-naming convention when creating
new icons on the flowsheet.
The third statement is the FORM statement which specifies the
XML file which defines the tabbed dialog box to display.
Following the FORM statement are one or more shape state-
ments (such as LINE or CIRCLE) that define the visual appear-
ance of the icon. The DATA statement provides additional
information for the shape.
There may be zero or more PORT statements which define
“point” connections for streams. The DATA statement provides
additional information for the PORT.

PRO/II User-Added Subroutine User Guide 9-1

 There may be zero or more PLIN statements which define
“line” connections for streams. The DATA statement provides
additional information for the port line.
The shape, PORT, PLIN, and ID statements may appear in any
order.
There must be one ID statement (usually at the end) that speci-
fies the location of the unit identifier. The DATA statement pro-
vides additional information for the identifier.

Associating an Icon Data File with a UAUOP Unit Operation

The files listed in Table 9-2 are required for a UAUOP unit opera-
tion to fully implement icons and tabbed dialog boxes in PRO/II.
Table 9-2: AutoGUI Files Associated with a UAUOP
File name Location Description
myUaUop.dll %P2Install%\Bin DLL containing runtime code for
UAUOP unit operation
myUaUop
myUaUop.ini %P2Install%\System Data Definition file
myUaUopIcon.dat %P2Install%\System Definition file for the icon to
display on the PFD icon palette
and in the PFD flowsheet.
myUaUop.xml %P2Install%\System AutoGUI XML definition file.

Note: (%P2Install% refers to the installation directory, such as

C:\simsci\proii82. See “Registering a Path to A User-Added DLL”
on page 11-7 for information about specifying the PRO/II installa-
tion path.
The association of the UAUOP icon with the data definition file
(*.ini) and the AutoGUI XML file (*.xml) is accomplished in the
icon data file (myUaUopIcon.dat):
GROUP 420001 “MyUAUOPName” "UaUOP" 1 "MYUAUOP"
ICON "MyUAUOPName" 60 0 20.0 "UOP%d" 1 0
FORM P2GenericUnit.dll myUaUop.xml
Specifically,
The last value on the GROUP line must be a text string that matches
one of the entries in the PRO/II UAS registry file P2UasReg.ini.
The FORM line must specify P2GenericUnit.dll as the first
argument and the name of the XML file as the second argument.

9-2 UAUOP Icons February 2009

Icon File Reference
The complete structure of an icon data file is shown in Table 9-3:
Table 9-3: Complete Structure of an Icon Data File
// Comment line
GROUP (exactly 1)
ICON (1 or more for the GROUP)
FORM (1 for each ICON)
shape (0 or more)
DATA (additional data for shape)
BEGOUTLINE (zero or more BEGO/ENDO sections)
shape or PLIN
DATA (additional data for shape or PLIN)
ENDOUTLINE
PORT (0 or more)
DATA (additional data for PORT)
PLIN (0 or more)
DATA (additional data for PLIN)
ID (exactly 1)
DATA (additional data for ID)
END (optional)

Notes:
Each ICON section is terminated by the next ICON statement or
an end-of-file.
The shape keyword can be any of a number of geometrical
shapes, such as LINE, CIRCLE, and POLY, as listed in Table 9-7,
”Shape Table”, on page 9-7.
The BEGOUTLINE and ENDOUTLINE statements are used to
define a general enclosed shape that is typically filled with the
user-defined preferred fill color and gradient.
The order of the FORM, shape, BEGOUTLINE/ENDOUTLINE,
PORT, and PLIN statements is not significant as long as each
shape, PORT, and PLIN is followed by its appropriate DATA
statement(s). The shape, PORT, and PLIN statements can
appear in any order. Within a BEGOUTLINE/ENDOUTLINE
sequence, however, the statements should be entered such that
they define an enclosed figure with the items drawn in the order
presented.
DATA statements contain one or more numeric values. Multiple
DATA statements act as continuations for the first DATA state-
ment. For example the statement DATA 1 2 3 on one line fol-
lowed by DATA 4 5 6 on the next line is equivalent to DATA 1
2 3 4 5 6 all on one line.
A line beginning with // is a comment line.

PRO/II User-Added Subroutine User Guide 9-3

 Statements

GROUP Statement
The GROUP statement defines the description of the icon and iden-
tifies which UAUOP in the p2uasreg.ini file is associated with this
icon. The format of this statement is:
GROUP 420001 <desc> "UAUOP" <show> <uauop>
Where:
420001 This code number is required to identify the icon as
being a UAUOP icon.
<desc> Text description for the icon. This text will be displayed
beneath the icon on the icon palette if the “large buttons”
option is used.
"UaUOP" This text string is required to identify the icon as being a
UAUOP icon.

<show> This value will typically be 1, which means that the icon
is displayed in the icon palette. 0 means the icon is not
shown in the icon palette.
<uauop> Text string identifying the type of UAUOP unit. This
text string must match the text string used in the
p2uasreg.ini file.

ICON Statement
Each ICON section starts with an ICON statement and ends with
another ICON statement, an END statement, or an end-of-file.
The format of the ICON statement (with all values on one line) is:
ICON <text> 60 <rflag> <sfac> <dform>
<dstart> <input>
Where:
<text> Descriptive text associated with this icon. If multiple
icons are supplied for a UAUOP unit, each icon can have
its own descriptive text.
60 This is the routing logic code and must be 60 for
UAUOP unit operations.

<rflag> Allowed flip/rotation settings during lay down,

0 = allow flip and rotate,
1 = allow flip only,
2 = do not allow flip or rotate.

9-4 UAUOP Icons February 2009

 The <rflag> value is used during keyword input file
import only. PROVISION tries to reorient the icon to best
fit the inputs and outputs. Regardless of this value, the
user can manually reorient the icon. “Flip” reflects the
icon in both the x and the y axes. “Rotate” performs
rotations in increments of 90 degrees.
<sfac> Scale factor, a floating point number. A larger factor
means a proportionately larger icon relative to the other
icons.
<dform> Auto-label format descriptor. This is a quoted text string
with the conventions of a "C" language format string. It
controls the displayed label under each instance of the
ICON. Each instance of the icon is numbered consecu-
tively, starting at the <dstart> value defined below. An
example is “UOP%03d”, which results in default unit
identifiers of UOP001, UOP002, and so on.
<dstart> Auto-label starting number. This is the number of the
first instance of the icon on the flowsheet. All ICONs in
the same group should have the same <dstart> value.
<input> Specify a value of 1 if input data is required. This sets
the initial color of the label to red.

FORM Statement
This statement defines the XML file to be used for data entry. The
format is:
FORM <dll_name> <xml_name>

where:
<dll_name> The name of the DLL used to process the XML file.
For UAUOP units, this should be P2GenericUnit.dll
<xml_name> The name of the XML file used to define the tabbed
dialog box for the UAUOP unit operation.

PRO/II User-Added Subroutine User Guide 9-5

 Shape Statements
Shape is a generic term for any of several statements, each of which
describes a graphic primitive such as a line, circle, or rectangle.
Several shape statements may be used to create a complex icon. The
format of a shape statement (all data on one line) is:

shape <ID> <line_color> <fill> <fill_color>

<width> <style>
where:
<ID> The numeric identifier for this shape. Usually set to -1.
<line_color> The line color. Default is -1. See Table 9-4, ”Color
Codes”.
Table 9-4: Color Codes
Value Color Value Color Value Color
-1 Default 6 Brown 13 Magenta
0 Black 7 Light Gray 14 Yellow
1 Blue 8 Dark Gray 15 White
2 Green 9 Light Blue 16 Light Yellow
3 Cyan 10 Light Green 17 Dark White
4 Red 11 Cyan
5 Magenta 12 Light Red

<fill> Fill flag, -1 for default. See Table 9-5, ”Fill Style
Codes”.
Table 9-5: Fill Style Codes
Value Fill Style
-1 Default
0 Hollow
1 Solid

<fill_color> Fill color, -1 for default. See Table 9-4, ”Color

Codes”, on page 9-6
<width> Line width, -1 for default.
<style>Line style, -1 for default. See Table 9-6, ”Line Style
Codes”.

9-6 UAUOP Icons February 2009

 Table 9-6: Line Style Codes
Value Line Style
-1 Default
0 Solid
1 Dash
2 DashDot
3 DashDotDot
4 Dot

An ICON is constructed using at least one shape statement (in addi-

tion to the ID statement). It must completely outline at least one
closed area when it appears on the PROVISION PFD. The icon
may be built either by a single shape statement that defines a closed
area (POLY, RECT, CIRCLE or ELLIPSE); or by using a BEGOUT-
LINE/ENDOUTLINE sequence that defines a closed area. The
enclosed area typically is filled with the default color gradient.
Each shape statement is followed by a one or more of DATA state-
ments which supply additional data. The DATA statements are con-
catenated, so several DATA statements are equivalent to a single
DATA statement with all the parameters. The interpretation of the
values on the DATA statements is given in Table 9-7.
Table 9-7: Shape Table
DATA
Shape Definition Parameters Notes
LINE Line x1, y1, x2, y2, ... A line may be multi-
segmented; if more than two
pairs of values are supplied,
consecutive segments will be
drawn.
LINE2 Arrow line x1, y1, x2, y2,... The line has an arrow at its
end. See LINE
LINE3 Segmented x1, y1, x2, y2,... The line has an arrow at the
arrow line. end of each segment. See
LINE
RLI Repeating x1, y1, x2, y2, The first four values give the
line dx, dy, number first line. dx and dy give the
offset to the following line
(both ends get the same
offset). The “number” is the
number of lines drawn.
POLY Polygon x1, y1, x2, y2,... Multi-sided shape that
automatically closes

PRO/II User-Added Subroutine User Guide 9-7

 RECT Rectangle xmin, ymin, Automatically closed shape
xmax, ymax
ELLIPSE Ellipse xc, yc, xr, yr Automatically closed shape
CIRCLE Circle xc, yc, radius Automatically closed shape
ARC Arc xc, yc, xr, yr, Elliptic arc, angles are
angle1, angle2 measured from the positive
x-axis counterclockwise, in
degrees.
ID Icon ID xc, yc Identifier for the icon
The coordinate system for the x and y values are: x increases to the right;
y increases down.
The origin can be chosen anywhere, but the standard practice is to pick an
origin in the upper left hand corner of the intended ICON, thus making all
coordinate values greater than or equal to 0.
Before any scaling, each unit of the coordinate system corresponds to
roughly two screen pixels. In this representation, the coordinates need to
be input as integers.

PORT statement
The PORT statement defines a stream connection point on the icon.
The format is:
PORT <id> <color> <type> <unused>
<width> <style> <name> <tooltip>
Where:
<id> The port identifier. If there are several ICONs in a
GROUP, they must have the same number of ports, and
the ports must have the same sequence of ID numbers.
Within each ICON, the port ID must be unique.
<color> Color. This value is not used, specify -1.
<type> Port type. Specify a value of 0, which signifies a PRO/II
process stream.
<unused> Not used. Specify -1.

<width> Not used. Specify -1.

<style> Not used. Specify -1.
<name> Name of port. Not used; enter any text as a placeholder.
<tooltip> Tooltip for port.

Additional data is specified on the DATA statement which follows

the PORT statement.
9-8 UAUOP Icons February 2009
 PLIN
The PORT statement defines a line segment; a feed/product stream
can be connected anywhere along the line.
PLIN <id> <color> <type> <unused>
<width> <style>
This statement is treated the same as PORT; however because it
defines a line connection instead of a point connection, the associ-
ated DATA statement has two additional values to specify the end-
point of the line. Also, since PLIN is also a line, it can be used in the
same way as a LINE statement to define enclosed areas.

DATA statements for PORT and PLIN

DATA <max_feed> <max_prod> <direct> <rnum>
<style> <portgroup> <port> <nRel>
<requiredgroup> <req_feeds> <req_prods> <side>
<phase> <x1> <y1> <x2> <y2>
The <x2> and <y2> values are only defined if the keyword is PLIN,
not PORT.
<max_feed> The maximum number of feed (input) streams.
-1 means no limit,
0 means no feeds.
<max_prod> The maximum number of product (output) streams.
-1 means no limit,
0 means no products.
Normally, either <max_feed> or <max_product> should be
zero, unless the port belongs to a feed/product portgroup. See
below.
<direct> Connection direction, not used (see “rnum” below),
specify a value of -1.
<rnum> Connection direction: (Used only for PORT, not PLIN.)
0 - right
1 - up
2 - left
3 - down
<style> Port style, not used, specify 0.
<portgroup> “portgroup” number, if this port belongs to a port
group. A port group has exactly two members, each of
which is a port or a port line. Specify a value of 0 for no
portgroup membership. Specify a value greater than 0 to
denote a portgroup. One member of a portgroup is for a
feed (input), and the other is for a product (output), but
PRO/II User-Added Subroutine User Guide 9-9
 the assignment of which is left open. Note that a “port-
group” is different from the “requiredgroup” below.
<port> Not used, set to 0.
<nRel> Not used, set to 0.
<requiredgroup> Indicates that at least one of the ports in a
requiredgroup must be connected. A value of 0 means no
group membership. A value greater than 0 means that
the port belongs to the requiredgroup of that number.
Note that this is distinct from the portgroup and from the
“Group” of icons. A requiredgroup can have any number
of members larger than 1. Not commonly used.
<req_feeds> The minimum number of feeds (input streams). If the
port is a member of a portgroup, either this number has
to be satisfied or the <req_prods> must be satisfied.
<req_prods> The minimum number of products (output streams).
If the port is a member of a portgroup, either this
number has to be satisfied or the <req_feeds> must
be satisfied.
<side> This number identifies the UAUOP "side number" asso-
ciated with this port. The first side is side 1, the second
side is side 2, and so on. Typically, this value will be the
same as the <portgroup> value; in that case if the
port is connected, then the other port in the group must
also be connected. One will be a feed and the other a
product.
<phase> Not used for UAUOP.

<x1> Location of port or port line starting point, x-coordinate.

<y1> Location of the port or the port line starting point,
y-coordinate.
<x2> PLIN statements only, defines the end x-coordinate of
the line port.
<y2> PLIN statements only, defines the end y-coordinate of
the line port.

BEGOUTLINE Statement
The BEGOUTLINE statement defines the start of an arbitrary
enclosed region.

BEGOUTLINE

9-10 UAUOP Icons February 2009

 The statement has no arguments.

ENDOUTLINE Statement
The ENDOUTLINE statement defines the end of an enclosed region
which was initialized by the BEGOUTLINE statement.
The syntax is:

ENDOUTLINE <ID> <line_color> <fill>

<fill_color> <width> <style>

The arguments are similar to the shape statement.

Icon file Examples

The following sections contain various icon examples.

Example 1: Box icon, two point ports, feed on the left

Demonstrates a basic "box" shape for a single-sided unit operation.
The left port is defined to be the feed and the right port is defined to
be the product.
.ini file extract
[Sides]
MAXSides = 1
SIDE 1 Side_1 1 1 1 1

.dat file
1 // Single side, point ports
2 GROUP 420001 "IconEx1" "UaUOP" 1 "ICONEXAMPLE01"
3 ICON "IconEx1" 60 0 20.0 "UOP%d" 1 0
4 FORM P2GenericUnit.dll ICONEXAMPLE01.xml
5 POLY -1 -1 -1 -1 -1 -1
6 DATA 0 0 10 0 10 2 0 2
7 PORT 101 -1 0 -1 -1 -1 "FEEDID" "Feed Port"
8 DATA 1 0 0 2 0 0 0 0 0 1 0 1 0
9 DATA 0 1
10 PORT 102 -1 0 -1 -1 -1 "PRODID" "Product Port"
11 DATA 0 1 0 0 0 0 0 0 0 0 1 1 0
12 DATA 10 1
13 ID -1 -1 -1 -1 -1 -1
14 DATA 11 3

In this example, the rectangle is drawn using the POLY statement on

line 5. In the coordinate system, the "x" value increases to the right
and the "y" value increases down.

The DATA statement at line 6 defines the starting point to be (0,0).

The top line is drawn to (10,0), the right side is drawn to (10,2), and
PRO/II User-Added Subroutine User Guide 9-11
 the bottom line is drawn to (0,2). The polygon is closed by automat-
ically drawing the final (left side) line back to (0,0).
Result
The screen shot in Figure 9-1 shows the icon after it has been added
to the flowsheet and as a new feed stream is being attached to the
icon. Notice that the left port is highlighted in red, indicating that it
requires a feed stream connection.
Figure 9-1: Example 1 - Dedicated Feed and Product Ports

On the DATA statement at line 8, the first integer sets the maximum
allowed number of feeds to 1, while the second integer sets the
maximum number of products to zero. Compare this to the data
statement at line 11, where the first integer sets the maximum feeds
to zero, while the second integer sets the maximum allowed prod-
ucts to 1.

The 8th entry on a DATA statement for a port declares the

<portgroup>. Note that the data statements for both ports (lines 8
and 11) set the value to zero.

Feed ports are displayed whenever the user places the cursor on the
terminal end of a stream, as shown in Figure 9-1. Product ports are
displayed when the originating end of a stream is selected. The next
example shows modified port behavior.

Example 2: Two ports, either port accepts feeds

This modifies the simple box icon created in example 1. In this
example, a feed can be attached to either the left port or the right
port. However, once a feed is connected to one port, the other port
only accepts products.
.ini file
[Sides]
MAXSides = 1
SIDE 1 Side_1 1 1 1 1
9-12 UAUOP Icons February 2009
 .dat file
1 // Single side, point ports, feed/prod each side
2 GROUP 420001 "IconEx2" "UaUOP" 1 "ICONEXAMPLE02"
3 ICON "IconEx2" 60 0 20.0 "UOP%d" 1 0
4 FORM P2GenericUnit.dll ICONEXAMPLE02.xml
5 POLY -1 -1 -1 -1 -1 -1
6 DATA 0 0 10 0 10 2 0 2
7 PORT 101 -1 0 -1 -1 -1 "PORT1" "Feed or Product"
8 DATA 1 1 0 2 0 1 0 0 0 1 1 1 0
9 DATA 0 1
10 PORT 102 -1 0 -1 -1 -1 "PORT2" "Feed or Product"
11 DATA 1 1 0 0 0 1 0 0 0 1 1 1 0
12 DATA 10 1
13 ID -1 -1 -1 -1 -1 -1
14 DATA 11 3
Compare this listing to example 1 to see the changes made to sup-
port "dynamic" port assignment:
1. The values of <max_feed>, <max_prod>, <req_feeds>, and
<req_prods> are identical on the DATA statements (lines 8 and
11) for ports 101 and 102. This configures both ports to accept
either feeds or products.
2. The <portgroup> attribute is set to 1 for both ports.
Result
Figure 9-2 shows the icon after it was added to the flowsheet and as
a new feed stream is being attached to the icon. Note that both ports
are available for attaching the feed.
Figure 9-2: Example 2 - Dynamic Feed and Product Ports

PRO/II User-Added Subroutine User Guide 9-13

 Example 3: Two ports, multiple feeds, one product
This example demonstrates multiple feeds to a single port. The
basic icon still is the simple box of example 1.
.ini file
[Sides]
MAXSides = 1
SIDE 1 Side_1 5 1 1 1
Notice that the maximum number of feeds (the 3rd argument) has
been increased to five.
.dat file
1 // Single side, point ports, multiple feeds
2 GROUP 420001 "IconEx3" "UaUOP" 1 "ICONEXAMPLE03"
3 ICON "IconEx3" 60 0 20.0 "UOP%d" 1 0
4 FORM P2GenericUnit.dll ICONEXAMPLE03.xml
5 POLY -1 -1 -1 -1 -1 -1
6 DATA 0 0 10 0 10 2 0 2
7 PORT 101 -1 0 -1 -1 -1 "PORT1" "Feed or Product"
8 DATA 5 1 0 2 0 1 0 0 0 1 1 1 0
9 DATA 0 1
10 PORT 102 -1 0 -1 -1 -1 "PORT2" "Feed or Product"
11 DATA 5 1 0 0 0 1 0 0 0 1 1 1 0
12 DATA 10 1
13 ID -1 -1 -1 -1 -1 -1
14 DATA 11 3
On lines 8 and 11, <max_feed> (the first entry on the DATA state-
ments for PORT 101 and PORT 102) has been changed to five. Cur-
rently, this value is not read from the SIDE statements of the .ini
file, and must be specified here.
Result
In Figure 9-3, one feed stream already has been connected to the
icon. A second feed stream is being added. The port is displayed
in green instead of red because the <req_feeds> value has been
satisfied.
Figure 9-3: Example 3 - Multiple Feeds to a Single Port

9-14 UAUOP Icons February 2009

 Note that, since the first feed stream was attached to the left port, all
subsequent feed streams must be attached to the same port. This is
the reason that the right port is not highlighted. Compare this figure
to Figure 9-2, which illustrates connecting the first feed.

Example 4: Box icon, two PLIN ports

Once again, the basic icon is a simple "box" shape for a single-sided
unit operation. However, this example uses PLIN statements to
define “line ports” instead of PORT statements that specify “point
ports”. To use PLIN statements, the icon outline must be created
using a BEGOUTLINE/ENDOUTLINE construct (instead of the sim-
pler POLY statement in previous examples). Compare this to Exam-
ple 1 on page 9-11.
.ini file
[Sides]
MAXSides = 1
SIDE 1 Side_1 1 1 1 1

.dat file
1 // Single side, line ports
2 GROUP 420001 "IconEx4" "UaUOP" 1 "ICONEXAMPLE04"
3 ICON "IconEx4" 60 0 20.0 "UOP%d" 1 0
4 FORM P2GenericUnit.dll ICONEXAMPLE04.xml
5 BEGOUTLINE
6 LINE -1 -1 -1 -1 -1 -1
7 DATA 10 0 0 0
8 PLIN 101 -1 0 -1 -1 -1 "FEEDID" "Feed Port"
9 DATA 1 0 0 2 0 1 0 0 0 1 0 1 0
10 DATA 0 0 0 2
11 LINE -1 -1 -1 -1 -1 -1
12 DATA 0 2 10 2
13 PLIN 102 -1 0 -1 -1 -1 "PRODID" "Product Port"
14 DATA 0 1 0 0 0 1 0 0 0 0 1 1 0
15 DATA 10 2 10 0
16 ENDOUTLINE -1 -1 -1 -1 -1 -1
17 ID -1 -1 -1 -1 -1 -1
18 DATA 11 3
The first entry on the DATA statement at line 9 of the listing defines
the left line port to accept a single feed. Similarly, the second entry
on the DATA statement at line 14 configures the right line port to
accept a single product.
Result
The screen shot in Figure 9-4 shows the icon after it has been added
to the flowsheet and as a new feed stream is being attached to the
icon. Notice that the left line port is highlighted in red, indicating
that it requires a feed stream connection.

PRO/II User-Added Subroutine User Guide 9-15

 Figure 9-4: Example 4 - Line Ports

Example 5: More complex icon, two line ports

This demonstrates the statements required to create a more complex
shape. This example also uses line ports.
.ini file
[Sides]
MAXSides = 1
SIDE 1 Side_1 1 1 1 1

.dat file
1 // Single side
2 GROUP 420001 "IconEx5" "UaUOP" 1 "ICONEXAMPLE05"
3 ICON "IconEx5" 60 0 20.0 "UOP%d" 1 0
4 FORM P2GenericUnit.dll ICONEXAMPLE05.xml
5 BEGOUTLINE
6 ARC -1 -1 -1 -1 -1 -1
7 DATA 5 2 5 2 0 180
8 PLIN 101 -1 0 -1 -1 -1 "FEEDID" "Feed"
9 DATA 1 0 0 2 0 1 0 0 0 1 0 1 0
10 DATA 0 2 0 10
11 ARC -1 -1 -1 -1 -1 -1
12 DATA 5 10 5 2 180 0
13 PLIN 102 -1 0 -1 -1 -1 "PRODID" "Product"
14 DATA 0 1 0 0 0 1 0 0 0 0 1 1 0
15 DATA 10 10 10 2
16 ENDOUTLINE -1 -1 -1 -1 -1 -1
17 LINE -1 -1 -1 -1 -1 -1
18 DATA 0 2 10 2
19 LINE -1 -1 -1 -1 -1 -1
20 DATA 0 10 10 10
21 ID -1 -1 -1 -1 -1 -1
22 DATA 5 14

The BEGOUTLINE/ENDOUTLINE construct (from line 5 to 16)

defines the enclosed area. The drawing starts at the upper right,

9-16 UAUOP Icons February 2009

 using an ARC statement (line 6) to draw a half-ellipse counterclock-
wise. The PLIN statement (line 8) defines line port 101 down the
left side. Next, an ARC statement (line 11) draws a half-ellipse at the
bottom. Finally, the PLIN statement (line 13) draws line port 102 up
the right side to close the outline.
Two additional LINE statements (lines 17 through 20) draw on top
of the enclosed area to give the appearance of a box in the middle,
with half-ovals on the top and bottom.
Result
Figure 9-5 illustrates the feed port on the left highlighted in red
before connecting the feed.
Figure 9-5: Example 5 - Connecting a Feed to a Complex Icon

Example 6: Two-sided unit operation

This demonstrates the specification required for a two-sided unit
operation.
.ini file
MAXSides = 2
SIDE 1 Side_1 1 1 1 1
SIDE 2 Side_2 1 1 1 1

.dat file
1 // Two sides, point ports
2 GROUP 420001 "IconEx6" "UaUOP" 1 "ICONEXAMPLE06"
PRO/II User-Added Subroutine User Guide 9-17
 3 ICON "IconEx6" 60 0 20.0 "UOP%d" 1 0
4 FORM P2GenericUnit.dll ICONEXAMPLE06.xml
5 POLY -1 -1 -1 -1 -1 -1
6 DATA 0 0 10 0 10 4 0 4
7 PORT 101 -1 0 -1 -1 -1 "FEEDID1" "Feed Side 1"
8 DATA 1 0 0 2 0 1 0 0 0 1 0 1 0
9 DATA 0 1
10 PORT 102 -1 0 -1 -1 -1 "PRODID1" "Prod Side 1"
11 DATA 0 1 0 0 0 1 0 0 0 0 1 1 0
12 DATA 10 1
13 PORT 201 -1 0 -1 -1 -1 "FEEDID2" "Feed Side 2"
14 DATA 1 0 0 2 0 2 0 0 0 1 0 2 0
15 DATA 0 3
16 PORT 202 -1 0 -1 -1 -1 "PRODID2" "Prod Side 2"
17 DATA 0 1 0 0 0 2 0 0 0 0 1 2 0
18 DATA 10 3
19 ID -1 -1 -1 -1 -1 -1
20 DATA 11 5

The <side> value is set to 1 or 2 depending on the side to which the

feed/product will be associated.
Result
Figure 9-6: Example 6 - Two-sided Icon

abc

9-18 UAUOP Icons February 2009

 Chapter 10
UAUOP INI File
Overview
Each modular user-added unit operation has its own unique initial-
ization file (referred to here simply as an INI file). The INI file
includes information needed by PRO/II to support and interact with
the UAUOP. This includes access information, sides configuration,
dimensional units of measure, and the data and storage needs of the
unit operation model. Table 10-1 lists the sections in an INI file
Table 10-1: Sections of an INI File for a UAUOP
Section Description
[Access Data] Required. Contains information that allows PRO/
II to find and call the UAUOP.
[Sides] Required. Configures the sides of the UAUOP.
[UOM] Optional. Defines units of measure for data
exchange between PRO/II and a UAUOP.
[Data Definition] Required. Defines data members and storage.

Keyword Summary
Access Data Summary

[Access Data] (Required)

Required Statements
DLLNAME=libraryname
ROUTINENAME=routinename
UATYPE=uoptype
Recommended Statements
PATH=%P2Install%SYSTEM
PROTOCOL=DLL
SYNTAX=FORTRAN { CPP | VB }
Optional Statements
ICON=iconfilename
DESC=description
Unsupported Statements (Do not apply to UAUOP)
Conditional for COM, DCOM, etc.

PRO/II User-Added Subroutine User Guide 10-1

 CLASS=classid
PROGID=identifier

Side Data Summary

[Sides] (Required)
MAXSIDES = nsides
SIDE idno name maxFeed maxProd minFeed minProd

Units of Measure Summary

[UOM] (Optional)
BASE = Internal {| English | Metric | SI }
classkw = uomkw

Data Definition Summary

[Data Definition] (Required)
MAXINT = nmax
TOTINT = ntot
MAXPAR = nmax
TOTPAR = ntot
MAXDBL = nmax
TOTDBL = ntot
MAXTEX = nmax
TOTTEX = ntot
INT idno idname isize intclass idefault ilo ihi
PAR idno idname isize uomclass vdefault vlo vhi
DBL idno idname isize uomclass vdefault vlo vhi
TEXT idno idname isize maxchar iminname

10-2 UAUOP INI File February 2009

Input Description
Access Data Section
Information in this section allows PRO/II to find and call the user-
added unit operation. A UAUOP cannot be used by PRO/II if this
information is missing or invalid.

Note: Each user must ensure the access information accurately

represents the paths and names used to install a UAUOP. This
may be different for each user. See “Registering [UAUOP] User-
Added Unit Operations” on page 11 of Chapter 2 for more
information.

Access Section Heading

[Access Data]
This heading statement is required as the first statement in the sec-
tion. It has no additional entries.

DLLNAME Statement
DLLNAME=libraryname
This statement identifies the dynamic link library file that contains
the executable code. It is required when the PROTOCOL statement
declares PROTOCOL=DLL (currently, the only protocol supported
for a UAUOP). Otherwise, it is ignored. Keyword DLLNAME may
be abbreviated to simply DLL.
libraryname This is the exact name of the DLL, including any suffix
such as “.DLL”. The name does not include any path
information. Embedded blanks are allowed when the
libraryname is enclosed in quotation marks. Trailing
blanks are discarded.
Whether or not the DLL name is case sensitive is determined by the
operating system used to run PRO/II. The libraryname entry should
exactly duplicate the upper and lower case characters used by the
file system to store the DLL. PRO/II tries to access the DLL using
the libraryname as entered. If that fails, the name is converted to all
upper case and re-tried. If the second attempt fails, PRO/II issues an
error message.

ROUTINENAME Statement
ROUTINENAME=routinename

PRO/II User-Added Subroutine User Guide 10-3

 This required statement names the subroutine that PRO/II calls to
run the user-added unit operation. Keyword ROUTINENAME may
be abbreviated to ROUTINE.
routinename The name of the subroutine that PRO/II calls. The
subroutine must reside in the dynamic link library file
identified by the DLLNAME statement. Fortran conven-
tions do not allow embedded blanks in the name.
As with the name of the DLL (above), the subroutine name may or
may not be case sensitive. By convention, Fortran prefers the name
to be all upper case to simplify exporting it from the DLL.

UATYPE Statement
UATYPE=uoptype
This statement is required to declare the unique identifier for the
UAUOP.

uoptype This is the identifier used by PRO/II to find the UAUOP.

It must be identical to the UATYPE entry for this unit
operation in the [UAUOP] section of the P2UasReg.ini
file. See “Registering [UAUOP] User-Added Unit
Operations” on page 11 of Chapter 2.
Declaring the uoptype both in the INI and P2UasReg files is an
intentional redundancy. This helps ensure the correct INI file is
associated with each registered UAUOP.

PATH Statement
PATH=%P2Install%\SYSTEM
The PATH statement declares the installed location of the library
file that contains the executable UAUOP code.
%P2Install%\SYSTEM This represents the default path when the
PATH statement is omitted. It assumes the library has
been installed in the SYSTEM directory of the PRO/II
installation. See “Registering a Path to a User-Added
DLL” on page 9 of Chapter 2 for a more detailed dis-
cussion.
In practice, developers almost never install their executable code in
the SYSTEM directory. Consequently, this statement is almost
always required. Any directory may be specified so long as PRO/II
is able to use the path to access the directory containing the execut-
able library file. For example, one UAUOP sample file shipped with
PRO/II creates an executable library in:
PATH=%P2Install%\User\Uas\UasF90\VF6\Release

10-4 UAUOP INI File February 2009

 where the %P2Install% macro expands to \SIMSCI\Proii82\
The syntax of the path is dependent upon the operating system used
to run PRO/II.

PROTOCOL Statement
PROTOCOL=DLL { | STATIC | UASLB | COM |
GCOCOM | DCOM | CORBA |
GCOCORBA | UNIX }
The PROTOCOL statement defines the access mechanism used by
PRO/II to access the UAUOP. Only the DLL (Dynamic Link Library)
option is supported for user-added unit operations. The other proto-
cols are used by other PRO/II add-ons, and are listed only for clar-
ity. Because PROTOCOL=DLL is the default, the PROTOCOL
statement is not required. However, it is recommended to explicitly
declare the protocol.

SYNTAX Statement
SYNTAX=FORTRAN{ CPP | VB }
This statement declares the syntax used when PRO/II calls the user-
added unit operation.
FORTRAN Use Fortran calling conventions when calling a user-
added unit operation. This is the default and the only
syntax supported for calling a UAUOP.
CPP Not supported. This is intended to use C++ calling con-
ventions to access a user-added subroutine.
VB Not supported. This is intended to use Visual Basic call-
ing conventions to access a UAUOP.
PRO/II always calls the Fortran interface routine of a UAUOP.
Developers may code calculations, reports, and other subroutines in
other languages. To do this, modifications would be needed in the
interface routine to call the other subroutines and functions using
appropriate calling conventions. Additionally, data exchanged with
PRO/II may need to be stored locally by the interface routine, since
storage formats may be different in other languages.

ICON File Statement

ICON=iconfilename
The ICON statement associates an AutoGUI icon file with the
UAUOP. Chapter 9, “UAUOP Icons”, provides extensive informa-
tion for creating an icon file. When the UAUOP does not implement

PRO/II User-Added Subroutine User Guide 10-5

 an optional AutoGUI data entry window, the ICON statement should
be omitted.

DESCRIPTION Statement
DESC=description
This allows the developer to enter a comment in the INI file. It is
allowed by PRO/II, but it is not available from a UAUOP.
description Up to 40 characters of any text. Enclose the descrip-
tion in quotation marks when embedded blank spaces
are present.

Unsupported Statements
CLASS=classid
Not supported for a UAUOP. This statement allows entering the
class identifiers required by other add-ons that interface with
PRO/II through a COM server.
PROGID=identifier
Not supported for a UAUOP. This statement allows entering the
Program ID required by other add-ons that interface with
PRO/II through a COM server.

Side Data Section

The “side” concept allows logical partitioning of the functionality
and data storage in a unit operation model. See “Data Structure of
One Side” on page 38 of Chapter 5. Every UAUOP always includes
at least one SIDE. The [Sides] section of the INI file defines the
number of sides the unit operation maintains. It also configures the
number of feeds and products that each side supports.

Sides Section Heading

[Sides]
This heading statement is required as the first statement in the sec-
tion. It has no additional entries.

MAXSIDES Statement
MAXSIDES =nsides
This statement declares the maximum number of sides in a UAUOP.
When this statement is omitted, the model contains one side.
nsides The number of sides to configure. This integer allows
any value between 1 and 50.

10-6 UAUOP INI File February 2009

 SIDE Statements
SIDE idno name maxFeed maxProd minFeed minProd
Each of these statements configures the feeds and products on a sin-
gle side of the model. One SIDE statement should be present for
each of the nsides declared on the MAXSIDE statement. All entries
are required in the order shown.
idno A unique integer identification number assigned to the
side. ID numbers start at 1 and continue to nsides. This
ID number may be used to access data from the side
array of the UAUOP storage object. It also may be used
as the sideid on a SIDE statement of PRO/II keyword
input.
name A unique name for the side. It also may be used as the
sideid on a SIDE statement of PRO/II keyword input. It
may contain up to 32 characters. Embedded blanks are
allowed, but are discouraged, since they require users to
enclose the identifier in quotation marks.
maxfeed The maximum number of PRO/II streams that the side
allows as feeds. Values range from zero to 10.
maxprod The maximum number of PRO/II streams that the side
allows as products (draws). Values range from zero to
10.
minfeed The minimum number of PRO/II streams that must be
attached to the side as feeds to satisfy minimum input
requirements. The value ranges from zero to maxfeed.
minprod The minimum number of PRO/II streams that must be
attached to the side as products to satisfy minimum out-
put requirements. The value ranges from zero to max-
feed.

Any specific SIDE may have both feeds and products, feeds and no
products, products and no feeds, or neither feeds nor products.
However, at least one side must have at least one feed. If no SIDE
has a feed, the PRO/II calculation sequencer will skip the UAUOP
during flowsheet convergence calculations. Products always are
optional.

Units of Measure Section

Data exchanged between PRO/II and each UAUOP may have asso-
ciated units of measure. This section allows developers to define the
system of dimensional units used for the data exchange. A devel-
oper first chooses a pre-defined system of units using a BASE state-
ment. Subsequent statements may “override” the base units used by

PRO/II User-Added Subroutine User Guide 10-7

 individual classes in the system. The selected base system, together
with all the individual class overrides, collectively are known as a
system of “user dimensions”.

UOM Section Heading

[UOM]
This heading statement is required as the first statement in the sec-
tion. It has no additional entries.

BASE System Statement

BASE = Internal {| English | Metric | SI }
Use this statement to declare the basic system of units used for data
exchange with PRO/II. The available options are:
Internal The system of units used internally in PRO/II. This is the
default when the BASE statement is omitted.
English The system of units commonly used in the United States.
Metric The metric system of units.
SI International System of Units.
See Chapter 7, “User-Added Units of Measure” for information
about the units used in each class of these systems.

UOM Class Override Statements

classkw = uomkw
The units of measure may be changed for each class in the base set
of dimensional units. Use a separate override statement for each
class being modified.
classkw This token represents any one of the class keyword iden-
tifiers listed in Table 7-2, ”Base Sets of Dimensional
Units of Measure,” on page 7-2.
uomkw This token represents a UOM keyword for a dimensional
unit from the class specified by classkw. Refer to Table
7-2 on page 7-2.
Example:
[UOM]
BASE = English
TEMP = K
TIME = MIN
The BASE statement sets the basic system of units to English,
which normally expects temperatures in Fahrenheit and time in

10-8 UAUOP INI File February 2009

 hours. The two override statements change temperature to be in
Kelvins and time to be in minutes.
These overrides automatically apply to compound UOM’s that
include the changed units. For example, the English unit for thermal
conductivity is Btu/hr-ft2-F. After applying the above changes for
temperature and time, the user unit for thermal conductivity would
be Btu/min-ft2-K.

Data Definition Section

This section defines the data storage structure used by a user-added
unit operation. Integer, floating-point, and text data are supported.
The statements assign ID names and numbers, and define the size of
user arrays. Numeric data may be assigned default values as well as
upper and lower bound values. It is also possible to associate float-
ing point data with the “user units” declared in the [UOM] section.

Data Definition Section Heading

[Data Definition]
This heading statement is required as the first statement in the sec-
tion. It has no additional entries.

Storage Allocation Statements

The storage allocation statements specify the number of variables
and the total amount of storage used by the UAUOP. The MAXxxx
statements specify the maximum number of variables available in
each data type. The TOTxxx statements specify the total amount of
storage that PRO/II will create and maintain for each instance of the
UAUOP.

Integer Storage Allocation Statements

MAXINT = nmax The number of defined INT variables, including
user-input variables and UAUOP results variables. This
limits the number of INT statements allowed in the [Data
Definition] section.

TOTINT = ntot The total storage to allocate for INT data.

ntot Specifies the amount of INT storage, counted in 32-bit
words. This must equal or exceed the sum of the lengths
of all INT scalar variables and the sizes of all INT array
variables. Count 1 word for each INT scalar and 1 word
for each element of each INT array.

PRO/II User-Added Subroutine User Guide 10-9

 Parameter Storage Allocation Statements
MAXPAR = nmax The number of defined PAR variables, includ-
ing user-input variables and UAUOP results variables.
This limits the number of PAR statements allowed in the
[Data Definition] section.

TOTPAR = ntot The total storage to allocate for PAR data.

ntot Specifies the amount of PAR storage, counted in 64-bit
(floating point) words. This must equal or exceed the
sum of the lengths of all PAR scalar variables and the
sizes of all PAR array variables. Count 1 word for each
PAR scalar and 1 word for each element of each PAR
array.
Double Precision Storage Allocation Statements
MAXDBL = nmax The number of defined DBL variables, including
user-input variables and UAUOP results variables. This
limits the number of DBL statements allowed in the
[Data Definition] section.

TOTDBL = ntot The total storage to allocate for DBL data.

ntot Specifies the amount of DBL storage, counted in 64-bit
(floating point) words. This must equal or exceed the
sum of the lengths of all DBL scalar variables and the
sizes of all DBL array variables. Count 1 word for each
DBL scalar and 1 word for each element of each DBL
array.
Text Data Storage
MAXTEX = nmax The number of defined TEXT variables, includ-
ing user-input variables and UAUOP results variables.
This limits the number of TEXT statements allowed in
the [Data Definition] section.
TOTTEX = ntot The total storage to allocate for storing text data.
ntot Specifies the total amount of TEXT storage, counted in
32-bit words. Each word holds up to 4 characters. This
must equal or exceed the sum of all sizes for all TEXT
scalar variables and the size of all TEXT arrays.
The size of each scalar TEXT item is computed from the
maxchar entry on each TEXT statement, as follows:

nwords = (maxchar +3) / 4

10-10 UAUOP INI File February 2009

 All elements of a TEXT array are the same size. The size
of each TEXT array is computed using the isize and
maxchar entries in each TEXT statement, as follows:

nwords = isize *((maxchar + 3) / 4)

See the example at the end of the next section, “Variable Definition
Statements”.

Variable Definition Statements

INT idno idname isize intclass idefault ilo ihi
PAR idno idname isize uomclass vdefault vlo vhi
DBL idno idname isize uomclass vdefault vlo vhi
TEXT idno idname isize maxchar iminname
Each of these statements defines a single variable of the indicated
type. Each variable may be a (single-valued) scalar or a (multi-
element) array, where each element holds a single value. In each
array, every element is the same size as all other arrays.
INT Defines one INT variable, either a scalar or an array.
PAR Defines one PAR variable, either a scalar or an array.
DBL Defines one DBL variable, either a scalar or an array.
TEXT Defines one TEXT variable, either a scalar or an array.
Where:
idno The ID number assigned to the variable. It must be
a value between 1 and MAXxxx, where MAXxxx is one
of MAXINT, MAXPAR, MAXDBL, or MAXTEX, as
appropriate.
idname An ID name assigned to the variable. The name may
contain up to 32 characters, but must be unique in the
data category. For example,
INT 1 MyABC
INT 2 MyABC

is invalid because the same ID name is assigned to two

INT variables. In contrast,
INT 1 MyABC
PAR 1 MyABC
DBL 1 MyABC
TEXT 1 MyABC

PRO/II User-Added Subroutine User Guide 10-11

 is acceptable (but perhaps confusing to a user!) because
the ID name is unique within each category of data.
isize The number of elements in the variable. A value of 1
defines a scalar variable, while a value of 2 or more
defines an array.
intclass Not supported on the INT statement. Always represent
this with a tilde ( ~ ), the placeholder symbol for an
omitted entry.
idefault An integer value assigned to the INT variable when no
value is supplied through user input. Use -2111111111
when no default value applies. Do not use a tilde ( ~ ).
ilo The lower bound value of the INT variable. User-sup-
plied values less than ilo generate an input error. Use
-2111111111 when no lower bound applies. Do not use
a tilde ( ~ ).
ihi The upper bound value of the INT variable. User-sup-
plied values greater than ihi generate an input error. Use
-2111111111 when no upper bound applies. Do not use
a tilde ( ~ ).
uomclass This is the keyword for a dimensional unit of measure
class; for example, TEMP for temperature units or PRES
for pressure units. The presence of a keyword associates
a UOM class with the variable. All data for the variable
(scalar or array) are converted to the user-unit of the
specified class. Table 7-2 on page 7-2 provides a com-
plete list of all available UOM class keywords.
This entry is supported only on PAR and DBL state-
ments. When a variable has no UOM, represent
uomclass with a tilde ( ~ ), the placeholder symbol for
an omitted entry.
vdefault A double precision value assigned to the PAR or DBL
variable when no value is supplied through user input.
Use -1.5D35 when no default value applies. Do not use
a tilde ( ~ ).
vlo The lower bound value of the PAR or DBL variable.
User-supplied values less than vlo generate an input
error. Use -1.5D35 when no lower bound applies. Do
not use a tilde ( ~ ).
vhi The upper bound value of the PAR or DBL variable.
User-supplied values greater than vhi generate an input

10-12 UAUOP INI File February 2009

 error. Use -1.5D35 when no upper bound applies. Do
not use a tilde ( ~ ).
maxchar For TEXT data only, maxchar is the maximum number
of characters allowed in one element of a scalar variable
or array. Typically, maxchar is a multiple of 4, since stor-
age is accomplished using words that store 4 characters
each.
iminname For TEXT data only, the minimum number of characters
in the ID name that makes the ID unique among the
names of all TEXT variables. This allows users in key-
word input to truncate long variable names to the short-
est unique string.

Example Data Definition

Assume the UAUOP has the following data requirements:

Variable Variable Element UOM Lower Upper

Default
ID No ID Name (Size) Class/Unit Bound Bound
INT INT
1 MyInt1 1 n/a 11 1 15
2 IntArray1 3 n/a None -15 +15
3 MyInt3 1 n/a None None None

PAR PAR
1 TempIn 1 Temperature 70 32 212
,F
2 TempOut 1 Temperature none 70 212
,F
3 PresIn 1 Pressure, 14.6959 1.0 50.0
psia
PresOut 1 Pressure, none 14.0 50.0
psia
DBL DBL
1 Xval 3 Duty, Watt 0.0 None None
2 Yval 3 Surf. Tens, None None None
N/m
3 CalcOut 3 n/a none None None
TEXT TEXT Element maxchar minnam
1 Mytext1 3 12 7 n/a n/a
2 MyText2 1 16 7

PRO/II User-Added Subroutine User Guide 10-13

 Assume UAUOP calculations are in SI units, with temperatures in
Fahrenheit, pressures in pounds per square inch, duty in Watts, and
surface tension in Newtons/meter. The following sample of the INI
file declares these user units for exchanging data with the UAUOP.
[UOM]
BASE = SI ;; Sets basic user system of UOM’s to be SI.
TEMP = F ;; Set temperature unit to be Fahrenheit.
PRES = PSIA ;; Overrides pressure unit to be psia.
DUTY = WATT ;; Overrides duty unit to be Watt.
;; SURF = N/M ;; No override needed, this is the SI unit.
The following example of the [Data Definition] section of an INI file
defines the storage and variables from the table of data above.
[Data Definition]
MAXINT = 3 ;; Allow 3 INT variables
TOTINT = 5 ;; Total words of integer storage
;; Counts INT 1 as 1 word (a scalar),
;; INT 2 as 3 words (an array),
;; INT 3 as 1 word (a scalar)
MAXPAR = 4 ;; Allow 4 PAR variables
TOTPAR = 4 ;; Total words of PAR storage (4 scalars)

MAXDBL = 3 ;; Allow 3 DBL variables

TOTDBL = 9 ;; Total words of DBL storage (3 arrays of
;; 3 elements in each array
MAXTEX = 2 ;; Allow 2 TEXT variables
TOTTEX = 13 ;; 13 words of TEXT storage

;; TOTTEX is the sum of (element i) * (maxchari+3)/4. In this case,

;; TEXT 1 = 3 * ( 12 + 3 ) / 4 = 3 * 3 = 9
;; TEXT 2 = 1 * ( 16 + 3 ) / 4 = 1 * 4 = 4
;; for a total of 13 words of storage.
;; Definition of variables follows
INT 1 “MyInt1” 1 ~ 11 1 15
INT 2 “IntArray1” 3 ~ -2111111111 -15 15
INT 2 “MyInt3” 1 ~ -2111111111 -2111111111 -2111111111

PAR 1 “TempIn” 1 TEMP 70.0 32.0 212.0

PAR 2 “TempOut” 1 TEMP -1.5E35 70.0 212.0
PAR 3 “PresIn 1 PRES 14.6959 1.0 50.0
PAR 4 “PresOut” 1 PRES -1.5E35 14.0 50.0

DBL 1 “Xval” 3 DUTY 0.0 -1.5E35 -1.5E35

DBL 2 “Yval” 3 -1.5E35 -1.5E35 -1.5E35
DBL 3 “CalcOut” 3 ~ -1.5E35 -1.5E35 -1.5E35

TEXT 1 “Mytext1” 3 12 7
TEXT 2 “MyTEXT2” 1 16 7

10-14 UAUOP INI File February 2009

INI File Usage Information
PRO/II Requirements
Each UAUOP model has its own INI file, and all instances of that
UAUOP in a simulation use the same INI file. While the data names
and storage structures of all instances are identical, the values of
data usually are different. The differences include user-supplied
input data and side data, where each instance typically has a unique
set of feed and product streams.
The unit operation INI file provides all the information necessary for
PRO/II to use a UAUOP through keyword input. It does not provide
all the information needed to implement input processing using an
optional AutoGUI Data Entry Window. Refer to Chapter 8,
“UAUOP AutoGUI” for extensive information about implementing
an AutoGUI DEW for a UAUOP.

File Naming Conventions

By convention, the name of the initialization file for a user-added
unit operation has the form:
uauopname.INI
Where:
uauopname The name registered as the UATYPE entry in the
P2UasReg.ini registration file.

.INI This suffix identifies the file as an initialization data

file.
These conventions are merely a convenience, since PRO/II imposes
minimal restrictions on the file name. However, the file name must
be registered in the [UAUOP] section of the P2UasReg.ini file. See
“Registering [UAUOP] User-Added Unit Operations” on page 11
of Chapter 2 for more information.

INI File Syntax

The INI file is a text file that can be edited using a plain-text editor
such as Visual Studio or NotePad©. Here is a brief summary of spe-
cial characters and limitations on their use.
Order of Entries
The sections in an INI file may appear in any order.
All data statements in a section must immediately follow the
appropriate [section] header.

PRO/II User-Added Subroutine User Guide 10-15

 The statements within a section may appear in any order.
Although the order documented in this chapter is preferred, it is
not required.
All entries on each statement are required. Omitted entries must
be represented by placeholder tokens. See “Placeholders” on
page 10-17 of this chapter.
Most statements do not support continuation lines. All entries
for most statements must appear on a single line.
Entries on each statement are order-dependent. They must
appear in the order documented in this chapter.
Case Sensitivity
Most entries are case insensitive. For example, [ACCESS DATA]
and [Access Data] are equivalent. However, some entries for system
dependent information are case sensitive. For example, on UNIX
systems, file names and directory paths are case sensitive. When
entering paths or file names, ensure that the entry in the INI file
exactly matches the case of the actual path or file name.
PRO/II reads and stores INI file data using the exact case of each
entry. When attempting to access a file or directory, PRO/II first
tries to use the exact syntax. If that fails, the data is converted to all
upper case and retried. Failure on the second try results in an error.
Comments
$, !, ; The dollar sign ($), exclamation point (!), and semicolon
(;) all denote the beginning of a comment line that is
ignored by the processor.
Any text to the right of a comment character is part of the comment.
Typically, entire lines should be marked as comment, so one of
these should be the left-most character on a comment line. Do not
use these characters elsewhere, such as embedding them within
names of data items.
Continuation Marks
A few statements in an INI file support continuation lines, but most
do not. It is safest to enter all data for each statement on a single
line. Using continuation lines in an INI file is not recommended.
*, & Asterisks (*) and ampersands (&) indicate the end of data
on a line, and instruct the processor to read additional
data from the next line.
These symbols may be embedded in descriptive text, when the text
is enclosed within quotation marks. When one of them is the right-
most character on a line, it acts as a continuation mark and is not

10-16 UAUOP INI File February 2009

 included as part of the text. Avoid using them in other situations,
such as in data names or directory paths.
Delimiters
One or more contiguous spaces act as a single delimiter between
entries. Commas are not delimiters.
[, {, <, >, }, ] Delimiter characters have specialized uses and should
be used only as described here. The delimiters have spe-
cific significance, and cannot be interchanged. They
must be used in pairs.
Brackets ([ ]) are used only to enclose the names of sections in
the INI file. Valid usage is restricted to the following tokens:
[Access Data], [Sides], [UOM], and [Data Definition].

Any other use is invalid.

Braces ({ }) and chevrons (< >) are reserved characters that
should not be used in an INI file.

Placeholders
Every entry on each statement is required. Missing entries must be
indicated by using the designated placeholder.
~ The tilde (~) is a placeholder that indicates an omitted
entry.
Use only one tilde for each omitted entry. To omit contiguous
entries, use one tilde for each omitted entry, with a blank space
between each tilde. Note: most numeric data use numeric values for
“missing” values, and do not support use of the tilde.
Quotation Marks
“, ‘ Full (“) and single (‘) quotation marks (i.e., apostrophes)
may be used in pairs to enclose text entries that include
embedded blanks. They are never part of a variable
name.
Any data that includes embedded blank spaces must appear in quo-
tation marks.
Variable Names
The ID names of variables on INT, PAR, DBL, and TEXT statements
must begin with an alphabetic character A-Z or a-z. Names may
contain embedded blanks, but are not recommended, because they
require users to enclose the name in quotation marks in keyword
input files.

PRO/II User-Added Subroutine User Guide 10-17

10-18 UAUOP INI File February 2009
 Chapter 11
Interfacial Area Utility
Overview
The rate-based calculations in PRO/II compute the mass and heat
transfer between the liquid and vapor phases on each separation
stage. The calculations require the interfacial area where these two
phases come in contact. The interfacial area utility allows third-
party developers to perform these calculations using their own user-
added subroutines. Only the RATEFRAC algorithm of the Column
model supports this. An example appears in “Using the Sample
Interfacial Area Utility” on page 2-14.
In rate-based calculations, the vapor and liquid phases are not in
equilibrium. The rate-based calculations in PRO/II do not support
liquid sub-phases at this time. Only bulk liquid properties are avail-
able to this subroutine.
While all fluids on a stage usually have the same pressure, the vapor
and liquid usually are at different temperatures. The model includes
an additional fluid that mitigates the mass transfer between the
vapor and liquid. The temperature of this interface fluid approxi-
mates the overall stage temperature used in an equilibrium model. It
is usually between the vapor and liquid temperatures. The total con-
tacting area between the bulk vapor and bulk liquid phases is the
interfacial area that this subroutine calculates.
PRO/II calls the interfacial area subroutine for each individual stage
during calculations. This means the calculation subroutine should
compute the interfacial area for a single separation stage. The single
value computed for interfacial area must return in the Results(1,1)
member of the data object. Also, the calculation routine must return
ISOLVE = 1 for each call. Any other value causes RATEFRAC to
terminate the problem with a fatal error.

Available Interfacial Area Data - Developers

When PRO/II calls a user-added utility, it delivers a pre-defined set
of data to use for computing the required results. Developers have
no control over the data passed to their subroutines. However, PRO/
II imposes no constraints on how the developer uses the data. After
each call to a user-added utility routine, PRO/II discards all input
data it passes to the user-added subroutine. Only the results returned
from the subroutine are retrieved. PRO/II sends new input data on
each call to the user-added subroutine.

PRO/II User-Added Subroutine User Guide 11-1

 All data exchanged between PRO/II and a user-added utility sub-
routine pass as members of a single data structure. The data struc-
ture passed to an interfacial area subroutine is compatible only with
an interfacial area subroutine. Table 11-1, ”Interfacial Area Data
Members”, is a summary of the complete data set available to
developers of interfacial area subroutines. Many of the data mem-
bers are passed to all the types of PRO/II utility subroutines. Chap-
ter 4, “Modular Utility Subroutines”, describes those items. Other
data members in Table 11-1 have special considerations that are
specific to an interfacial area subroutine. The sections immediately
following Table 11-1 describe these items.
Table 11-1: Interfacial Area Data Members
Member Type Description Keyword
Module Data
UasType C 12 Always "UAIFAREA"
UasPath C 256 Path to DLL directory from
P2UasReg.ini
UasName C 32 Actual name of subroutine
to call, from P2UasReg.ini
UasID C 32 PRO/II ID of this UAS,
from P2UasReg.ini
General Data
ThermoFl I4 Thermodynamic method
set flag
DiagnosticFl I4 Diagnostic flag
UomSystem I4 UOM system flag
1 = PRO/II internal
2 = English
3 = Metric
4 = SI
Context C 12 Context flag "INPUT"
process input
"CROSSCHECK"
"CALCULATION"
"OPCALC" post
convergence
"REPORT"

11-2 Interfacial Area Utility February 2009

 Table 11-1: Interfacial Area Data Members
Member Type Description Keyword
iContext I4 Integer version of context
1 "INPUT" process input
2 "CROSSCHECK”
3 "CALCULATION"
4 "OPCALC" post
convergence
5 "REPORT"
Phase I4 Phase of interest
0 = Phase is not applicable
to the calculations
1 = Vapor (not used here)
2 = Liquid (not used here)
CallerID C 12 ID of calling Unit
Operation
Exist L4 Logical .True. if data object
is populated with valid data
Component Data
NOC I4 Total number of
components in problem
CompIndex(i) I4 Internal component
numbers, in input order,
i = 1, NOC
Fluid Data
ValidFlVapor I4 1 = valid Vapor fluid from
PRO/II
ValidFlLiquid I4 1 = valid Liquid fluid from
PRO/II
ValidFlIface I4 1 = valid Interface fluid
from PRO/II
FlVapor Fluid Vapor phase fluid data
object
FlLiquid Fluid Liquid phase fluid data
object
FlIface Fluid Interface phase fluid data
object
Stage Data
IS1(1) I4 Column type flag COLTYPE
1 = packing 2 = trays

PRO/II User-Added Subroutine User Guide 11-3

 Table 11-1: Interfacial Area Data Members
Member Type Description Keyword
DS1(1) DP Cross-sectional area of XAREA
stage, area.
DS1(2) DP Weir height, length HTWIER
DS1(3) DP Downcomer area, area AREADC
DS1(4) DP Flow path length, length LENGFL

Packing Data
IS1(2) I4 Packing type (use only with PTYPE
IS1(3), packing
arrangement, below)
IS1(3) I4 Packing arrangement PARRANGE
1 = random
2 = structured
IS1(4) I4 Packed stage number PSECTION
DS1(5) DP Packed section diameter, PDIAM
fine length
DS1(6) DP Packed section height, PHEI
length
DS1(7) DP Size of packing, fine PSIZE
length.
DS1(8) DP Packing specific area, area. PSPAR
DS1(9) DP Packing critical surface PSURC
tension, SurfTens
DS1(10) DP Packing factor, 1/length. PFAC

Tray Data
IS1(6) I4 Tray type TTYPE
1 = bubble cap
2 = valve
3 = sieve
IS1(8) I4 Stage number of stage with TRAYNO
trays
IS1(10) I4 Number of passes per tray, TPASS
currently always 1
DS1(11) DP Tray diameter, fine length TDIAM
DS1(12) DP Tray height, fine length THEI

11-4 Interfacial Area Utility February 2009

 Table 11-1: Interfacial Area Data Members
Member Type Description Keyword
DS1(13) DP Active tray area. The TACTA
dimensional class is fine
area
DS1(14) DP Number of trays in section, NTRAY
dimensionless
Output Data to Return
Results(1,1) DP Overall interfacial area returns in
Results(1,1).
For a packed stage, this is interfacial area /
unit of packing area (dimensionless)
For a stage with trays, units are: area/unit
of stage volume (= 1/length)
ISOLVE I4 Solution flag to return UAS.
0 = no processing took place
1 = solved (expected value)
2 = errors encountered, but reasonable
results returned
3 = failed, stop calculations
SizeR1 I4 First extent of Results
vector (1) not a return value
SizeR2 I4 Second extent of Results
vector (1) not a return value
The Member column lists the exact name of each member.
These names are used for direct access to the data from
within the data object; e.g. IAObj%NOC
The Type column indicates the data type declared for each entry
C nnn Character string containing up to nnn characters
I4 Integer(4) integer scalar value (one 4 byte word)
L4 Logical(4) logical scalar variable (one 4 byte word)
The only possible values are .TRUE. or .FALSE.
DP A REAL(8) double precision scalar value.
The Keyword column lists the identifiers used to retrieve the
data using one of the accessor utilities within
class_UasObj.mod. When available, this is an alternative to
using direct data access via the "member" name.

PRO/II User-Added Subroutine User Guide 11-5

 Module Data, General Data, Component Data
These sections of Table 11-1 are generic, since the same data set is
passed to all types of utility routine supported by PRO/II. Refer to
Chapter 4, ”Modular Utility Subroutines”. Since interfacial area
does not apply to a particular phase, the phase flag member of
UASOBJ does not apply to this utility subroutine.

Fluid Data
The data object for interfacial area includes three separate fluids.
Each is a partial analog of a PRO/II stream. See Chapter 6, ”UAS
Modular Fluids” for a list of all available data.

FlVapor A fluid object that contains the data for the stage
bulk vapor phase. It supports data for the total
fluid and for the bulk vapor phase. Since the
fluid is all vapor, the data for the total fluid and
the vapor phase are identical.

FlLiquid A fluid object that contains the data for the stage
bulk liquid phase. It supports data for the total
fluid and for the bulk Liquid phase. Since the
fluid is all liquid, the data for the total fluid and
bulk liquid phase are identical. It does not
include any data for possible liquid sub-phases.

FlIface A fluid object that contains data for the Total

fluid, bulk vapor phase, and bulk liquid phase. It
does not include data for any possible liquid
sub-phases.

Valid- These are validation flags for the available flu-

FlVapor ids. Each flag normally has a value of 1 (.True.)
Valid indicating that the fluid data structure contains
FlLiquid valid data. A value of 0 indicates the fluid and
ValidFlIface its data are not available.

11-6 Interfacial Area Utility February 2009

 Stage Data
This section contains general data about the distillation column that
requests the interfacial area. This information includes flags that
characterize the column configuration.

IS1(1) Column Type Flag. It indicates whether the current

separation stage has trays or packing.
1 = packing - use only packing data with this value
2 = trays - use only tray data with this value
Either packing or tray data is furnished on each tray
call; not both. Use this flag to code branching logic
in the calculation subroutine to use only the appro-
priate data.

DS1(1) The cross sectional area of the stage. The dimen-

sional class is area.

DS1(2) Weir height. The dimensional class is length.

DS1(3) Downcomer area. The dimensional class is area.

DS1(4) Flow path length. The dimensional class is length.

Packing Data
This section contains packing data when the current stage is a
packed stage. This data is available only when the Column Type
flag indicates a packed stage (IS1(1) = 1). Do not use this data when
IS1(1) has a different value.
Only the packing types listed in Tables 12-7.9 and 12-7.10 of the
PRO/II Keyword Manual are available for use with an interfacial
area subroutine. This is due to the additional data required by the
rate-based calculations that only the RATEFRAC Column algorithm
performs. The additional data for other packing types are propri-
etary and not available.

IS1(1)=1 Column Type Flag that indicates the stage has

packing.

PRO/II User-Added Subroutine User Guide 11-7

 IS1(2) This flag indicates the type of packing on the stage.
Use with the Packing Arrangement flag (below) to
determine if the packing is random or structured. See
the PRO/II Keyword Manual, Table 12-7.9 for avail-
able random packing, and Table 12-7.10 for avail-
able structured packing types.

IS1(3) Packing Arrangement flag. Use only when IS1(1) =

1. Also, use with IS1(2), packing type, above.
IS1(3) = 1 random packing
IS1(3) = 2 structured packing

IS1(4) Stage number of the current (packed) stage.

DS1(5) Diameter of the (stage in a) packed section. The

dimensional class is fine length.

DS1(6) Height of the packed section. The dimensional class

is length.

DS1(7) Size of the packing. The dimensional class is fine

length.

DS1(8) Specific area of the packing. This is the area per unit
volume of the packing on the stage. The dimensional
class is area. Multiply the specific area by the vol-
ume of packing to obtain total packing area.

DS1(9) Critical surface tension of the packing. The dimen-

sional class is surface tension.

DS1(10) Packing factor. The dimensional class is inverse

length ( 1.0 / length )

11-8 Interfacial Area Utility February 2009

 Note: PRO/II distinguishes between random and structured pack-
ing, and the numbering of the two packing classes overlap. Use
the Packing Arrangement flag, IS1(3), to determine whether the
packing arrangement is random or structured. Then use IS1(2),
the Packing Type Flag, to obtain the actual packing type. Refer to
Table 12-7.9 in the PRO/II Keyword Manual for the numbering of
random packing types. See Table 12-7.10 in the PRO/II Keyword
Manual for the numbering of structured packing types. As an
example, refer to the following comparison.

Data Member Packing Type

Random Pall Structured

Rings (plastic) M250Y

IS1(1) Column Stage Type 1 1

IS1(2) Packing Type I 5 5

IS1(3) Packing 1 2
Arrangement

IS1(1) always is 1 when indicating a packed stage.

IS1(2) is 5 for both the random-packed pall rings and the structured
M250Y packing.
IS1(3) must be tested to determine the actual packing to which
IS1(2) refers.

PRO/II User-Added Subroutine User Guide 11-9

 Tray Data
This section contains tray data when IS1(1) = 2 (the Column Type
Flag = 2). Do not attempt to use this data when IS1(1) has a differ-
ent value.

IS1(1)=2 Column Type Flag that indicates the stage has trays.

IS1(6) The type of tray on the stage.

1 = bubble cap tray
2 = valve tray
3 = sieve tray

IS1(8) Stage number of the current (tray) stage.

IS1(10) Number of passes per tray. Currently, always 1 pass.

DS1(11) Diameter of tray on current stage. The dimensional

class is fine length.

DS1(12) Tray height. The dimensional class is fine length.

DS1(13) Active tray area. This is the tray area that participates
in the separation process. It usually is a fraction of
the total tray area. The dimensional class is fine area.

DS1(14) Number of trays in the section. May be a non-integer

value. Dimensionless.

Note: A single correlation for interfacial area often is not suitable

for all the possible tray configurations. Often, developers imple-
ment separate correlations for bubble cap, valve, and sieve trays.
Use the Tray Type flag, IS1(6), to implement branching logic
when implementing and writing separate calculation code for dif-
ferent tray types.

11-10 Interfacial Area Utility February 2009

 Returned Results (required)
The interfacial area calculation subroutine must return two values to
PRO/II:

ISOLVE Returned solution flag. Use a value for

ISOLVE from Table 3-3. Always return
ISOLVE= 1 when returning a reasonable value
for interfacial area. All other return codes
cause PRO/II to terminate calculations imme-
diately. Also refer to the topic “ISOLVE
Return Values” on page 4-4.

Results(1,1) Interfacial area calculated return value. Valid

values are greater than zero. This is the total
area of contact between the vapor and liquid
phases on the stage.
For packing (IS1(1) = 1), this is the interfacial
area per unit of packing area. The returned
value is dimensionless.
For trays (IS1(1) = 2), this is the interfacial
area per tray volume, or area/volume, which is
length2 / length3. This simplifies to 1/length,
so the dimensional units class is inverse
length. The length unit of measure (meter,
feet, etc.) must be the same as the length unit
of the dimensional units system in use. (Use
the UOM entry of the P2UasReg.ini file to
determine the dimensional units system. Refer
to Table 7-2 on page 7-2.)

The following two data members are not return values, but are
included here to complete the documentation.

SizeR1 First dimension of the Results array. The value

always is 1.

SizeR2 Second dimension of the Results array. The

value always is 1. The class_UasObj data con-
structor sizes the Results array as
Results(SizeR1,SizeR2).

PRO/II User-Added Subroutine User Guide 11-11

 Sample Interfacial Area Utility
Sample code for an interfacial area utility is available on the instal-
lation disk. The PRO/II installation program optionally allows
installing a sample project for user-added subroutines. The sample
code provided by SIMSCI is not intended for general use in
RATEFRAC simulations. The default directory for installing the
sample source code is:
..\USER\UAS\UASF90\

This sub-directory is located in the directory tree of the PRO/II

installation. The sample code for the interfacial area utility resides
in the following files.

AREAMAIN.F90 PRO/II calls this interface routine. It must

be properly registered in the [UAIFAREA]
section of the P2UasReg.ini file.

AREACALC.F90 This routine calculates and returns a value

for the heat transfer coefficient. It is called
whenever the context flag is "CALC". It
also sets the ISOLVE return flag.

AREAREPO.F90 A sample output report routine that writes

results of the user-added calculations. Nor-
mally, this would be called when the con-
text flag is "REPORT".

“Using a User-Added Modular Utility in PRO/II” on page 2-14

describes using a complete sample project that includes code for
computing interfacial area. Chapter 4, ”Modular Utility Subrou-
tines”, discusses various aspects of developing a user-added utility
for PRO/II. Those guidelines apply when creating an interfacial
area subroutine.

11-12 Interfacial Area Utility February 2009

 Chapter 12
Binary Mass Transfer Utility

Overview
The rate-based calculations in PRO/II compute the mass transfer
between the liquid and vapor phases on each separation stage. The
calculations require binary mass transfer coefficients for each
binary pair of components on the separation stage. This mass
transfer utility allows third-party developers to compute the binary
coefficients using their own user-added subroutines. Only the
RATEFRAC algorithm of the Column model supports this. A sam-
ple project that includes an implementation of a working mass
transfer subroutine is available. Refer to “Using a User-Added
Modular Utility in PRO/II” in Chapter 2,“Modular UAS Build Pro-
cedures”.
In rate-based calculations, the vapor and liquid phases are not in
equilibrium. The rate-based calculations in PRO/II do not support
liquid sub-phases at this time. Only bulk liquid properties are avail-
able to this subroutine.
While all fluids on a stage usually have the same pressure, the vapor
and liquid usually are at different temperatures. These two phases
are in contact with each other at the vapor-liquid interface. PRO/II
passes the interfacial area of the stage into this routine. (A user-
added subroutine may be used to compute the interfacial area. Refer
to Chapter 11,“Interfacial Area Utility”). No other properties of the
interface are available.
PRO/II calls the mass transfer subroutine for each individual stage
during calculations. On each call, the calculation subroutine should
compute the mass transfer coefficients of all component pairs for a
single separation stage. The computed coefficients must return as a
two dimensional matrix in the Results array. The Results array is a
member of the data object passed through the argument list of the
call to the subroutine. Also, the calculation routine must return
ISOLVE = 1 for each call. Any other value causes RATEFRAC to
terminate the problem with a fatal error.

PRO/II User-Added Subroutine User Guide 12-1

Available Mass Transfer Data - Developers
When PRO/II calls a user-added utility, it delivers a pre-defined set
of data for computing the required results. Developers have no con-
trol over the data passed to their subroutines. However, PRO/II
imposes no constraints on how the developer uses the data. After
each call to a user-added utility routine, PRO/II discards all input
data it passes to the user-added subroutine. Only the results returned
from the subroutine are retrieved. PRO/II sends new input data on
each call to the user-added subroutine.
All data exchanged between PRO/II and a user-added utility sub-
routine pass as members of a single data structure. The data struc-
ture passed to a mass transfer subroutine is not compatible with
other types of user-added subroutine. Table 12-1 on page 12-2 is a
summary of the complete data set available to the developers of a
mass transfer subroutine. Many of the data members are passed to
all the types of PRO/II utility subroutines. Chapter 4,“Modular
Utility Subroutines” describes those items. Other data members in
Table 12-1 have special considerations that are specific to a mass
transfer subroutine. The sections immediately following Table 12-1
describe these items.
Table 12-1: Mass Transfer Data Members
Member Type Description Keyword
Module Data
UasType C 12 Always "UAMASSTR"
UasPath C 256 Path to DLL directory
from P2UasReg.ini
UasName C 32 Actual name of subroutine
to call, from P2UasReg.ini
UasID C 32 PRO/II ID of this UAS,
from P2UasReg.ini
General Data
ThermoFl I4 Thermodynamic method
set flag (not currently
supported)
DiagnosticFl I4 Diagnostic flag (not
currently supported)
UomSystem I4 UOM system flag
1 = PRO/II internal
2 = English
3 = Metric
4 = SI

12-2 Binary Mass Transfer Utility February 2009

 Member Type Description Keyword
Context C 12 Context flag
"INPUT" process input
"CROSSCHECK"
"CALCULATION"
"OPCALC" post
convergence
"REPORT"
iContext I4 Integer version of context
1 "INPUT" process input
2 "CROSSCHECK"
3 "CALCULATION"
4 "OPCALC" post
convergence
5 "REPORT"
Phase I4 Phase of interest
1 = Vapor
2 = Liquid
CallerID C 12 ID of calling Unit
Operation
Exist L4 Logical .True. if data
object is populated with
valid data
Component Data
NOC I4 Total number of
components in problem
CompIndex(i) I4 Internal component
numbers, in input order,
I = 1, NOC
DA2(i,j) DP Binary diffusion DIFFCO
coefficients. i = 1 to NOC,
j = 1 to NOC. The
dimensional units are area/
time.
Fluid Data
ValidFlVapor I4 1 = valid Vapor fluid from
PRO/II
ValidFlLiquid I4 1 = valid Liquid fluid from
PRO/II
FlVapor Fluid Vapor phase fluid data
object

PRO/II User-Added Subroutine User Guide 12-3

 Member Type Description Keyword
FlLiquid Fluid Liquid phase fluid data
object
Stage Data
IS1(1) I4 Column type flag COLTYPE
1 = packing 2 = trays
DS1(1) DP Cross-sectional area of XAREA
stage. The dimensional
class is area.
DS1(2) DP Weir height, length HTWIER
DS1(3) DP Downcomer area. The AREADC
dimensional class is area.
DS1(4) DP Flow path length, length LENGFL
DS1(15) DP Interfacial area (total). The IFAREA
dimensional class is area.
Packing Data
IS1(2) I4 Packing type (use only PTYPE
with IS1(3), packing
arrangement, below)
IS1(3) I4 Packing arrangement PARRANGE
1 = random 2 = structured
IS1(4) I4 Packed stage number PSECTION
DS1(5) DP Packed section diameter. PDIAM
The dimensional class is
fine length
DS1(6) DP Packed section height. The PHEI
dimensional class is
length.
DS1(7) DP Size of packing. The PSIZE
dimensional class is fine
length.
DS1(8) DP Packing specific area. The PSPAR
dimensional class is area.
DS1(9) DP Packing critical surface PSURC
tension. The dimensional
class is surface tension.
DS1(10) DP Packing factor. The PFAC
dimensional units are
1/length.

12-4 Binary Mass Transfer Utility February 2009

 Member Type Description Keyword
Tray Data
IS1(6) I4 Tray type: TTYPE
1 = bubble cap
2 = valve
3 = sieve
IS1(8) I4 Stage number TRAYNO
IS1(10) I4 Number of passes per tray, TPASS
currently always 1
DS1(11) DP Tray diameter, fine length TDIAM
DS1(12) DP Tray height. The THEI
dimensional class is fine
length
DS1(13) DP Active tray area. The TACTA
dimensional class is fine
area
DS1(14) DP Number of trays in NTRAY
section, dimensionless
Output Data to Return
Results(i,j) DP Matrix of returned binary
mass transfer coefficient
values. The dimensions
are wt-moles/time. i=1 to
NOC, j=I to NOC.
ISOLVE I4 Solution flag to return UAS.
0 = no processing took place
1 = solved (expected value)
2 = errors encountered, but reasonable
results returned
3 = failed, stop calculations
SizeR1 I4 First extent of Results
vector (NOC) (not a return
value.)
SizeR2 I4 Second extent of Results
vector (NOC) (not a return
value.)
The MEMBER column lists the exact name of each member.
These names are used for direct access to the data from within
the data object; e.g. IAObj%NOC

PRO/II User-Added Subroutine User Guide 12-5

 Member Type Description Keyword
The Type column indicates the data type declared for each entry
C nnn Character string containing up to nnn characters
I4 Integer(4) integer scalar value (one 4 byte word)
L4 Logical(4) logical scalar variable (one 4 byte word)
The only possible values are .TRUE. or .FALSE.
DP A REAL(8) double precision floating point scalar value
The Keyword column lists the identifiers used to retrieve the data
using one of the accessor utilities within class_UasObj.mod. When
available, this is an alternative to using direct data access via the
"member" name.

Module Data, General Data

These sections of Table 12-1 are generic, since the same data set is
passed to all types of utility routine supported by PRO/II. Refer to
Chapter 4,“Modular Utility Subroutines”.

Component Data
For a binary mass transfer subroutine, binary diffusion coefficients
for every pair of components are available in the DA2 array of the
UaObj data object.

NOC Number of components in the problem.

CompIndex(i) Internal component numbers in input order. "i" =

1 to NOC

DA2(i,j) Binary diffusion coefficients for every compo-

nent pair. The dimensional units are area/time. i =
1 to NOC, j = 1 to NOC

12-6 Binary Mass Transfer Utility February 2009

 Fluid Data
The data object for mass transfer coefficients includes two separate
fluids. Each is a partial analog of a PRO/II stream. See Chapter
4,“Modular Utility Subroutines”, for a list of all available data.

FlVapor A fluid object that contains the data for the

stage bulk vapor phase. It supports data for the
total fluid and for the bulk vapor phase. Since
the fluid is all vapor, the data for the total fluid
and the vapor phase are identical.

FlLiquid A fluid object that contains the data for the

stage bulk liquid phase. It supports data for the
total fluid and for the bulk Liquid phase. Since
the fluid is all liquid, the data for the total fluid
and bulk liquid phase are identical. It does not
include any data for possible liquid sub-
phases.

FlIface This fluid is not supported by binary mass

transfer user-added subroutines.

ValidFlVapor These are validation flags for the available

ValidFlLiquid fluids. Each flag normally has a value of 1
(.True.) indicating that the fluid data structure
ValidFlIface contains valid data. A value of 0 indicates the
fluid and its data are not available.

Stage Data
This section contains general data about the distillation column that
requests the binary mass transfer coefficients. This information
includes flags that characterize the column configuration.

IS1(1) Column Type Flag. It indicates whether the current

separation stage has trays or packing.
1 = packing - use only packing data with this value
2 = trays - use only tray data with this value
Either packing or tray data is furnished on each tray
call; not both. Use this flag to code branching logic
in the calculation subroutine to use only the appro-
priate data.

PRO/II User-Added Subroutine User Guide 12-7

 DS1(1) The cross-sectional area of the stage. The dimen-
sional class is area.

DS1(2) Weir height. The dimensional class is length.

DS1(3) Downcomer area. The dimensional class is area.

DS1(4) Flow path length. The dimensional class is length.

DS1(15) Specific interfacial area on the stage. Valid values are

greater than zero. This is the total area of contact
between the vapor and liquid phases on the stage.
For packing (IS1(1) = 1), this is the interfacial area
per unit of packing area. The value is dimension-
less.For trays (IS1(1) = 2), this is the interfacial area
per tray volume, or area/volume, which is length2 /
length3. This simplifies to 1/length, so the dimen-
sional units class is inverse length. The length unit of
measure (meter, feet, etc.) must be the same as the
length unit of the dimensional units system in use.
(Use the UOM entry of the P2UasReg.ini file to
determine the dimensional units system. Refer to
Table 7-2 on page 7-2.)

Packing Data
This section contains packing data when the current stage is a
packed stage. This data is available only when the Column Type
flag indicates a packed stage (IS1(1) = 1). Do not use this data when
IS1(1) has a different value.

Only the packing types listed in Tables 12-7.9 and 12-7.10 of the
PRO/II Keyword Manual are available for use with a binary mass
transfer subroutine. This is due to the additional data required by
the rate-based calculations that only the RATEFRAC Column algo-
rithm performs. The additional data for other packing types are pro-
prietary and not available.

12-8 Binary Mass Transfer Utility February 2009

 IS1(1)=1 Column Type Flag that indicates the stage has
packing.

IS1(2) This flag indicates the type of packing on the stage.

Use with the Packing Arrangement flag (below) to
determine if the packing is random or structured. See
the PRO/II Keyword Manual, Table 12-7.9 for avail-
able random packing, and Table 12-7.10 for avail-
able structured packing types.

IS1(3) Packing Arrangement flag. Use only when IS1(1) =

1. Also, use with IS1(2), packing type, above.
IS1(3) = 1 random packing
IS1(3) = 2 structured packing

IS1(4) Stage number of the current (packed) stage.

DS1(5) Diameter of the (stage in a) packed section. The

dimensional class is fine length.

DS1(6) Height of the packed section. The dimensional class

is length.

DS1(7) Size of the packing. The dimensional class is fine

length.

DS1(8) Specific area of the packing. This is the area per unit
volume of the packing on the stage. The dimensional
class is area. Multiply the specific area by the vol-
ume of packing to obtain total packing area.

DS1(9) Critical surface tension of the packing. The dimen-

sional class is surface tension.

DS1(10) Packing factor. The dimensional class is inverse

length ( 1.0 / length )

PRO/II User-Added Subroutine User Guide 12-9

 Note: PRO/II distinguishes between random and structured pack-
ing, and the numbering of the two packing classes overlap.
Use the Packing Arrangement flag, IS1(3), to determine
whether the packing arrangement is random or structured.
Then use IS1(2), the Packing Type Flag, to obtain the actual
packing type. Refer to Table 12-7.9 in the PRO/II Keyword
Manual for the numbering of random packing types. See
Table 12-7.10 in the PRO/II Keyword Manual for the num-
bering of structured packing types. As an example, refer to
the following comparison.

Packing Type
Random Pall Structured
Data Member Rings (plastic) M250Y

IS1(1) Column Stage Type 1 1

IS1(2) Packing Type I 5 5

IS1(3) Packing Arrange- 1 2

ment

IS1(1) always is 1 when indicating a packed stage. IS1(2) is 5 for

both the random-packed pall rings and the structured M250Y pack-
ing. IS1(3) must be tested to determine the actual packing to which
IS1(2) refers.

12-10 Binary Mass Transfer Utility February 2009

 Tray Data
This section contains tray data when IS1(1) = 2 (the Column Type
Flag = 2). Do not attempt to use this data when IS1(1) has a differ-
ent value.

IS1(1)=2 Column Type Flag that indicates the stage has

trays.

IS1(6) The type of tray on the stage.

1 = bubble cap tray
2 = valve tray
3 = sieve tray

IS1(8) Stage number of the current (tray) stage.

IS1(10) Number of passes per tray. Currently, always 1

pass.

DS1(11) Diameter of tray on current stage. The dimen-

sional class is fine length.

DS1(12) Tray height. The dimensional class is fine

length.

DS1(13) Active tray area. This is the tray area that par-
ticipates in the separation process. It is usually
a fraction of the total tray area. The dimen-
sional class is fine area.

DS1(14) Number of trays in the section. May be a non-

integer value. Dimensionless.

Note: A single correlation for mass transfer coefficients often is

not suitable for all the possible tray configurations. Typically,
developers implement separate correlations for bubble cap,
valve, and sieve trays. Use the Tray Type flag, IS1(6), to
implement branching logic when implementing and writing
separate calculation code for different tray types.

PRO/II User-Added Subroutine User Guide 12-11

 Returned Results (required)
The binary mass transfer calculation subroutine must return a
matrix of binary mass transfer coefficient values in the Results
member of the UasObj data structure. Additionally, it must return a
value for ISOLVE.

ISOLVE Returned solution flag. Use a value for

ISOLVE from Table 3-3 on page 3-4. Always
return ISOLVE= 1 when returning reasonable
values in the Results array. All other return
codes cause PRO/II to terminate calculations
immediately. See “ISOLVE Return Values”
on page 2-18 of Chapter 2.

Results(i,j) The matrix of calculated mass transfer coeffi-

cients. The results should include a value for
every pair of components i and j, where i = 1
to NOC, j = 1 to NOC. The dimensional class
is mole rate (wt-moles / time).Positive values
indicate net mass transfer from the bulk liquid
to the vapor phase. Negative values indicate
net mass transfer from the vapor to the bulk
liquid phase.

The following two data members are not return values, but are
included here to complete the documentation.

SizeR1 First dimension of the Results array. The value

always is NOC.

SizeR2 Second dimension of the Results array. The

value always is NOC. The class_UasObj data
constructor sizes the Results array as
Results(SizeR1,SizeR2).

Sample Binary Mass Transfer Utility

Sample code for a binary mass transfer coefficient utility is avail-
able on the installation disk. The PRO/II installation program
optionally allows installing a sample project for user-added subrou-
tines. The sample code provided by SIMSCI is not intended for
general use in RATEFRAC simulations. The default directory for
installing the sample source code is:

12-12 Binary Mass Transfer Utility February 2009

 ..\USER\UAS\UASF90\
This sub-directory is located in the directory tree of the PRO/II
installation. The sample code for the binary mass transfer coeffi-
cient utility resides in the following files.

MASSMAIN.F90 PRO/II calls this interface routine. It

must be properly registered in the
[UAMASSTR] section of the P2UasReg.ini
file.

MASSCALC.F90 This routine calculates and returns values

for binary mass transfer coefficients. It is
called whenever the context flag is
"CALC". It also sets the ISOLVE return
flag.

HEATREPO.F90 A sample output report routine that writes

results of the user-added calculations. Nor-
mally, this would be called when the con-
text flag is "REPORT".

• The topic“Using a User-Added Modular Utility in PRO/II” on

page 2-14 describes using a complete sample project that
includes code for computing binary mass transfer coefficients.
Chapter 4,“Modular Utility Subroutines” discusses various
aspects of developing a user-added utility for PRO/II. Those
guidelines apply when creating a binary mass transfer coeffi-
cient subroutine

PRO/II User-Added Subroutine User Guide 12-13

12-14 Binary Mass Transfer Utility February 2009
 Chapter 13
Heat Transfer Utility

Overview
PRO/II supports user-added utility subroutines to compute the heat
transfer coefficient (HTC) between the liquid and vapor phases on
each separation stage. Only the RATEFRAC algorithm of the Col-
umn model supports this. A sample project that includes a working
heat transfer subroutine is available. See “Using a User-Added
Modular Utility in PRO/II” on page 14 of chapter 2 of this manual.
The heat transfer coefficient subroutine uses only average proper-
ties of the total bulk fluid on the stage. No liquid or vapor phase
data is available. Binary diffusion coefficients and binary mass
transfer coefficients are passed in by PRO/II. The mass transfer
coefficients already incorporate fluid properties. They also incorpo-
rate the effects of the mechanical configuration of the separation
stage. Consequently, a very limited set of stage, packing, and tray
data is available.
The HTC calculations do not depend upon the mechanical configu-
ration of the stage. This means a single correlation often is adequate
for all stage configurations. Flags for column stage type (packed or
with trays), packing arrangement, packing type, and tray type are
available if the developer chooses to include logical branching in
the code.
PRO/II calls the heat transfer subroutine for each individual stage
during calculations. On each call, the calculation subroutine should
compute the heat transfer coefficient for a single separation stage.
The computed value must return in element Results(1,1) of the data
object passed through the argument list of the call to the subroutine.
Also, the calculation routine must return ISOLVE = 1 for each call.
Any other value causes RATEFRAC to terminate the problem with
a fatal error.

PRO/II User-Added Subroutine User Guide 13-1

Available Heat Transfer Data - Developers
When PRO/II calls a user-added utility, it delivers a pre-defined set
of data for computing the required results. Developers have no con-
trol over the data passed to their subroutines. However, PRO/II
imposes no constraints on how the developer uses the data. After
each call to a user-added utility routine, PRO/II discards all input
data it passes to the user-added subroutine. Only the results returned
from the subroutine are retrieved. PRO/II sends new input data on
each call to the user-added subroutine.
All data exchanged between PRO/II and a user-added utility sub-
routine pass as members of a single data structure. The data struc-
ture passed to a heat transfer subroutine is not compatible with other
types of user-added subroutine. Table 13-1 on page 13-2 is a sum-
mary of the complete data set available to developers of a heat
transfer subroutine. Many of the data members are passed to all the
types of PRO/II utility subroutines. Chapter 4, “Modular Utility
Subroutines” describes those items. Other data members in Table
13-1 have special considerations that are specific to a heat transfer
subroutine. The sections immediately following Table 13-1 describe
these items.

Table 13-1: Heat Transfer Data Members

Member Type Description Keyword
Module Data
UasType C 12 Always "UAHEATTR"
UasPath C 256 Path to DLL directory from
P2UasReg.ini
UasName C 32 Actual name of subroutine
to call, from P2UasReg.ini
UasID C 32 PRO/II ID of this UAS,
from P2UasReg.ini
General Data
ThermoFl I4 Thermodynamic method
set flag (not currently
supported)
DiagnosticFl I4 Diagnostic flag (not
currently supported)

13-2 Heat Transfer Utility February 2009

 Table 13-1: Heat Transfer Data Members
Member Type Description Keyword
UomSystem I4 UOM system flag
1 = PRO/II internal
2 = English
3 = Metric
4 = SI
Context C 12 Context flag
"INPUT" process input
"CROSSCHECK"
"CALCULATION"
"OPCALC" post
convergence "REPORT"
iContext I4 Integer version of context
1 "INPUT" process input
2 "CROSSCHECK”
3 "CALCULATION"
4 "OPCALC" post
convergence
5 "REPORT"
Phase I4 Phase of interest
1 = Vapor
2 = Liquid
CallerID C 12 ID of calling Unit
Operation
Exist L4 Logical .True. if data object
is populated with valid data
Component Data
NOC I4 Total number of
components in problem
CompIndex(i) I4 Internal component
numbers, in input order,
I = 1, NOC
DA2(i,j) DP Binary diffusion DIFFCO
coefficients. i = 1 to NOC,
j = 1 to NOC. The
dimensional units are area/
time.

PRO/II User-Added Subroutine User Guide 13-3

 Table 13-1: Heat Transfer Data Members
Member Type Description Keyword
DA3(i,j) DP Binary mass transfer MASSCO
coeffs.
i = 1 to NOC,
j = 1 to NOC. Dimensional
units are wt-moles/time.
Fluid Data
No fluid data structures are available in heat transfer routines. Only
average bulk fluid properties are available.
DS1(16) DP Average viscosity of fluid HTWIER
on the stage. The
dimensional class is
viscosity.
DS1(17) DP Average density of fluid on AREADC
the stage. The dimensional
class is density.
DS1(18) DP Average heat capacity (Cp) LENGFL
of fluid on the stage. The
dimensional class is Cp.
DS1(19) DP Average thermal IFAREA
conductivity of fluid on the
stage. The dimensional
class is ThermCond.
Stage Data
IS1(1) I4 Column type flag COLTYPE
1 = packing
2 = trays
Packing Data
IS1(2) I4 Packing type (use only with PTYPE
IS1(3), packing
arrangement, below)
IS1(3) I4 Packing arrangement PARRANGE
1 = random
2 = structured
IS1(4) I4 Packed stage number PSECTION
Tray Data
IS1(6) I4 Tray type TTYPE
1 = bubble cap
2 = valve
3 = sieve

13-4 Heat Transfer Utility February 2009

 Table 13-1: Heat Transfer Data Members
Member Type Description Keyword
IS1(8) I4 Stage number of stage with TRAYNO
trays
IS1(10) I4 Number of passes per tray, TPASS
currently always 1
DS1(14) DP Number of trays in section, NTRAY
dimensionless
Output Data to Return
Results(1,1) DP Heat transfer coefficient
return value. The
dimensional units are duty/
temperature.
ISOLVE I4 Solution flag to return
UAS.
0 = no processing took
place
1 = solved (expected value)
2 = errors encountered, but
reasonable results returned
3 = failed, stop calculations
SizeR1 I4 First extent of Results
vector (NOC) (Not a return
value.)
SizeR2 I4 Second extent of Results
vector (NOC) (Not a return
value.)
The MEMBER column lists the exact name of each member. These
names are used for direct access to the data from within the data object;
e.g. IAObj%NOC
The Type column indicates the data type declared for each entry
C nnn Character string containing up to nnn characters
I4 Integer(4) integer scalar value (one 4 byte word)
L4 Logical(4) logical scalar variable (one 4 byte word)
The only possible values are .TRUE. or .FALSE.
DP A REAL(8) double precision floating point scalar value
The Keyword column lists the identifiers used to retrieve the data using
one of the accessor utilities within class_UASOBJ.mod. When
available, this is an alternative to using direct data access via the
"member" name.

PRO/II User-Added Subroutine User Guide 13-5

 Module Data, General Data
These sections of Table 13-1 are generic, since the same data set is
passed to all types of utility routine supported by PRO/II. Refer to
Chapter 4, “Modular Utility Subroutines”.

Component Data
For a heat transfer coefficient subroutine, binary diffusion coeffi-
cients for every pair of components are available in the DA2 array
of the UASOBJ data object.

NOC Number of components in the problem.

CompIndex(i) Internal component numbers in input order. "i" =

1 to NOC.

DA2(i,j) Binary diffusion coefficients for every compo-

nent pair. The dimensional units are area/time. i
= 1 to NOC, j = 1 to NOC.

DA3(i,j) Binary mass transfer coefficients foe every com-

ponent pair. The dimensional units are area/time.
i = 1 to NOC, j = 1 to NOC.

Fluid Data
The data object passed to a heat transfer coefficient subroutine does
not include any fluid data structures. Only a few average bulk fluid
properties are available as individual members.

DS1(16) Average viscosity of fluid on the stage. The dimen-

sional class is viscosity.

DS1(17) Average density of fluid on the stage. The dimen-

sional class is density.

DS1(18) Average heat capacity (Cp) of fluid on the stage. The

dimensional class is Cp.

DS1(19) Average thermal conductivity of fluid on the stage.

The dimensional class is Thermal Conductivity.

13-6 Heat Transfer Utility February 2009

 Stage Data
This section contains general data about the distillation column that
called the subroutine. The only available data value is the flag used
to determine whether the stage has packing or trays.

IS1(1) Column Type Flag. It indicates whether the current

separation stage has trays or packing.
1 = packing - use only packing data with this value
2 = trays - use only tray data with this value
Either packing or tray data is furnished on each tray
call, not both. Use this flag to code branching logic
in the calculation subroutine to use only the appro-
priate data.

Packing Data
This section contains packing data when the current stage is a
packed stage. This data is available only when the Column Type
flag indicates a packed stage (IS1(1) = 1). Do not use this data when
IS1(1) has a different value.
Only the packing types listed in Tables 12-7.9 and 12-7.10 of the
PRO/II Keyword Manual are available for use with an HTC subrou-
tine. This is due to the additional data required by the rate-based
calculations that only the RATEFRAC Column algorithm performs.
The additional data for other packing types are proprietary and not
available.

IS1(1)=1 Column Type Flag that indicates the stage has

packing.

IS1(2) This flag indicates the type of packing on the stage.

Use with the Packing Arrangement flag (below) to
determine if the packing is random or structured. See
the PRO/II Keyword Manual, Table 12-7.9 for avail-
able random packing, and Table 12-7.10 for avail-
able structured packing types.

IS1(3) Packing Arrangement flag. Use only when IS1(1) =

1. Also, use with IS1(2), packing type, above.
IS1(3) = 1 random packing
IS1(3) = 2 structured packing

PRO/II User-Added Subroutine User Guide 13-7

 IS1(4) Stage number of the current (packed) stage.

Note: PRO/II distinguishes between random and structured pack-

ing, and the numbering of the two packing classes overlap. Use
the Packing Arrangement flag, IS1(3), to determine whether the
packing arrangement is random or structured. Then use IS1(2),
the Packing Type Flag, to obtain the actual packing type. Refer to
Table 12-7.9 in the PRO/II Keyword Manual for the numbering of
random packing types. See Table 12-7.10 in the PRO/II Keyword
Manual for the numbering of structured packing types. As an
example, refer to the following comparison.

Data Member Packing Type

Random Pall Structured

Rings (plastic) M250Y

IS1(1) Column Stage Type 1 1

IS1(2) Packing Type I 5 5

IS1(3) Packing Arrangement 1 2

IS1(1) is always 1 when indicating a packed stage. IS1(2) is 5 for

both the random-packed pall rings and the structured M250Y pack-
ing. IS1(3) must be tested to determine the actual packing to which
IS1(2) refers.

13-8 Heat Transfer Utility February 2009

 Tray Data
This section contains flags to determine the tray configuration when
IS1(1) = 2 (the Column Type Flag = 2). Do not attempt to use this
data when IS1(1) has a different value.

IS1(1)=2 Column Type Flag that indicates the stage has trays.

IS1(6) The type of tray on the stage.

1 = bubble cap tray
2 = valve tray
3 = sieve tray

IS1(8) Stage number of the current (tray) stage.

IS1(10) Number of passes per tray. Currently, this always is

1 pass.

Returned Results (required)

The calculation subroutine must return a single value for the overall
heat transfer coefficient. It also must return a value for the solution
flag ISOLVE. Returning ISOLVE = 1 indicates successful comple-
tion of calculations. Any other value causes PRO/II to terminate all
flowsheet calculations with a fatal error.

ISOLVE Returned solution flag. Use a value for

ISOLVE from Table 13-1. Always return
ISOLVE= 1 when returning a reasonable value
in the Results array. All other return codes
cause PRO/II to terminate calculations imme-
diately. Refer to See “ISOLVE Return Values”
on page 18 of chapter 2.

Results(1,1) The overall heat transfer coefficient returned

to PRO/II. The dimensional units are duty/
temperature.A positive value indicates net
heat transfer from the bulk liquid to the vapor
phase. A negative value indicates net heat
transfer from the vapor to the bulk liquid
phase.

PRO/II User-Added Subroutine User Guide 13-9

 Sample Heat Transfer Coefficient Utility
Sample code for a heat transfer coefficient utility is available on the
installation disk. The PRO/II installation program optionally allows
installing a sample project for user-added subroutines. The sample
code solves successfully for selected configurations; however, it is
not intended for general use in PRO/II. The default directory for
installing the sample source code is:
..\USER\UAS\UASF90\
This subdirectory is located in the directory tree of the PRO/II
installation. The sample code for the heat transfer coefficient utility
resides in the following files.

HEATMAIN.F90 PRO/II calls this interface routine. It must

be properly registered in the [UAHEATTR]
section of the P2UasReg.ini file.

HEATCALC.F90 This routine calculates and returns a value

for the heat transfer coefficient. It is called
whenever the context flag is "CALC". It
also sets the ISOLVE return flag.

HEATREPO.F90 A sample output report routine that writes

results of the user-added calculations. Nor-
mally, this would be called when the con-
text flag is "REPORT".

The topic“Using a User-Added Modular Utility in PRO/II” on page

2-14 describes using a complete sample project that includes code
for computing the heat transfer coefficient. Chapter 4, “Modular
Utility Subroutines”, discusses various aspects of developing a
user-added utility for PRO/II. Those guidelines apply when creating
any user-added utility subroutine.

13-10 Heat Transfer Utility February 2009

 Chapter 14
Classic UAS Introduction

PRO/II User-Added Subroutines

The user-added subroutine (UAS) feature of PRO/II allows incor-
poration of custom calculation methods into the standard PRO/II
program via subroutines written in Fortran. The older implementa-
tion, now referred to as “Classic UAS”, still is functional and fully
supported. Features of the classic interface are described in the
remaining chapters of this Guide.
The new modular user-added interface was designed specifically to
address shortcomings of the classic interface. Most future develop-
ment of the user-added capabilities in PRO/II will be accomplished
in the new modular interface. The modular interface is documented
in the earlier chapters of this Guide starting with Chapter 1 “Modu-
lar UAS Introduction”.

Classic User-Added Interface

The calculation methods that may be incorporated with this inter-
face include:
User-Added Thermodynamic Methods
User-Added Transport Property Methods
RATEFRAC Transport Calculation Methods
User-Added Unit Operations (classic and modular)
User-Added Reaction Kinetics
User-Added Pressure-drop methods (in select unit operations)
Equation-based and Index-based user-defined methods for
Refinery Inspection Properties and named Special properties.
For each user-added calculation method, there is a specific method
for interfacing the custom routines with the standard PRO/II simu-

PRO/II User-Added Subroutine User Guide 14-1

 lator. Detailed explanations appear in separate chapters of this
manual.

Note: See Chapter 9 of the PRO/II User Guide for information on

using and customizing classic User-Added Unit Operations
for use in the PROVISION Graphical User Interface.

Software Requirements for PRO/II UAS

Compilers and Linkers
Developers integrate user-added subroutines written in Fortran into
PRO/II by creating a custom version of the dynamic link library
UASLB.DLL. To compile and link user-added subroutines into the cur-
rent PC version of PRO/II, use the following compiler:
Intel Visual Fortran version 10.1 or newer (standard or profes-
sional editions). This compiler is compatible with Net 2003 and
Net 2005 architectures.
Important: The Compaq Visual Fortran compiler no longer is com-
patible. Starting with version 8.2, PRO/II is built on the Net 2003
architecture. This change was required to continue delivering new
product versions on the current and future operating systems from
Microsoft Corporation.
Other legacy compilers, such as Lahey Fortran and MicroSoft Pow-
erStation Fortran, also are no longer compatible with current ver-
sions of PRO/II UAS because those compilers are incompatible
with the Net 2003 architecture.

While the recommended compiler is strongly preferred, other

compilers or languages may be used to create a user DLL. The only
real restrictions are:
The compiler must be based upon and compatible with the Net
2003 architecture from Microsoft Corporation. Other compilers
use different storage architectures that are incompatible with
PRO/II. The only sure way to determine compatibility is to try
them out.
The compiler and linker support Fortran 90 data types, modules,
and subroutine calling conventions.

14-2 Classic UAS Introduction February 2009

Hardware Requirements for PRO/II UAS
PRO/II is built and certified on Microsoft Windows© operating sys-
tems (OS).
Starting with version 8.2, PRO/II is fully compliant with the
Windows Vista©, the preferred operation system.

Windows XP© and Windows 2000© should pose no problems,

but they no longer are available from Microsoft.
Earlier versions of Windows no longer are supported, since they
do not permit the Net 2003 architecture.
The ProVision Graphical User Interface (GUI) does not func-
tion properly on other operating systems, such as Unix.

Adequate dynamic memory is required. Windows Vista© rec-

ommends a minimum of 2 GB but strongly recommends 3 GB
of dynamic memory, which should be adequate to run PRO/II
successfully. PRO/II routinely may use 350 MB or more of
memory.
Hard disks should be no more than about 75% full, and always
should have 2 GB or more of free space to avoid excessive frag-
mentation of the Windows file system.

PRO/II User-Added Subroutine User Guide 14-3

Program Limits
Although PRO/II internally has no fixed limits on the number of
components, the classic user-added interface for PRO/II imposes
certain hard restrictions. The limitations shown in Table 14-1 apply.
Table 14-1: PRO/II UAS Limitations
Calculation/Model Component/Variable
Maximum
Classic User-Added 2500 Components in Flowsheet
Calculations1
Classic User-Added Unit IPARM (250)
Operations RPARM (500)
HEAT (10)
SUPPLE (10000)
User-Added Kinetic Models 50 Components in Flowsheet
IPARM (10)
RPARM (70)
SUPPLE (200)
Modular User-Added Dynamic allocation, no fixed
Calculations limits.
1) Except user-added kinetics

Note: For flow sheets containing more than 2500 components,

contact your SIMSCI representative to obtain a version of
PRO/II User-Added Subroutines with an increased compo-
nent maximum. (This is not required for modular user-
added applications.)
Note: For user-added thermodynamic and transport properties,
the TDATA array (and corresponding UDATA statement) is
limited to 2600 entries.
Note: These limits do not apply to the new modular user-added
subroutines.

14-4 Classic UAS Introduction February 2009

Upgrading Legacy User-Added Subroutines
Starting with version 8.2, PRO/II is based upon the Net 2003 archi-
tecture and no longer is compatible with any earlier versions. All
user-added projects created using PRO/II 8.1 and any earlier ver-
sion must be recompiled and re-built. This must be done using the
new Intel Fortran compiler, version 10.1 or newer, or another com-
piler compatible with the Net 2003 architecture. Follow the direc-
tions in the following section, “Build Procedure for Classic PRO/II
UAS” on page 14-6 to perform the rebuild.

Use of Common Blocks

Note: All newer modular user-added applications use Fortran mod-
ules that provide dynamic data objects to pass all data. No
common blocks are used in these implementations.
If your previous installation of UAS was built on a version earlier
than PRO/II 5.5, please contact your SIMSCI support representative
for information about upgrading your user-added subroutines.
Previous to PRO/II version 5.5, common block definitions were
specified directly in the source code. For example:
COMMON /FACTOR/ TCONVT, TFAC, . . .
Now you need to only specify the name of the INCLUDE file (with
its proper path) that contains the common block of interest. For the
common block /FACTOR/, it suffices to specify:
INCLUDE ‘FACTOR.CMN’
In order to maintain compatibility with the supplied INCLUDE files,
you should ensure that the original common variable names con-
tained in these common blocks have not been modified.
These INCLUDE files are supplied as part of the UAS/PDTS product
in the C:\SIMSCI\PROII82\USER\CMNS directory.
These changes facilitate the creation of DLL versions of user-added
subroutines. These source code modifications are required only
when using a MicroSoft Windows version of PRO/II. User-added
subroutines on other platforms do not require modification.

PRO/II User-Added Subroutine User Guide 14-5

 Replacement Source Code
Important: PRO/II now delivers Intel Visual Fortran solutions and
projects that replace the older (now obsolete) workspaces and
projects used formerly with Compaq Visual Fortran. Table 1-2 on
page 1-11 shows the new solutions and projects on the left with the
corresponding workspaces and projects they replace on the right.

Build Procedure for Classic PRO/II UAS

This manual contains instructions for writing the user-added sub-
routines in Fortran, compatible with PRO/II. It does not contain
extensive tutorial material about the Fortran language or using the
supported compilers.
The procedures described below illustrate the method using the
example subroutines USER42.FOR and U42OUT.FOR. to create a unit
operation in the classic user-added interface.

Note: These instructions assume the User-Added Subroutine

modules are installed in the default directory structure, typ-
ically: C:\SIMSCI\ PROII82\UAS.
In the following discussions, modify the indicated paths if the
modules are installed in a different directory.
The Intel project files are in different directories than the obsolete
Compaq project files. Refer to Table 1-2 on page 1-11.
All supplied source code still resides in the same source directories as
previously. Most of the source code is unchanged, and is utilized by
the new projects from their current locations. Refer to Table 1-2 on
page 1-11.

Building with the Intel Visual Fortran Compiler

Begin by opening the appropriate development tools. The Intel
Visual Fortran Compiler, version 10.1 or newer must be installed in
Visual Studio for Net 2003.
Open Visual Studio for Net 2003.
From the File menu, select Open Solution...
Open the solution file:
\SIMSCI\PROII82\USER\UAS\ EXAMPLES\ IF8\UASLB.SLN, then click
OK.

14-6 Classic UAS Introduction February 2009

 Next, add the user-added Fortran files USER42_IF8.FOR and
U42OUT_IF8.FOR from directory \SIMSCI\PROII82\USER\UAS\ EXAM-
PLES\EXAM1\ into the project file:

In the Solution Explorer, click the “+” box to expand the

UasLb project.
Right click the Source Files folder to open the action menu,
and choose Add Existing Item ... to open the Add Existing Item
dialog.
Navigate to the folder:
\SIMSCI\PROII82\USER\UAS\EXAMPLES\EXAM1\ and add the files
USER42_IF8.FOR and U42OUT_IF8.FOR. (If the files already are in
the project, Visual Studio displays an appropriate message.)

Note: USER42_IF8.FOR and U42OUT_IF8.FOR are modified versions

of USER42.FOR and U42OUT.FOR to allow user-added subrou-
tines compiled with Intel Fortran compiler to write output
to the standard output files provided by PRO/II. For addi-
tional information, please refer to the section ““Source
Code Changes for Intel Fortran:” on page 14-11.
Click the Open button to add the files, exit the dialog, and
update the project file.
Now, everything is ready to build the new dynamic link library:
Ensure the solution configuration is set to Release.
Select the Build UASLB.DLL option from the Build menu.
Intel Visual Fortran builds the dynamic link library UASLB.DLL
in . . . \USER\EXAMPLES\VF6\UASLB\DEBUG or . . . \USER\EXAM-
PLES\VF6\ UASLB\RELEASE depending on the UASLB project set-
tings. To make this new DLL available to PRO/II, you must
copy it to the executable directory where you installed the
product (i.e., \SIMSCI\PROII82\BIN).

Note: Before copying the file, you must close PRO/II.

Make a backup copy of the original DLL by typing:

COPY \SIMSCI\PROII82\BIN\UASLB.DLL
\SIMSCI\PROII82\BIN\UASLB.SAV
Copy the new DLL to the \SIMSCI\PROII82\BIN directory by typ-
ing:
COPY UASLB.DLL \SIMSCI\PROII82\BIN\*

PRO/II User-Added Subroutine User Guide 14-7

 The DLL now is usable by PRO/II.
Now everything is ready to build the new dynamic link library:
Select the Build -> UASLB option from the Build menu.
Intel Visual Fortran builds the dynamic link library UASLB.DLL
in . . . \USER\EXAMPLES\IF8\DEBUG\ or
. . . \USER\EXAMPLES\ IF8\RELEASE\, depending on the UASLB
project settings. To make this new DLL available to PRO/II,
copy it to the executable directory where you installed the
product (i.e., \SIMCI\PROII82\BIN).

Note: Before copying the file, you must close PRO/II if it is open,

Make a backup copy of the original DLL by typing:

COPY \SIMSCI\PROII82\BIN\UASLB.DLL \SIM-
SCI\ PROII82\BIN\UASLB.SAV
Copy the new DLL to the \SIMSCI\PROII82\BIN directory by
typing:
COPY UASLB.DLL \SIMSCI\PROII82\BIN
The DLL now is usable by PRO/II.

Customizing a UAS Data Entry Window

To create a customized PRO/II data entry window to be used for a
specific user-added calculation subroutine, two ASCII files must be
created in the directory specified by the UserConfigDir= entry in the
PROII.INI file. These two files are named UASLIST.INI and USERXX.INI,
and are described in Chapter 9 of the PRO/II User’s Guide.

14-8 Classic UAS Introduction February 2009

Fortran Coding Standards
All classic user-added subroutines should be written in ANSI stan-
dard Fortran 77 or Fortran 90 to insure compatibility with PRO/II.

Note: Because the interface COMMON blocks are written in Fortran

77, any Fortran file that INCLUDEs them should be written
using fixed-format source. The COMMON blocks are incom-
patible with free-format source code. To use common
blocks in free-format source, use the compiler directive
!DEC$ NOFREEFORM before including the common and use
!DEC$ FREEFORM after the include statements. For example,
!free form code here
!DEC$ NOFREEFORM
INCLUDE ‘FACTOR.CMN’
!DEC$ FREEOFRM
!free form code here

Information flow between user-added subroutines and PRO/II is

accomplished through:
Subroutine argument lists.
Interface subroutines.
Common storage blocks.
Chapters 16 through 22 provide specific details regarding classic
user-added subroutines for various functions. In each case, addition
of a user-added calculation subroutine involves replacement of a
dummy subroutine already present in PRO/II. Thus, the user-writ-
ten subroutine must be given a name and an argument list identical
to those of the dummy subroutine.
Interface subroutines that perform various functions are described
in Chapter 15, Interfacing Software. These subroutines may be
called by the user-added subroutines to transfer information to and
from the PRO/II storage areas.
User-written subroutines may also communicate through certain
common storage locations (also described in Chapter 15). Retrieval
of information from the common storage blocks for component
properties, thermodynamic data, and conversion factors is allowed.
In addition, a special common storage area has been included in the
PRO/II program for user-added thermodynamic subroutines.

Note: There are no specific size limitations regarding user-added

subroutines.

PRO/II User-Added Subroutine User Guide 14-9

Fortran Programming Guidelines
The following guidelines should be followed when writing user-
added subroutines:
1. Storage variables should always be initialized since many oper-
ating systems do not perform this function.
2. As appropriate, user-added subroutines should test for calcula-
tion error conditions such as zero divides, exponent overflows,
etc.
3. The PRO/II interface subroutines all return error flags that
should be tested by the user-added subroutines. Appropriate
action should be taken when an error code is returned.
4. Common storage information in the PRO/II common blocks
/XPROPX/, /CUDATA/, /OUTFAC/, and /FACTOR/ must not be altered.
5. Care must be exercised to not alter any variables in the user-
added common block, /UTHERX/, except those allowed items
described in Chapter 15.
6. Use the FIGETU routine to obtain correct Fortran unit numbers
for special sequential input or output files (see Chapter 15,
Interfacing Software).
7. Dimensional units must be considered when performing calcu-
lations. (All stored data in the PRO/II system are in input
dimensional units except critical properties as noted in the dis-
cussion of /XPROPX/.)
8. Good Fortran coding practices should be observed, particularly
for user-added subroutines to be used repetitively such as ther-
modynamic functions or unit operations to be used in calcula-
tion loops.
9. All loops within user-added subroutines should have pre-
defined limits. Avoid open-ended DO loops.

14-10 Classic UAS Introduction February 2009

Source Code Changes for Intel Fortran:
PRO/II 8.3 is built with the Intel Fortran compiler. Fortran unit
numbers from a Compaq-compiled library cannot be used by the
executable libraries created by the Intel compiler. For example,
assume a file is opened by an Intel Fortran library using Logical
File unit 10. Then, that file unit number is passed to a subroutine
compiled using the Compaq Fortran compiler. A READ or WRITE
statement using that file unit will fail in the Compaq-compiled
library because the file unit numbers do not match. This is due to
architectural changes in the “.NET” platform (used by the Intel
compiler and PRO/II).
There are at least two cases where PRO/II opens a file and passes
the associated file unit number to a user-added subroutine.
PDTS application: the NFOUT argument returned from the
PAOPEN() subroutine
User-Added Subroutine: IDATA(6) of the USERnn unit operation
subroutine.
In both cases, PRO/II calls the intrinsic Fortran OPEN function, then
passes the unit number a user-added subroutine. Applications built
using the Intel Fortran compiler cannot directly use this Fortran unit
number in a WRITE statement. Instead, the utility subroutine PAWRITE
has been provided to allow your application to write output to the
file. The following code fragments illustrate the required changes:
Original PDTS example that may fail:
CHARACTER(LEN=16) :: NAME
INTEGER(4) :: NFOUT
. . .
CALL PAOPEN( NAME, " ", NFOUT, IRCODE )
1001 FORMAT( A )
WRITE( NFOUT, 1001 ) “This Write FAILS”

PDTS example modified for Intel Fortran inter-operation with

Compaq Fortran:
CHARACTER(LEN=16) :: NAME
INTEGER(4) :: NFOUT
CHARACTER(LEN=78) :: cLine
. . .
1001 FORMAT( A )
. . .
CALL PAOPEN (NAME, " ", NFOUT, IRCODE)

PRO/II User-Added Subroutine User Guide 14-11

 cLine = "This fixes the problem"
CALL PAWRITE( NFOUT, cLine )

Original UAS example that may fail:

SUBROUTINE USER42( IPARM, RPARM, SUPPLE,
& HEAT, IDATA, ISOLVE, ISTOP )
. . .
INTEGER(4), INTENT(IN) :: IDATA( 30 )
INTEGER(4) :: NFOUT
1001 FORMAT( A )
. . .
IOUT = IDATA(6)
WRITE( NFOUT, 1001 ) “This may FAIL”

A UAS example modified for Intel Fortran inter-operation with

Compaq Fortran:
SUBROUTINE USER42( IPARM, RPARM, SUPPLE,
& HEAT, IDATA, ISOLVE, ISTOP )
. . .
INTEGER(4), INTENT(IN) :: IDATA( 30 )
CHARACTER(LEN=78) :: cLine
. . .
cLine = "This fixes the problem"
CALL PAWRITE( NFOUT, cLine )

Note: To open a file not used by PRO/II, call subroutine FIGETU

to obtain a Fortran unit number from PRO/II. Then call the
Fortran OPEN() function directly from the user-added sub-
routine. This approach eliminates the need for any code
changes to the READ or WRITE statements. The reason is that
the OPEN, READ, and WRITE calls are executed under the
same architecture, so the discontinuities discussed above
do not apply.

14-12 Classic UAS Introduction February 2009

 Chapter 15
Interfacing Software

This chapter discusses the facilities available for communication of

data between the PRO/II program and user-added subroutines.Link-
age is accomplished through:
Subroutine argument lists.
Interface subroutines, provided in the PRO/II program.
Common storage blocks in PRO/II available to user-added sub-
routines.
Table 15-1 provides access to documentation of the interface sub-
routines in PRO/II. These subroutines may be called as needed and
are fully described later in this chapter. The callable double preci-
sion interface routines are suitable for use in both classic and modu-
lar user-added subroutines. The single precision interfaces should
not be used by modular user-added subroutines.
Similarly, Table 15-2 highlights the common storage blocks avail-
able to classic user-added subroutines. Complete details are given
later in this chapter. These common blocks are not initialized for
calls to modular user-added subroutines, and therefore cannot be
used in modular user-added subroutines. User-defined data files are
also discussed in this chapter.

PRO/II User-Added Subroutine User Guide 15-1

 Table 15-1: Interface Subroutines
Name Description See page...
Output and Reporting 15-7
HEAD Heads and numbers output page 15-7
UAERR Reports an error, warning, or message to 15-7
PRO/II. Also formats and writes a
message.
PAWRITE PDTS subroutine that writes a single line 15-9
of pre-formatted text to any logical file
unit.
FIGETU Retrieves a logical file unit that does not 15-48
conflict with other PRO/II file usage.
Streams and Stream Data 15-10
URXINF Retrieves 12-character stream and unit IDs 15-12
and 40-character names.
GETBLNAM Returns the name of the blend from a 15-13
stream-containing assay components.
DURXST Reads or stores data from a double 15-14
precision classic stream vector
URXSTR Single precision version of DURXST 15-14
DURXSTR Retrieves and stores double precision 15-15
stream data. Similar to DURXST.
USTHER Sets the current thermodynamic method to
that of a given PRO/II stream. Resets 20-5
component properties in common XPROPY.
DUSTPRP Retrieves a double precision property from 20-6
a PRO/II stream, one scalar per call.
USTPRP Single precision version of DUSTPRP. 20-6

DUSTRIP Retrieves any scalar Refinery Inspection 20-7

Property from a PRO/II stream.
USTRIP Single precision version of DUSTRIP. 20-7

DUCURVE Computes pseudo-component properties

for current thermodynamic methods set. 20-15
(2 data points required).
UCURVE Single precision version of UCURVE. 20-15
DUBULK Double precision analog of UCURVE, 20-19
when only a single data point is available.

15-2 UAS Interfaces February 2009

 Table 15-1: Interface Subroutines
Name Description See page...
UBULK Single precision version of DUBULK. 20-19
DUDIST Generates a 21 point distillation cut-point 20-9
array. Double precision.
UDIST Single precision version of UDIST. 20-9
DUPSEUC Retrieves start and end components, and all
double precision cut-point temperatures 20-4
from a blend.
UPSEUC Single precision version of DUPSEUC. 20-4
DURATE Retrieves double precision pseudo-
component flow rates from TBP 20-12
distillation data.
URATE Single precision version of DURATE. 20-12
UPETMD Estimates missing component fixed
properties. Updates /XPROPY/ data. 20-22
Single precision.
Calculation Interfaces 15-16
DFLASH Double precision interface for flash
calculations. Calls DU2FLSH for VLE and 15-16
DU3FLSH for VLLE thermodynamics.
XFLASH Single precision interface for flash
calculations. Calls UFLSH for VLE and 15-16
U3FLSH for VLLE thermodynamics.
DU2FLSH Perform 2-phase (VLE) flashes (no solids) 15-19
UFLSH Single Precision version of DU2FLSH. 15-22
DU3FLSH Perform rigorous 3-phase flash 15-25
calculations
U3FLSH Single Precision version of DU3FLSH. 15-27
DTTPROP Computes double precision transport and
thermodynamic properties of a standard 15-29
user stream.
TTPROP Single precision version of DTTPROP. 15-29
DUHS Compute density, enthalpy, heat capacity, 15-31
or entropy for a single stream phase.
UHS Compute density, enthalpy, heat capacity, 15-31
or entropy for stream.
DUH2OP Compute double precision water properties 15-33

PRO/II User-Added Subroutine User Guide 15-3

 Table 15-1: Interface Subroutines
Name Description See page...
UH2OP Single precision version of DUH2OP. 15-33
DUDENS Compute double precision wet and dry 15-35
flowing volumes for streams.
UDENS Single precision version of DUDENS. 15-35
KCOMPU Returns K-values for use in user flash 15-37
DHCOMPU Returns enthalpies in double precision 15-39
standard user streams for use in user flash.
HCOMPU Single precision version of DHCOMPU. 15-39
Solids Handling 21-1
USOLSTR Retrieves and stores streams containing 21-3
solids.
UFLSHSOL Performs vapor/liquid flash for streams
with solids. May be used in place of 21-5
UFLSH and U3FLSH
USOLDENS Calculates the solid stream density 21-8
UHSSOLID Calculates solid molar heat capacity, molar 21-9
enthalpy, and molar entropy
USOLCDAT Retrieves pure solid component heat of
fusion, normal melting point temperature, 21-10
triple point temperature, or triple point
pressure.
GETPSDC Retrieves the number of Particle Size 21-11
Distribution (PSD) cuts for any single
component.
USOLPSD Retrieves or stores the Particle Size 21-11
Distribution data
UPDSCPY Copies all Particle Size Distribution data 21-12
Component Identification and Data 15-40
COINUM Retrieves a component’s internal sequence
number - given the input (print)-sequence 15-43
number.
COPNUM Retrieves a component’s input (print)-
sequence number - given the internal 15-42
sequence number.
GETNCOMP Retrieves various component counts (for 21-2
solids problems).

15-4 UAS Interfaces February 2009

 Table 15-1: Interface Subroutines
Name Description See page...
UDEFNC Retrieves a component’s input (print) or
internal sequence number - given the ID 20-3
and Library number.
CONAME Retrieves the ID of a component - given
the internal sequence number of the 15-43
component.
UCOPRP Retrieve many component properties,
including most refinery inspection 15-44
properties.
DZMolWt Retrieve or store a double precision array 15-46
of component molecular weights.
ZMW2 Single precision version of DZMolWt 15-46
DZSg60 Retrieve or store a double precision array 15-47
of component specific gravities at 60F.
ZSG602 Single precision version of DZSg60. 15-47

Note: Support for free-form keyword input data for user-added

methods is provided in the PRO/II standard input proce-
dures. The Graphical User Interface supports them as well.
For example,
from the PROVISION Input menu, select Thermodynamic data to
open the SIMSCI - Thermodynamic Data dialog box.
Scroll the Category list box and select User-added methods.
The available methods will populate the Primary Methods list
box.

PRO/II User-Added Subroutine User Guide 15-5

 Table 15-2: Interface Common Blocks
Name Description page...
Common Blocks
/PMXUSR/ Contains integer parameter MAXCN, which
is required to dimension arrays in other 15-49
common blocks.

/DFACTOR/ Double precision conversion factors for 15-50

dimensional units.
/FACTOR/ Single precision version of DFACTOR. 15-50

/DOUTFAC Double precision output conversion factors 15-52

and dimensions, component names.
/OUTFAC/ Single precision version of DUOTFAC. 15-52

/DUTHERX/ Transfers double-precision data between 15-55

user thermodynamic functions and PRO/II
/UTHERX/ Transfers double-precision data between 15-55
user thermodynamic functions and PRO/II

/DXPROPX/ Pure component data - invariant 15-56

/XPROPX/ Single precision version of /DXPROPX/ - 15-56
invariant.

/XPROPY/ Single precision pure component data - 20-23

may change for each thermodynamic
methods set.

/DCUDATA/ Double precision storage, transfers user- 15-58

defined input data between PRO/II and user
thermodynamic routines (UKHSx)/
/CUDATA/ Single precision version of DCUDATA. 15-58

/CSPEC/ Single precision storage of isentropic flash 15-58

specification.
Note: Storage of user-calculated data is permissible only in common
blocks /DCUDATA/, /CUDATA/, /UTHERX/, and /XPROPY/.

15-6 UAS Interfaces February 2009

Output and Reporting Routines
HEAD
This subroutine may be called by user-added output subroutines to
generate a new page in the standard PRO/II Output Report file.
Actions include page ejection, automatic numbering, and heading
of page with information from the problem TITLE statement.
Calling sequence:
CALL HEAD

UAERR
Purpose: Register an error, warning, or message in the PRO/II error
subsystem and write a user-defined message to a standard output
file.
Calling sequence:
UAERR( cELevel, IUNO, MESSAGE )
Where:

cELevel Required input single character that acts as an option for

the error level to register. Allowed values include:
“E” Severe error, calculations failed.
“W” Warning, calculations hampered, results may be
suspect.
“M” Message, no error, calculations succeeded,
information is merely advisory.
IUNO Required scalar input. The internal order number of a unit
operation. This may be a UAUOP that calls UAERR; or a
unit operation that calls a user-added utility that calls
UAERR. A value of zero omits IUNO from the message.
MESSAGE Required character input. This is the text of the error
message to display or print. It may contain up to 200
characters of text.

The error level indicates the severity of the reported problem. In

most cases, a user-added subroutine is either a unit operation or a
utility called from a unit operation. In either case, the error behaves
as if it was generated by a unit operation.

PRO/II User-Added Subroutine User Guide 15-7

 An Error terminates flowsheet calculations when registered outside
a flowsheet recycle loop. When registered inside a recycle loop, an
Error fails the current loop iteration, but may allow additional itera-
tions of the loop.
A Warning does not halt calculations, but informs a user that a prob-
lem exists. A Message conveys only information. For example,
assume a user-added subroutine allows the user to enter a calcula-
tion option, but the user neglects to supply it. A message would be
appropriate to inform the user that the “default” method is being
used. If no default is allowed, then a Warning or an Error may be
more appropriate.
Argument IUNO is an integer that identifies the parent unit operation
from where the error occurred. For a user-added unit operation, it is
available in member %UasIdNo of the unit operation data object. For
a user-added utility, IUNO is available in member %UasIdNo of the
utility data object.
Argument MESSAGE is the text of the error. It may be a quoted literal
string or a CHARACTER string variable. It does not need to include
the error level (error, warning, etc.) or a unit operation identifier.
The other two arguments
Consider the following code fragment:
INTEGER(4) :: IUNO
CHARACTER(LEN=78) :: Message
IUNO = 0 ! Unit operation is unknown
IF( INTdata( 1 ) .LE. 0 ) THEN
Message = “Default method used when“ &
// “INTdata( 1 ) = 0”
CALL UAERR( “M”, IUNO, Message )
END IF
The call to UAERR generates the following message:
** MESSAGE ** Default method used when
INTData( 1 ) = 0

15-8 UAS Interfaces February 2009

 PAWRITE
This routine writes a single record of pre-formatted text to any Log-
ical File Unit (LFU) open for writing formatted, sequential informa-
tion. To use it, create a string variable and format it as desired.
Obtain the Logical File (LFU) of the target file. Call PAWRITE,
passing the LFU and string variable as arguments of the call.
Calling sequence:
PAWRITE( LFU, cLine )
where:

LFU input Integer Logical File unit of a sequential formatted

file with WRITE permission.
cLine Input character string or variable containing a single line
of formatted text or data.

Example:
The sample code snippet demonstrates declaring the character vari-
able, populating it with text and numerical values, and calling
PAWRITE. It assumes the file is open and the logical file unit is avail-
able in variable LFU.
. . .
INTEGER(4) :: LFU, Ival
REAL(8) :: Rval
CHARACTER(LEN=133) :: cLine
. . .
Rval = 23.4
Ival = 3
cLIne = “The value of RVAL( ) is :”
WRITE( cline(19,21), “( I3 )” ) Ival
WRITE( cLine(29:39), “(F9.4)” ) Rval
CALL PAWRITE( LFU, TRIM(cLine) )
The single line of output would be:
The value of RVAL( 3) is : 23.4000

PRO/II User-Added Subroutine User Guide 15-9

Stream Data Interfaces
Storage of stream data no longer is limited to streams declared as
products from the user-written subroutine. Stream data may be
stored in any stream in a simulation.
PRO/II provides many subroutines for transferring stream data to
and from user-added subroutines. The subroutines usually transfer
data in variables or arrays in the subroutine call list. Most of the
interface routines were constructed with specific purposes in mind.
This has resulted in several different conventions being used to
arrange data transferred in arrays. Depending upon the specific
interface routine, the array data to be transferred must be arranged
in one of several forms. Briefly, these forms include:

User Stream Vector

The user stream vector is a very old special purpose array hav-
ing a definite but limited structure. Stream data are transmitted
through a variably dimensioned user stream vector as follows:

Vector
Position Description
1 Total molar flow in input units of rate
2 Temperature in input units of temperature
3 Pressure in input units of pressure
4 Total enthalpy in 103 input energy units per time
5 Total liquid mole fraction including liquid water
6 Liquid water mole fraction (dimensionless)
7 Compressibility factor (Z) computed from the K-
value or enthalpy method, enthalpy having
preference (dimensionless)
8-10 Reserved for PRO/II
11-NOC Individual component molar flow rates in PRO/II
internal component order and input dimensional
units of molar flow rate. (NOC = number of
components)

The dimensional units for data in the stream vector correspond

to those chosen for problem input. The compressibility factor is
only defined for single-phase streams and is calculated from the
K-value or enthalpy method, not from the density method. Sub-
routine UHS is used for the calculation of Z from the density

15-10 UAS Interfaces February 2009

 method(s). For density calculations, use subroutine UDENS.
Component rates are stored in PRO/II internal order, so use
function COPNUM when it is desired to manipulate the values in
print order (used for data input and writing output reports).
Create a user stream vector in a user-added subroutine by
dimensioning it to the actual number of components plus 10
(NOC+10). In routines where NOC is not directly available,
include common block PMXUSR. This provides access to vari-
able MAXCN, which is the maximum allowed number of compo-
nents supported in classic user-added subroutines. An example
of declaring a double precision user stream vector named
DStrVec and a single precision user-stream vector named StrVec:

INCLUDE PMXUSR.CMN
REAL(8) :: DStrVec( MAXCN + 10 )
REAL(4) :: StrVec( MAXCN + 10 )

Internal Data Array

These arrays typically transfer pure component data, one value
per component. Data values are arranged in internal PRO/II
component order. Usually, the transferred values are dimension-
less, or use internal PRO/II dimensional units. An example of
declaring a single and a double precision internal data array:
INCLUDE PMXUSR.CMN
REAL(8) :: DIntArray( MAXCN )
REAL(4) :: SIntArray( MAXCN )

External Data Array

These arrays typically transfer pure component data, one value
per component. However, data values are transferred in compo-
nent print order (i.e., the order used for data input and report
writing). The transferred values are dimensionless, or use
dimensional units used for data input. An example of declaring
a single and a double precision internal data array:
INCLUDE PMXUSR.CMN
REAL(8) :: DExtArray( MAXCN )
REAL(4) :: SExtArray( MAXCN )

The following chapter sections describe the stream data interface

routines, many of which use these array constructs.

PRO/II User-Added Subroutine User Guide 15-11

 URXINF
This subroutine allows the user to access a 12-character unit ID and
a 40-character descriptive name. These two items are available for
the user-added unit operation, a specified feed stream, or a specified
product stream.
Calling sequence:
CALL URXINF( CTYPE,INDX, CID, CNAME, IERR )
Where:

CTYPE Input character string indicating request.

Valid entries are:
‘UNIT’ Return unit ID and name
‘FEED’ Return feed stream ID and name for feed INDX
‘PROD’ Return product stream ID and name for product INDX
INDX Input integer index of feed or product for which ID and
NAME are needed. No significance if unit ID and name
requested.
CID Output, the 12-character unit/stream ID
CNAME Output, up to 40-character unit/stream name
IERR Output integer flag. Non-zero value indicates error has
occurred.

15-12 UAS Interfaces February 2009

 GETBLNAM
This subroutine retrieves the name of the blend used by the speci-
fied stream for characterizing assay components.
Calling sequence:
CALL GETBLNAM( cSID, cBLName, iBLType, IErrOut)
Where:
cSID Input, 12-character identifier of the stream of interest. The
stream should contain assay components.
cBLName Returns the 12-character name of the blend.
iBLType A returned flag indicating whether or not the stream is
included in the named blend.
1 cBLName is the name of a BLEND that includes the
stream petroleum components.
2 XBLEND was applied to this stream to exclude it from
the blend named by cBLName.
iErrOut An integer that returns the error status code. The returned
values may be:
0 Success, returned results are valid.
1 Failure, stream indicated by cSID could not be found.
2 Failure, no blend name.

PRO/II User-Added Subroutine User Guide 15-13

 DURXST double precision
URXSTR single precision
Stream data may be retrieved and stored with these subroutines.
Usage (double precision):
CALL DURXST( cSID, DStrVec, IOTYPE, IERR )
Usage (single precision):
CALL URXSTR( cSID, SStrVec, IOTYPE, IERR )
Where:

cSID Stream identifier as described in the problem input (up to

12 alphanumeric characters, designated as a character
variable).
DStrVec Double precision user stream vector used by DURXST
SStrVec Single precision user stream vector used by URXSTR
Contains data to be stored or retrieved for stream CID.
See “User Stream Vector” on page 15-10
IOTYPE Function to perform:
1 Retrieve stream data.
2 Store stream data (only allowed for streams
defined as products).
IERR Error flag:
0 No errors
1 IOTYPE is not 1 or 2.
2 Stream CID is not found.
3 Stream CID is not a declared product and storage
has been requested.
4 Attempt to store a stream with either a negative
flow rate, a temperature, or pressure out of
bounds, or a negative component molar flow rate.
5 Attempt to retrieve data for a stream not yet
calculated by PRO/II.

The error flag always should be checked after calling this routine.
Stream flow is computed by summing component mole rates in
STREAM(10+1) through StrVec(10+NOC). When storing data, total
stream rate in StrVec(1) is required. When the summation of compo-
nent rates differs from the value supplied in StrVec(1) by a relative
error greater than 1.0e-6, an error message is generated, the stream
rate specified in StrVec(1) is stored, and the component rates in
StrVec(11) to StrVec(NOC+1) are normalized so they sum to the rate
specified in StrVec(1).

15-14 UAS Interfaces February 2009

 In all cases however, a negative value for rate in DStrVec(1) or
SStrVec(1), or in any element from (11) through (10+NOC), causes a
fatal error. Values of zero do not generate an error.
The DStrVec (or SStrVec) array contains data only for molecular
weight components. It does not differentiate between molecular
weight solid and fluid compositions. This subroutine ignores non-
molecular weight solids. See Chapter 21, UAS Solid Components,
for alternative routines such as USOLSTR that handle solids.

DURXSTR double precision

Calling sequence:
CALL DURXST( cSID, DStrVec, IOTYPE, IERR )
This is a special-purpose routine that still is supported only to main-
tain compatibility with some special applications. Usage generally
is discouraged. It serves a purpose similar to DURXST and URXSTR,
with the following differences. When storing data:
Storage fails when the rate in DStrVec(1) is zero or negative.
Rate, temperature, pressure, and enthalpy values passed in
DStrVec(1) to DStrVec(4) use PRO/II internal dimensional units,
not input dimensional units.
Rates kg-moles/second
Temperature Kelvins
Pressures kilo-Pascals
Enthalpies kilo-Joules/second
Component rates are not summed or tested to sum to
DStrVec(1). This allows the possibility of inconsistent data.

Wherever possible, use of this routine should be replaced by using

DURXST.

cSID Stream identifier as defined in the problem input.

DStrVec Double precision user stream vector contains data to be
stored or retrieved for stream cSid.
See “User Stream Vector” on page 15-10
IOTYPE Function to perform:
1 Retrieve stream data.
2 Store stream data.
IERR Error flag as defined above for URXSTR:
0 No errors
All other values indicate an error condition.

PRO/II User-Added Subroutine User Guide 15-15

Flash Calculation Interfaces
DFLASH double precision
XFLASH single precision
Both of these interface routines may be called to perform either
VLE or VLLE flash calculations. DFLASH and XFLASH inspect the
thermodynamic method set to determine the correct type of flash to
perform. Using them removes the requirement of knowing whether
or not the active thermodynamic METHOD set supports rigorous two
liquid phase equilibria.
Call these routines from a legacy user-added unit operation.
DFLASH and XFLASH cannot interrogate the thermodynamic
METHOD set when called from other types of user-added subrou-
tines.
DFLASH and XFLASH use the (first) thermodynamic method set
assigned to the user-added unit operation that calls to them.
(Legacy user-added unit operations typically have only one
thermodynamic method set assigned to them.)
The following table illustrates the choice of flash calculation rou-
tine based upon the thermodynamic METHOD set.
Table 15-3: Calculation Routines Used by DFLASH and XFLASH
Calculation Routine Used For
Interface Routine
VLLE Thermo VLE Thermo
DFLASH calls DU3FLSH DU2FLSH
XFLASH calls U3FLSH UFLSH

DFLASH is a newer implementation and has an enhanced argu-

ment list. In particular, the argument DatValIn eliminates the
need to use variable SISENV in common block CUSPEC.CMN
when performing isentropic flashes.
The argument list of XFLASH.remains unchanged to maintain
backward compatibility. It still uses variable SISENV in common
block CUSPEC.CMN when performing isentropic flashes.
The foregoing differences in the argument lists notwithstand-
ing, DFLASH and XFLASH use identical logic to interrogate the
thermodynamic METHOD set and to choose either a VLE or a
VLLE flash.

15-16 UAS Interfaces February 2009

 Usage (double precision):
CALL DFLASH( STRMIN, ITYPE, DatValIn, VAPOUT, &
XL1OUT, XL2OUT, XK1VAL, XK2VAL, &
IFTYPE, IERR )
Usage (single precision):
CALL XFLASH( STRM, VAPOUT, XL1OUT, XL2OUT, &
XK1VAL, XK2VAL, ITYPE, IFTYPE, IERR )
Where:

STRMIN Input STRMIN is a double precision and STRM is a single

or precision standard user stream vector containing
data for the stream to flash. See “User Stream
STRM
Vector” on page 15-10
ITYPE Input integer specifies the calculation type:
1 or 101 Isothermal flash (T defined, P defined)
2 or 102 Adiabatic flash (T defined, P calculated)
3 or 103 Adiabatic flash (P defined, T calculated)
4 or 104 Dew point (T defined, P calculated)
5 or 105 Dew point (P defined, T calculated)
6 or 106 Bubble point (T defined, P calculated)
7 or 107 Bubble point (P defined, T calculated)
8 or 108 Isentropic (T defined, P calculated)
9 or 109 Isentropic (P defined, T calculated)
10 or 110 Water dew point (T defined, P calculated)
11 or 111 Water dew point (P defined, T calculated)
Note: 1xx indicates use K-values input in argument
XKValues for the flash type specified by xx.
DatValIn Input a double precision scalar value of total stream
(DFLASH entropy. Required and used only with isentropic flashes.
only) Refer to ”Isentropic Flash Example 1:”, pg 15-21,
below. Supply a value using dimensional units of
entropy used for input data. Not available in XFLASH;
use SYSENV instead (see ”Isentropic Flash Example
2:”, pg 15-24).
VAPOut Output standard user stream vector that returns the vapor
product mole flow rates from the flash (in array
elements 11-NOC+10). See “User Stream Vector” on
page 15-10. Double precision array for DFLASH, single
precision array for XFLASH.
XL1Out Output standard user stream vector that returns the
primary (first or light or hydrocarbon) liquid phase
product mole flow rates from the flash. Double precision
array for DFLASH, single precision array for XFLASH.

PRO/II User-Added Subroutine User Guide 15-17

 XL2Out Output standard user stream vector containing any
second liquid phase mole rates. (When water
DECANT=ON, this vector contains the decanted
water). Double precision array for DFLASH, single
precision array for XFLASH.
XK1Val Output double precision array of returned K-values
representing the equilibrium between the vapor and
primary (light or hydrocarbon) liquid phases
(dimensioned to NOC or greater).
XK2Val Output array of returned K-values representing the
equilibrium between the two liquid phases (dimensioned
to NOC or greater). Double precision array for DFLASH,
single precision array for XFLASH.
IFTYPE Output integer flag indicating type of flash performed.
1 = VLE flash (with or without DECANT)
2 = VLLE flash
IERR The returned integer error flag:
0 No errors
1 Flash convergence failure
2 ITYPE invalid, not in range 1-7
3 The flow rate in SStVecIn( 1 ) is zero or negative
For IERR = 2 or 3, no calculations will be
performed.

Note: All result values return in problem input dimensional units.

Also, the thermodynamic METHOD set used by TTPROP must
declare methods for computing transport properties.
Note: To request vapor pressures when assay fractions are
present, a KVALUE= LIBRARY method (need not be used)
should be used to insure setup of vapor pressure data for
PETROLEUM components.

15-18 UAS Interfaces February 2009

 DU2FLSH double precision
Subroutine DU2FLSH performs a two phase flash of a process stream.
It is an enhanced double precision version of U2FLSH. This flash is a
vapor/liquid (VLE) two-phase flash with an optional pure water
phase (DECANT=ON) as a non-rigorous second liquid phase. Calling
sequence:

CALL DU2FLSH( DStVecIn, ITYPE, DatValIn, &

VapOut, XL1Out, XL2Out, &
XKValues, IERR )
Where:

DStVecIn Input double precision standard user stream vector

containing data for the stream to flash. See “User
Stream Vector” on page 15-10
ITYPE Input integer specifies the calculation type:
1 or 101 Isothermal flash (T defined, P defined)
2 or 102 Adiabatic flash (T defined, P calculated)
3 or 103 Adiabatic flash (P defined, T calculated)
4 or 104 Dew point (T defined, P calculated)
5 or 105 Dew point (P defined, T calculated)
6 or 106 Bubble point (T defined, P calculated)
7 or 107 Bubble point (P defined, T calculated)
8 or 108 Isentropic (T defined, P calculated)
9 or 109 Isentropic (P defined, T calculated)
10 or 110 Water dew point (T defined, P calculated)
11 or 111 Water dew point (P defined, T calculated)
Note: 1xx indicates use K-values input in argument
XKValues for the flash type specified by xx.
DatValIn Input a double precision scalar value of total stream
entropy. Required and used only with isentropic
flashes. Refer to ”Isentropic Flash Example 1:”, pg
15-21, below. Supply a value using dimensional units
of entropy used for input data.
VapOut Output double precision standard user stream vector
that returns the vapor product mole flow rates from
the flash (in array elements 11-NOC+10). See “User
Stream Vector” on page 15-10
XL1Out Output double precision standard user stream vector
that returns the primary (first or light or hydrocarbon)
liquid phase product mole flow rates from the flash.

PRO/II User-Added Subroutine User Guide 15-19

 XL2Out Output double precision standard user stream vector
containing any second liquid phase mole rates. (When
water DECANT=ON, this vector contains the
decanted water).
XKValues A local double precision array that returns equilibrium
K-values for each component from the calculations in
PRO/II internal order. It is dimensioned to NOC or
larger. It also is used to supply available input K-
values to use in a flash when the ITYPE variable has a
value between 101 and 111.
IERR The error flag:
0 No errors
1 Flash convergence failure
2 ITYPE invalid (not in range 1-11or 101-111)
3 The flow rate of DStVecIn(1) is zero
For IERR = 2 or 3, no calculations are performed.

Note: IERR should be checked after each calculation and appropri-

ate action taken.
Flashes that this subroutine is capable of performing include:
Isothermal flash (temperature and pressure specified)
Adiabatic flash (temperature specified, pressure calculated)
Adiabatic flash (temperature calculated, pressure specified)
Dew point (temperature specified, pressure calculated)
Dew point (temperature calculated, pressure specified)
Bubble point (temperature specified, pressure calculated)
Bubble point (temperature calculated, pressure specified)
Isentropic flash (temperature specified, pressure calculated)
Isentropic flash (temperature calculated, pressure specified)
Water dew point (temperature specified, pressure calculated)
Water dew point (temperature calculated, pressure specified).
Note: While the argument lists of subroutines DU2FLSH and UFLSH
are different, their calculations functionally are the same. The
main difference is that DU2FLSH includes argument DatValIn to
supply data for an isentropic flash. This eliminates the need to
use variable SISENV in common block /CUSPEC/, as is required
by routine UFLSH.
Data from the stream to be flashed is loaded into a standard user
stream vector DStVecIn. See “User Stream Vector” on page 15-10
Argument ITYPE declares the type of flash. For an isentropic flash,
the user specifies the stream entropy in argument DatValIn.

15-20 UAS Interfaces February 2009

 Optionally, ITYPE may take a value between 101 and 111. This
requests a corresponding flash of ITYPE 1 through 11. It also directs
the flash to use the following additional data passed in:
K-values passed in through argument array XKValues. Any
K-values loaded into argument array XKValues are used in
the flash calculations. Values greater than zero are required
for all components. If even one value is zero or negative,
this option is ignored. Values must be supplied in PRO/II
component internal order.
Total liquid flow input through DStVecIn( 5 ) and total water
flow input through DStVecIn( 6 ) are used to compute initial
estimates for the non-aqueous liquid phase and vapor phase
rates.
Arguments VapOut, XL1Out, and XL2Out are double precision stan-
dard user stream vectors See “User Stream Vector” on page 15-10
Argument VapOut returns the vapor phase results, while argument
XL1Out returns the primary (first or only) liquid phase results. When
the water DECANT option is ON, the results for the free-water decant
(second liquid) phase return in argument XL2Out. Argument XKVal-
ues returns calculated K-values or the k-values optionally passed in.

Isentropic Flash Example 1:

For isentropic flashes (types 8, 108, 9 and 109 only), the user
must first calculate the entropy of the stream and pass it in
using input argument DatValIn. One method of computing the
entropy is to call subroutine DUHS. The entropy so obtained
should be set directly into argument variable DatValIn (in input
units of entropy). Once this has been done, the user then calls
subroutine DU2FLSH. For example:
CALL DUHS( 2, 1, DStVecIn, SV, X, IERR )
CALL DUHS( 2, 2, DStVecIn, SL, X, IERR )
DatValIn = DStVecIn(5) * SL &
+ (1.0D0-DStVecIn(5)) * SV
CALL DU2FLSH( DStVecIn, ITYPE, DatValIn, &
VapOut, XL1Out, XL2Out, &
XKValues, IERR )
DStVecIn, VapOut, XL1Out, and XL2Out are double precision user stream
vectors that store data using the dimensional units defined for prob-
lem input. See “User Stream Vector” on page 15-10

PRO/II User-Added Subroutine User Guide 15-21

 UFLSH single precision
Subroutines UFLSH and DU2FLSH perform a two phase flash of a pro-
cess stream. This flash is a vapor/liquid (VLE) flash with an
optional pure water phase (DECANT=ON) as a non-rigorous second
liquid phase. All floating point arguments to UFLSH are single pre-
cision. However, internally all calculations are preformed using
double precision, and are identical to DU2FLSH. Calling sequence:

CALL UFLSH( SStVecIn, VapOut, XL1Out, &

XL2OUT, XKValues, ITYPE, IERR )
Where:

SStVecIn Input single precision standard user stream vector

containing data for the stream to flash. See “User
Stream Vector” on page 15-10
VapOut Output single precision standard user stream vector
that returns the vapor product mole flow rates from
the flash (in array elements 11-NOC+10).
XL1Out Output single precision standard user stream vector
that returns the primary (first or light or hydrocarbon)
liquid phase product mole flow rates from the flash.
XL2Out Output single precision standard user stream vector
containing any second liquid phase mole rates. (When
water DECANT=ON, this vector contains the
decanted water).
XKValues A local single precision array that returns equilibrium
K-values for each component from the calculations in
PRO/II internal order. It is dimensioned to NOC or
larger. It also is used to supply available input K-
values to use in a flash when the ITYPE variable has a
value between 101 and 111.
ITYPE Input integer specifies the calculation type:
1 or 101 Isothermal flash (T defined, P defined)
2 or 102 Adiabatic flash (T defined, P calculated)
3 or 103 Adiabatic flash (P defined, T calculated)
4 or 104 Dew point (T defined, P calculated)
5 or 105 Dew point (P defined, T calculated)
6 or 106 Bubble point (T defined, P calculated)
7 or 107 Bubble point (P defined, T calculated)
8 or 108 Isentropic (T defined, P calculated)
9 or 109 Isentropic (P defined, T calculated)

15-22 UAS Interfaces February 2009

 10 or 110 Water dew point (T defined, P calculated)
11 or 111 Water dew point (P defined, T calculated)
Note: 1xx indicates use K-values input in argument
XKValues for the flash type specified by xx.
IERR The error flag:
0 No errors
1 Flash convergence failure
2 ITYPE is not in range 1-11
3 The flowrate of STREAM is zero
For IERR = 2 or 3, no calculations will be
performed.

Note: IERR should be checked after each calculation and appropri-

ate action taken.
Flashes that this subroutine is capable of performing include:
Isothermal flash (temperature and pressure specified)
Adiabatic flash (temperature specified, pressure calculated)
Adiabatic flash (temperature calculated, pressure specified)
Dew point (temperature specified, pressure calculated)
Dew point (temperature calculated, pressure specified)
Bubble point (temperature specified, pressure calculated)
Bubble point (temperature calculated, pressure specified)
Isentropic flash (temperature specified, pressure calculated)
Isentropic flash (temperature calculated, pressure specified)
Water dew point (temperature specified, pressure calculated)
Water dew point (temperature calculated, pressure specified).
Data from the stream to be flashed is loaded into a standard user
stream vector See “User Stream Vector” on page 15-10 The liquid
and/or vapor portions corresponding to the desired calculations are
returned in standard user stream vectors.
Optionally, ITYPE may take a value between 101 and 111. This
requests a corresponding flash of ITYPE 1 through 11. It also directs
the flash to use the following additional data passed in:
K-values passed in through argument array XKValues. Any
K-values loaded into argument array XKValues are used in
the flash calculations. Values greater than zero are required
for all components. If even one value is zero or negative,
this option is ignored. Values must be supplied in PRO/II
component internal order.
Total liquid flow input through DStVecIn( 5 ) and total water
flow input through DStVecIn( 6 ) are used to compute initial
PRO/II User-Added Subroutine User Guide 15-23
 estimates for the non-aqueous liquid phase and vapor phase
rates.

Isentropic Flash Example 2:

For isentropic flashes (types 8 and 9), the user must first calcu-
late the entropy of STREAM by calling subroutine UHS. The
entropy so obtained should be set directly into the variable
SISENV in common block /CUSPEC/. Once this has been done,
the user then calls subroutine UFLSH. For example,
INCLUDE CUSPEC.CMN
. . .
CALL UHS( 2, 1, STREAM, SV, X, IERR )
CALL UHS( 2, 2, STREAM, SL, X, IERR )
SISENV = STREAM(5) * SL
& + (1.0D0-STREAM(5)) * SV
CALL UFLSH( STREAM, VAPOUT, XL1OUT, XL2OUT,
& XKVALU, ITYPE, IERR )
SStVecIn, VapOut, XL1Out, and XL2Out transfer data using the dimen-
sional units defined for problem input. They are single precision
standard user stream vectors, described above. See “User Stream
Vector” on page 15-10

15-24 UAS Interfaces February 2009

 DU3FLSH double precision
Subroutine DU3FLSH may be used to perform flash calculations
using rigorous VLLE equilibrium thermodynamic methods. The
flash is able to produce one vapor and two liquid products. This
means water decant systems (DECANT=ON) should not use this rou-
tine, but they should use DU2FLSH instead.
Usage (Double Precision):
CALL DU3FLSH( DStVecIn, ITYPE, DatValIn, &
VapOut, XL1OUT, XL2OUT, &
XK1VAL, XK2VAL, IERR )
Where:

Note: Except for the XK1OUT and XK2OUT arrays, the call is very
similar to the call to UFLSH described previously,

DStVecIn Input double precision standard user stream vector

containing data for the stream to flash.See “User Stream
Vector” on page 15-10 Data is transferred using problem
input dimensional units.
ITYPE Input integer specifying the type of flash calculation:
1 Isothermal flash (T specified, pressure specified)
2 Adiabatic flash (T specified, pressure calculated)
3 Adiabatic flash (T calculated, pressure specified)
4 Dew point (T specified, pressure calculated)
5 Dew point (T calculated, pressure specified)
6 Bubble point (T specified, pressure calculated)
7 Bubble point (T calculated, pressure specified)
8 Isentropic (T defined, P calculated)
9 Isentropic (P defined, T calculated)
10 Water dew point (T defined, P calculated)
11 Water dew point (P defined, T calculated)
DatValIn Input a double precision scalar value of total stream
entropy. Required and used only with isentropic flashes.
See “Isentropic Flash Example 1:” on page 15-21 Supply
a value using dimensional units of entropy used for input
data.
VapOut Output double precision standard user stream vector that
returns the vapor product mole flow rates from the flash
(in array elements 11-NOC+10). See “User Stream
Vector” on page 15-10
XL1Out Output double precision standard user stream vector that
returns the primary (first or light or hydrocarbon) liquid
phase product mole flow rates from the flash.

PRO/II User-Added Subroutine User Guide 15-25

 XL2Out Output double precision standard user stream vector that
returns the second (heavy or aqueous) liquid phase
product mole flow rates from the flash.
XK1Out Output double precision array of returned K-values
representing the equilibrium between the vapor and
primary (light or hydrocarbon) liquid phases (variably
dimensioned to NOC or greater).
XK2Out Output double precision array of returned K-values
representing the equilibrium between the two liquid
phases (variably dimensioned to NOC or greater).
IERR The error flag:
0 No errors
1 Flash convergence failure
2 ITYPE invalid, not in range 1-7
3 The flow rate in SStVecIn( 1 ) is zero or negative
For IERR = 2 or 3, no calculations will be
performed.

This routine is an enhanced double precision version of U3FLSH. It

supports several flash types not supported by U3FLSH, including
isentropic flashes and water dew point flashes. It also implements
improvements in the argument list. Argument DatValIn serves the
same purpose as described earlier in this chapter for DU2FLSH.

15-26 UAS Interfaces February 2009

 U3FLSH single precision
Subroutine U3FLSH may be used to perform flash calculations using
rigorous VLLE equilibrium thermodynamic methods. The flash is
able to produce one vapor and two liquid products. This means
water decant systems (DECANT=ON) should not use this routine, but
they should use UFLSH or DU2FLSH instead.
Calling sequence:
CALL U3FLSH( SStVecIn, VAPOUT, XL1OUT, &
XL2OUT, XK1Out, XK2Out, &
ITYPE, IERR )
Note: Except for the XK1OUT and XK2OUT arrays, the call is very
similar to the call to UFLSH described previously,
Note: Although the floating point arguments of this routine are sin-
gle precision, internally all calculations are double precision.
Where:

SStVecIn Input single precision standard user stream vector

containing data for the stream to flash. See “User Stream
Vector” on page 15-10
VapOut Output single precision standard user stream vector that
returns the vapor product mole flow rates from the flash
(in array elements 11-NOC+10).
XL1Out Output single precision standard user stream vector that
returns the primary (light or hydrocarbon) liquid phase
product mole flow rates from the flash.
XL2Out Output single precision standard user stream vector
containing any second (heavy or aqueous) liquid phase
mole rates.
XK1Out Output single precision array of returned K-values
representing the equilibrium between the vapor and
primary (light or hydrocarbon) liquid phases (variably
dimensioned to NOC or greater).
XK2Out Output single precision array of returned K-values
representing the equilibrium between the two liquid
phases (variably dimensioned to NOC or greater).

PRO/II User-Added Subroutine User Guide 15-27

 ITYPE Input integer specifying the type of flash calculation:
1 Isothermal flash (T specified, pressure specified)
2 Adiabatic flash (T specified, pressure calculated)
3 Adiabatic flash (T calculated, pressure specified)
4 Dew point (T specified, pressure calculated)
5 Dew point (T calculated, pressure specified)
6 Bubble point (T specified, pressure calculated)
7 Bubble point (T calculated, pressure specified)
IERR The error flag:
0 No errors
1 Flash convergence failure
2 ITYPE invalid, not in range 1-7
3 The flow rate in SStVecIn( 1 ) is zero or negative
For IERR = 2 or 3, no calculations will be
performed.

Note: For dew point flashes (types 4 and 5), this flash method is the
same as UFLSH since, by definition, no liquids can exist.
This routine does not support any isentropic flashes.

15-28 UAS Interfaces February 2009

Property Calculation Interfaces
DTTPROP double precision
TTPROP single precision
Call this subroutine to calculate any of the following properties:
Pure component vapor pressures in input units.
Pure component molar ideal gas enthalpies (H*i ) (103 energy
units per mole).
Transport properties for a single phase of a stream in input
units.
Data from the stream for which properties are desired is loaded into
a standard user stream vector and passed as an argument to
DTTPROP. (See “User Stream Vector” on page 15-10)

Calling sequence:
Usage (double precision):
CALL DTTPROP( ITYPE, IPHASE, DPrOut, &
DStVecIn, IERR )
Usage (single precision):
CALL TTPROP( ITYPE, IPHASE, SPrOut, &
SStVecIn, IERR )
Where:

ITYPE Integer input flag for desired property:

1 Vapor pressures of pure components
2 Ideal gas enthalpies of pure components
3 Transport properties of requested phase (5 max)
4 Thermal conductivity of requested phase
5 Viscosity of requested phase
6 Surface tension of liquid, only when IPHASE=2
IPHASE Integer input flag for Stream phase of interest:
1 Vapor phase
2 Liquid phase
DPrOut Returned floating point array that returns the calculated
or properties. DPrOut is a double precision local array, and
SPrOut SPrOut is a single precision local array. The minimum
dimension of this array depends on the value of ITYPE.
ITYPE Size of DPrOut (or SPrOut)
1 or 2 NOC
3, 4, 5, or 6 5

PRO/II User-Added Subroutine User Guide 15-29

 ITYPE = 1 returns NOC values of pure component vapor
pressures in PRO/II internal component
order (input pressure units).
ITYPE = 2 returns NOC values of ideal gas enthalpy
values in PRO/II internal component order.
ITYPE = 3-6 use the first five positions of DPROPS,
based on IPHASE and ITYPE, as shown.
IPHASE=2 (liquid)
PROP(1) Liquid surface tension (ITYPE=3 or 6)
PROP(2) Liquid viscosity (ITYPE=3 or 5)
PROP(3) Liquid thermal conductivity (ITYPE=3 or 4)
IPHASE=1 (vapor)
PROP(4) Vapor viscosity (ITYPE=3 or 5)
PROP(5) Vapor thermal conductivity (ITYPE=3 or 4)
DStVecIn DStVecIn is a double precision and SStVecIn is a single
or precision input standard user stream vector containing
SStVecIn data from the stream of interest. See “User Stream
Vector” on page 15-10 All values are in problem input
dimensional units. Component rate values are in PRO/II
internal order.
IERR Returned integer error condition flag:
0 No errors
1 IPHASE not equal to 1 or 2
2 ITYPE not in the range 1-6
3 Flowrate of stream is zero
4 Property requested is not available
The error flag should be tested after each call to
DTTPROP or TTPROP.

Note: All result values return in problem input dimensional units.

Also, the thermodynamic METHOD set used by TTPROP must
declare methods for computing transport properties.
Note: To request vapor pressures when assay fractions are
present, a KVALUE= LIBRARY method (need not be used)
should be used to insure setup of vapor pressure data for
PETROLEUM components.

15-30 UAS Interfaces February 2009

 DUHS double precision
UHS single precision
These routines compute the enthalpy, entropy, molar heat capacity,
or compressibility for a single specified phase of a stream. When
the stream is known to be single phase, these routines may be called
to compute a property for the bulk stream. Separate calls should be
made for each phase of a mixed-phase stream. Data for the stream
phase is loaded into a standard user stream vector (See “User
Stream Vector” on page 15-10) All data values are transferred using
problem input dimensional units.
Calling sequence:
CALL DUHS( ITYPE, IPHASE, DStVecIn, DValOut, &
DCpOut, IERR )

CALL UHS( ITYPE, IPHASE, SStVecIn, SValOut, &

SCpOut, IERR )
Where:

ITYPE Input integer flag for property requested:

1 Enthalpy and/or heat capacity
2 Entropy
3 Compressibility factor on a dry basis
calculated from the density method(s)
declared on the METHODS statement.
IPHASE Input integer indicating phase of interest:
1 Vapor
2 Liquid
DStVecIn Input standard user stream vector that transfers data
or for one stream phase. See “User Stream Vector” on
SStVecIn page 15-10 Data is in dimensional units used for
problem input. DStVecIn is double precision and
SStVecIn is single precision.
DValOut Scalar floating point variable that returns the property
or requested. DValOut is double precision and SValOut is
SValOut single precision. Enthalpies are reported in 103 energy
units per time. Entropy is reported as energy per time per
temperature using dimensional units defined for problem
input.

PRO/II User-Added Subroutine User Guide 15-31

 DCpOut A floating point scalar that returns stream molar heat
or capacity (specific heat) when ITYPE = 1. DCpOut is
SCpOut double precision while SCpOut is single precision. The
value is reported as energy per mole per temperature
degree using dimensional units defined for problem input.
IERR Error flag:
0 No errors
1 IPHASE not specified as 1 or 2
2 ITYPE not in range 1-3
3 Enthalpy/entropy calculation failed
4 Compressibility factor calculation failed
5 At least one of the following has been
detected: negative stream flow rate,
temperature or pressure out of bounds, or a
negative component molar flow rate.

Compressibility factors are always on a dry basis. An alternative

method for calculating densities is to use subroutine DUDENS or
UDENS. Those routines calculate both the wet and dry actual volume
of a stream.
The error flag should be examined and appropriate action taken
after each call to UHS.

15-32 UAS Interfaces February 2009

 DUH2OP double precision
UH2OP single precision
These subroutines determine properties for water, either as liquid or
vapor. Each call returns one specified property of water. All data in
the arguments use the dimensional units declared for problem input
data. While the arguments to routine UH2OP are single precision, all
internal calculations are performed in double precision.
Calling sequence:
CALL DUH2OP( ITYPE, IPHASE, TempInD, &
PresInD, DDum, &
ValOutD, dVdTOutD )

CALL UH2OP( ITYPE, IPHASE, TempInS, &

PresInS, SDum, &
ValOutS, dVdTOutS )
Where:

ITYPE Integer input flag for property requested:

1 Vapor volume (vapor volume units per mole)
2 Enthalpy (thousands of energy units per mole)
3 Entropy (energy units per mole per degree of
temperature)
4 Saturation pressure (in input units of pressure)
5 Saturation temperature (input temperature units)
6 Liquid volume (liquid volume units per mole)
All properties are on a molar basis in the dimensional
units selected for problem input.
IPHASE Integer input flag for water phase:
1 Vapor
2 Liquid
TempInD Temperature of interest, input in problem input units.
TempInS TempInD is double precision and TempInS is single
precision.
PressInD Pressure of interest, input in problem input units. PresInD
PressInS is double precision and PresInS is single precision.
DDum No longer used. Retained only to maintain argument list
SDum compatibility with previous versions. DDum is a double
precision scalar and SDum is a single precision scalar.

PRO/II User-Added Subroutine User Guide 15-33

 ValOutD The returned value of the requested property. The value is
ValOutS in dimensional units declared for problem input data.
ValOutD is a double precision scalar and ValOutS is a
single precision scalar.
dVdTOutD The returned derivative of the property with respect to
dVdTOutS temperature (dv/dT). dVdTOutD is a double precision
scalar and dVdTOutS is a single precision scalar.

15-34 UAS Interfaces February 2009

 DUDENS double precision
UDENS single precision
These subroutines return the wet and dry actual volumes (at flowing
temperature and pressure conditions) for a single phase of a stream
as calculated using the density method(s) declared for input data of
the simulation.
Usage (double precision):
CALL DUDENS( IPHASE, DStVecIn, DDryVol, &
DWetVol, IERR )
Usage (single precision):
CALL UDENS( IPHASE, SStVecIn, SDryVol, &
SWetVol, IERR )
Where:

IPHASE Input integer flag for the phase:

1 Vapor
2 Liquid
DStVecIn Input Standard stream vector containing data for the phase
SStVecIn of interest. See “User Stream Vector” on page 15-10
DStVecIn is double precision and SStVecIn is single
precision.
DDryVol Returned actual dry volumetric flow rate of the phase.The
SDryVol value uses different dimensional units depending upon the
phase:
IPHASE Return value uses these dimensional units
1 Vapor volume units per time
2 Liquid volume units per time
DDryVol is double precision
SDryVol is single precision.
DWetVol Returned actual wet volumetric flow rate of the phase.
SWetVol The value uses different dimensional units depending
upon the phase:
IPHASE Return value uses these dimensional units
1 Vapor volume units per time
2 Liquid volume units per time
DDryVol is double precision
SDryVol is single precision.
IERR 0 No error
1 IPHASE is not 1 or 2, no results returned

PRO/II User-Added Subroutine User Guide 15-35

 To call these routines, load data for the phase of interest in the
DStVecIn or SStVecIn argument array. For a stream known to be a
single phase, these routines can compute the actual volume for the
bulk stream. For mixed phase streams, a separate call is required for
each phase.
These routines do not set the density calculation method and do not
set the thermodynamic METHOD set to use. The assumption is that
these routines are called from a user-added unit operation, and a
thermodynamic method set used by the unit operation is currently in
effect. If no density methods were defined in the thermodynamic
method set, the K/H method is used, if applicable.
The subroutines do not directly return stream density. Users may
calculate the density of a stream (phase) by dividing the weight rate
of the stream (phase) by the returned value(s).
density = total weight rate / specific volumetric flow rate
= (weight/time) / (volume/time) = weight/time

15-36 UAS Interfaces February 2009

 KCOMPU double precision
This double precision subroutine returns K-values and temperature
derivatives of K-values for use by a user-added flash subroutine. All
floating point arguments are double precision.
Calling sequence:
CALL KCOMPU( TEMP, PRES, VAPIN, XL1IN, &
XL2IN, XK1VAL, XK2VAL, DK1DT, &
DK2DT, IXFLAG, KFLAG, KDFLAG )
Where:

TEMP Temperature, in input units, at which K-values are

required. This is an input double precision scalar.
PRES Pressure, in input units, at which K-values are required.
This is an input double precision scalar.
VAPIN Input double precision standard user stream vector of
the vapor phase data. See “User Stream Vector” on page
15-10 Data values are in input dimensional units.
XL1IN Input double precision standard user stream vector of
the L1 (light or hydrocarbon) liquid phase.
XL2IN Input double precision standard user stream vector of
the L2 (heavy or aqueous) liquid phase.
XK1VAL Returned double precision array of K-values for L1
liquid phase components in PRO/II internal component
order.
XK2VAL Returned double precision array of K-values for L2
liquid phase components in PRO/II internal component
order.
DK1DT Returned double precision array of temperature
derivatives for L1 liquid phase components in PRO/II
internal component order.
DK2DT Returned double precision array of temperature
derivatives for L2 liquid phase components in PRO/II
internal component order.
IXFLAG Input integer composition flag:
0 No composition dependencies
1 Yes, calculations are composition dependent
KFLAG Input integer K-value option flag
1 Consider light phase only for K-value
calculations.
2 Consider both phases for K-values calculations.

PRO/II User-Added Subroutine User Guide 15-37

 KDFLAG Input integer derivative option flag
1 Consider light phase only for derivative
calculations.
2 Consider both phases for derivative calculations.

Note: XK1VAL, XK2VAL, DK1DT, and DK2DT must be dimensioned to

NOC. For example,
REAL(8) :: XK1VAL( NOC ), XK2VAL( NOC )
There is no single precision analog of this subroutine.

15-38 UAS Interfaces February 2009

 DHCOMPU double precision
HCOMPU single precision
These subroutines return enthalpies for use with a user-added flash
method.
Calling sequence:
CALL DHCOMPU( TempInD, PresInD, VaporD, &
XL1D, XL2D )
CALL HCOMPU( TempInS, PresInS, VaporS, &
XL1S, XL2S )
Where:

TempInD Temperature at which enthalpies are required. This is an

TempInS input double precision scalar that uses input units of
temperature.
PresInD Pressure at which enthalpies are required. This is an
PresInS input double precision scalar that uses input units of
pressure.
VaporD A standard user stream vector for the vapor phase.
VaporS VaporD is double precision and VaporS is single
precision. This must be loaded with vapor phase data to
pass in. The vapor results return in elements 4, 7, and 8.
See “User Stream Vector” on page 15-10
XL1D Standard user stream vector for the L1 (light or
XL1S hydrocarbon) liquid phase. XL1D is double precision
and XL1S is single precision. This must be loaded with
L1 phase data to pass in. The L1 results return in
elements 4, 7, and 8. See “User Stream Vector” on page
15-10
XL2D Standard user stream vector for the L2 (heavy or
XL2S aqueous) liquid phase. XL2D is double precision and
XL2S is single precision. This must be loaded with L2
phase data to pass in. The L2 results return in elements
4, 7, and 8. See “User Stream Vector” on page 15-10

The phase enthalpy values return in element (4) of the user stream
vectors. Element (7) returns the compressibility factors as calcu-
lated from the K/H method. Element (8) returns the derivative of
enthalpy with respect to temperature (dH/dT).

Note: Enthalpies have units of 103 energy units per time.

PRO/II User-Added Subroutine User Guide 15-39

Interfaces for Solids
The legacy interfaces in PRO/II support only vapor and liquid
phases in streams. Chapter 21 describes new interfaces that support
solids phases. Most of the routines were not available prior to
PRO/II version 8.0. Refer to example routine USER57.FOR for some
code demonstrations that use these solids-handling routines.

Component Identification Interface Routines

Many of the user-added interface routines reference components by
order number rather than by name or other text identifier. It is
important to understand how PRO/II handles components to insure
the interface routines handle component data properly.

Internal Component Order vs. Print Order

What Is Internal Component Order?

PRO/II reorders components internally based on phase availability.
This allows calculations to be performed efficiently on contiguous
groups of components. Phase availability refers to the phases
(vapor, liquid, solid) in which a component is allowed to exist. This
usually is determined by the availability of data. For example, some
components may have complete data for all three phases and be
designated as VLS; while others might lack data for the solid phase
and be designated as VL.
This reordering is referred to as SIMSCI Internal Component Order.
By contrast, the sequence order for the components selected by the
user at input and in the output reports is referred to as Print Order.
This reordering impacts user-added subroutines that assume com-
ponents are ordered in Internal Order. The user must take steps as
described below to handle the internal component order.
The grouping of components by phase designation for internal use
is as shown in Table 15-4.
Table 15-4: Component Phase Versus Internal Order
Phase Availability Internal Order
VL 1st group
VLS 2nd group
LS 3rd group
S 4th group

15-40 UAS Interfaces February 2009

 For example, if we compare the print order and internal order which
are based on the following keyword input file extract:
COMPONENT DATA
LIBID 1, N2 / 3, CH4 / 4, C2 / 5, C3 / &
6, IC4 / 7, NC4, &
BANK = PROII_8.3:PROCESS
LIBID 2, CO2, BANK = PROII_8.3:SIMSCI
The default PRO/II phase designations, print order, and internal
order for components nitrogen through n-butane are given in Table
15-5 below.
Table 15-5: Phase Designation, Print and Internal Order for N2-NC4
Print Internal
Component Phase Designation Order Order
N2 VL 1 1
CO2 VLS 2 7
CH4 VL 3 2
C2 VL 4 3
C3 VL 5 4
IC4 VL 6 5
NC4 VL 7 6

Although CO2 is the 2nd component as far as the input file and
printed reports are concerned (i.e., Print Order), it is the 7th compo-
nent in Internal Order because the SIMSCI bank designation indi-
cates that it is a VLS component, while the other components from
the PROCESS databank have VL phase availability. For ease of
internal calculation, the VL components are grouped ahead of VLS
components.
You can see the phase availability from the component PRO/II out-
put report by using the keywords INPUT=ALL on the PRINT statement
in the General Data category of input. You can also force the phase
designation to be uniform by using a PHASE statement in the Com-
ponent Data category of input (see Chapter 1 of the SIMSCI Com-
ponent Manual). Thus, in the above illustration, the user could force
the internal order to match the input order by using the PHASE state-
ment:
PHASE VL=1,7 or PHASE VL=2

PRO/II User-Added Subroutine User Guide 15-41

 How Order Affects User-Added Subroutines
In user-added subroutines, compositional arrays are in Internal
Order.

Note: An important exception is user-added kinetics which con-

verts all compositional data to Print Order in the arrays passed to
USKIN1-5.

Thus, all compositional arrays in the UTHERX and XPROPX com-

mons, the stream compositions in the standard STREAM array used
by TTPROP, UHS, UDENS, URXSTR, etc. are all in Internal Order. If you
are assuming that components are in Print Order, then you must use
the COPNUM and COINUM subroutines described below to access the
Internal Order.

Component Order, Identification, and Data

COPNUM
This subroutine returns the component print order number when
given the internal order number. See also ”UDEFNC”, pg 20-3
Calling sequence:
CALL COPNUM( iCint, iSlate, ICprint )
Where:

iCint Input integer Internal component number

iSlate Input integer Value = 1 always
iCprint Output integer Print component number

Example: Retrieving Component Print Order Numbers

!
! Retrieve Component Print Order Numbers
!
1001 FORMAT( “ Internal Number = “, I5,
& “ Print Number = “, I5 )
!
DO iCint = 1, NOCX
CALL COPNUM(iCint, 1, iCprint)
WRITE (IOUT, 1001) iCint, iCprint
END DO

15-42 UAS Interfaces February 2009

 COINUM
This subroutine returns component internal order numbers given the
print order numbers.
Calling sequence:
CALL COINUM( iCprint, iSlate, iCint )
Where:

iCprint Input integer Print component number

iSlate Input integer Value not significant for user
iCint Output integer Internal component number

Example: Retrieving Component Internal Order Numbers

!
! Process Data in Print Order.
! Assume TDATA contains a K-Value array
! in print order
!
DO iCprint = 1, NOCX
CALL COINUM (iCprint, iSlate, iCint )
XKV(iCint) = TDATA(iCprint)
END DO

CONAME
This function retrieves the text ID of a given component. The
returned value of the function is a character string of up to 16 char-
acters in length.
Calling sequence:
COMPID = CONAME( iSlate, iCint )
Where:
iSlate Integer input indicating the component slate to use:
1 = Normal Component, including solid components
2 = Ionic component (used only for electrolytes)
iCint Integer input of the internal order number of the
component of interest.
COMPID The returned 16 character component ID

PRO/II User-Added Subroutine User Guide 15-43

 UCOPRP double precision
This double precision subroutine retrieves or stores specified com-
ponent property data to the current active set of component proper-
ties. The property is processed for all components in each call.
Usage (Double Precision):
CALL UCOPRP( cPropKw, iPropNo, cRWflag, NDIM,
DCoProp, iErrOut )
Where:
cPropKw Input key word (used if non-blank) that uniquely
identifies a named component property.
For example, use "MW" for molecular weight.
CALL UCOPRP( “MW”, 0, “READ”, &
NOCTOT, DCoProp, iErrOut )
This call retrieves the molecular weight of all components in the
simulation (except non-molecular weight components). Available
fixed properties are listed in Table 15-6. Note IPropIn should be zero.
Additionally, cPropKw may designate any named special property
listed in Table A-1, "Keywords for Named Special Properties" in
Appendix A. This entry must be a character variable or a keyword
coded as a literal string enclosed in quotation marks. When blank,
argument iPropNo is required to identify a numbered special
property.
iPropNo Input integer value (1 - 60) identifying a user-defined
special property, as in SPROP(iPropNo). This is required
because SPROP's are only numbered and have no pre-
defined name.
IPropNo is used only when cPropKw is blank or null; otherwise, it is
ignored. For example,
CALL UCOPRP( “ ”, 3, “READ”, &
NOCTOT, CpProp, iErrOut )
retrieves the value of user-defined special property 3 (SPROP(3)) for
all components.
cRWflag Argument cRWflag is an input text string option flag
with values of:
"READ" Read (retrieve) the property values and return
them in call argument array DCoProp.
"WRITE" Write (store) values passed in through the
DCoProp array to the active set of component
properties.

15-44 UAS Interfaces February 2009

 NDIM Variable NDIM is the number of values to read or write.
Array DCoProp contains all NDIM values to read or write.
This routine always processes exactly NOCTOT values. It
processes one value for each of NOCTOT components.
Since this is under user control, no tests are made to
ensure the values are legitimate. This could mostly be a
problem during a WRITE rather than a READ. If NDIM is
less than NOCTOT, then an error is returned and the READ
or WRITE fails.
If NDIM is greater than NOCTOT, only the first NOCTOT
items are processed in DCoProp and the others are
ignored. This is considered normal behavior and does not
generate either an error or a warning.
DCoProp A double precision floating point array containing at
least NOCTOT elements. Each element passes one
property value for each of the NOCTOT components in
PRO/II internal component order.
iErrOut An integer output variable that returns the error flag. A
value of zero indicates successful completion with no
errors. Any other value indicates failure, and the results
are indeterminate. This usually means no action was
performed.

Table 15-6: Named Properties Available through UCOPRP

cPropKw Description
‘NBP’ Normal Boiling Point temperature
‘MW’ Molecular weight
‘SG60’ Specific Gravity at 60 F
‘OMEGA’ Acentric factor
‘TC’ Critical Temperature
‘PC’ Critical Pressure
‘VC’ Critical Volume
‘ZC’ Critical compressibility factor
‘RAKT’ Rackett parameter
‘CNUM’ Carbon number
‘ZNUM’ Hydrogen deficiency number
‘WATK’ Watson K coefficient
See Appendix A for Special Property Keywords

PRO/II User-Added Subroutine User Guide 15-45

 DzMolWt double precision
ZMW2 single precision
These integer functions retrieve or store the molecular weight of
every component in the simulation that has a molecular weight. The
returned integer value of the function is the error flag.
Usage (Double Precision):
INTEGER(4) :: DZMolWt
. . .
ifOk = DZMolWt( IRDWT, IDIM, DVecIO )
Usage (Single Precision):
INTEGER(4) :: ZMW2
. . .
ifOk = ZMW2(IDIM, SVecIO, IRDWT )
where:
IRDWT Integer input read/write option flag. values are:
0 Read
1 Write
IDIM Size of data array DVecIo. Because data are ordered
component input order, this size must accommo-
date all components in the problem, typically NOC-
TOT. See “Internal Component Order vs. Print
Order” on page 15-40. See “GETNCOMP” on page
21-2 to obtain counts of various types of compo-
nents.
DVecIO Data array of molecular weights, one per compo-
nent, arranged in (external) component print order.
The size must be large enough to store a value for
every component in the simulation. (For one
option, See “/PMXUSR/” on page 15-49.)
ifOk Error return. 0 = no error. >0 = array DVecIO is too
small Only ifOk components were processed.

These routines may be used as alternatives to using the more gen-

eral-purpose routine UCoPrp. The only real difference is:
DzMolWt and ZMW2 use an external data array to pass data
in component print order. Routine UCoPrp uses an internal
data array to pass data in PRO/II internal component order. See
“Internal Data Array” on page 15-11for definitions of these
arrays.

15-46 UAS Interfaces February 2009

 DzSg60 double precision
ZSg602 single precision
These functions retrieve or store the specific gravity at standard
conditions (60 degrees Fahrenheit) of every component in the simu-
lation. The returned integer value of the function is the error flag.
Usage (Double Precision):
INTEGER(4) :: DZSG60
. . .
ifOk = DZSG60( IRDWT, IDIM, DVecIO )
Usage (Single Precision):
INTEGER(4) :: ZSG602
. . .
ifOk = ZSG602( IDIM, SVecIO, IRDWT )
where:
IRDWT Integer input read/write option flag. values are:
0 Read
1 Write
IDIM Size of data array DVecIo. Because data are ordered
component input order, this size must accommo-
date all components in the problem, typically NOC-
TOT. See “Internal Component Order vs. Print
Order” on page 15-40. See “GETNCOMP” on page
21-2 to obtain counts of various types of compo-
nents.
DVecIO Data array of specific gravities, one per compo-
nent, arranged in (external) component print order.
The size must be large enough to store a value for
every component in the simulation. (For one
option, See “/PMXUSR/” on page 15-49.)
ifOk Error return. 0 = no error. >0 = array DVecIO too
small to process all components.

These routines may be used as alternatives to using the more gen-

eral-purpose routine UCoPrp. The only real difference is:
DzMolWt and ZMW2 use an external data array to pass data
in component print order. Routine UCoPrp uses an internal
data array to pass data in PRO/II internal component order. See
“Internal Data Array” on page 15-11for definitions of these
arrays.

PRO/II User-Added Subroutine User Guide 15-47

User-Defined Data Files
FIGETU
This is a PRO/II utility that guarantees that the FORTRAN unit
number passed to your FORTRAN OPEN statement will not conflict
with files opened by the UAS system.
Calling sequence:
CALL FIGETU( 1, LOUT )
Where:

1 Input integer digit “1” requests a single file unit. This is

the only recommended value to use.
LOUT Output Integer scalar variable that returns the first
available file unit. This must be an integer variable, not a
constant.

The FIGETU subroutine call returns the next available FORTRAN

unit number for input or output as integer variable LOUT. A sample
code extract is shown below:
CHARACTER(LEN=8) :: FNAME
CHARACTER(LEN=12) :: FEXTRA
1001 FORMAT(“ Enter File Name: “)
1002 FORMAT( A )
. . .
! Open a logical file unit for output
!
CALL FIGETU(1, LOUT)
!
! Open file ‘FNAME.OXX’ as a new, formatted
! sequential file
!
FEXTRA = FNAME // ‘OXX’
OPEN( UNIT=LOUT, FILE=FEXTRA, STATUS=‘NEW’,
& FORM=‘FORMATTED’, ACCESS=‘SEQUENTIAL’)

15-48 UAS Interfaces February 2009

Common Storage Blocks
Several types of classic user-added subroutine use common blocks
to exchange data with PRO/II. The common blocks are installed
during installation of PRO/II user-added subroutines, typically in
directory %p2install%\user\CMNS\. Starting with PRO/II version
8.2.1, PRO/II installs a double precision and a single precision ver-
sion of each common. Previously, only single-precision versions
were available. To use any of the available common blocks, access
them using an INCLUDE statement in a Fortran subroutine or func-
tion. Never attempt to use both the single precision and double
precision version of the same common block in the same subrou-
tine or function.

/PMXUSR/
This include file contains a single parameter - MAXCN - that defines
the maximum number of components supported by user-added sub-
routines in PRO/II. Starting with PRO/II version 8.0, MAXCN =
2500. In earlier versions, MAXCN was limited to 300. MAXCN is an
invariant parameter that cannot be altered by a user.
Usage:
INCLUDE ‘PMXUSR.CMN’
Where:

MAXCN Maximum components allowed in a user-added

subroutine by PRO/II. MAXCN is an integer parameter
with a value of 2500. It’s only purpose is to dimension
other arrays in common blocks UTHERX.CMN,
XPROPX.CMN, and XPROPY.CMN.

Example:
The following code snippet demonstrates the proper ordering
of INCLUDE statements in a user-added subroutine.
INCLUDE ‘PMXUSR.CMN’ ! Required to use others below
INCLUDE ‘UTHERX.CMN’ ! Always after PMXUSR
INCLUDE ‘XPROPX.CMN’ ! Always after PMXUSR
INCLUDE ‘XPROPY.CMN’ ! Always after PMXUSR
There should be no compelling reason for the user to use MAXCN
directly. Instead, call interface routine GETNCOMP to obtain cur-
rent component counts in a problem.
Note: User-added subroutines must include PMXUSR.CMN before
they include UTHERX.CMN, XPROPX.CMN, or XPROPY.CMN.

PRO/II User-Added Subroutine User Guide 15-49

 /DFACTOR/ double precision
/FACTOR/ single precision
Common blocks /DFACTOR/ and /FACTOR/ contain dimensional unit
conversion factors and certain physical constants. These conversion
factors can be used to convert input dimensional units to the base
units as shown below. The variables in /DFACTOR/ and /FACTOR/ have
exactly the same names and are in exactly the same order. The only
difference is that /DFACTOR/ contains double precision values while
/DFACTOR/ contains single precision values of the same conversion
factors.
Note: Never attempt to include both /DFACTOR/ and /FACTOR/ in the
same subroutine, since that would cause fatal compilation errors.
Usage (double precision):
INCLUDE ‘DFACTOR.CMN’
Usage (single precision)
INCLUDE ‘FACTOR.CMN’
This include file contains the following common block:
COMMON /FACTOR/
& TCONVT, TFAC, PCONVT, PFAC,
& TIMFAC, WTFAC, VVFAC, ARFAC,
& XLVFAC, SPGFAC, HSFAC, WKFAC,
& VISFAC, TCFAC, VVFACA, STFAC,
& FACA, FACB, EXPFAC, XM3FAC,
& FTOR, CTOK, XKTOR, ATM,
& VVTOML, RCONST, DUMMY(14)
Where:
TRankine = [(temp)p + TCONVT] · TFAC
Psia = [(pres)p + PCONVT] · PFAC
Sec = (time)p · TIMFAC
Lb = (wt)p · WTFAC
(Standard vapor volume)p · 106 = (moles)p * VVFAC
Ft2 = (area)p · ARFAC
Ft3 = (liquid volume)p · XLVFAC
(60°F density)p = SpGr · SPGFAC
Btu/(time)p = (enthalpy/time)p · HSFAC
Horsepower = [(ΔH · 103)/time]p · WKFAC
Centipoise = (viscosity)p · VISFAC
Btu/hr-°F-Ft = (thermal conductivity)p · TCFAC

15-50 UAS Interfaces February 2009

 Ft3 = (vapor volume)p · VVFACA
Dynes/cm = (surface tension)p · STFAC
The common includes the following conversion factors for use in
user-added subroutines. Developers should not attempt to modify
the values of these factors.

FACA, Reserved, not available

FACB
EXPFAC 2.3026 ln(X) = EXPFAC ( log10(X) )
XM3FAC 35.314667 ft3/m3 (cubic meters to cubic feet)
FTOR 459.67 (Fahrenheit to Rankine)
CTOK 273.15 (Celsius to Kelvin)
XKTOR 1.8 (Kelvin to Rankine)
ATM 14.6959 (Atmospheres to psia)
VVTOML Obsolete, not used
RCONST 1.9872 (Gas constant)
Note: Subscript p denotes problem input dimensional units.

PRO/II User-Added Subroutine User Guide 15-51

 /DOUTFAC/ double precision
/OUTFAC/ single precision
Common block /DOUTFAC/ contains factors for scaling and conver-
sion of problem output to alternate dimensional units when the OUT-
DIMENSION feature of PRO/II is used. It also includes alphanumeric
representations for the output dimensional units and the component
names. Common block /OUTFAC/ is a single precision version that
contains exactly the same data as /DOUTFAC/.
Usage:
INCLUDE ‘PMXUSR.CMN’ ! Required to use DOUTFAC
INCLUDE ‘DOUTFAC.CMN’
or
INCLUDE ‘PMXUSR.CMN’ ! Required to use OUTFAC
INCLUDE ‘OUTFAC.CMN’
The INCLUDE file contains either common DOUTFAC or OUTFAC:
COMMON/DOUTFAC/
& TXXX(20), IHOL(37), IXNAME(4, MAXCN)

The only difference is array TXXX, which is double precision in

DOUTFAC.CMN and is single precision in OUTFAC.CMN. Output
items may be multiplied by the TXXX array to accomplish any
needed conversions to output dimensions when multiple output
dimensions are used.
Weight/time = (weight/time)p · TXXX(1)
Liquid volume/time = (liquid volume)p · TXXX(2)
Weight = weightp · TXXX(3)
Liquid volume = (liquid volume)p · TXXX(4)
Liquid density = (liquid density)p · TXXX(5)
Enthalpy = enthalpyp · TXXX(8)
Enthalpy/time = (enthalpy/time)p · TXXX(9)
Temperature base = TXXX(10)
Pressure base = TXXX(11)
Enthalpy/weight = (enthalpy/weight)p · TXXX(12)
Scale factor1 = TXXX(13)
Actual vapor vol./time = (actual vapor vol./time)p · TXXX(14)
Vapor density = (Vapor density)p · TXXX(15)
Thermal Conductivity = (Thermal conductivity)p · TXXX(16)

15-52 UAS Interfaces February 2009

 Viscosity = (Viscosity)p · TXXX(17)
Surface Tension = (Surface tension)p · TXXX(18)
Standard vapor volume = (Standard vapor volume)p · TXXX(20)
For temperature and pressure conversions, factors from /FACTOR/
must also be used.
Temp = (tempp + TCONVT) · TXXX(6) - TXXX(10)
Pres = (presp + PCONVT) · TXXX(7) - TXXX(11)
where TCONVT and PCONVT are from /DFACTOR/ (or /FACTOR/).
For the above conversions, the subscript p is used to represent prob-
lem input dimensional units.
The IHOL array shown in Table 15-7 contains Hollerith information
corresponding to the output dimensions. All entries are A4 except
temperature which is A3. Blanks are denoted with b.
Table 15-7: Hollerith Array
IHOL Description Format Illustration
1 Per time unit /XXX
2 Weight unit XXb
3 Multiple weight units bXXS
4 Per weight /XXb
5 Degree bDEG
6 Temperature unit bXb
7 Pressure unit XXXX
8 Energy unit XXXX
9 Liquid volume unit XXXX
10 Per liquid volume /XXX
11 Vapor volume unit XXXX
12 Per vapor volume /XXX
13 Length unit XXbb
14 Work unit bXXb
15,16 Viscosity unit XXXX XXXX
17,19 Thermal conductivity XXXX XXXX XXXX
unit
20,21 Surface tension unit XXXX XXXX
22 Liquid bLIQ

PRO/II User-Added Subroutine User Guide 15-53

 Table 15-7: Hollerith Array (Continued)
IHOL Description Format Illustration
23 UIDb
24 Vapor bVAP
25 ORbb
26 Mixed bMIX
27 EDbb
28 Mole MOLE
29 Mols MOLS
30 Wet WET
31 Dry bDRY
32 Blank bbbb
33 Zero bbb0
3
34 10 bbMb
35 106 bMMb
36 per 103 /Mbb
6
37 per 10 /MMb

Note: When the unit dimension does not require all non-
blank positions as shown above, it is spaced accord-
ingly. For example, a pressure unit of Pascals would
be represented bPAb.

Note: The IHOL array is appropriately modified from input

dimensions when alternate output dimensions are
requested. The IXNAME array contains the component
names in the format XXXX XXXX XXXX XXXX (4A4).

15-54 UAS Interfaces February 2009

 /DUTHERX/ double precision
/UTHERX/ single precision
Common block /DUTHERX/ and /UTHERX/ provide an interface that
transfers data between user-added thermodynamic subroutines and
PRO/II. See ”DUTHERX Common Block (or UTHERX)”, pg 16-3,
for complete information about using these commons.
Usage:
INCLUDE ‘PMXUSR.CMN’ ! Required to use DUTHERX
INCLUDE ‘DUTHERX.CMN’ ! double precision
or
INCLUDE ‘PMXUSR.CMN’ ! Required to use UTHERX
INCLUDE ‘UTHERX.CMN’ ! single precision
These INCLUDE file contains the following common block:
COMMON / DUTHERX /
& TEMPX, TDELTX, PRESX,
& XVV, XLL, XLL2, YXSAT,
& XXSOL, XKV, DRVX, HSX1,
& HSX2, ZXX1, ZXX2,
& IFLGX, IXXFLG, JXXFLG, NOCZ,
& IFPHZ, KUOUT, KDECNT, KVTYPE,
& KDCALL

All the variables are fully described in ”DUTHERX Common Block

(or UTHERX)”, pg 16-3. Only variable KDCALL is described here.

KDCALL This flag controls whether or not PRO/II stores data returned
in the common block. PRO/II initializes this flag to zero just
prior to each call to a user-added subroutine. When a user-
added subroutine alters data in this common with the intent
of having PRO/II store it, that user-added subroutine must set
KDCALL = 1. Upon return to PRO/II, all data is stored when
KDCALL = 1. For any other returned value of KDCALL,
any and all returned data are discarded.

PRO/II User-Added Subroutine User Guide 15-55

 /DXPROPX/ double precision
/XPROPX/ single precision
Common /DXPROPX/ contains double-precision values for the pure
component properties for the components declared in the problem
input data. Common /XPROPX/ contains single-precision values for
the same properties using exactly the same variable names in
exactly the same order.

Note: The property values must not be altered in any way by user-
added subroutines.
Note: Never attempt to use both /DXPROPX/ and /XPROPX/ in the
same subroutine or function.
Usage (double precision):
INCLUDE ‘PMXUSR.CMN’ ! Required to use DXPROPX
INCLUDE ‘DXPROPX.CMN’
or (single precision):
INCLUDE ‘PMXUSR.CMN’ ! Required to use XPROPX
INCLUDE ‘XPROPX.CMN’
This INCLUDE file contains the following common block:
COMMON /DXPROPX/
& XMW(MAXCN), BP(MAXCN), DENS(MAXCN),
& TC(MAXCN), PC(MAXCN), VC(MAXCN),
& ZC(MAXCN), OMEGA(MAXCN), HFORM(MAXCN),
& GFORM(MAXCN),
& LIBNO(MAXCN), KOCMOL, KOCTOT,
& KOCVL, KOCVLS, KOCLS,
& KOCV, KOCL, KOCS
Where:

Floating Point Values In Common

XMW Molecular weights
BP Normal boiling points in problem input units
DENS Component liquid densities at 60ºF (15.55ºC) and one
atmosphere in problem input units.
TC Critical temperatures, absolute input temperature units
PC Critical pressures, absolute input pressure units
VC Critical volumes, cc/gm mole
1) PETROLEUM and NONLIB components are given a LIBNO of ‘0’. Library
ID numbers for all Library components may be found in the Modular
Thermodynamics User Manual.

15-56 UAS Interfaces February 2009

 ZC Critical compressibility (Z’s)
OMEGA Acentric factors
HFORM Heat of formation in energy units/mole
GFORM Energy of formation in energy units/mole
Integer Values in Common
LIBNO Library ID numbers for components.1
KOCMOL Number of molar weight-based components
KOCTOT Total number of normal components.
KOCVL Number of components that can
exist in vapor and liquid phases.
KOCVLS Number of components that can
exist in vapor, liquid, and solid phases.
KOCLS Number of components that can
exist in liquid and solid phases.
KOCV Number of components that can exist in the vapor phase.
KOCL Number of components that can exist in the liquid phase.
KOCS Number of components that can exist in the solid phase.
1) PETROLEUM and NONLIB components are given a LIBNO of ‘0’. Library
ID numbers for all Library components may be found in the Modular
Thermodynamics User Manual.

PRO/II User-Added Subroutine User Guide 15-57

 /DCUDATA/ double precision
/CUDATA/ single precision
Common block /DCUDATA/ is a single-vector double precision stor-
age area for various groups of stream, unit, and component data.
Common /CUDATA/ is a single precision version of the same com-
mon. Extensive discussion of usage is presented in Chapter 16,
DCUDATA Common Block, page 16-8.
Usage (double precision):
INCLUDE ‘DCUDATA.CMN’ ! double precision
or (single precision):
INCLUDE ‘CUDATA.CMN’ ! single precision
The INCLUDE file contains the following common block:
COMMON /DCUDATA/ TDATA(2600) Where:

TDATA Real constants, entered in the Thermodynamic Data

category of input (see Chapter 16, User-Added
Thermodynamic Property Methods).

/CUSPEC/
Common block /CUSPEC/ is required only in any subroutine calling
UFLSH to perform an isentropic flash. This common transfers the
stream entropy to the UFLSH call interface program for use in the
isentropic flash.
INCLUDE ‘CUSPEC.CMN’
This INCLUDE file contains the following common block:
COMMON/CUSPEC/ IX1(10),SISENV,RX1(7)
Where:

SISENV Entropy of the stream to be used as the target entropy for

the call to UFLSH. The value should be obtained by
calling subroutine UHS and transferred to SISENV
without any dimensional or other conversion. Variable
SISENV is explicitly declared single precision.

Note: None of the double-precision subroutines use the CUSPEC

common or variable SISENV. Instead, all of them include an addi-
tional variable in the argument list of the call to pass in the stream
entropy.

15-58 UAS Interfaces February 2009

 Chapter 16
User-Added Thermodynamic
Property Methods
Overview
PRO/II supports user-added subroutines that perform K-value,
enthalpy, entropy, or density calculations. To indicate to PRO/II that
a user-added thermodynamic property method is being used instead
of a built-in method in a keyword file, you must specifically declare
module using the METHOD statement. For example, to use a user-
added K-value method in a keyword input file:
METH KVALUE=U1,ENTH=CP,ENTR=CP,DENS(V)=SRK, &
DENS(L)=API, TRANS=PETRO, SET=1
In the ProVision Graphical User interface, navigate to the Input
menu -> Thermodynamic data to open the SIMSCI - Thermody-
namic Data dialog box. Scroll the Category list and select User-
Added Methods. The available user-added methods will populate
the Primary Methods list box. Highlight the user-added method of
choice and click the Add button to move the selection to the Defined
Systems list box. To match the preceding keyword example, select
“User-added 1” from he Primary Methods list box and click the Add
button.
Next, click the Modify button to open the Thermodynamic - Modifi-
cation dialog box. Ensure “User-added 1” is the Current Method for
the “K-value (VLLE)” property. Make any other necessary adjust-
ments to inform PRO/II of exactly which properties the user-added
subroutine can (and cannot) calculate. When satisfied with the con-
figuration, press the OK button on each dialog box to return to the
main PFD window.
The examples above indicate that the previously linked user-added
K-value method, U1, is to be used in thermodynamic method set

PRO/II User-Added Subroutine User Guide 16-1

 “1.” The valid entries for the KVALUE keyword are U1, U2, U3, ...,
U15. Each entry corresponds to a specific user-added subroutine.
Keyword entry U1 corresponds to the Fortran subroutine named
UKHS1.FOR, U2 corresponds to UKHS2.FOR, and so on.

Note: These subroutines may be used to calculate K-values,

enthalpies, entropies, or densities and may call all other
subroutines.
To use this K-value method in a unit operation calculation, you
would use a similar keyword construct. For example, to perform an
isothermal flash at 30°F:
FLASH UID=FL1
FEED 1
PROD V=2, L=3
ISOT TEMP=30, DP=0
METHOD SET=1

Rigorous VLLE Calculations

When calling a user-added subroutine for VLLE K-values, PRO/II
passes the compositions of the light and heavy liquid phases in the
XLL and XLL2 arrays, respectively. You must, however, make sure
that the user-added subroutine for VLE K-values works with a sin-
gle-liquid phase composition via the XLL vector.
For enthalpy, entropy, and density calculations, the user-added sub-
routine is called for the two liquid phases individually. There is no
need to worry about dealing with two liquid compositions at once,
and later combining the results into a single bulk value. PRO/II
does this combination for you at a higher level.

Component Internal Order vs. Print Order?

PRO/II reorders components internally based on phase availability.
This is done so that calculations can be performed efficiently on
contiguous groups of components. This reordering is referred to as
SIMSCI Internal Component Order. By contrast, the sequence order
for the components selected by the user at input and in the output
reports is referred to as Print Order. This reordering impacts user-
added subroutines that assume components are ordered in Print
Order. Developers must include code to handle the internal compo-
nent order. Refer to subroutines COINUM and COPNUM in Chapter
15 for information about properly handling component data
accessed through the PRO/II interface routines.

16-2 User-Added Thermodynamic Property Methods February 2009

Communicating with PRO/II
Most PRO/II interface subroutines communicate with the user-
added subroutine through argument lists in the subroutine call;
however, there is no argument list for any of the 15 thermodynamic
property subroutines UKHS1.FOR through UKHS15.FOR. For all of
these routines, data exchange with PRO/II is via two double preci-
sion common storage blocks: DUTHERX.CMN and DCUDATA.CMN, or
their single precision alternatives UTHERX.CMN and CUDATA.CMN

DUTHERX Common Block (or UTHERX)

The DUTHERX common block passes double precision variables to
and from the PRO/II calculation engine. These variables include
temperature, pressure, vapor and liquid composition, entropy,
enthalpy, and density values. Alternatively, the UTHERX common
provides a single precision version of the common using exactly the
same variable names.
Each UKHSxx.FOR routine must include the following lines of code:
INCLUDE ‘PMXUSR.CMN’ ! brings in MAXCN
INCLUDE ‘DUTHERX.CMN’ ! double precision
or
INCLUDE ‘PMXUSR.CMN’
INCLUDE ‘UTHERX.CMN’ ! single precision
The common block includes the following variables:
COMMON / DUTHERX /
& TEMPX, TDELTX, PRESX,
& XVV, XLL, XLL2, YXSAT,
& XXSOL, XKV, DRVX, HSX1,
& HSX2, ZXX1, ZXX2,
& IFLGX, IXXFLG, JXXFLG, NOCZ,
& IFPHZ, KUOUT, KDECNT, KVTYPE,
& KDCALL

All variables are scalars except the following:

REAL*8 XVV(MAXCN), XLL(MAXCN), XLL2(MAXCN),
& XKV(MAXCN), DRVX(MAXCN)
INTEGER IFLGX(15)
The order of variables is different in DUTHERX and UTHERX. How-
ever, both use exactly the same variable names. Accessing the com-
mon by using one of the INCLUDE statements illustrated above
eliminates concerns about the declared order of variables.

PRO/II User-Added Subroutine User Guide 16-3

 Storing Returned Data
Both commons include integer variable KDCALL to control storing
or discarding data returned from the user-added subroutine in the
common block.

KDCALL This flag controls whether or not PRO/II stores data returned
in the common block. PRO/II initializes this flag to zero just
prior to each call to a user-added subroutine. When a user-
added subroutine alters data in this common with the intent
of having PRO/II store it, that user-added subroutine must set
KDCALL = 1. Upon return to PRO/II, all data is stored when
KDCALL = 1. For any other returned value of KDCALL,
any and all returned data are discarded.

Common DUTHERX and UTHERX both include a KDCALL variable.

PRO/II processes these independently. Users should avoid using
both DUTHERX and UTHERX in the same application.

Note: The size of the arrays dimensioned above (by MAXCN from
PMXUSR.CMN) corresponds to the 2500 component maxi-
mum limit discussed in “/PMXUSR/” on page 49 of Chap-
ter 15.
The input variables passed into the user-added subroutine routine
from PRO/II depend on what thermodynamic property is being cal-
culated by that routine and are shown in Table 16-1.
Table 16-1: UTHERX Input Variables Passed Into UKHSxx (xx = 1-15)
K-
Name Description Value H S rho

IXXFLG Flag indicating what data is requested valid valid valid valid
by PRO/II (see below).
JXXFLG Returned flag conveying information
back to PRO/II based on IXXFLG valid valid valid valid
request. IXXFLG and JXXFLG are
discussed below.
NOCZ Number of components in problem— valid valid valid valid
must not exceed MAXCN
IFPHZ Phase Flag n/a valid valid valid
KUOUT FORTRAN file unit number for writing valid valid valid valid
to default output file.
n/a Not applicable

16-4 User-Added Thermodynamic Property Methods February 2009

 Table 16-1: UTHERX Input Variables Passed Into UKHSxx (xx = 1-15) (Continued)
K-
Name Description Value H S rho

TEMPX Temperature at which to generate valid valid valid valid

property values (Input Units).
TDELTX Temperature increment in Input units valid valid valid n/a
for calculating derivatives.
PRESX Pressure at which property values are to valid valid valid n/a
be generated (Input Units).
XVV Array of vapor phase composition in valid valid valid valid
mole fractions.
XLL Array of liquid phase compositions in valid valid valid valid
mole fractions.
XLL2 Array of 2nd liquid phase composition
in mole fractions (if water decant is ON, valid valid valid valid
this is decanted water only).
n/a Not applicable

TEMPX, PRESX and TDELTX are all in input units, i.e., their tempera-
ture and pressure units correspond to the choices made on the
DIMENSION statement in the General Data Category of input. If con-
version to another system of units is required by the user-added
methods, then this can be accomplished using values available in
the common block FACTOR (see “/DFACTOR/ double precision” on
page 50 of Chapter 15).
The output variables passed from the user-added subroutine into
PRO/II also depend on what thermodynamic property is being cal-
culated by that routine and are shown in Table 16-2.
Table 16-2: UTHERX Output Variables Passed From UKHSxx. (xx = 1-15)
K-
Name Description Value H S rho
YXSAT Saturated vapor mole fraction for water
at TEMPX and PRESX. Required if valid n/a n/a n/a
water decant is ON (KDECNT > 0).
XXSOL Solubility of water in the non-aqueous
liquid phase expressed as molal fraction
of water at saturation. Required if water valid n/a n/a n/a
decant is ON. May be set equal to 1.0 if
decant is OFF.
n/a Not applicable

PRO/II User-Added Subroutine User Guide 16-5

 Table 16-2: UTHERX Output Variables Passed From UKHSxx. (xx = 1-15) (Continued)
K-
Name Description Value H S rho
XKV Array of the calculated component valid n/a n/a n/a
K-values
DRVX Array of derivatives of property values,
Y, with temperature, T (dY/ dT).
(If property value derivatives are
needed, TDELTX will be greater than valid valid valid valid
zero. If so, the user-added routine must
place the derivatives in the DRVX
array.)
HSX1 Enthalpy and entropy values at TEMPX n/a valid valid n/a
and PRESX
HSX2 Enthalpy and entropy values at TEMPX n/a valid valid n/a
+ TDELTX and PRESX
ZXX1 Vapor compressibility factor valid valid valid valid
ZXX2 Liquid compressibility factor valid valid valid valid
IFLGX Array of 15 Integer parameters valid valid valid valid
initialized to zero and available to the
user as counters, flags, etc.
KDECNT Position of water in the component list, valid n/a n/a n/a
if water decant is ON. Otherwise = 0.
KVTYPE Set to 1 if PRO/II requires VL K-values, valid n/a n/a n/a
2 for LL K-values, 0 for all other cases.
KDCALL Set equal to 1 to store returned data. valid valid valid valid
This variable differentiates the UTHERX
common from the older UTHERM
common.
n/a Not applicable

Variables IXXFLG and JXXFLG

These DUTHERX common flags communicate information about the
calculation status between the user-added subroutine and PRO/II.
IXXFLG PRO/II passes this flag to the user-added subroutine to indi-
cate which properties to compute (e.g., K-values, enthalpies,
etc.).
JXXFLG is returned to PRO/II from the user-added subroutine to
indicate which property values are being returned, or
whether a calculation error occurred.

16-6 User-Added Thermodynamic Property Methods February 2009

 For example, PRO/II often passes a value of -1 in IXXFLG to the
user-added subroutine. This is a request for information on the type
of K-value method used by the user-added routine. If the user-added
routine calculates K-values using a liquid activity method (such as
the NRTL method), it should return a value of 3 in JXXFLG to PRO/
II. This indicates the K-value method is strongly composition-
dependent.
Table 16-3: Values of IXXFLG, JXXFLG for Thermodynamic Property Methods
Value of Value of
Property IXXFLG Description JXXFLG Description
K-Value -1 Requests type of K- 1 K-value method not compositional
value method being dependent (i.e., not an equation of
supplied. state or liquid activity coefficient
method.)
2 K-value method is based on an
equation of state.
3 K-value method is based on liquid
activity coefficients.
K-Value 0 Initial estimates of 0 Initial K-value estimates calculated
K-values needed by using SIMSCI initial estimate
PRO/II, i.e., values methods. Note: Critical properties
not yet available in (Tc, Pc, w must be available for all
arrays XVV, XLL, components).
or XLL2.
1 The user-added K-value method
will return initial K-value estimates
via the XKV array.
99 Calculation error occurred.
K-Value 1 - K-values are needed and are
available in arrays XVV, XLL, and
XLL2. Use for all subsequent calls
to the user-added routine.
Enthalpy 2 Enthalpy values 0 Enthalpy values are being returned
requested in the form, i.e., H-H*/RT.
1 Enthalpy values are being returned
in the form H/RT.
99 Calculation error occurred.
Entropy 3 Entropy values 0 Entropy values are being returned
requested in the form, i.e., S-S*/RT.

PRO/II User-Added Subroutine User Guide 16-7

Table 16-3: Values of IXXFLG, JXXFLG for Thermodynamic Property Methods
Value of Value of
Property IXXFLG Description JXXFLG Description
1 Entropy values are being returned
in the form S/RT.
99 Calculation error occurred.
Density 4 Density values 99 Calculation error occurred.
requested.

After JXXFLG is set, the user-added routine should return to the call-
ing routine as illustrated below for a routine UKHS1 calculating
K-values using an equation of state method:
SUBROUTINE UKHS1
. . .
INCLUDE ‘PMXUSR.CMN’
INCLUDE ‘UTHERX.CMN’
. . .
IF ( IXXFLG .LE. -1 ) THEN
JXXFLG = 2
GO TO 9999
ENDIF
. . .
9999 CONTINUE
END SUBROUTINE UKHS1
In this example, IXXFLG is equal to -1, indicating a request from
PRO/II for the user-added subroutine to specify the degree of com-
positional dependency. In this case the subroutine sets and returns
JXXFLG equal to 2. This indicates the user-added subroutine imple-
ments a composition-dependent equation of state method.

DCUDATA Common Block

CUDATA Common Block
The DCUDATA common block is used to pass user-supplied double
precision data to the user-added property routine via the UDATA key-
word in the PRO/II keyword input file. The CUDATA common block
is a single precision alternative to DCUDATA. Both versions of the
common contains one variable, TDATA. TDATA is an array that may
contains 2600 elements available to transfer floating point values.

16-8 User-Added Thermodynamic Property Methods February 2009

 COMMON / DCUDATA / TDATA(2600)
or COMMON / CUDATA / TDATA(2600)
For example, assume the user-added enthalpy method UKHS1.FOR
(designated by the keyword entry ENTH=U1 on the METHOD state-
ment) requires input data that may change from one run to another
(e.g., constants from regressed data). The UDATA statement may be
used to pass these values to the user-added routine.
METHOD KVAL=SRK, ENTH=U1, ENTR=SRK, &
DENS(V)=SRK, DENS(L)=API, &
TRANS=PETRO, SET=A
ENTH
UDATA 1, 0.5 / 2, 1.0 / 3, 1.5 . . .
To enter values in the PRO/II GUI,
navigate to Input menu -> ThermoDynamic Data. Refer to
Figure 16-1.
Figure 16-1: Selecting A User-Added Subroutine in Provision

Scroll the Category list box and select User-Added Methods to

populate the Primary Methods list box. In the Primary Methods
list, highlight User-Added 1, then click the Add button (1) to
add it to the Defined Systems list (2) box (as entry U101). With

PRO/II User-Added Subroutine User Guide 16-9

 U101 highlighted, click the Modify button (3) to open the Ther-
moDynamic Data - Modification dialog box. See Figure 16-2.
Figure 16-2: Preparing to Enter Thermodynamic User Data

Click an Enter Data button on any row that displays User-

added-1 as the Current Method to open the Thermodynamic
Data - User Added... window.
Figure 16-3 shows the window with the sample data filled in. All
the data is shared among all the properties that the User-added 1
method computes. Note the Parameter Numbers correspond to the
storage elements of the TDATA array in common CUDATA.

16-10 User-Added Thermodynamic Property Methods February 2009

 Figure 16-3: User-Added Thermodynamics Data Entry

PRO/II passes these values to the user-added subroutine through the

TDATA array in the CUDATA common block:

SUBROUTINE UKHS1
. . .
INCLUDE ‘PMXUSR.CMN’
INCLUDE ‘UTHERX.CMN’
INCLUDE ‘CUDATA.CMN’
By adding two lines of code to echo the values in CUDATA:
1001 FORMAT( “ TDATA = “, 5F10.4 )
WRITE(IOUT, 1001)( TDATA(I), I = 1, 5 )
The following results could be written to the output file:
TDATA = 0.5000 1.0000 1.5000 . . .

Handling Water Decant

In PRO/II, water may be treated as a separate decant phase or as a
regular component. Using water DECANT is an alternative to using

PRO/II User-Added Subroutine User Guide 16-11

 rigorous VLLE thermodynamics. Use the WATER statement in key-
word input as shown below:
METH KVAL=U1,ENTH=U1,ENTR=CP,DENS(V)=SRK, &
DENS(L)=API, TRANS=PETRO, SET=1
WATER DECANT=ON
In the above input example, water decanting is turned ON. Thus,
water will be treated as a separate (decanted) pure component. In
normal VLE thermodynamics with DECANT=OFF, water is not dif-
ferentiated and is treated as any other component. Starting first in
version 8.1, the default used in previous versions of PRO/II is dis-
abled. PRO/II now requires an explicit WATER statement to set
DECANT=ON. Regardless of whether or not water decant is desired,
Invensys Process Systems recommends always using an explicit
WATER statement when using user-added thermodynamic methods.

To set the WATER DECANT option through the GUI

Open the Input menu and select Thermodynamic Data.
In the dialog box that opens, highlight any thermodynamic
method from the Defined Systems list box and click the Modify
button.
In the Thermodynamic Data - Modification dialog box that
opens, click the Water Options button to open the Thermody-
namic Data - Water Options dialog box.
To set DECANT=OFF, un-check the Decant Water as a Pure
Phase check box.
This option is available only when the METHOD set (selected in the
Defined System list box) supports water decanting.
When water is treated as a separate system (i.e., DECANT=ON), the
system pressure is reduced by the corresponding water partial pres-
sure and all computations are carried out on a water-free basis. The
water vapor is assumed to form an ideal vapor mixture with the
hydrocarbon and light gas vapor. When water partial pressure
reaches the saturation pressure, an ideal liquid phase consisting of
pure water will be formed. Water will dissolve in the hydrocarbon
liquid phase up to the saturation limit.
The expression for water K-values is as follows:
0
Pw
K w = -------------
- (16-1)
∏ Xs

16-12 User-Added Thermodynamic Property Methods February 2009

 where:
0
P w =vapor pressure of water
Π =system pressure

X S =solubility of the water in the hydrocarbon liquid

Use of KDECNT Flag

Integer flag KDECNT in common UTHERX allows a user-added sub-
routine to determine if water DECANT is ON or OFF, and also locates
the position of water in the component list. Table 16-4 shows the
significance of the KDECNT value.
Table 16-4: Significance of KDECNT Value
Value of
KDECNT Significance
Zero Water decant is OFF
Non-Zero Water decant is ON. The value of KDECNT is the
(positive) internal order number of water in the component list.

Note: Water decant does not require water to be in component posi-

tion number 1. Therefore, it is important to know the posi-
tion of water in the component list.

Water Decant In User-Added K-Value Methods

Vapor and liquid compositions pass to user-added K-value subrou-
tines through arrays XVV and XLL in common UTHERX. The values
in these arrays are on a dry basis when DECANT is ON.

Note: Compositions will be normalized to be on a water-free

basis when water DECANT is ON.
When water decant is ON, the user must return the following:
XKV( KDECNT ) K-value of water.
DRVX( KDECNT ) Derivative for water (as required).
YXSAT Saturation vapor mole fraction for water at
TEMPX and PRESX.
XXSOL Solubility of water in non-aqueous liquid phase
expressed as molar fraction of water at
saturation at TEMPX and PRESX.

PRO/II User-Added Subroutine User Guide 16-13

 Water Decant In Other User-Added Thermodynamic Properties
When water DECANT is ON, all thermodynamic properties of the
free water decant phase (enthalpy, entropy, etc.) are calculated using
special water property methods. This includes streams containing
H2O as the only (single) component.
Compositions of vapor and non-aqueous liquid phases are com-
puted on a wet basis. Compositions include (dissolved) water.
Therefore, when water is present in the vapor or liquid, the user
should calculate the property values for the water component using
subroutine UH2OP. The internal-order position of water when decant
is ON is available in variable KDECNT.

User-added Water Enthalpy With DECANT=ON

User-added subroutines UKHSx allow calculating k-values,
enthalpy, and entropy with user-supplied methods. The calculations
include water when DECANT=OFF. However, with DECANT=ON,
water properties normally are computed independently using inter-
nal correlation. Routine UH2OP calls the declared property methods
to compute properties for pure water, which historically did not
include user-added methods.
Starting with PRO/II version 8.2, it now is possible to use the same
user-added water enthalpy method when DECANT=ON. In keyword
input, declare a user-added method to compute enthalpy for all
components. Then, set DECANT=ON and declare the enthalpy
method for water as USER. The following is a keyword example.
THERMO
METHOD SYSTEM=SRK, ENTHALPY=U6
WATER DECANT=ON, ENTHALPY=USER
In the input sample above, ENTHALPY=U6 on the METHOD statement
specifies user-added subroutine UKHS6 to compute enthalpy.
The ENTHALPY=USER entry on the WATER statement specifies com-
puting water enthalpy using the user-added subroutine
declared for the METHOD statement. In this sample, that is
user-added subroutine UKHS6. Now, routine UKHS6 will com-
puter water enthalpy when DECANT = ON or OFF.

Example 16-1: Water Decant Property Calculations

This example assumes water DECANT is ON, so free water is han-
dled as a separate phase. This example also illustrates use of the
FACTOR common for unit conversion, the XPROPX common for

16-14 User-Added Thermodynamic Property Methods February 2009

 access to component library numbers, and subroutine UH2OP to cal-
culate pure water properties. Specific usage information, including
descriptions of the argument call lists, appears in Chapter 15, Inter-
facing Software.
SUBROUTINE UKHS1
. . .
INCLUDE ‘PMXUSR.CMN” ! Brings in MAXCN
INCLUDE ‘UTHERX.CMN’ ! Brings in thermo data
INCLUDE ‘XPROPX.CMN’ ! Brings in component data
INCLUDE ‘FACTOR.CMN’ ! Brings in conversion factors
!
! Perform this calculation ONLY if DECANT is ON
!
IF( KDECNT .GT. 0 ) THEN
!
! Use subroutine UH2OP to get water Vapor Pressure
!
CALL UH2OP( 4, 1, TEMPX, PRESX,
& TDELTX, VPW, TDERIV )
!
! Use TCONVT and TFAC from common FACTOR to
! convert TEMPX to degrees F
!
TDEGF = (TEMPX + TCONVT)* TFAC - 459.6D+0
IF( TDEGF .LE. 0.0D+0 ) TDEGF = 0.01D+0
!
! Compute XXSOL (exponent XEXP is REAL(4))
!
XEXP = (-9.0306 + 3.072 * ALOG10( TDEGF))
XXSOL = 10.0D+0 ** XEXP
!
! Compute YXSAT
!
YXSAT = VPW / PRESR
!
! Compute Water K-value and derivative dK/dT
!
XKV(KDECNT) = YXSAT / XXSOL
DRVX(KDECNT) = XKV(KDECNT) * TDERIV
END IF

Example 16-2: Regular Solution Theory K-Value Method

This subroutine calculates equilibrium K-values with the
expression:
o
γi Pi
K i = ---------
- (16-2)
P
where:

PRO/II User-Added Subroutine User Guide 16-15

 γi = liquid phase activity coefficient for component i
Pio = vapor pressure for component i
P = system pressure
Activity coefficients are calculated with the Hildebrand equation:
L 2
Vi ( δi – δm )
ln γ i = ------------------------------
- (16-3)
RT
where:
ViL = liquid molal volume for component i
δi = solubility parameter for component i
R = gas constant
T = temperature
and:
L
ΣX i V i δ i
δ m = -------------------- (16-4)
L
ΣX i V i

Liquid molal volumes and solubility parameters for each compo-

nent are entered as constants through the PRO/II keyword input file
with liquid molal volumes entered as TDATA( 1 ) - (300) and solubil-
ity parameters as TDATA( 301 ) - (600).
Allowance has been made to treat free water as a separate phase.

FORTRAN Listing

UKHS4.FOR—User-Added K-Value Method Using Regular

Solution Theory
SUBROUTINE UKHS4
!
INCLUDE ‘PMXUSR.CMN’
! This subroutine calculates K-values using
! Regular Solution Theory. Water may be
! handled as a separate phase by using the
! DECANT=ON option.
!
INCLUDE ‘FACTOR.CMN’ ! Conversion factors
INCLUDE ‘UTHERX.CMN’ ! Thermo data
! INCLUDE ‘CUDATA.CMN’ ! User-input data
!

16-16 User-Added Thermodynamic Property Methods February 2009

 REAL(4) :: STREAM(MAXCN+10), VPS(MAXCN),
& VMOLE(MAXCN), SOLU(MAXCN)
!
KDCALL = 1 ! Requests using new UTHERX
!
JXXFLG = 0 ! Initialization
ZXX1 = 0.0D+0
ZXX2 = 0.0D+0
!
! Handle PRO/II request for component
! dependency status.
! Setting JXXFLG = 3 informs PRO/II that
! this is a liquid activity method.
!
IF( IXXFLG .EQ.-1 ) THEN
JXXFLG = 3
GO TO 999
END DO
!
! Initialize local variables and arrays
!
TDERIV = 0.0D+0
STREAM( 1 : MAXCN + 10 ) = 0.0D+0
VPS( 1 : MAXCN ) = 0.0D+0
VMOLE( 1 : MAXCN ) = 0.0D+0
SOLU( 1 : MAXCN ) = 0.0D+0
!
! Set up component data
! Molar Volume are in TDATA( 1-300)
! Solubility parameters in TDATA(301-600)
! but
! The data are in PRINT order. Rearrange
! into INTERNAL order. Use routine
! COINUM to obtain internal numbers.
!
DO iCPrint = 1, NOCZ
CALL COINUM( iCPrint, IS, iCintern )
VMOLE(iCintern) = TDATA(iCPrint)
SOLU( iCintern) = TDATA(iCPrint + 300)
END DO
!
! Case 0: PRO/II requested initial K values
!
IF( IXXFLG .EQ. 0 ) THEN
JXXFLG = 0 ! Tell PRO/II to generate
GO TO 999 ! initial K-values
!
! Case N : PRO/II requested a property other

PRO/II User-Added Subroutine User Guide 16-17

 ! than K-values

!
ELSE IF( IXXFLG .NE. 1 ) THEN
JXXFLG = 99 ! fatal error return flag
GO TO 999
END IF
!
! Case 1: PRO/II requested K-values
! First fetch Component Vapor Pressures
! from PRO/II.
!
STREAM(1) = 1.0D+0 ! Initialize STREAM
STREAM(2) = TEMPX
STREAM(3) = PRESX
DO I = 4, 10
STREAM(I) = 0.0D+0
END DO
DO I = 1, NOCZ
STREAM(I+10) = 1.0D+0
END DO
ITYPE = 1
IFAZE = 1
!
CALL TTPROP( ITYPE,IFAZE,VPS,STREAM, IERR )
!
! Compute Mixture Properties
!
SOLM = 0.0D+0
VOLM = 0.0D+0
DO I=1,NOCZ
VOLI = XLL(I) * VMOLE(I)
VOLM = VOLM + VOLI
SOLM = SOLM + VOLI * SOLU(I)
END DO
IF( VOLM .GT. 0.0D+0 ) SOLM = SOLM / VOLM
PPHC = PRESX
!
! - If WATER DECANT = ON, subtract the partial
! pressure of the free water
!
IF( KDECNT .GT. 0 ) THEN
CALL H2OP( 4, 1, TEMPX, PRESX,
& TDELTX, VPS(KDECNT), TDERIV )
PPHC = PRESX * (1.0D+0 - XVV(KDECNT))
END IF
!
! Compute K-values

16-18 User-Added Thermodynamic Property Methods February 2009

 !
TDEGK = (TEMPX + TCONVT) * TFAC / XKTOR
!
DO I=1,NOCZ
GAMMA = EXP(VMOLE(I)
& * ( SOLU(I)-SOLM)**2
& / (RCONST * TDEGK) )
XKV(I) = GAMMA * VPS(I) /PPHC
END DO
!
! - Handle DECANTED WATER, if applicable
!
IF( KDECNT .GT. 0 ) THEN
DEGF = (TEMPX + TCONVT) * TFAC - FTOR
DEGF = AMAX1(DEGF, 0.01D+0)
xLogF = LOG10( DEGF )
xExp = -9.0306D+0 + 3.072D+0 * XLogF
Base10= 10.0D+0
XXSOL = Base10 ** ( xExp )
YXSAT = VPS( KDECNT ) / PRESX
XKV( KDECNT ) = YXSAT / XXSOL
END IF
!
! Compute temperature derivatives from
! the analytical expression (dKdT)
! Skip calculations if delta T is near zero
!
IF( ABS( TDELTX ) .GT. 1.0D-25 ) THEN
DO I = 1, NOCZ
DRVX(I) = -XKV(I) * VMOLE(I)
& * (SOLU(I) - SOLM)**2
& / (RCONST * TDEGK**2)
END DO
!
! Adjust for any Water Decant
!
IF( KDECNT .GT. 0 ) THEN
DRVX(KDECNT) = XKV(KDECNT) * TDERIV
END IF
END IF
C
999 CONTINUE ! Error return point
END SUBROUTINE UKHS4

PRO/II Keyword Input File

TITLE PROB=UKHS4, PROJ=UKHS4, USER=SIMSCI, &
DATE=MAR-2006

PRO/II User-Added Subroutine User Guide 16-19

 $ TESTS UKHS4
DESC TEST A USER REGULAR SOLUTION METHOD
DESC THE FIRST AND THIRD FLASHES SHOULD GIVE
DESC THE SAME RESULTS WHILE THE SECOND FLASH
DESC SHOULD DECANT WATER
COMPONENT DATA
LIBID 1,H2O/2,C1 /3,C2/4,IC4/5,NC4/ &
6,IC5/7,NC5/ 8,NC8,, C6 PLUS, &
BANK=PROII_8.3:SIMSCI, PROII_8.3:PROCESS
THERMO DATA
METHOD KVALUE=U4, ENTH=LK, DENS=LK, SET=U4REG
WATER DECANT=OFF
KVALUE
$ Liquid Volumes stored in 1-300,
$ Solubility parameters in 301-600
$
UDATA 1,18.069/ 37.97/ 59.23/ 105.24/ 96.48/ &
117.1 /116.05/ 163.01 / &
301, 23.37/ 5.67/ 6.06 / 6.145/ 6.697/ &
6.775/ 7.04/ 7.53
$
METHOD SYSTEM=U4, ENTH=LK, DENS=LK, &
ENTR=NONE, SET=U4DEC
WATER DECANT=ON
KVALUE
$ Liquid Volumes stored in 1-300,
$ Solubility parameters in 301-600
$
UDATA 1,18.069/37.97/ 59.23/105.24/ 96.48/ &
117.1 /116.05/ 163.4/ &
301,23.37/ 5.67/ 6.06/ 6.145/ 6.697/ &
6.775/ 7.04/ 7.53
$
METHOD SYSTEM=REGULAR, ENTH=LK,DENS=LK, &
ENTR=NONE, NAME=REGU
STREAM DATA
$ Feeds for User Thermo Method
PROP STRM=1, TEMP=200, PRES=150, &
COMP=2,100/3,100/4,75/5,75/ &
6, 54/7, 45/8,10
PROP STRM=20, TEMP=350, PRES=150, COMP=1,1000
$ Feeds for PRO/II thermo method
PROP STRM=1A, TEMP=200, PRES=150, &
COMP=2,100/3,100/4,75/5,75/ &
6, 54/7, 45/8,10
PROP STRM=20A, TEMP=350, PRES=150, COMP=1,1000
UNIT OPERATIONS
FLASH KPRINT, NAME=USER DRY, UID=F1

16-20 User-Added Thermodynamic Property Methods February 2009

 FEED 1
PROD L=2, V=3
ISO TEMP=150,PRES=100
METHOD SET=U4REG
FLASH KPRINT,NAME=USER DECANT,UID=F2
FEED 1,20
PROD L=4,V=5,W=6
ISO TEMP=150,PRES=100
METHOD SET=U4DEC
FLASH KPRINT,NAME=REGULAR DRY,UID=F3
FEED 1A
PROD L=7,V=8
ISO TEMP=150,PRES=100
METHOD SET=REGU
END

Partial PRO/II Output File

SIMULATION SCIENCES INC. R PAGE P-3
PROJECT UKHS4 PRO/II 5.0 UAS 386/EM
PROBLEM UKHS4 OUTPUT SIMSCI
FLASH DRUM SUMMARY JUN99
======================================================================
FLASH ID F1 F2 F3
NAME USER DRY USER DECANT REGULAR DRY
FEEDS 1 1 1A
20
PRODUCTS VAPOR 3 5 8
LIQUID 2 4 7
WATER 6
TEMPERATURE, F 150.000 150.000 150.000
PRESSURE, PSIA 100.000 100.000 100.000
PRESSURE DROP, PSI 50.000 50.000 50.000
MOLE FRAC VAPOR 0.93136 0.30654 0.93132
MOLE FRAC LIQUID 0.06864 0.69346 0.06868
MOLE FRAC MW SOLID 0.00000 0.00000 0.00000
DUTY, MM BTU/HR -0.70081 -4.00258 -0.70084
FLASH TYPE ISOTHERMAL ISOTHERMAL ISOTHERMAL

VAPOR-LIQUID COMPOSITIONS AND K-VALUES FOR UNIT 1, ‘F1’

COMPONENT VAPOR LIQUID K-VALUE
--------- -------- ------- ----------
1 H2O 0.00000 0.00000 4.9000E+01
2 C1 0.23373 0.00255 9.1770E+01
3 C2 0.23270 0.01663 1.3992E+01
4 IC4 0.16776 0.10422 1.6097E+00
5 NC4 0.16418 0.15278 1.0746E+00
6 IC5 0.10901 0.23485 4.6417E-01

PRO/II User-Added Subroutine User Guide 16-21

 7 NC5 0.08754 0.24053 3.6393E-01
8 C6 PLUS 0.00508 0.24844 2.0454E-02

VAPOR-LIQUID COMPOSITIONS AND K-VALUES FOR UNIT 2, ‘F2’

COMPONENT VAPOR LIQUID K-VALUE
----------- -------- -------- ----------
1 H2O 0.03697 0.00451 8.1945E+00
2 C1 0.22344 0.00243 9.2033E+01
3 C2 0.22258 0.01586 1.4036E+01
4 IC4 0.16136 0.09973 1.6180E+00
5 NC4 0.15835 0.14710 1.0765E+00
6 IC5 0.10622 0.22847 4.6492E-01
7 NC5 0.08566 0.23540 3.6389E-01
8 C6 PLUS 0.00543 0.26651 2.0360E-02

VAPOR-LIQUID COMPOSITIONS AND K-VALUES FOR UNIT 3, ‘F3’

COMPONENT VAPOR LIQUID K-VALUE
--------- --------- ------- ----------
1 H2O 0.00000 0.00000 4.9053E+01
2 C1 0.23374 0.00255 9.1757E+01
3 C2 0.23270 0.01673 1.3912E+01
4 IC4 0.16776 0.10422 1.6097E+00
5 NC4 0.16418 0.15279 1.0746E+00
6 IC5 0.10900 0.23485 4.6415E-01
7 NC5 0.08753 0.24052 3.6393E-01
8 C6 PLUS 0.00508 0.24835 2.0446E-02

Enthalpy and Entropy Calculations

Enthalpies and entropies may be calculated for streams based on
temperature, pressure, and composition (either liquid or vapor). See
“User-added Water Enthalpy With DECANT=ON” on page 16-14
for more information about computing water enthalpy.
Calculated enthalpies must be returned to PRO/II in dimensionless
form, that is, divided by the quantity RT where:
R= gas constant in units consistent with the problem input
dimensional units for enthalpy and those units used
for temperature.
T= temperature
Calculated enthalpies may be given in either of two forms, namely:
*
H – H- = Δ H-
---------------- ------- (16-5)
RT RT
or

16-22 User-Added Thermodynamic Property Methods February 2009

 Δ H-
------- (16-6)
RT
where:
H*= ideal gas enthalpy
When form (16-5) is used, PRO/II will always compute H*:

No. Comps.
* *
H = ∑ xi Hi (16-7)
i=1

and
xi = mole fraction for component
Hi* = ideal gas enthalpy for component
Two enthalpy values must be computed, with one at a temperature
increment above the stated temperature, where the increment is
passed through a common block. These two values are used by
PRO/II to calculate the heat capacity for the stream at the stated
temperature.
User-computed enthalpies may be used for any unit operation cal-
culation, either user- or PRO/II defined. When rigorous distillation
is to be used in conjunction with user-computed enthalpies, it is
mandatory that dimensionless partial derivatives of enthalpy with
respect to composition be computed for each component:
ΔH ⁄ Δx i
-------------------
RT
Entropies may also be computed for streams based on temperature,
pressure, and composition. Calculated values are returned on a per
mole basis in dimensionless form, that is, divided by the gas con-
stant, R.
Entropies may be computed in two forms (similar to enthalpies):
*
ΔS ⁄ Δx Si – S
------------------i = -------------
- (16-8)
RT RT
where:
S*= ideal gas entropy
or
S/R (16-9)

PRO/II User-Added Subroutine User Guide 16-23

 When equation (16-8) is used, PRO/II computes the ideal gas
entropy:

No. Comps.
* *
S = ∑ xi Si (16-10)
i=1

where:
xi = mole fraction for component i
Si* = ideal gas entropy for component i

Note: S* is computed from the ideal gas enthalpy equation. Ideal

gas enthalpy equations must be available for all compo-
nents when S* is to be computed.

Example 16-3: Petroleum Liquid and Vapor Enthalpy Calcula-

tions
Enthalpies for saturated liquids and vapors are to be generated using
the following relationships:
Liquid heat capacities are calculated using equation (16-11):

C p = [ ( 0.6811 – 0.308SG ) + 0.000815T – 0.000306SG ] . (16-11)

( 0.055K + 0.35 )
where:
Cp= heat capacity, Btu/lb °F
SG = specific gravity at 60°F
K = Watson K factor = 3 ( ABP ) ⁄ ( SG )

T = temperature, °F
ABP = average boiling point, R
The latent heat at the normal boiling point is calculated using the
following:
λb = NBP (8.75 + 4.571 log (NBP)) (16-12)
where:
λb = latent heat, cal/g-mole
NBP = normal boiling point, K

16-24 User-Added Thermodynamic Property Methods February 2009

 Finally, the latent heat at any temperature T is calculated using the
following:
T c – T ⎞ .38
λ = ⎛ ----------------
----- - (16-13)
λb ⎝ T c – T b⎠

where:
Tc = critical temperature, R
T = temperature, R
Tb = normal boiling point, R
Liquid enthalpies are calculated by integration of equation (16-11)
from 32°F to the desired temperature. Vapor enthalpies are derived
by adding the latent heat to the liquid enthalpies.
The mixture critical temperature and normal boiling point are calcu-
lated as mole-average properties.
The Watson K factor is computed based on the average normal boil-
ing point of the mixture.
PRO/II furnishes (ΔH/Δxi) terms based on the calculated enthalpy
and the component ideal gas enthalpies as supplied from the library
(for defined components) or generated by PRO/II’s petroleum char-
acterization methods. Allowance has been made to calculate water
as a separate phase.

FORTRAN Listing

UKHS3.FOR — User-Added Enthalpy Method

SUBROUTINE UKHS3
!
REAL(8), PARAMETER :: DZ0 = 0.0D+0
INCLUDE ‘FACTORS.CMN’! conversion factors
INCLUDE ‘PMXUSR.CMN’ ! brings in MAXCN
INCLUDE ‘XPROPX.CMN’ ! component data
INCLUDE ‘UTHERX.CMN’ ! thermo data
!
CHARACTER(LEN=78) :: cLine
REAL(8) :: SGL, BPL, WTL,
& TCL, WATERX, TOT
!
! - Statement function to calculate enthalpy
! from the Cp equation

PRO/II User-Added Subroutine User Guide 16-25

 XXXH(T,XK,SG) = (0.055*XK + 0.35)
& * ( (0.6811 - 0.308*SG) * (T-32)
& + 0.5 * ( 0.000815D+0 - 0.000306D+0
& * SG) * (T * T - 1024.0D+0) )
! -
!
! - Set JXXFLG to indicate H/RT is returned
JXXFLG = 1
KDCALL = 1
! - Test for correct use of this subroutine
! Error if request is not for enthalpy
IF( IXXFLG .NE. 2 ) THEN
cLine = “*** ERROR-User Method U3 “
& // “ calculates enthalpies only -”
WRITE( KUOUT, “( A )” ) cLine
cLIne = “ but IXXFLG = “
WRITE( KUOUT, “(A,I3)” ) cLine, IXXFLG
JXXFLG = 99
GO TO 99
END IF
!
! - Compute Liquid Enthalpy
!
SGL = DZ0 ! initialize summation
BPL = DZ0 ! variables
WTL = DZ0
TCL = DZ0
WATERX = DZ0
TOT = DZ0
Setup : DO I = 1, NOCZ
! Skip decant component
IF( I .EQ. KDECNT) CYCLE Setup
! Test IFPHZ for Vapor phase
IF( IFPHZ .EQ. 1 ) THEN
FLO = XVV( I ) ! Vapor phase
ELSE
FLO = XLL( I ) ! Liquid phase
END DO
SGL = SGL + XMW(I) * FLO / DENS(I)
WTL = WTL + XMW(I) * FLO
BPL = BPL + BP(I) * FLO
TCL = TCL + TC(I) * FLO
TOT = TOT + FLO
END DO Setup
SGL = ( WTL / SGL ) / SPGFAC
!
! Normalizing Molec Wt, NBP, and TC

16-26 User-Added Thermodynamic Property Methods February 2009

 ! Handle water when DECANT = ON by
! Variable WATERX = water mole fraction
!
IF( KDECNT .GT. 0 ) THEN
WTL = WTL / TOT ! molec wt
BPL = BPL / TOT ! NBP
TCL = TCL / TOT ! Tcrit
IF( IFPHZ .EQ. 1 ) THEN
WATERX = XVV( KDECNT )
ELSE
WATERX = XLL( KDECNT )
END IF
END IF
!
! Convert Tcrit and Tbp to Rankine
! Note Tcrit and Tbp already are in
! absolute temperature units
!
TCL = TCL * TFAC
BPL = ( BPL + TCONVT ) * TFAC
!
! Compute Watson K of the mixture
!
WK = BPL ** 0.33333 / SGL
!
! Convert temperatures to Fahrenheit for
! use in the Cp equation
!
T1 = ( TEMPX + TCONVT ) * TFAC - FTOR
T2 = ( TEMPX + TDELTX + TCONVT ) * TFAC
& - FTOR
!
! Integrate Cp equation to compute enthalpy
! Basis is 32 F liquid
!
HSX1 = XXXH ( T1, WK, SGL )
HSX2 = XXXH ( T2, WK, SGL )
!
! Convert temperatures back to Rankine
! for Latent Heat calculations
!
T1 = T1 + FTOR
T2 = T2 + FTOR
!
! Convert enthalpy to dimensionless form
! ( H/RT )
!
HSX1 = HSX1 * WTL / ( RCONST * T1 )

PRO/II User-Added Subroutine User Guide 16-27

 HSX2 = HSX2 * WTL / ( RCONST * T2 )
!
! Vapor
! 1. Compute Latent Heat in Btu/lb-mole
! at NBP using Kistiakowski eqn
! XLAMBP = latent heat
! 2. Use Watson corr. to determine
! DH1 = latent heat at T1
! DH2 = latent heat at T2
! 3. Add latent heat to liquid
! HSX1 = vapor enthalpy at T1
! HSX2 = vapor enthalpy at T2
!
IF ( IFPHZ .EQ. 1 ) THEN
XLAMBP = BPL * ( 8.75 +
& 4.571*LOG10( BPL / XKTOR ) )
!
DH1 = XLAMBP * ( (1.0D+0 - T1 / TCL)
& / (1.0D+0 - BPL/TCL) ) ** 0.38
DH2 = XLAMBP * ( (1.0D+0 - T2 / TCL)
& / (1.0D+0 - BPL/TCL) ) ** 0.38
HSX1 = HSX1 + DH1 / ( RCONST * T1 )
HSX2 = HSX2 + DH2 / ( RCONST * T2 )
END IF
!
! Decant Water (only when DECANT = ON)
! 1. Call H2UOP for water enth at T1, T2
! 2. Convert H2O H to dimensionless form
! 3. Add water H to get total enthalpy
!
IF( KDECNT .GT. 0 ) THEN
DELTA = DZ0
CALL UH2OP( 2, IFPHZ, TEMPX,
& PRESX, DELTA, HW1, T3 )
CALL UH2OP( 2, IFPHZ, TEMPX+TDELTX,
& PRESX, DELTA, HW2, T3 )
HW1 = HW1 * HSFAC / (RCONST * T1)
HW2 = HW2 * HSFAC / (RCONST * T2)
HSX1 = HSX1*TOT + HW1*WATERX
HSX2 = HSX2*TOT + HW2*WATERX
END IF
99 CONTINUE
END SUBROUTINE UKHS3

16-28 User-Added Thermodynamic Property Methods February 2009

 PRO/II Keyword Input File
TITLE PROB=USERADD, PROJ=UKHS3, USER=SIMSCI, &
DATE=Mar-2006
DESC Input to test sample UKHS3 routine
COMPONENT DATA
LIBID 1,H2O
THERMO DATA
METHOD KVALUE=GS, ENTHALPY=U3, ENTR=NONE, &
DENS(L)=IDEAL, DENS(V)=SRK
STREAM DATA
PROP STREAM=1, RATE(V)=16, TEMP=300, &
PRES=25
D86 STREAM=1, DATA=0,150/10,230/50,273/ &
90,320/100,395
API STREAM=1, AVG=51.3
$
PROP STREAM=2, TEMP=300, PRES=150, &
COMP=1, 100, RATE(W)=200
UNIT OP DATA
FLASH UID=F-1 $ DRY FLASH
FEED 1
PROD L=3,V=4
ADIA
FLASH UID=F-2 $ WET FLASH
FEED 1,2
PROD L=5,V=6
ADIA
END

PRO/II User-Added Subroutine User Guide 16-29

 Partial PRO/II Output
PROJECT UKHS3 PRO/II UAS 386/EM
PROBLEM USERADD OUTPUT SIMSCI
STREAM MOLAR COMPONENT RATES
==============================================================
FLASH ID F-1 F-2
NAME
FEEDS 1 1
2
PRODUCTS VAPOR 4 6
LIQUID 3 5
TEMPERATURE, F 300.000 219.166
PRESSURE, PSIA 25.000 25.000
PRESSURE DROP, PSI 0.000 0.000
MOLE FRAC VAPOR 0.32590 0.28149
MOLE FRAC TOTAL LIQUID 0.67410 0.71851
MOLE FRAC H/C LIQUID 0.67410 0.28919
MOLE FRAC FREE WATER 0.00000 0.42933
DUTY, MM BTU/HR 0.00000 0.00000
FLASH TYPE ADIABATIC-P ADIABATIC-P

PROJECT UKHS3 PRO/II UAS 386/EM

PROBLEM USERADD OUTPUT SIMSCI
STREAM MOLAR COMPONENT RATES
==============================================================
STREAM ID 1 2 3 4
NAME
PHASE MIXED WATER DRY LIQ DRY VAP
FLUID RATES, LB-MOL/HR
1 H2O 0.0000 11.1019 0.0000 0.0000
2 NBP 116 0.2066 0.0000 0.0566 0.1501
3 NBP 140 0.2544 0.0000 0.0839 0.1705
4 NBP 166 0.2384 0.0000 0.0949 0.1435
5 NBP 189 0.2362 0.0000 0.1100 0.1261
6 NBP 213 0.3354 0.0000 0.1807 0.1547
7 NBP 239 0.5490 0.0000 0.3391 0.2100
8 NBP 266 2.1353 0.0000 1.4901 0.6452
9 NBP 281 1.7531 0.0000 1.2936 0.4596
10 NBP 311 0.4020 0.0000 0.3248 0.0771
11 NBP 337 0.2575 0.0000 0.2208 0.0367
12 NBP 362 0.2016 0.0000 0.1807 0.0209
13 NBP 387 0.1810 0.0000 0.1676 0.0134
14 NBP 402 0.0295 0.0000 0.0277 1.7748E-03
TOTAL RATE, LB-MOL/HR 6.7800 11.1019 4.5704 2.2096
TEMPERATURE, F 300.0000 300.0000 300.0000 300.0000
PRESSURE, PSIA 25.0000 150.0000 25.0000 25.0000
ENTHALPY, MM BTU/HR 0.1393 0.0538 0.0763 0.0630

16-30 User-Added Thermodynamic Property Methods February 2009

 MOLECULAR WEIGHT 113.9263 18.0150 117.5334 106.4653
MOLE FRAC VAPOR 0.3259 0.0000 0.0000 1.0000
MOLE FRAC TOTAL LIQ 0.6741 1.0000 1.0000 0.0000
MOLE FRAC H/C LIQUID 0.6741 0.0000 1.0000 0.0000
MOLE FRAC FREE WATER 0.0000 1.0000 0.0000 0.0000

PROJECT UKHS3 PRO/II UAS 386/EM

PROBLEM USERADD OUTPUT SIMSCI
STREAM MOLAR COMPONENT RATES
==============================================================
STREAM ID 5 6
NAME
PHASE WET LIQUID WET VAPOR
FLUID RATES, LB-MOL/HR
1 H2O 7.7220 3.3799
2 NBP 116 0.0620 0.1446
3 NBP 140 0.0948 0.1596
4 NBP 166 0.1095 0.1289
5 NBP 189 0.1282 0.1080
6 NBP 213 0.2105 0.1249
7 NBP 239 0.3915 0.1576
8 NBP 266 1.6908 0.4446
9 NBP 281 1.4514 0.3018
10 NBP 311 0.3560 0.0460
11 NBP 337 0.2374 0.0202
12 NBP 362 0.1910 0.0106
13 NBP 387 0.1747 6.2863E-03
14 NBP 402 0.0287 7.9667E-04
TOTAL RATE, LB-MOL/HR 12.8483 5.0335
TEMPERATURE, F219.1656219.1656
PRESSURE, PSIA 25.0000 25.0000
ENTHALPY, MM BTU/HR 0.0831 0.1100
MOLECULAR WEIGHT 57.5859 46.1978
MOLE FRAC VAPOR 0.0000 1.0000
MOLE FRAC TOTAL LIQUID 1.0000 0.0000
MOLE FRAC H/C LIQUID 0.4025 0.0000
MOLE FRAC FREE WATER 0.5975 0.0000

PRO/II User-Added Subroutine User Guide 16-31

PROJECT UKHS3 PRO/II UAS 386/EM
PROBLEM USERADD OUTPUT SIMSCI
STREAM SUMMARY
======================================================================
STREAM ID 1 2 3 4
NAME
PHASE MIXED WATER DRY LIQ DRY VAP

——- TOTAL STREAM ——- ---------- ---------- ---------- ----------

RATE, LB-MOL/HR 6.780 11.102 4.570 2.210
M LB/HR 0.772 0.200 0.537 0.235
TEMPERATURE, F 300.000 300.000 300.000 300.000
PRESSURE, PSIA 25.000 150.000 25.000 25.000
MOLECULAR WEIGHT 113.926 18.015 17.533 106.465
ENTHALPY, MM BTU/HR 0.139 5.38E-02 7.63E-02 6.29E-02
BTU/LB 180.359 269.082 142.126 267.665
MOLE FRACTION LIQUID 0.67410 1.000 1.000 0.000
MOLE FRAC FREE WATER 0.000 1.000 0.000 0.000

——- TOTAL VAPOR ———

RATE, LB-MOL/HR 2.210 N/A N/A 2.210
M LB/HR 0.235 N/A N/A 0.235
M FT3/HR 0.681 N/A N/A 0.681
STD VAP RATE(1), M FT3/HR 0.839 N/A N/A 0.839
MOLECULAR WEIGHT 106.465 N/A N/A 106.465
ENTHALPY, BTU/LB 267.665 N/A N/A 267.665
CP, BTU/LB-F 0.440 N/A N/A 0.440
DENSITY, LB/M FT3 345.276 N/A N/A 345.276
Z (FROM DENSITY) 0.9456 N/A N/A 0.9456

——- TOTAL LIQUID ——-

RATE, LB-MOL/HR 4.570 11.102 4.570 N/A
M LB/HR 0.537 0.20 0.537 N/A
FT3/HR 13.058 3.490 13.058 N/A
GAL/MIN 1.628 0.435 1.628 N/A
STD LIQ RATE, FT3/HR 11.072 3.208 11.072 N/A
MOLECULAR WEIGHT 117.533 18.015 117.533 N/A
ENTHALPY, BTU/LB 142.126 269.082 142.126 N/A
CP, BTU/LB-F 0.607 1.013 0.607 N/A
DENSITY, LB/FT3 41.137 57.305 41.137 N/A
Z (FROM DENSITY) 8.7614E-0 5.7842E-03 8.7614E-03 N/A

(1) STANDARD VAPOR VOLUME IS 379.49 FT3/LB-MOLE (60 F AND 14.696 PSIA)

16-32 User-Added Thermodynamic Property Methods February 2009

======================================================================
STREAM ID 1 2 3 4
NAME
PHASE MIXED WATER DRY LIQ DRY VAP
——- DRY STREAM ——- ---------- ---------- ---------- ----------
RATE, LB-MOL/HR 6.780 N/A 4.570 2.210
M LB/HR 0.772 N/A 0.537 0.235
STD LIQ RATE, FT3/HR 16.000 N/A 11.072 4.928
MOLECULAR WEIGHT 113.926 N/A 117.533 106.465
MOLE FRACTION LIQUID 0.6741 N/A 1.0000 0.0000
REDUCED
TEMP (KAYS RULE) 0.7150 N/A 0.7062 0.7339
PRES (KAYS RULE) 0.0588 N/A 0.0602 0.0561
ACENTRIC FACTOR 0.3182 N/A 0.3284 0.2973
WATSON K (UOPK) 11.618 N/A 11.618 11.618
STD LIQ DENSITY,
LB/FT3 48.276 N/A 48.517 47.734
SPEC GRAVITY 0.7741 N/A 0.7779 0.7654
API GRAVITY 51.300 N/A 50.392 53.374

——— DRY VAPOR ———-

RATE, LB-MOL/HR 2.210 N/A N/A 2.210
M LB/HR 0.235 N/A N/A 0.235
M FT3/HR 0.681 N/A N/A 0.681
STD VAP RATE(1),
M FT3/HR 0.839 N/A N/A 0.839
SPECIFIC GRAVITY
(AIR=1.0) 3.676 N/A N/A 3.676
MOLECULAR WEIGHT 106.465 N/A N/A 106.465
CP, BTU/LB-F 0.440 N/A N/A 0.440
DENSITY, LB/M FT3 345.276 N/A N/A 345.276

——— DRY LIQUID ———

RATE, LB-MOL/HR 4.570 N/A 4.570 N/A
M LB/HR 0.537 N/A 0.537 N/A
FT3/HR 13.058 N/A 13.058 N/A
GAL/MIN 1.628 N/A 1.628 N/A
STD LIQ RATE, FT3/HR 11.072 N/A 11.072 N/A
SPECIFIC GRAVITY
(H2O=1.0) 0.7779 N/A 0.7779 N/A
MOLECULAR WEIGHT 117.533 N/A 117.533 N/A
CP, BTU/LB-F 0.607 N/A 0.607 N/A
DENSITY, LB/FT3 41.137 N/A 41.137 N/A
(1) STANDARD VAPOR VOLUME IS 379.49 FT3/LB-MOLE (60 F AND 14.696 PSIA)

PRO/II User-Added Subroutine User Guide 16-33

PROJECT UKHS3 PRO/II UAS 386/EM
PROBLEM USERADD OUTPUT SIMSCI
STREAM SUMMARY
==============================================================
STREAM ID 5 6
NAME
PHASE WET LIQUID WET VAPOR
——- TOTAL STREAM ——-
RATE, LB-MOL/HR 12.848 5.033
M LB/HR 0.740 0.233
TEMPERATURE, F 219.166 219.166
PRESSURE, PSIA 25.000 25.000
MOLECULAR WEIGHT 57.586 46.198
ENTHALPY, MM BTU/HR 8.311E-02 0.110
BTU/LB 112.335 473.109
MOLE FRACTION LIQUID 1.00000 0.00000
MOLE FRACTION FREE WATER 0.59752 0.00000
——- TOTAL VAPOR ———
RATE, LB-MOL/HR N/A 5.033
M LB/HR N/A 0.233
M FT3/HR N/A 1.439
STD VAP RATE(1), M FT3/HR N/A 1.910
MOLECULAR WEIGHT N/A 46.198
ENTHALPY, BTU/LB N/A 473.109
CP, BTU/LB-F N/A 0.440
DENSITY, LB/M FT3 N/A 161.601
Z (FROM DENSITY) N/A 0.9810
——- TOTAL LIQUID ——-
RATE, LB-MOL/HR 12.848 N/A
M LB/HR 0.740 N/A
FT3/HR 16.039 N/A
GAL/MIN 2.000 N/A
STD LIQ RATE, FT3/HR 14.621 N/A
MOLECULAR WEIGHT 57.586 N/A
ENTHALPY, BTU/LB 112.335 N/A
CP, BTU/LB-F 0.645 N/A
DENSITY, LB/FT3 46.129 N/A
Z (FROM DENSITY) 4.2840E-03 N/A
(1) STANDARD VAPOR VOLUME IS 379.49 FT3/LB-MOLE
(60 F AND 14.696 PSIA)

16-34 User-Added Thermodynamic Property Methods February 2009

PROJECT UKHS3 PRO/II UAS 386/EM
PROBLEM USERADD OUTPUT SIMSCI
STREAM SUMMARY
==============================================================
STREAM ID 5 6
NAME
PHASE WET LIQUID WET VAPOR
——— DRY STREAM ———
RATE, LB-MOL/HR 5.126 1.654
M LB/HR 0.601 0.172
STD LIQ RATE, FT3/HR 12.389 3.611
MOLECULAR WEIGHT 117.193 103.801
MOLE FRACTION LIQUID 1.0000 0.0000
REDUCED TEMP (KAYS RULE) 0.6317 0.6623
PRES (KAYS RULE) 0.0601 0.0551
ACENTRIC FACTOR 0.3274 0.2897
WATSON K (UOPK) 11.618 11.618
STD LIQ DENSITY, LB/FT3 48.492 47.535
SPECIFIC GRAVITY 0.7775 0.7622
API GRAVITY 50.485 54.151
——— DRY VAPOR ———-
RATE, LB-MOL/HR N/A 1.654
M LB/HR N/A 0.172
M FT3/HR N/A 0.471
STD VAP RATE(1), M FT3/HR N/A 0.628
SPECIFIC GRAVITY (AIR=1.0) N/A 3.584
MOLECULAR WEIGHT N/A 103.801
CP, BTU/LB-F N/A 0.596
DENSITY, LB/M FT3 N/A 364.571
——— DRY LIQUID ———
RATE, LB-MOL/HR 5.126 N/A
M LB/HR 0.601 N/A
FT3/HR 13.707 N/A
GAL/MIN 1.709 N/A
STD LIQ RATE, FT3/HR 12.389 N/A
SPECIFIC GRAVITY (H2O=1.0) 0.7775 N/A
MOLECULAR WEIGHT 117.193 N/A
CP, BTU/LB-F 0.561 N/A
DENSITY, LB/FT3 43.829 N/A
(1) STANDARD VAPOR VOLUME IS 379.49 FT3/LB-MOLE (60 F AND 14.696 PSIA)

PRO/II User-Added Subroutine User Guide 16-35

Density Calculations
Example 16-4: Gunn-Yamada Liquid Density Calculations
For this example, the Gunn-Yamada method is used to calculate
actual liquid densities. Vapor densities correspond to those com-
puted by the enthalpy or K-value subroutine (based on the correla-
tions used).
For the Gunn-Yamada method:

V- = -----
C-
---- (16-14)
Vr Cr

where:
V, Vr=volume at desired and reference temperatures
C, Cr=density factors at desired and reference temperatures
and
(0)
C = V T r ( 1 – ωΓT r ) (16-15)

where:
2
Γ = 0.29607 – 0.09045T r – 0.04842T r (16-16)

Tr = reduced temperature

ω = acentric factor
and (for 0.2 ≤ Tr ≤ 0.8)
(0) 2
V = 0.33593 – 0.33953T r + 1.51941T r
3 4 (16-17)
– 2.02512T r + 1.11422T r

and (for 0.8 < Tr ≤ 0.99)

(0)
V = 1 + 1.3 1 – T r log ( 1 – T r ) – 0.50879 ( 1 – T r )
2 (16-18)
– 0.91534 ( 1 – T r )

Mixture critical temperatures are evaluated with Kay’s rule, and the
method is limited to a range: 0.2 ≤ Tr ≤ 0.99. Reference densities
are computed using the pure component specific gravities at 60°F,
as provided in the component data.
Reference: Gunn, R. D. and Yamada, T., 1971, AIChE J., 17:1341

16-36 User-Added Thermodynamic Property Methods February 2009

 FORTRAN Listing

UKHS1.FOR — User-Added Liquid Density Method

SUBROUTINE UKHS1
!
! Compute Liquid Densities at flowing
! conditions using the GUNN-YAMADA method
!-
INCLUDE ‘PMXUSR.CMN’ ! brings in MAXCN
INCLUDE FACTOR.CMN’ ! conversion factors
INCLUDE ‘XPROPX.CMN’ ! component data
INCLUDE ‘UTHERX.CMN’ ! Thermo data
!
REAL(4) :: XVV(MAXCN), XLL(MAXCN),
& XLL2(MAXCN), XKV(MAXCN),
& DRVX(MAXCN)
INTEGER(4) :: IFLGX(15)
!
! Statement functions to evaluate GAMMA and
! V0 terms at given Tr’s
!
XXXGAM(TR) = 0.29607D+0 - 0.09045 * TR
& - 0.04842 * TR * TR
!
! Tr from 0.2 to 0.8
!
XXXZOL(TR) = 0.33593D0
& - 0.33953D0 * TR + 1.51941D0 *TR * TR
& - 2.02512D0 * TR * TR * TR
& + 1.11422D0 * TR * TR * TR * TR
!
! Tr from 0.8 to 0.99
!
XXXZOH(TR) = 1.0D0 + 1.3D0 * (1.0D0-TR)
& **0.5*LOG10(1.-TR)
& -0.50879D0 * (1.0D0 - TR)
& -.91534D0 * (1.-TR)*(1.0D0 - TR)
!
! Test that Liquid Density was requested
!
IF( IXXFLG .NE. 4 .OR. IFPHZ .NE. 2 )THEN
JXXFLG = 99
GO TO 9999
ENDIF
!
! Set KDCALL = 1 (used common UTHERX)
!
KDCALL = 1

PRO/II User-Added Subroutine User Guide 16-37

 !
! Convert pressure to psia
!
PSIA = (PRESX + PCONVT) * PFAC
!
! Convert flowing temperature to deg Rankine
!
TDEGR = (TEMPX + TCONVT) * TFAC
!
! Compute mixture molec wt, Tcrit, acentric
! factor and sp.gr at 60F
WTM = 0.0D0
ACEN = 0.0D0
TCRM = 0.0D0
DENM = 0.0D0
DO I = 1, NOCZ
ACEN = ACEN + XLL(I) * OMEGA(I)
TCRM = TCRM + XLL(I) * TC(I)
DENM = DENM + XLL(I) * XMW(I)/DENS(I)
WTM = WTM + XLL(I) * XMW(I)
END DO
!
DENM = WTM / DENM
!
! Convert mixture density to SPGR at 60 F
!
SPGM = DENM / SPGFAC
!
! Convert TCRM to deg R (Note Tcs already
! are in absolute temperature units)
TCRM = TCRM * TFAC
!
! Evaluate Tr and compute density factor
! at flowing conditions
!
TRF = TDEGR / TCRM
!
! Reset Tr if .GE. 1.
!
IF (TRF .GE. 1.0D0) TRF = 0.99D+0
IF (TRF .LE. 0.8D0) VZERO = XXXZOL(TRF)
IF (TRF .GT. 0.8D0) VZERO = XXXZOH(TRF)
CFLOW = VZERO * TRF * (1.0D0
& - (ACEN * TRF * XXXGAM(TRF)))
!

! Correct Tr and correction factor at

! 60 deg F (Reference temperature)

16-38 User-Added Thermodynamic Property Methods February 2009

 !
TRR = (60.0D0 + FTOR) / TCRM
!
! Reset Tr if it is .GE. 1.
!
IF( TRR .GE. 1.0D0 ) TRR = 0.99
IF( TRR .LE. 0.8D0 ) VZERO = XXXZOL(TRR)
IF( TRR .GT. 0.8D0 ) VZERO = XXXZOH(TRR)
CREF = VZERO * TRR
& * (1.0D0 - (ACEN *TRR *XXXGAM(TRR)))
!
!
! Compute the flowing density in lb/ft3
!
DENSE = CFLOW * SPGM * 62.2997D0 / CREF
!
! Convert flowing density to ft3/lb mole
!
VOLU = WTM / DENSE
!
! Convert flowing density to a Z factor
!
ZXX2 = PSIA * VOLU / 10.731D0 / TDEGR
!
9999 CONTINUE
!
END SUBROUTINE UKHS1

PRO/II User-Added Subroutine User Guide 16-39

 PRO/II Keyword Input File
TITLE PROB=USERADD, PROJ=UKHS1, USER=SIMSCI, &
DATE=Mar-2006
$
$ TESTS UKHS1
$
COMP DATA
LIBID 1, C2 / 2, C3 / 3, NC4 / 4, NC5
THERMO DATA
METHODS KVALUE=GS, ENTH=SRK, DENS(L)=U1, &
DENS(V)=SRK
STREAM DATA
PROP STRM=1, TEMP=150, PRES=150, &
COMP= 25 / 25 / 25 / 25
UNIT OPERATIONS
FLASH
FEED 1
PROD L=2, V=3
ISO TEMP=150, PRES=200
FLASH
FEED 1
PROD L=4, V=5
ISO TEMP=200, PRES=150
END

Partial PRO/II Output File

SIMULATION SCIENCES INC. R PAGE P-5
PROJECT UKHS1 PRO/II UAS 386/EM
PROBLEM USERADD OUTPUT SIMSCI
STREAM SUMMARY Mar-2006
==============================================================
STREAM ID 1 2 3 5
NAME
PHASE MIXED LIQUID VAPOR VAPOR
——- TOTAL STREAM ——- ---------- ---------- ---------- ----------
RATE, LB-MOL/HR 100.000 54.570 45.430 100.000
M LB/HR 5.111 3.134 1.977 5.111
STD LIQ RATE, FT3/HR 154.342 88.242 66.100 154.342
TEMPERATURE, F 150.000 150.000 150.000 200.000
PRESSURE, PSIA 150.000 200.000 200.000 150.000
MOLECULAR WEIGHT 51.111 57.437 43.511 51.111
ENTHALPY, MM BTU/HR 0.778 0.221 0.398 1.164
BTU/LB 152.246 70.536 01.417 227.785

16-40 User-Added Thermodynamic Property Methods February 2009

 MOLE FRACTION LIQUID 0.3247 1.0000 0.0000 0.0000
REDUCED TEMP(KAYS RULE) 0.8629 0.8116 0.9338 0.9337
PRES(KAYS RULE) 0.2538 0.3582 0.3172 0.2538
ACENTRIC FACTOR 0.1759 .1986 0.1485 0.1759
WATSON K (UOPK) 14.467 13.816 15.501 14.467
STD LIQ DEN, LB/FT3 33.115 5.520 29.905 33.115
SPEC. GRAVITY 0.5310 0.5695 0.4795 0.5310
API GRAVITY 134.991 116.949 163.598 134.991

———— VAPOR ————-

RATE, LB-MOL/HR 67.53 N/A 45.430 100.000
M LB/HR 3.142 N/A 1.977 5.111
M FT3/HR 2.554 N/A 1.250 4.133
STD VAP RATE(1),
M FT3/HR 5.627 N/A 17.240 37.948
SPECIFIC GRAVITY
(AIR=1.0) 1.606 N/A 1.502 1.765
MOLECULAR WEIGHT 46.52 N/A 43.511 51.111
ENTHALPY, BTU/LB 204.446 N/A 201.417 227.785
CP, BTU/LB-F 0.486 N/A 0.501 0.509
DENSITY, LB/M FT3 230.509 N/A 1581.297 1236.654
Z (FROM DENSITY) 0.8669 N/A 0.8411 0.8757
———— LIQUID ————
RATE, LB-MOL/HR 32.470 54.570 N/A N/A
M LB/HR 1.969 3.134 N/A N/A
FT3/HR 41.561 7.341 N/A N/A
GAL/MIN 5.182 8.396 N/A N/A
STD LIQ RATE, FT3/HR 53.889 88.242 N/A N/A
SPECIFIC GRAVITY (H2O=1.0) 0.5858 0.5695 N/A N/A
MOLECULAR WEIGHT 60.638 57.437 N/A N/A
ENTHALPY, BTU/LB 68.941 70.536 N/A N/A
CP, BTU/LB-F 0.665 0.686 N/A N/A

DENSITY, LB/FT3 47.373 46.544 N/A N/A

Z (FROM DENSITY) 0.0293 0.0377 N/A N/A

(1) STANDARD VAPOR VOLUME IS 379.49 FT3/LB-MOLE (60 F AND 14.696 PSIA)

THE FOLLOWING ZERO-RATE STREAMS WERE NOT PRINTED

4

PRO/II User-Added Subroutine User Guide 16-41

16-42 User-Added Thermodynamic Property Methods February 2009
 Chapter 17 Transport and Special
Property Subroutines
Each transport property subroutine has the capability of calculating
viscosity, thermal conductivity, and surface tension for a given
stream phase. Viscosity and thermal conductivity are supported by
liquid and vapor phases. Surface tension applies to liquid phases
only.

Note: Liquid diffusivities cannot be calculated by a user-added

transport subroutine.
Roughly the first half of this chapter discusses user-added transport
properties. The latter half discusses user-added special property
subroutines.

User-Added Transport Property Subroutines

User Information
As a user, it is your responsibility to ensure that there is a corre-
spondence between the method selected in the input data and the
properties supported by the subroutine.

Transport Method Selection Using Keywords

Table 17-1 shows the correspondence between PRO/II keyword
input property methods and user-added transport property methods.

Table 17-1: PRO/II Keywords for User-Added Transport

Statement Keyword Entry
METHOD TRANSPORT U1, U2, U3, U4, or U5
or VISCOSITY= U1, U2, U3, U4, or U5
or VISCOSITY(V)= U1, U2, U3, U4, or U5
or VISCOSITY(L)= U1, U2, U3, U4, or U5

PRO/II User-Added Subroutine User Guide 17-1

 Table 17-1: PRO/II Keywords for User-Added Transport
Statement Keyword Entry
or CONDUCTIVITY= U1, U2, U3, U4, or U5
or CONDUCTIVITY(V)= U1, U2, U3, U4, or U5
or CONDUCTIVITY(L)= U1, U2, U3, U4, or U5
or SURFACE= U1, U2, U3, U4, or U5

Note: The keywords VISCOSITY and CONDUCTIVITY may have qual-

ifiers (V) or (L) associated with them. The qualifiers limit
the property calculations to the vapor or liquid phase,
respectively. When no qualifier is present, the property
method applies to both liquid and vapor calculations.

Transport Method Selection Using ProVision

Selecting user-added transport property methods in the ProVision
GUI is simple. Figure 17-1 shows the Transport Properties Dialog
box used for transport property methods selection.
Figure 17-1: Selecting User-added Transport Properties

Figure 17-1 shows an example of using the U1 method to compute

liquid viscosity, liquid thermal conductivity, and surface tension.
Follow these steps to obtain this configuration using ProVision.

17-2 Transport and Special Property Subroutines February 2009

 Select Thermodynamic Data from the Input menu.
Highlight any methods group in the Category list box to popu-
late the Primary Methods list box.
Highlight the desired system in the Primary Methods list box
and click the Add button to move it to the Defined Systems list
box.
Highlight a method in the Defined Systems list and click the
Modify button to open the Modification dialog box.
In the drop-down list boxes for Liquid Viscosity, Liquid Ther-
mal Conductivity, and Surface Tension, select User-added 1.
Users need to know which properties each user-added subroutine
supports. PRO/II cannot determine this. Any properties not sup-
ported by a user-added subroutine may be computed by selecting an
alternative PRO/II method from each drop-down list box.
Each user-added transport method available through input (U1, U2,
U3, U4, or U5 in keywords, User-added 1 through User-added 5 in
the GUI) corresponds to a particular transport property subroutine.
Table 17-2 shows the transport property subroutine that corresponds
to each keyword entry.
Table 17-2: Subroutine to Keyword to GUI Input
Correspondence
Keyword User-added
Method GUI Method Subroutine
U1 User-added 1 UTRAN1
U2 User-added 2 UTRAN2
U3 User-added 3 UTRAN3
U4 User-added 4 UTRAN4
U5 User-added 5 UTRAN5

PRO/II User-Added Subroutine User Guide 17-3

 Transport Property Developer Information
This section presents information primarily of interest to developers
of user-added Transport Properties subroutines. Following these
guidelines helps ensure a successful implementation.
Only subroutine developers can decide which properties a subrou-
tine calculates. However, they also have the responsibility of pro-
viding this information to their intended end-users.

Transport Property Subroutine Coding Guidelines

Each call from PRO/II expects the subroutine to return a single
value for one property of the specified phase. If the subroutine does
not calculate a property value, it should return a value of zero in
variable VALUE.
Calling sequence:
SUBROUTINE UTRANn( IPHASE, ICODE, STRM, VALUE )
where:

n The number of the transport property routine ( 1 to 5 ).

IPHASE Input Integer scalar flag indicating the requested
phase.
1 Vapor property requested
2 Liquid property requested
ICODE Input Integer scalar flag indicating the requested
property.
1 Thermal conductivity requested
2 Viscosity requested
3 Surface tension requested (only when IPHASE = 2)
STRM Input single-precision standard user stream vector that
contains the phase data that serve as the basis for the
calculations. Inside the subroutine, this should be
dimensioned as an automatic array (use an asterisk for
the number of elements). All stream values are passed
in from PRO/II in problem input dimensional units.
VALUE Output double precision scalar. This variable returns
the calculated value of the requested property in
problem input units.

Note: Each UTRANn subroutine may use any of the user-added

capabilities documented in Table 15-1 on page 15-2 of this
manual with the following exception: Do not call subrou-
tine TTPROP with ITYPE=3 or greater from within
UTRANn.

17-4 Transport and Special Property Subroutines February 2009

 Pure component data may be retrieved from the /XPROPX/ common
block as described in Chapter 15. In special situations, pure compo-
nent data also may be available in common /XPROPY/, described
in Chapter 20, UAS Refinery Reactor Simulation.

Note: The subroutine should convert returned values to input

units before returning them in variable VALUE. The
/FACTOR/ common block provides conversion factors for
this purpose. However, you must first convert them to cen-
tipoise (for viscosity), Btu/hr./oF/ft (for conductivity), and
dynes/cm (for surface tension) as documented in Chapter
16, User-Added Thermodynamic Property Methods.
Example Problems
Example 17-1: Calculating Transport Properties Using User-Supplied
Transport Data Points
Sometimes it might be desirable to directly input the value of a
transport property to be used in PRO/II calculations rather than
have it be predicted by the simulator. An example might arise in
modeling rigorous heat exchangers in a refinery pre-heat train. If
you know the viscosity of your crude oil as a function of tempera-
ture (and if you know that none of it vaporizes in the exchangers),
you might want to put in those viscosities directly for use in the rig-
orous HX calculations. This can be easily accomplished with a user-
added subroutine.
In this example, subroutine UTRAN2 calculates any transport prop-
erty by interpolating or extrapolating tabular property data (up to 10
points) supplied by the user. Interpolation and extrapolation may be
linear or may be specified to be ln(prop) vs. 1/T. The required infor-
mation is entered through keyword input using the UDATA statement.
The values are stored and available in the UTRAN2 routine from
array TDATA of common block /CUDATA/. The element numbers in
UDATA correspond to the same element numbers in TDATA. The input
data is defined as follows:

TDATA( 1 ) NPTS = number of tabular data points

TDATA( 2 ) Interpolation/extrapolation flag
1 = linear
2 = ln(prop) vs. 1/T
TDATA( 11 to Temperatures in input units, in ascending
10 + NPTS ) order

PRO/II User-Added Subroutine User Guide 17-5

 TDATA( 21 to Corresponding property values in input
20 + NPTS ) units

FORTRAN Listing

UTRAN2.FOR — User-Added Calculation Routine

SUBROUTINE UTRAN2(IPHASE, ICODE, STREAM, VALUE)
!
INCLUDE ‘PMXUSR.CMN’ ! brings in MAXCN
INCLUDE ‘FACTOR.CMN’ ! conversion factors
INCLUDE ‘XPROPX.CMN’ ! component properties
INCLUDE ‘UTHERX.CMN’ ! thermodynamics data
!
! Argument declarations
INTEGER(4), INTENT(IN) :: IPHASE, ICODE
REAL(4) :: STREAM(*) ! automatic array sizing
REAL(4), INTENT(OUT) :: VALUE
!
! Local declarations
!
REAL(8) :: TK(10), TEMPK, THI, TLO,
& VHI. VLO
INTEGER(4) :: NPTS, ifErr, INFLG
CHARACTRER(LEN=212) :: cLine ! for errors
!
! ---------- Code begins here ----------
!
VALUE = 0.0D+0 ! initialize return value
ifErr = 0 ! error counter
!
! Error return if requested property is not
! viscosity or phase is not liquid.
!
IF( ICODE .NE. 2 .OR. IPHASE .NE. 2 ) THEN
JXXFLG = 99 ! error flag in /UTHERX/
GO TO 999
ENDIF
!
! Error if number of points is invalid
! ( must be between 2 and 10 )
!
NPTS = ANINT( TDATA( 1 ) ) ! handle round-off
IF( NPTS .LT. 2 ) THEN
cLine = “ERROR - At least 2 points “
& // “are required.”
CALL UAERR( “E”, 0, cLine )
ifErr = ifErr + 1

17-6 Transport and Special Property Subroutines February 2009

 ELSE IF( NPTS .GT. 10 ) THEN
cLine = “ERROR - No more than 10 “
& // “points are required.”
CALL UAERR( “E”, 0, cLine )
ifErr = ifErr + 1
ENDIF
!
! Error if Interp/Extrap flag is not 1 or 2
!
INFLG = ANINT( TDATA( 2 ) )
IF( INFLG .LE. 1 ) THEN
INFLG = 1
ELSE IF( INFLG .GT. 2 ) THEN
cLine = “ERROR - Extrapolation flag “
// “is invalid (exceeds 2).”
CALL UAERR( “E”, 0, cLine )
ifErr = ifErr + 1
ENDIF
!
! Error any zero or negative data.
! Error if any temperatures do not increase.
!
DO I = 1, NPTS
TK(I) = (TDATA(10+I)+TCONVT)*TFAC/XKTOR
IF( TK(I) .LE. 0.0D0 ) THEN
cLine = “ERROR - Invalid value in “
& // “data item “
WRITE(cLine(36:38),”(I3)”) I
CALL UAERR( “E”, 0, cLine )
ifErr = ifErr + 1
ELSE IF (TDATA(20+I) .LE. 0.0D0) THEN
cLine = “ERROR - Invalid value in “
& // “data item “
WRITE(cLine(36:38),”(I3)”) I
CALL UAERR( “E”, 0, cLine )
ifErr = ifErr + 1
ELSE IF( I .GT. 1 ) THEN
IF( TK(I) .LE. TK(I-1) ) THEN
cLine = “ERROR - Temperatures “
& // “must be in increasing order”
CALL UAERR( “E”, 0, cLine )
ifErr = ifErr + 1
ENDIF
ENDIF
END DO
!
! Error exit if any errors were found
!

PRO/II User-Added Subroutine User Guide 17-7

 IF( ifErr .GT. 0 ) THEN
cLine = “[UTRAN2] found input errors”
CALL UAERR( “E”, 0, cLine )
JXXFLG = 99 ! error flag in /UTHERX/
GO TO 999
END IF
!
! Convert stream temperature to Kelvin
!
TEMPK = (STREAM(2)+TCONVT) * TFAC / XKTOR
!
! Bracket stream temperature between 2 data
! temperatures.
! Use T1 & T2 if stream temp is below T1
! Use last 2 temps if stream temp is above
! the last data temperature
!
IF( TEMPK .LE. TK(1) ) THEN
THI = TK(2)
TLO = TK(1)
VHI = TDATA(22)
VLO = TDATA(21)
ELSE IF (TEMPK .GE. TK(NPTS)) THEN
THI = TK(NPTS)
TLO = TK(NPTS-1)
VHI = TDATA(20+NPTS)
VLO = TDATA(19+NPTS)
ELSE
!
! Bound temperature above and below
!
DO I = 2, NPTS
IF (TK(I) .GE. TEMPK) THEN
THI = TK(I)
TLO = TK(I-1)
VHI = TDATA(20+I)
VLO = TDATA(19+I)
ENDIF
END DO
END IF
!
! Interpolate based on flag.
! INFLG = 1 means Linear interpolation
!
IF( INFLG .LE. 1 ) THEN
SLOPE = (VHI-VLO) / (THI-TLO)
VALUE = VLO + SLOPE*(TEMPK-TLO)
!
 ! INFLG = 2 means log(prop) vs 1/Temp
!
ELSE IF( INFLG .EQ. 2 ) THEN
VHILN = LOG(VHI)
VLOLN = LOG(VLO)
THIINV = 1.D0 / THI
TLOINV = 1.D0 / TLO
TINV = 1.D0 / TEMPK
SLOPE = (VHILN-VLOLN) / (THIINV-TLOINV)
VALUE = VLOLN + SLOPE * (TINV-TLOINV)
VALUE = EXP( VALUE )
ENDIF
!
999 CONTINUE ! error exit point
END SUBROUTINE UTRAN2

PRO/II Keyword Input File

TITLE PROJECT=USERADD,PROBLEM=UTRAN2, USER=SIMSCI,
DATE=03/01/2006
PRINT RATE=M, STREAM=ALL, INPUT=ALL
DIME ENGLISH
COMPONENT DATA
LIBID 1,ETHANE/2,PROPANE/3,IBUTANE/4,BUTANE/ 5,PENTANE
TBPCUTS 115,300,6/400,10/650,8/800,4/1500,6
THERMODYNAMIC DATA
METHOD SYSTEM=BK10,TRAN=PETRO,VISC(L)=U2
VISC(L)
UDATA 1,2/ 2,1/ 11, 200/ 12, 400/ 21, 5.0/ 22, 3.0
STREAM DATA
PROP STREAM=1, TEMP=375, PRES=300, PHASE=M, &
RATE(V)=3125, ASSAY=WT
D2887 STREAM=1, DATA=5.74, 135/ 19.55,210 / &
35.89, 370/ 60.04, 565/ 69.82,665 / &
78.38, 800/ 87.94, 990
API STREAM=1,AVG=45.37, DATA=8.33, 80.01 / &
16.89, 62.90/ 34.8,50.6 / &
55.47, 38.20/ 80.10, 27.5
MW STREAM=1, AVG=162.9, DATA=18.92,99.5/33.4,135/ &
48.4, 184.7/ 9.8, 334.8/ 100, 789
LIGHT STREAM=1,PERCENT(W)=10.4, NORMALIZE, &
COMP(M)=1,0.1/2,1.4/3,0.65/4,3.15/5,5.1
NAME 1, CRUDE FEED
UNIT OPERATIONS
HCURVE UID=HC1, NAME=HEATING CRV
ISO STREAM=1, TEMP=375,600, PRES=300, POINTS=21
PROP TRANS
END

PRO/II User-Added Subroutine User Guide 17-9

 Partial PRO/II Output
SIMULATION SCIENCES INC. R PAGE P-7
PROJECT UKHS1 PRO/II UAS 386/EM
PROBLEM USERADD OUTPUT SIMSCI
HEATING/COOLING CURVE JUN99
==============================================================================
UNIT 1, ‘HC1’, ‘HEATING CRV’ (CONT)
TRANSPORT PROPERTIES FOR STREAM 1 - DRY
VISCOSITY THERMAL CONDUCTIVITY SURFACE
NO. TEMP PRES VAPOR LIQUID VAPOR LIQUID TENSION
F PSIA CP BTU/HR-FT-F DYNE/CM
--------------------------------------------------------------------------------
1 375.00 300.00 N/A 3.2500E+00 N/A 4.6893E-02 1.0539E+01
2 386.25 300.00 N/A 3.1375E+00 N/A 4.6085E-02 1.0042E+01
3 397.50 300.00 N/A 3.0250E+00 N/A 4.5276E-02 9.5479E+00
4 408.75 300.00 N/A 2.9125E+00 N/A 4.4468E-02 9.0585E+00
5 420.00 300.00 N/A 2.8000E+00 N/A 4.3660E-02 8.5735E+00
6 431.25 300.00 N/A 2.6875E+00 N/A 4.2855E-02 8.0932E+00
7 442.50 300.00 N/A 2.5750E+00 N/A 4.2053E-02 7.6176E+00
8 453.75 300.00 N/A 2.4625E+00 N/A 4.1255E-02 7.1470E+00
9 465.00 300.00 N/A 2.3500E+00 N/A 4.0464E-02 6.6815E+00
10 476.25 300.00 N/A 2.2375E+00 N/A 3.9682E-02 6.2215E+00
11 487.50 300.00 N/A 2.1250E+00 N/A 3.8912E-02 5.7672E+00
12 498.75 300.00 N/A 2.0125E+00 N/A 3.8157E-02 5.3188E+00
13 510.00 300.00 N/A 1.9000E+00 N/A 3.7420E-02 4.8768E+00
14 521.25 300.00 N/A 1.7875E+00 N/A 3.6705E-02 4.4414E+00
15 532.50 300.00 N/A 1.6750E+00 N/A 3.6018E-02 4.0132E+00
16 541.17 300.00 N/A 1.5883E+00 N/A 3.5509E-02 3.6882E+00
17 543.75 300.00 1.3555E-02 1.5625E+00 2.7197E-02 3.5409E-02 3.6450E+00
18 555.00 300.00 1.3584E-02 1.4500E+00 2.7614E-02 3.4984E-02 3.4626E+00
19 566.25 300.00 1.3612E-02 1.3375E+00 2.8023E-02 3.4575E-02 3.2885E+00
20 577.50 300.00 1.3641E-02 1.2250E+00 2.8427E-02 3.4181E-02 3.1220E+00
21 588.75 300.00 1.3671E-02 1.1125E+00 2.8826E-02 3.3801E-02 2.9623E+00
22 600.00 300.00 1.3701E-02 1.0000E+00 2.9220E-02 3.3434E-02 2.8089E+00

17-10 Transport and Special Property Subroutines February 2009

User-Added Special Property Subroutines
PRO/II user-added subroutines allow calculating values of special
properties using user-added methods. PRO/II supports special prop-
erties in two broad categories:
User-defined (or numbered, unnamed) properties referenced
using SPROP(idno). Users assign these an integer ID number
as part of defining the property.
Pre-defined (or named, not numbered), often referred to as
Refinery Inspection Properties. The pre-defined identifiers for
these properties are available in Table 17-3.
Special properties in both categories may be in the form of an Index
relationship or an actual property value. User-added subroutines are
available for special properties in both categories using either or
both forms.

Keyword Input

Typical Usage

...
COMPONENT DATA
LIBID 1,IC4/ 2,NC4/ 3,NC5
THERMO DATA
(Input statements for special property Index Method)
METHOD SYSTEM=setid, &
SPROP( idno ) = USINDEX, or PROPID= USINDEX
and
SPROP(M or WT or LV, idno) GAMMA=value, &
REFINDEX=value, REFVALUE=value {, NAME=text}
or
PROPID(M or WT or LV)GAMMA=value, &
REFINDEX=value, REFVALUE=value
and
INDEX ixno, rvalue/ ...
or DATA icno, rvalue/...

(Input statements for special property Formula Method)

METHOD SYSTEM=setid, &
SPROP( idno ) = USFORM, or PROPID= USFORM
and
SPROP(M or WT or LV, idno) {, NAME=text}
or
PROPID(M or WT or LV)

PRO/II User-Added Subroutine User Guide 17-11

 { and DATA icno, pvalue/ ...
and/or UIDATA ivalue/...
and/or URDATArvalue/... }
STREAM DATA
. . .

where:

SPROP(idno) Use the appropriate statement for the property to

calculate. In keyword input, each of these
or statements begins a group of input. Statements
that immediately follow provide data for this
PROPID property. A subsequent SPROP or PROPID
statement ends this group and begins a new
input group.
PROPID Represents a keyword for a pre-defined, named
special property. For example, to compute Wax
content using a user-supplied formula method,
replace this with WAX=USFORM. Refer to Table
17-3 for a complete list of keywords that
identify special properties.

SPROP(idno) Indicates a numbered (unnamed) special

property. The SPROP statement requires the
integer qualifier to identify the numbered
property.

idno This required integer qualifier is the

identification number assigned to the numbered
special property. For example, to compute
numbered special property 5 from a user-added
Index method, use SPROP(5)=USINDEX

GAMMA These entries must be supplied when using the

REFINDEX USINDEX mixing method.
REFVALUE All are required when using the USINDEX
method. None are allowed when using the
USFORM method. Refer to “Component Invariant
Special Properties” in chapter 8 of the Component
Data Keyword Manual and “Special Property
Methods Data” in chapter 8 of the Thermody-
namic Data Keyword Manual.
NAME Use this keyword to assign an optional descriptive
name to a numbered special property (only on an
SPROP statement). This appears in lists of special
properties that are generated in the PROVISION

17-12 Transport and Special Property Subroutines February 2009

 Graphical User Interface. It also appears in the
simulation output report.

USFORM, These options select a user-added method for the

USINDEX property.
USFORM requires Fortran routine SPUSER.FOR to be
written and built in UASLB.DLL. The SPUSER
routine calculates the property value using the
GAMMA, REFINDEX, REFVALUE, DATA and
INDEX data input on the appropriate SPROP or
PROPID statement. Developer information
appears later in this chapter.
USINDEX requires Fortran routine CVUSER.FOR to be
written and built in UASLB.DLL. This routine
converts an index value to a property value, and
also converts a property value to an index value.
Developer information appears later in this
chapter.

Data Statements Allowed with the USINDEX Method

(Exactly one of these two statements is allowed, and is required.)
INDEX ixno, rvalue / ... Supplies index values for the bulk mix-
ture. Typically required when using the USINDEX
to convert from given index values to property
values.
icno Required to order each index value.
rvalue Required non-negative floating-point index value.
or
DATA icno, rvalue / ... Supplies property values for individual
components. Use it with a USINDEX index
method that converts bulk property values to
index values. The values are summed and the
bulk property value is passed to USINDEX. Refer
to the chapter 8 of either the Component or Ther-
modynamic Data Input Manuals for the summa-
tion equation used.
icno Required to identify the component in input order.
rvalue Required non-negative floating-point index value
for component icno.

PRO/II User-Added Subroutine User Guide 17-13

 Data Statements Allowed with the USFORM Method
(Any combination of these statements is allowed with USFORM.)
DATA icno, pvalue / ... Supplies property values for individual
components. This array is passed to a USFORM
subroutine method that converts bulk property
values to index values. The input entries are
counted and used to size the data array.
icno Required to identify the component in input order.
pvalue Required non-negative floating-point property
value for component icno.
UIDATA Supplies integer values that pass to subroutine
USFORM. (Not passed to CVUSER). The devel-
oper of the USFORM subroutine specifies if this
data is needed. The input entries are counted and
used to size the data array.
ivalue User-supplied integer data values. At least one
value should be supplied when this statement
appears in the input.
URDATA Supplies floating-point values passed to subrou-
tine USFORM. (Not passed to CVUSER).
rvalue User-supplied floating point data values. At least
one value should be supplied when this statement
appears in the input.

Table 17-3: Predefined (Named) Special Property Ordinal

Numbers
Ordinal Named (Refinery Inspection)
ID Keyword Property
1 KVIS(basis) Kinematic viscosity
2 CLOUD(basis) Cloud point temperature
3 POUR(basis) Pour point temperature
4 FLPT(CC, basis) Flash point Temperature, Closed Cup
FLAS(CC, basis) Generally, these replace FLSH
FLPO(CC, basis)
5 SULF(basis) or Sulfur content
SULP(basis)
6 CETN(basis) Cetane number (replaced CNUM)
7 SMOKE(basis) Smoke point

17-14 Transport and Special Property Subroutines February 2009

 Table 17-3: Predefined (Named) Special Property Ordinal
Numbers (Continued)
Ordinal Named (Refinery Inspection)
ID Keyword Property
8 AROM(MONO, Mono-Aromatics content (replaces
basis) ARO1, AR88O1)
9 AROM(DI, basis) Di-Aromatics content (replaces
ARO2)
10 AROM(TRI, basis) Tri-Aromatics content (replaces
ARO3)
basis = M, WT, or LV
11 AROM(TETR, Tetra-Aromatics content (replaces
basis) ARO4)
12 AROM(PENT, Penta-Aromatics content (replaces
basis) ARO5)
13 AROM(HEPT, Hepta-Aromatics content (replaces
basis) ARO7)
14 AROM(TOTAL, Total-Aromatics content (replaces
basis) AROT)
15 NAPH(basis) Naphthene content
16 PARA(NORM, Normal Paraffin content (replaces
basis) PARN)
17 PARA(ISO, basis) Iso-Paraffin content (replaces PARI)
18 PARA(ALKY, Alkyl-Paraffin content (replaces
basis) PARA)
19 PARA(POLY, Poly Paraffin content (replaces PARP)
basis)
20 PARA(TOTA, Total Paraffin content (replaces PART)
basis)
basis = M, WT, or LV
21 OLEF(MONO, or Mono-Olefin content (replaces OLEM,
OLEF(NORM, OLEN)
basis)
22 OLEF(BRAN, or Branched Olefin content (replaces
OLEF(ISO, OLEB)
basis)
23 OLEF(CYCL, Cyclic Olefin content (replaces OLEC)
basis)
24 H2(WT) Hydrogen content (replaces HYDR)

PRO/II User-Added Subroutine User Guide 17-15

 Table 17-3: Predefined (Named) Special Property Ordinal
Numbers (Continued)
Ordinal Named (Refinery Inspection)
ID Keyword Property
25 CARB(WT) Carbon content
26 VA(WT) Vanadium content (replaces VANA)
27 NICK(WT) Nickel content
28 SODI(WT) Sodium content
29 OXYG(WT) Oxygen content
30 N2(TOTA, WT) or Total Nitrogen content (replaces
NITR(TOTA, WT) N2TO)

31 N2(BASI, WT) or Basic Nitrogen content (replaces

NITR(BASI, WT) N2BA)
32 N2(NONB, WT) or Non-basic Nitrogen content (replaces
NITR(NONB, WT) N2NB)
33 ASPH(C5, WT) Asphaltene C5 content (replaces
ASP5)
34 ASPH(C7, WT) Asphaltene C7 content (replaces
ASP7)
35 V50(basis) V50 value
36 VIND(basis) Viscosity Index
37 PENET(basis) Penetration Index
38 FRZP(basis) or Freeze point temperature
FRPT(basis) or
FREZ(basis)
39 CCR(basis) Conradson carbon residue
40 RCR(basis) Ramsbottom carbon residue
basis = M, WT, or LV
41 CHRA(WT) Carbon-hydrogen ratio
42 TAN(WT) or Total acid number
ACID(WT)
43 WAX(WT) Wax content
44 ASH(WT) Ash content
45 RON(C, basis) Research octane number
46 MON(C, basis) Motor octane number

17-16 Transport and Special Property Subroutines February 2009

 Table 17-3: Predefined (Named) Special Property Ordinal
Numbers (Continued)
Ordinal Named (Refinery Inspection)
ID Keyword Property
47 REFR(C20, basis) Refractive index at 20 Celsius
or RI(C20, basis)
48 RIND(WT) Ring index
49 ARIN(WT) Aromatic index
50 GIND(WT) Grade index
basis = M, WT, or LV
51 SIND(WT) Structure index
52 LUMI(WT) Luminometer number (Luminosity)
53 NOAC(WT) Noack volatility
54 JT(WT) Joule-Thompson (replaces JOUT)
55 EXPN(WT) Expansivity (replaces EXPN)
56 VSOUND(WT) Velocity of sound (replaces VSND)
57 BULK(WT) Bulk Modulus (replaces BMOD)
58 CVOL(WT) CVOL EOS
59 CETA(basis) or Cetane index
CETI(basis)
60 IBP(basis) Initial boiling point of cut
basis = M, WT, or LV
61 FBP(basis) Final boiling point of cut
62 MERC(WT) Mercaptan content
63 NPHL(basis) Naphthalene content
64 ANIL(basis) or Aniline point
ANPT(basis)
65 BROM(WT or LV) Bromine number
66 ANEU(WT or LV) Neutralization number (replaces
NEUT)
67 CFPP(basis) Cold filter plug point
68 ICI(basis) Icing index
69 STUI(basis) or Startup index
STAR(basis) or
SUI(basis) or
SI(basis)

PRO/II User-Added Subroutine User Guide 17-17

 Table 17-3: Predefined (Named) Special Property Ordinal
Numbers (Continued)
Ordinal Named (Refinery Inspection)
ID Keyword Property
basis = M, WT, or LV
70 WUI(basis) or Warm-up index
WARM(basis)
71 SOFT(WT or LV) Softening point
72 PHEN(WT) Phenol content
73 MON(L, basis) MON at 3 ml (replaces MAT3)
74 RON(L, basis) RON at 3 ml (replaces RAT3)
75 ASUL(WT) Aliphatic Sulphur content
76 REFR(C70, basis) Refractive index at 70 Celsius
or RI(C70, basis)
77 AROM(RING, Aromatic ring content (generally
basis) replace ARRI)
78 IRON(WT) Iron content
79 WTAR(WT) Weight Aromatics (replaces WARO)

80 WTPA(WT) Weight Paraffins (replaces WPAR)

81 WTNA(WT) Weight Naphthenes (replaces WNAP)
82 FLPT(OC, basis) Flash point Temperature, Open Cup
FLAS(OC, basis) Generally, these replace FLSH
FLPO(OC, basis)
83 CVLI(US, basis) Car vapor lock index (USA) (replaces
CVLU)
84 CVLI(EU, basis) Car vapor lock index (Europe)
(replaces CVLE)
85 MEAB Mean average boiling point temp.
(replaces MEAP)
86 CABP Cubic average boiling point temp
87 MOAB Molal average boiling point temp.
(replaces MOBP)
88 NHV Net heating value (replaces ANHV)
89 IDLT IDL type
basis = M, WT, or LV
90 PEPT(basis) Peptising power

17-18 Transport and Special Property Subroutines February 2009

 Table 17-3: Predefined (Named) Special Property Ordinal
Numbers (Continued)
Ordinal Named (Refinery Inspection)
ID Keyword Property
91 PVAL(basis) P value
92 FRMX(basis) FR maximum
93 FLOC(basis) Flocculation ratio
94 CPWX(basis) Congealing point of wax
95 PWAX(basis) Paraffinic wax content
96 CPPW(basis) Congealing point of Paraffinic wax
97 ARIP(MONO, IP Aromatics (mono) (replaces ARI1)
basis)
98 ARIP(DI, basis) IP Aromatics (di) (replaces ARI2)
99 ARIP(TRI, basis) IP Aromatics (tri) (replaces ARI3
basis = M, WT, or LV
100 ARIP(TOTAL) IP Aromatics (total)
101 MSUL(WT) Mercaptan sulphur (replaces MERS)
102 TRS(WT) Total reactive sulphur
103 FLPT(CC, basis) Wong Closed-cup Flash Point temp.
FLAS(CC, basis) (generally replace FLPW and FLSH)
FLPO(CC, basis)

SPROP( n, basis ) User-defined (numbered) special

property “n” (n = 1 to 9999, but only
60 SPROP’s are allowed.)
basis = M, WT, or LV

PRO/II User-Added Subroutine User Guide 17-19

 Special Property Developer Information
The remainder of this chapter presents information primarily of
interest to developers of user-added Special Properties subroutines.
Only subroutine developers can decide which properties a subrou-
tine calculates. However, they also have the responsibility of pro-
viding this information to their intended end-users.
PRO/II provides templates of two subroutines for calculating spe-
cial properties:
SPUSER Used by the USFORM option.

CVUSERUsed by the USINDEX option.

As delivered, both routines contain sample calculation code. How-

ever, to use them effectively, the user must re-code them and rebuild
the UASLB.DLL project. Refer to “Build Procedure for Classic PRO/II
UAS” in chapter 14.

Special Property Subroutine Coding Guidelines

Following these guidelines helps ensure a successful implementa-
tion. In PRO/II, special properties are manipulated routinely in two
forms:
Actual property values. These may be computed by the user-
added subroutine SPUSER.FOR. SPUSER.FOR does not compute
or use Index values.
Index values. These are generated by converting actual prop-
erty to the index form using correlations within PRO/II. The
equations involved are presented in chapter 8 of the Compo-
nent Data Keyword Manual and in chapter 8 of the Thermody-
namic Data Keyword Manual.
If desired, developers may write their own version of subrou-
tine CVUSER.FOR as an alternative method of accomplishing the
conversions.
Each call from PRO/II expects the subroutine to return a single
value for one property of the specified phase. If the subroutine
does not calculate a property value, it should return a value of
zero as the result of the calculation.

17-20 Transport and Special Property Subroutines February 2009

 Subroutine SPUSER
This subroutine computes special property values. It is called once
for each value of each property. All data input by the appropriate
DATA, UIDATA, and URDATA statements is available to the subrou-
tine.
Calling sequence:
SUBROUTINE SPUSER( iStrID, IDProp, iPropType, &
NCOMP, UDatIn, lenIU, IUData, &
lenUR, URData, XCOMP, ValOut )
where:

iStrID Input ID number of the stream for which to compute a

property value. (Typically not used for calculations.)
IDProp This input integer value identifies the special property to
compute. For user-defined properties, this maps to
SPROP(IDProp).
For pre-defined special properties, IDProp may be found in
Table 17-3. For Example, “Vanadium Content” is
number 26 in the table.
After determining whether the property is an SPROP or a
named property, use this argument to branch to
process different properties.
iPropType Input integer scalar flag indicating the major property
class of the requested property. Values include:
1 Named (Pre-defined Refinery Inspection) Property
2 Numbered (User-defined) SPROP(IDProp)
Use this flag to create a logical branch between the
two types of property.
NCOMP Input integer indicating the total number of
components in the simulation. This also is the
dimension of the UDatIn argument array.
UDatIn An optional double-precision array of input data. This
is the array of values input on the DATA statement for
this property. It includes up to one value for each
component in the simulation; typically, the property
value of each pure component. The array size is
NCOMP. The component numbers used to input values
have not been re-arranged, so the values effectively
are in component input order.
lenIU This input integer is the size of the IUData input array.
IUData An optional integer array of data input on the UIDATA
statement. The number of values is lenIU, so
IUDATA(lenIU) is the proper declaration
lenUR This input integer is the size of the URData input array.

PRO/II User-Added Subroutine User Guide 17-21

 URDATA An optional double precision array of data input on
the URDATA statement. The number of values is
lenUR, so URDATA(lenUR) is the proper declaration.
XCOMP Input double precision array of pure component
composition expressed as mole fraction of each
component. If non-molecular weight components are
to be processed, the developer should consider
characterizing them using data in the UIDATA and
URDATA arrays of input data.
ValOut Output double precision scalar property value. This
must be the bulk property that incorporates any and
all contributions of the individual components. This
variable returns the calculated value of the requested
property in PRO/II internal dimensional units.

Subroutine CVUSER
This subroutine performs conversion between property values and
property index values. Indexes typically are logarithmic forms of
property values. Being logarithmic, they tend to linearize the behav-
ior when combining properties. When coding this routine, it should
be capable of converting index values to property values; and con-
versely, be capable of converting property values to index values. It
is called once for each value to convert. All data input by the appro-
priate DATA, UIDATA, and URDATA statements is available to the
subroutine.
Calling sequence:
SUBROUTINE CVUSER( iOptCvt, VIndex, VProp, GAMMA, &
CONST, IDProp )
where:
iOptCvt This input integer flag indicates the conversion to
perform. Set iOptCvt to one of these two values to
convert a (pre-defined) named property:
1 Convert the Index value (of a named special
property) passed as input in argument VIndex to a
property value returned in VProp.
2 Convert the property value (of a named special
property) passed as input input in argument
VProp to an index value returned in VIndex.

17-22 Transport and Special Property Subroutines February 2009

 Set iOptCvt to one of these two values to convert a
user defined (numbered SPROP) property:
201 Convert the Index value (of a numbered SPROP)
input in argument VIndex to a property value
returned in VProp.
202 Convert the property value (of a numbered
SPROP) input in argument VProp to an index
value returned in VIndex.
VIndex This is the Index value of the special property.
It is input when iOptCvt = 1, and must be converted to a
property value returned in VProp.
Calculate VIndex from VProp when iOptCvt = 2.
VProp This is the actual value of the special property.
It is input when iOptCvt = 2, and must be converted to
an Index value returned in VIndex.
VIndex must be calculated and returned when
iOptCvt = 2.
GAMMA This is input and is typically used in the following
formula. When not supplied through input, Gamma
assumes a value of 1.0.

1.0
log ( Index ) = ⎛ -------------------⎞ log10 ( VProp ) + CONST
10 ⎝ Gamma⎠
(17-1)
CONST This input argument represents the Index value at
reference conditions as determined by input values
REFINDEX and REFVALUE.
IDProp This input integer value identifies the special property
to compute. For user-defined properties, this
maps to SPROP(IDProp).
For pre-defined special properties, IDProp may be
found in Table 17-3. For Example, “Vanadium
Content” is number 26 in the table.
After determining whether the property is an SPROP
or a named property, use this argument to
branch to process different properties.

PRO/II User-Added Subroutine User Guide 17-23

17-24 Transport and Special Property Subroutines February 2009
 Chapter 18
Classic Unit Operations
Overview
The User-Added Unit Operation interfaces described in this chapter
allow users and other independent developers to supplement the
PRO/II-supplied unit operations with their own unit operations.
Both the keyword input facilities and the ProVision Graphical User
Interface fully support these user-added unit operations.
They are fully integrated into the flowsheet sequencer, so their exe-
cution is indistinguishable from that of PRO/II’s internal unit mod-
els. User-added unit operations accept feed streams as input from
other unit operations in the flowsheet. Calculation capabilities are
limited only by the creativity of the developer. Their product
streams may serve as feeds to other flowsheet units. For example, it
is possible to integrate a user-added heat exchanger or solids dryer
into a PRO/II flowsheet. Using the DEFINE features of PRO/II, they
can directly access data for other flowsheet unit operations. The cal-
culated results they store internally are available to other flowsheet
units. In addition to performing calculations, user units can generate
printed report and create files of data for use by programs external
to PRO/II.
A user-added unit operation may execute (a) during flowsheet cal-
culations only, or (b) at output-time only. User-added units called
during flowsheet calculations must have at least one feed stream to
satisfy flowsheet connectivity requirements. Output-time calcula-
tions may be preferred for a single-pass execution after flowsheet
convergence has been achieved. User-added unit operations also
support an optional output subroutine having the express purpose of
writing final results directly into PRO/II’s standard output report.
Starting in PRO/II version 8.0, new object-oriented unit operation
interfaces vastly extend these user-added capabilities. Discussion of
PRO/II User-Added Subroutine User Guide 18-1
 those features begins in Chapter 3, "Modular Interface Software" of
this manual.

User Information
Keyword Summary
Unit Identification (required)
USn UID=uid, {NAME=text}, {BYPASS=1}

Feeds and Products (conditional)

FEED sid {, sid, sid,....}
PRODUCT {sid, sid, sid,....}
User Input Data (optional)
Integer Inputs
IPARM integer {, integer, ....} (Up to 250 values)
Real Number Inputs
RPARM real {, real , .... } (Up to 500 values)
SUPPLEMENTAL i, reali {, ... / j, realj+1 ... } (Up to 10000 values)
HEAT duty x 10-6, {, duty x 10-6, ... } (Up to 10 values)

Alternative Definition of Operating Parameters

DEFINE RPARM( elno ) AS <unit type>=uid, <param>, {<op, <ref>}
or
DEFINE RPARM( elno ) AS STREAM=sid, <prop>, {<op, <ref>}

General Information
User input data are supplied to user-added unit operations using
PRO/II keyword statements or the ProVision GUI. From a users’
perspective, there is not a lot of difference between setting up a
user-added unit or one of PRO/II’s internal unit operations.
The operating parameters for these user-added units may be input
by the user or derived from previous unit operations through the
DEFINE feature of PRO/II. See chapter 10.5 in the PRO/II Keyword
Manual, or the PRO/II User’s Guide for more information. Input
processing facilities are included in PRO/II for user-written unit
operations. However, routines for optional output reports must
always be written by the user.

18-2 Classic Unit Operations February 2009

 Calculated results from user-supplied unit operations may be stored
in IPARM, RPARM, and SUPPLEMENTAL arrays. Other flowsheet units
may access the data stored in the RPARM array using the DEFINE con-
struct described in chapter 10.5 of the PRO/II Keyword Manual.

Input Description
Unit Identification (required)
USnn UID=uid, {NAME=text}, {BYPASS=1}

In the Unit Operation category of a PRO/II keyword input file, you

must indicate which user-added models are being used. The first
statement of the declaration must be the Unit Identification state-
ment. Chapter 10.2 in the PRO/II Keyword Manual describes the
entries in more detail.

USnn Required. A composite keyword consisting of the prefix

US and a 1, 2, or 3 digit integer that identifies the
specific user-subroutine that performs the calculations.
Valid values of nn are 1-20 and 41-120. nn is part of the
US keyword. Table 18-2, “Naming Conventions for Unit
Op Subroutines,” on page 18-14 maps these keywords to
actual user-added subroutines. For example, keyword
US41 (where nn=41) specifies subroutine USER81.for.
Note: Numbers 21-40 are reserved for PRO/II.
UID Required. A unique unit identifier containing up to 12
characters. This identifies the unit on the flowsheet.
NAME Optional descriptive text string containing no more than
40 characters.
BYPASS Optional integer scalar that acts as a flag to control when
calculators are performed.
1 = Normal calculations during flowsheet convergence.
This is the default when an entry is omitted.
2 = Perform calculations only after flowsheet has
converged. The unit is skipped during flowsheet
convergence calculations.

Note: Units that run normally (BYPASS=1, during flowsheet con-

vergence calculations) require at least one feed stream to
satisfy the connectivity requirements of the calculation
sequencer.

PRO/II User-Added Subroutine User Guide 18-3

 The BYPASS flag does not affect any output routines (UnnOUT). Out-
put routines execute only during standard report generation; never
during flowsheet calculations.
For bypass units (BYPASS = 2), all feeds and products are optional.

Note: For bypass units (BYPASS = 2), the product streams cannot
be stored with URXSTR or other stream storage routines.

Feeds and Products

FEED sid, {sid, sid,....}
PRODUCT {sid, ... sid, sid,....}
where:
sid A flowsheet stream identifier. It is a character string that
may contain up to 12 characters. All product streams
always are optional. When a unit executes in BYPASS
mode (i.e., bypass=2), all feeds are optional.
The following notes describe the requirements imposed by PRO/II.
Developers of specific user-added unit operations may impose other
restrictions. Users must be aware of and comply with any other
restrictions imposed by the developer.

Note: Units that run normally (BYPASS=1, during flowsheet con-

vergence calculations) require at least one feed stream to
satisfy the connectivity requirements of the calculation
sequencer.
Note: For bypass units (BYPASS = 2), the product streams cannot
be stored with URXSTR or other stream storage routines.
Note: There is essentially no limit on the number of feed and
product streams allowed for each user-added unit opera-
tion. The number of feeds and products are counted during
input processing and storage is allocated dynamically.

Thermal Conditions
The thermal conditions for feed streams to user-added unit opera-
tions are defined by PRO/II. There are no provisions for the user to
specify them.

18-4 Classic Unit Operations February 2009

 Keywords for User Data Input
IPARM integer {, integer, ....} (Up to 250 values)
RPARM real {, real, .... } (Up to 500 values)
HEAT duty x 10-6, {, duty x 10-6, ... } (Up to 10 values)
SUPPLEMENTAL i, reali {, ... / j, realj+1 ... } (Up to 10000 values)
The following definitions only include limitations imposed by
PRO/II. Developers of user-added unit operations may impose addi-
tional restrictions on data input that users must observe.

IPARM Optional integer array of user input data. Each integer

entry represents one scalar integer value. PRO/II
imposes an absolute limit of 250 values.
RPARM Optional single-precision array of user input data. Each
real entry represents one scalar single-precision value.
PRO/II imposes an absolute limit of 500 values.
HEAT Optional single-precision array of user input data. Each
duty x 10-6 entry represents one scalar single-precision
value. PRO/II imposes an absolute limit of 10 values.
SUPPLE Optional single-precision array of user input data. Each
real entry represents one scalar single-precision value.
PRO/II imposes an absolute limit of 10,000 values.

PRO/II does not associate any dimensional units of measure with

any of the data. All data values entered through input is passed
unchanged to the user-added subroutine.
For the IPARM, RPARM, and HEAT arrays, the position of the input data
determines the storage element. Numbering begins with element 1
for the first supplied value. Separate entries with commas. Use
additional commas as placeholders for omitted values. For example,
to store 5.0 in element 5 and 7.0 in element 7 of the RPARM array:
RPARM , , , ,5.0, ,7.0
The HEAT array originally was intended to transfer heater/cooler
duties to user-added subroutines in duty units of measure (i.e.,
energy per time). However, it does not and never has applied
dimensional units conversions to the data. It is supported only for
backward compatibility, and for the convenience of developers who
choose to use it.
The SUPPLEMENTAL array uses an input syntax different from the
other arrays. Due to its large size, it is convenient to designate
“starting elements” to facilitate entering more than one series of

PRO/II User-Added Subroutine User Guide 18-5

 data. The “i” and “j” entries represent integer starting element num-
bers. If the element number is omitted, the associated real entry is
stored in the next available storage element. The following exam-
ples store 101.0 in element 1, 102.0 in element 2, 2031.0 in element
2031, and 2032.0 in element 2032.
SUPPLE 101.0, 102.0 / 2031, 2031.0, 2032.0
or
SUPPLE 1, 101.0/ 2, 102.0/ &
2031, 2031.0/ 2032, 2032.0
Note the first value (101.0) is stored in element 1, even when the
element number is missing. Supply the element number to store the
first entry in a different element (other than element 1).

Dynamic Definition of RPARM Values

DEFINE RPARM( elno ) AS <unit type>=uid,<param>,{<op,<ref>}
or
DEFINE RPARM( elno ) AS STREAM= sid, <prop>, {<op, <ref>}

In the keyword input for a user-added unit operation, the definition

of individual RPARM elements may be deferred until the unit is
called to perform calculations. This is accomplished by using the
DEFINE statement described in chapter 10.5 of the PRO/II Keyword
Input Manual. Available parameters are listed in chapter 10.3,
Flowsheet Parameters, in the same manual.

Example 18-1: Dynamically Importing RPARM Values

Any of the first 100 elements of the RPARM array may be set to
external flowsheet values dynamically. Use a DEFINE statement
in the input of the user-defined unit operation to accomplish
this. Each time PRO/II calls the user-added subroutine, it auto-
matically imports the external flowsheet parameter and uses it
to update the specified RPARM element. The following example
illustrates this use of the DEFINE statement.
RPARM element value imported from another unit operation:

CALCULATOR UID=C1
PROCEDURE
R(1) = 13.376
R(2) = 52800
RETURN
US2 UID=USER2
FEED ...
PROD ...
DEFINE RPARM(1) AS CALC=C1, RESULT(2)

18-6 Classic Unit Operations February 2009

 DEFINE RPARM(2) AS CALC=C1, RESULT(1)
These two DEFINE statements set RPARM(1) = 52800 and
RPARM(2) = 13.376.

Example 18-2: Dynamically Exporting RPARM Values

Any of the first 100 elements of the RPARM array may be
exported to reset external flowsheet parameters dynamically.
Use a DEFINE statement in the input of another unit operation to
accomplish this.
This actually is the same situation as import example 5-2. The
difference is that the DEFINE statement appears in an external
flowsheet unit operation, not within the user-added subroutine.
Each time PRO/II calls the external unit operation, it automati-
cally imports the specified RPARM value from the user-added
unit operation and uses it to update the specified parameter. The
following example illustrates this use of the DEFINE statement.
RPARM element value exported to another unit operation:

US4 UID=USER4 ! +-- temp

FEED ... ! | +-- pres
PROD ... ! | |
RPARM 13.376, 52800, 0.0, 0.0, 0.0
! element 1 2 3 4 5
FLASH UID=F1
FEED ...
PROD ...
ISO
DEFINE PRES AS US4=USER4, PARA(4)
DEFINE TEMP AS US4=USER4, PARA(3)
In this case, the 3rd and 4th real parameters are calculated by the
user subroutine and passed to the flash unit operation.

User-Added Unit Operations and Recycle Loops

User-added unit operations may be used within flowsheet recycle
loops in exactly the same manner as any other unit operations.

User-Added Unit Operations and Controllers

Parameters stored in the RPARM array for a user-added unit opera-
tion may be used by a feedback controller as control parameters.
They may also be used in the specification of a feed forward con-
troller (DEFINE), a feedback controller (CONTROLLER, MVC) or a
flowsheet OPTIMIZER. Only values stored in the RPARM array are
available as flowsheet parameters. Refer to example 5-3.

PRO/II User-Added Subroutine User Guide 18-7

 Example 18-3: Spec and Vary Using RPARM
The first 100 RPARM elements of the unit operation may be used as
control variables or as specification values by PRO/II control units.
This is illustrated by the following examples.

Control Variable

Syntax:
CONTROLLER UID=C1
SPEC ...
VARY <utype>=<uid>, PARA(elno)
where:

<utype> The declared type of the user added unit operation

(US1, US2, US41, etc.).
<uid> The unit’s unique identifier
elno The element number of RPARM to vary. The
controller permutes RPARM( elno ) to solve the
problem.

Sample Code:
To control RPARM(5) for unit C11, defined by user-added subrou-
tine US2, the following VARY statement could be used:
VARY US2=C11, PARA(5)

Specification

Syntax:
CONTROLLER UID=C1
SPEC <utype>=<uid>, PARA(elno), VALUE= rval
VARY ...
where:

<utype> The declared type of the user added unit operation

(US1, US2, US41, etc.).
<uid> The unit’s unique identifier
elno The element number of RPARM used as the target.
The specification (RPARM( elno ) must be a
calculated result in unit <uid>.
rval The calculated value of RPARM( elno ) after
calculations converge.

18-8 Classic Unit Operations February 2009

 Sample Code:
To specify RPARM(3) to be 4.812 for unit H45, defined by user
subroutine US42, the following SPEC statement could be used:
SPEC US42=H45, PARA(3), VALUE=4.812

Developer Information
Guidelines
Developers should acquire a reasonably thorough understanding of
using user-added subroutines before beginning code development.
All the previous information for users is relevant. This section high-
lights areas of concern that developers may encounter.

Organizing Unit Operation Code

PRO/II execution proceeds through a series of processing steps that
broadly include: input processing, data cross-checks, flowsheet
solution, output-pass calculations, and report writing. PRO/II does
not call any user-added subroutines during input processing and
cross-checking. It calls user-added calculation routines only for
flowsheet solution and output-pass calculations. Finally, PRO/II
calls only user-added output routines (and not the calculation rou-
tines) when generating output reports.
It is important to keep these steps in mind when organizing the
code. For example, if code to valid input data is desired, it should
appear in the user-added calculation routines. All checking and
error exits should occur before the actual calculations begin. An
IPARM element might be reserved as an internal counter of the
number of times the calculation routine is called from PRO/II. The
flag could be used to perform the input checks only on the first
entry. Similarly, all code that reports final results should reside in
the output routines; not in calculation routines. Output routines typ-
ically test the ISOLVE flag a successful calculation solution, and nor-
mally omit more detailed data validation.

PRO/II Feed Streams

Developers should not attempt to change or modify any feed stream
data, since that could corrupt the integrity of the flowsheet. A com-
mon approach is to copy feed stream data to local internal storage,
or simply copy it to a product stream and perform the calculations
using that copy of the data. Routine URXSTR allows retrieving (but
not storing) feed stream data from stream storage.

PRO/II User-Added Subroutine User Guide 18-9

 User-added unit operations must accept at least one feed stream to
be included in flowsheet calculations. If the unit is intended to exe-
cute only in the output-calculation step after the flowsheet has con-
verged, then no feed streams are required.

Thermal Condition of Feeds

The thermal condition of feed streams is set by PRO/II and should
not be altered by user-added unit operations. These conditions
include temperature, pressure, phase state, enthalpy, compositions,
and compressibility factor.

Note: It is never permissible for a user-added unit operation to

replace any feed stream data in stream storage.
Product Streams
Product streams may be created by the user-added calculation rou-
tine and placed into stream storage for subsequent use by other
user-added unit operations. The decision to create or use product
streams is left to the developer. PRO/II never requires them in any
execution step.
It is the responsibility of the developer to ensure that all necessary
properties are set for all product streams before exiting a calculation
routine. Typically, this involves calculating the properties and then
saving the product streams using URXSTR. Conversely, an output
report routine should never attempt to store stream (or any other)
data, since it is by definition merely reporting completed results.
Table 18-1 identifies some of the subroutines that may be used for
this purpose.
Table 18-1: Interface Routines for Product Stream Properties
Subroutine Description
UFLSH Performs flash calculations
U3FLSH Performs VLLE flash calculations
UFLSHSOL Performs flash calculations for streams that contain
solids components.
UHS Generates enthalpy, entropy, and density data
URXSTR Retrieves and stores stream data in stream storage
TTPROP Calculates transport properties
UH2OP Calculates water properties
UDENS Computes wet and dry flowing volumes

18-10 Classic Unit Operations February 2009

 Refer to Table 15-1 on page 15-2 for a complete listing of stream
interface routines.

Example 18-4: Spec and Vary Using RPARM

Thermal Condition of Products

The thermal condition of product streams is set by user-added
unit operation calculations. Often this is a primary purpose of the
subroutine.
Interface subroutine USTHER allows user-added subroutines to select
a specific thermodynamic method set to use when performing
stream calculations. This is available only when two or more
method sets exist in the simulation problem. Call USTHER before
performing flashes or other stream property calculations.

Designing Data Storage

Data arrays IPARM, RPARM, HEAT, and SUPPLEMENTAL array are the
primary storage for calculated results in addition to user input data.

Integer Inputs
IPARM integer,.... (Up to 250 values)

Real Number Inputs

RPARM real no,.... (Up to 500 values)
SUPPLEMENTAL i,Ri/Ri+1/.../j,Rj/Rj+1... (Up to 10000 values)

Heater/Cooler duties
HEAT duty x 10-6,.... (Up to 10 values)
When designing the storage requirements of a user-added unit oper-
ation, a developer should first characterize the data as input data,
calculated results, or other data used internally by the unit operation
(such as flags and counters).
Generally, user input data should be mapped at the beginning of
storage arrays. If used, the HEAT array typically contains only user
input data. Leave some empty elements after the end of input data
and map in the internal variables. After leaving a few more empty
elements, map calculated results towards the end of the array. The
empty elements leave room for later additions.
Separate integer data from floating-point data and map it into the
IPARM array.

PRO/II User-Added Subroutine User Guide 18-11

 Identify floating-point data that may be useful in other parts of a
simulation. These typically are scalar values. Map them into the
RPARM array, with any user input data mapped first, at the begin-
ning of the array.
The first 100 elements of the RPARM array are available for use else-
where in the flowsheet through the standard SPEC, VARY, DEFINE,
PARAMETER, and CONSTRAINT constructs available in controllers.
They also are accessible to CASE STUDIES through the CHANGE,
PARAMETER, and RESULT constructs.

Decide whether or not to store any data in the HEAT array and map it
there as desired.
The remaining data should be mapped to the SUPPLEMENTAL array.
This is where the larger blocks of data should be stored. Determine
whether or not some of the data constitute sub-arrays. For example,
multiple temperatures and multiple pressures routinely are needed.

User-Added Unit Operations and Recycle Loops

User unit operations may be used in recycle loops in exactly the
same manner as any other unit operations. If desired, the calculation
subroutine may perform cross-checks of the input data, and write
progress messages or intermediate calculated results. When using
the output interface routines (HEAD, UAOUT, etc.) the output typically
appears in the History file.
Convergence or non-convergence should be signaled from user
modules. Fatal errors also should be signaled so that calculations
may be aborted. Developers should use the ISOLVE and ISTOP vari-
ables to return status codes to PRO/II. The calculation routine
returns these variables to PRO/II when it completes execution after
being called.

Note: For user-added units in recycle loops, it is important that

the calculations be performed as efficiently as possible to
minimize computing costs.

18-12 Classic Unit Operations February 2009

 Calculation Routines -- Fortran Coding Conventions
Information is communicated to the user subroutine through the
subroutine’s argument list and the common blocks described in
Chapter 15, "Interfacing Software".
Calling sequence:
CALL USERnn( IPARM, RPARM, SUPPLE, HEAT,
& IDATA, ISOLVE, ISTOP )
!
! Argument Declarations
!
INTEGER(4) :: IPARM( * ) ! in/out 250 elements
REAL(4) :: RPARM( * ) ! in/out 500 elements
REAL(4) :: SUPPLE( * ) ! in/out 10000 elements
REAL(4) :: HEAT( * ) ! in/out 10 elements
INTEGER(4), INTENT( IN ) :: IDATA( * )
INTEGER(4), INTENT( OUT ) :: ISOLVE
INTEGER(4), INTENT( OUT ) :: ISTOP

where:

nn Subroutine number, 41-60, 81-160 (Table 18-2)

IPARM1 Integer parameters (250)
1
RPARM Real parameters (500)
SUPPLE1 Real data storage (10000)
HEAT1 Heat duties x 10-6 (10)

IDATA(1) Number of feeds

IDATA(2) Number of products
IDATA(3) Number of heaters
IDATA(4) Number of components
IDATA(5) Water decant switch:
1 = water is regular component
2 = water is decanted
IDATA(6) Standard output file
IDATA(7) Integer representation of first 4 characters of the
unit identifier for unit (A4).

PRO/II User-Added Subroutine User Guide 18-13

 IDATA(8)-(10) Integer representation of first 12 characters of
the name for unit (3A4).
See Coding Practice 3, below.
(IDATA(8)-(10) are available to output
subroutines at printout time only.
Output Variables
ISOLVE2 Solution flag:
0 No Solution, no calculations attempted
1-9 No solution
10 Solution reached
ISTOP2 Fatal error switch:
0 No Fatal errors, continue calculations
1 Yes, Fatal errors. Halt all calculations
1) IPARM, RPARM, SUPPLE, and HEAT arrays may contain input data,
internal subroutine data, and calculated results.
2) ISOLVE and ISTOP are initialized to zero by PRO/II.

Subroutine Naming Conventions

PRO/II associates input keywords with specific user-added subrou-
tines. It also associates a specific output routine with each calcula-
tion routine. These associations are implemented through a pre-
defined set of the subroutine naming conventions. Developers must
use the subroutine names shown in Table 18-2 to achieve a success-
ful implementation.
Table 18-2: Naming Conventions for Unit Op Subroutines
Input Calculation Output
Keyword1 Routine Name1 Routine Name1,2
US1 USER41 U41OUT
... through ...
US20 USER60 U60OUT

US41 USER81 U81OUT

... through ...
US120 USER160 U160OUT
1) User-Added Units 21 through 40 are reserved for SIMSCI
internal units.
2) Output subroutines are optional. However, if supplied,
they must follow the correspondence shown above.

The following coding practices are highly recommended:

18-14 Classic Unit Operations February 2009

 1. Verify feed streams. Use interface routine URXINF to identify
required feed streams. If a feed essential to the calculations is
missing, call UAERR to register an Error, Warning, or Message
in the PRO/II error-processing system. Return ISOLVE with a
value between 1 and 9 to indicate the unit did not solve. Devel-
opers decide the significance of the values 1 - 9. It may also be
desirable to return ISTOP=1 or call UAERR to register an Abort.
Either option terminates all flowsheet calculations immedi-
ately, but use this option with care. It is normal for feeds to
units in recycle loops to start with rates of zero. In a well-
formed simulation, the feed flows build up on successive recy-
cle iterations to finally achieve a valid solution.
2. Verify feed stream data. Use interface routine URXSTR to
retrieve feed stream data. Any required feeds having a zero rate
might be an error. If so, implement appropriate error
processing.
3. Use URXINF to retrieve the 12-character ID’s of other feeds,
product streams, and of the unit operation itself, as desired.
4. Check the input data for completeness and consistency, and
perform any necessary error processing. Call UAERR to register
an error in the PRO/II error system.
5. Perform calculations, saving results in the IPARM, RPARM,
SUPPLE, and HEAT heat arrays, as appropriate.
6. Intermediate results may be printed as desired. Define an IPARM
element as an intermediate print flag, so users can control the
printout.
7. Write intermediate printout to the PRO/II history file or the dis-
play terminal using output routine UAOUT. (PRO/II may inter-
cept terminal output if it conflicts with the graphical user
interface display). Alternatively, use the unit number from
IDATA(6) to write to the history file using routine PAWRITE. To
write to a completely different file, use routine FIGETU to obtain
a valid unused file unit number. Open a file on the file unit, and
use the file unit number with routine PAWRITE to write data to
the file. Be sure to close the file before returning to PRO/II.
8. Set properties for product streams using interfacing routines
described in Chapter 15, "Interfacing Software". Performing a
flash is practice to set the properties.
9. Store product streams in data stream storage by using URXSTR.

PRO/II User-Added Subroutine User Guide 18-15

 10. Set ISOLVE appropriately. ISOLVE is preserved for each execution
of a user module and may be used as a counter for non conver-
gence for recycle problems. When a value of 9 (or less, depend-
ing on the user’s preference) is reached, a catastrophic situation
may be signaled by setting ISTOP to 1.
11. When the calculations solve satisfactorily, return ISOLVE=10
and ISTOP=0.

Output Subroutines
Output subroutines for the user-written unit operations are optional.
Their purpose is to report the results of user-added unit operation
calculations. PRO/II associates one output subroutine with each for
user-added unit operation calculation routine. These associations
are maintained through the subroutine naming conventions. Devel-
opers of user-added output routines must obey the naming conven-
tions listed previously in Table 18-2. For example, use output
routine U59OUT to generate a report for calculation routine USER59.
As delivered, PRO/II includes an output routine for each user-added
unit operation. Most of them contain no active code, so they do not
produce any reports. The intent is for developers to write appropri-
ate code to accurately report the results of their unit operations.
When an output routine is called without first replacing it with user-
written code, PRO/II typically generates the following message:
*** WARNING *** USER-ADDED SUBROUTINE ******
IS CALLED IN THIS PROBLEM BUT NO CODE WAS
SUPPLIED BY THE USER.

Reporting Data in Output Dimensional Units

Output subroutines for user-added units must be programmed to
generate results in a variety of dimensional units of measure. This
can be accomplished by using the /OUTFAC/ and /FACTOR/ common
blocks as described in Chapter 15, "Interfacing Software". Sample
code for subroutine U42OUT.FOR appears in the examples near the
end of this chapter.

Example:
Assume RPARM(26-30) contains temperatures. The following
partial code sample demonstrates using the /OUTFAC/ common
to convert and print values in output units from a UxxOut
routine.

18-16 Classic Unit Operations February 2009

 INCLUDE 'PMXUSR.CMN'
INCLUDE 'FACTOR.CMN ! brings in TCONVT factor
INCLUDE 'OUTFAC.CMN ! brings in IHOL, TXXX data
1010 FORMAT( / 10X, 'TEMPERATURE, ', A2, 5X, 5F13.2 )
ifOK = 0
DO I = 26, 30
IF( RPARM( I ) .GT. DZ0 ) THEN
TE(I) = (RPARM(I)+TCONVT)*TXXX( 6 )-TXXX(10)
ifOK = ifOK + 1
ELSE
TE(I) = -1000.0D+0 ! indicates missing value
ENDIF
END DO
IF ( NOT .GT. 0 ) THEN
IOUT = IDATA( 6 ) ! LFU of standard report file
WRITE( IOUT, 1010 ) IHOL(6), ( TE( K ), K = 1, NOT )
END IF
Refer to /OUTFAC/ in Chapter 15 for more discussion of using
the TCONVT, TXXX( 6 ), and TXXX( 10 ) conversion factors, and
IHOL data to report the units of measure.

Availability of Data
PRO/II delivers the calculated results from a user-added unit opera-
tion to the corresponding output subroutine in two ways:
Arguments in the subroutine call list. These include the IPARM,
RPARM, SUPPLE, and HEAT arrays (described earlier).
Product streams.
The output subroutine for each user unit operation in the flowsheet
is called at printout time.
All output values must be multiplied by the appropriate output con-
version factors available in common block /OUTFAC/ (see Chapter
15, "Interfacing Software") to ensure that the multiple output
dimension and scaling features of PRO/II execute properly for user-
written output subroutines.

PRO/II User-Added Subroutine User Guide 18-17

 Output Subroutines -- Fortran Coding Conventions
Calling sequence:
CALL UnnOUT( IPARM, RPARM, SUPPLE, HEAT, IDATA )
where:

nn 41-60, 81-160 Subroutine number

(Table 18-2)
IPARM, RPARM, These arrays are discussed at length earlier
SUPPLE, HEAT, and in this chapter.
IDATA

Output Page Layout

User output subroutines should follow the margin conventions used
by PRO/II. In the basic layout, the first character of each row is
reserved for Fortran line control characters. Beginning with the sec-
ond character, the page is ruled into vertical columns, each contain-
ing 13 characters. Table 18-3 defines the column character positions
across a page.
Table 18-3: PRO/II Output Report Page Layout
Character
Column Positions Description of Contents
1 2-14 Labels and units of measure
2 15-27 Labels and units of measure
3 28-40 1st data column
4 41-53 2nd data column
5 54-66 3rd data column
6 67-79 4th data column. Last column when
WIDTH=80
7 80-92 5th data column. First column when
WIDTH=120 or 132
8 93-105 6th data column
9 106-118 7th data column. Last column when
WIDTH=120
10 119-131 8th data column. Available only
when WIDTH=132

Standard 8½ by 11 inch paper only displays 66 rows of 80 charac-

ters. Using 6 rows for headings, each page may contain up to 60
rows of output.

18-18 Classic Unit Operations February 2009

 Example Problems
These examples illustrate many of the features available for user-
written unit operations. Each example has a corresponding output
subroutine; however, this is not a necessity unless printout in addi-
tion to the standard PRO/II output is desired. (If special printout is
not desired for a user-written unit operation, the dummy printout
subroutine supplied by PRO/II satisfy the system requirements.)
All subroutines in the examples have been written in a general man-
ner, with calculations independent of the input dimensions selected
by the user.
The following details are given for each example:
Description of the subroutine.
Fortran listing for the subroutine.
Problem keyword input file.
Excerpts from the problem output.
Example 18-5: Pipe Pressure Drop Model
This unit operation may be used to compute pressure drops for liq-
uid or vapors flowing in commercial steel or wrought-iron pipe-
lines. The Darcy formula for pressure drop is used:
2
ρfLv -
ΔP = --------------------- (18-1)
12d ⋅ 2g c

where:
ΔP = pressure drop, psi
ρ = density, lb/ft3
v = mean velocity, ft/sec
L = length, ft
d = inside diameter, in.
gc = gravitational constant, 32.2 ft/sec2
f = friction factor
Friction factors are calculated using mathematical equivalents for
the charts presented by L. F. Moody.
For laminar flow,

f = 64 ⁄ N Re (18-2)

where:

PRO/II User-Added Subroutine User Guide 18-19

 NRe = Reynolds number
For turbulent flow,

log f = – 1.666 – 0.1962 log d (18-3)

The Darcy formula, equation (18-1), is used for both liquid and
vapor calculations.
For vapor calculations in which ΔP is less than 10% of the entering
pressure, inlet conditions are used for density. For vapor pressures
greater than 10% but less than 40% of the entering pressure, the
average density is used. The equation is not valid for vapor when
pressure drops exceed 40% of the entering pressure.
A flash calculation at outlet conditions is performed to test for
phase change.
No provision has been included in the user-added unit operation for
mixed-phase streams. Therefore, invalid use of the module will be
signaled when calculations are requested for mixed-phase streams.
One feed stream is allowed for this unit calculation; optionally, one
product stream may be requested.
The following conditions cause termination of calculations:
Zero or invalid feed.
Mixed phase feed.
Compressibility calculation failure.
Vapor which violates maximum pressure drop.
Incorrect product description.
Generation failure of product with flash or storage of product.
Phase change caused by pressure drop.
Inability to set product stream (when present).
Any of the above failures that prevent generation of a requested
product stream from the unit will result in termination of all other
PRO/II calculations as well.
Data to this subroutine are supplied in the RPARM array as follows:

RPARM(1) Pipe inside diameter, inches

RPARM(2) Pipe length, feet

18-20 Classic Unit Operations February 2009

 Note: The above dimensions cannot be changed; however, all
other input dimensions may be selected as desired by the
user.
Data for printout are passed into an output subroutine with corre-
sponding names, as follows:

IPARM(2) Input Integer Print switch:

1 Missing feed
2 Mixed phase feed
3 Z calculation failure
4 Missing diameter/length data
5 Vapor too large for method
6 Average properties used
7 Flash failure for product generation
8 Phase change occurs
9 Unable to set product stream
IPARM(3) Input Integer flag specifying the inlet phase:
1 Vapor
2 Liquid
RPARM(1) Inside diameter, inches
RPARM(2) Pipe length, feet
RPARM(3) Inlet temperature, °F
RPARM(4) Inlet pressure, psia
RPARM(5) Inlet Z factor
RPARM(6) Outlet temperature, °F
RPARM(7) Outlet pressure, psia
RPARM(8) Outlet Z factor
RPARM(9) Velocity, ft/sec
RPARM(10) Reynolds number
RPARM(11) Pressure drop, psi
RPARM(12) Friction factor

Note: A viscosity method must be declared in the thermodynamic

METHOD set used by this module. Otherwise, viscosity data
are not available for the Reynold’s number determination.
Reference: Crane Technical Paper 410, 1976.

PRO/II User-Added Subroutine User Guide 18-21

 Fortran Listings
USER42.FOR—User-Added Pressure Drop Routine

SUBROUTINE USER42( IPARM, RPARM, SUPPLE, HEAT,

& IDATA, ISOLVE, ISTOP )
!
! Compute pressure drops in steel pipes for liquids
! and vapors. MIXED feeds are NOT ALLOWED.
!
INCLUDE ‘PMXUSR.CMN’ ! brings in MAXCN
INCLUDE ‘FACTOR.CMN’ ! conversion factors
INCLUDE ‘XPROPX.CMN’ ! component properties
!
INTEGER(4) :: IPARM(*), IDATA(*), ISOLVE, ISTOP
REAL(4) :: RPARM(*), SUPPLE(*), HEAT(*)
!
REAL(4) :: STREAM(MAXCN+10), PROP(MAXCN),
& XKAY(MAXCN), VAP(MAXCN+10),
& XLIQ(MAXCN+10), XLQ2(MAXCN+10)
CHARACTER*12 CID
CHARACTER*40 CNAME
!
1001 FORMAT(‘ERROR !! FEED STREAM ‘,A12,’ IS MISSING’)
1002 FORMAT(‘ERROR !! FEED STREAM ‘,A12, ‘ IS MIXED PHASE’)
1003 FORMAT(‘ERROR !! COMPRESSIBILTY CALCULATION FAILURE’)
1004 FORMAT(‘ERROR !! PIPE DIMENSIONS INVALID ‘ /
+ ‘DIAMETER = ‘,E15.6,/,
+ ‘LENGTH = ‘,E15.6)
1005 FORMAT(‘ERROR!! DELTA P FOR VAPOR EXCEEEDS 40% ‘,
& ‘INLET PRESSURE’)
1007 FORMAT(‘ERROR !! FLASH FAILURE AT OUTLET CONDITION’)
1008 FORMAT(‘ERROR!! PHASE CHANGE AT OUTLET - CALCULATION
& ‘INVALID’)
1009 FORMAT(‘ERROR !! UNABLE TO STORE PRODUCT STREAM ‘,A12)
!
IERR = 0
NOP = IDATA(2)
NOCX = IDATA(4)
IOUT = IDATA(6)
DO I = 1, MAXCN+10
STREAM(I) = 0.0
END DO
!
! Use IPARM(2) as the output switch
!
IPARM(2) = 0
!
! Retrieve feed stream
!
CALL URXINF( ‘FEED’, 1, CID, CNAME, IERR )
IF( IERR .EQ. 0 ) THEN

18-22 Classic Unit Operations February 2009

 CALL URXSTR(CID,STREAM,1,IERR)
ENDIF
IF( IERR. NE. 0 .OR. STREAM(1) .LE. 0.0) THEN
IPARM(2) = 1
WRITE( IOUT, 1001 ) CID
ISOLVE = 1
ISTOP = 1
GO TO 9999
ENDIF
!
! Set Phase flag - Check for mixed-phase feed
!
IF( ABS(STREAM(5) - 1.0) .LT. 0.01 ) THEN
IFAZE = 2
ELSE IF( STREAM(5) .LT. 0.01 ) THEN
IFAZE = 1
ELSE
IPARM(2) = 2
WRITE( IOUT, 1002 ) CID
ISOLVE = 1
ISTOP = 1
GO TO 9999
ENDIF
!
! Calculate compressibility factor
!
CALL UHS( 3, IFAZE, STREAM, ZF, DZ, IERR )
!
IF( IERR .NE. 0 ) THEN
IPARM(2) = 3
WRITE( IOUT, 1003 )
ISOLVE = 1
ISTOP = 1
GO TO 9999
ENDIF
!
! Calculate feed stream molecular weight
!
WT = 0.0
DO I = 1,NOCX
WT = WT + STREAM(I+10) * XMW(I)
END DO
WT = WT / STREAM(1)
!
! Retrieve inlet temperature(r), pressure(psia),
! and density(lb/ft3)
!
DEGR = (STREAM(2) + TCONVT) * TFAC
PSIA = (STREAM(3) + PCONVT) * PFAC
RHO = PSIA * WT / ZF / DEGR / 10.731
!
! Check pipe diameter and length
!
PRO/II User-Added Subroutine User Guide 18-23
 DIA = RPARM(1)
XLEN = RPARM(2)
!
IF( DIA .LE. 0.0 .OR. XLEN .LE. 0.0 ) THEN
IPARM(2) = 4
WRITE( IOUT, 1004 ) DIA, XLEN
ISOLVE = 1
ISTOP = 1
GO TO 9999
END IF
!
! CROSS-SECTIONAL AREA (FT2)
!
AREA = 3.14159 * DIA * DIA / 576.0
!
! Velocity (ft/sec)
!
CUFTSE = STREAM(1) * WT * WTFAC / TIMFAC / RHO
VELOC = CUFTSE / AREA
!
! CALCULATE VISCOSITY(CP)
!
CALL TTPROP( 5, IFAZE, PROP, STREAM, IERR )
!
IF( IFAZE .EQ. 1) THEN
CP = PROP(4) * VISFAC
ELSE
CP = PROP(2) * VISFAC
END IF
!
! Reynolds number
!
REY = 123.9 * RHO * DIA * VELOC / CP
!
! DARCY FRICTION FACTOR
!
IF( REY .LE. 2100.0 ) THEN
FFACT = 64. / REY
ELSE
XLOGF = -1.666 - 0.1962 * ALOG10(DIA)
FFACT = 10.0**XLOGF
ENDIF
!
! Pressure drop (psi)
!
DELTP = 0.001294 * RHO * FFACT * XLEN
& * VELOC * VELOC / DIA
!
! Convert delta P to input units
! Calculate outlet pressure
!
DELP = (DELTP / PFAC) - PCONVT
POUT = STREAM(3) - DELP

18-24 Classic Unit Operations February 2009

 !
! Save inlet conditions
!
RPARM(3) = DEGR - FTOR
RPARM(4) = PSIA
RPARM(5) = ZF
!
! Check assumptions for VAPOR
!
IF( IFAZE .EQ. 1 ) THEN
!
! Error if Delta P exceeds 40% of
! inlet pressure
!
IF( DELTP .GT. 0.4 * PSIA ) THEN
IPARM(2) = 5
WRITE( IOUT, 1005 )
ISOLVE = 1
ISTOP = 1
GO TO 9999
ELSE IF( DELTP .GT. 0.1*PSIA ) THEN
!
! Delta P between 10 & 40% of inlet pressure
! Use average density and velocity
STREAM(3) = POUT
CALL UHS( 3, IFAZE, STREAM, ZF2, DZ, IERR )
!
IF( IERR .NE. 0 ) THEN
IPARM(2) = 3
WRITE( IOUT, 1003 )
ISOLVE = 1
ISTOP = 1
GO TO 9999
END IF
!
DEGR =(STREAM(2) + TCONVT) * TFAC
PSIA =(STREAM(3) + PCONVT) * PFAC
RHO2 =PSIA * WT / ZF2 / DEGR / 10.731
RHOA =(RHO + RHO2) / 2.
CUFTSE= STREAM(1) * WT * WTFAC
& / TIMFAC / RHOA
VELO2 = CUFTSE / AREA
VELOA = (VELOC + VELO2) / 2.0
DELTP = 0.001294 * RHOA* FFACT * XLEN
& * VELOA * VELOA / DIA
POUT = RPARM(4) - DELTP
VELOC = VELOA
RHO = RHOA
IPARM(2) = 6
ENDIF
END IF
!
! Save Results
PRO/II User-Added Subroutine User Guide 18-25
 !
IPARM(3) = IFAZE
RPARM(9) = VELOC
RPARM(10) = REY
RPARM(11) = DELTP
RPARM(12) = FFACT
!
! Flash stream at outlet pressure
!
STREAM(3) = POUT
CALL UFLSH( STREAM, VAP, XLIQ, XLQ2,
& XKAY, 3, IERR )
!
! Check for flash failure
!
IF( IERR .NE. 0 ) THEN
IPARM(2) = 7
WRITE( IOUT, 1007 )
ISOLVE = 1
ISTOP = 1
GO TO 9999
END IF
!
! Store results from outlet flash
TCALC = VAP(2)
STREAM(2) = TCALC
STREAM(5) = (XLIQ(1) + XLQ2(1)) / STREAM(1)
STREAM(6) = XLQ2(1) / STREAM(1)
RPARM(6) = ((STREAM(2) + TCONVT) * TFAC) - FTOR
RPARM(7) = ( STREAM(3) + PCONVT) * PFAC
IF( ABS(STREAM(5) - 1.0) .LT. 0.01 ) THEN
IFAZE = 2
ELSE IF( STREAM(5) .LT. 0.01 ) THEN
IFAZE = 1
ELSE
IFAZE = 0
END IF
!
! Check for a phase change
!
IF( IFAZE .NE. IPARM(3) ) THEN
IPARM(2) = 8
WRITE( IOUT, 1008 )
ISOLVE = 1
ISTOP = 1
GO TO 9999
END IF
!
! Compute compressibility at outlet
!
CALL UHS( 3, IFAZE, STREAM, ZF2, DZ, IERR )
IF( IERR .NE. 0 ) THEN
IPARM(2) = 3

18-26 Classic Unit Operations February 2009

 WRITE( IOUT, 1003 )
ISOLVE = 1
ISTOP = 1
GO TO 9999
END IF
STREAM(7) = ZF2
RPARM(8) = ZF2
!
! Set Product streams
!
IF( NOP .NE. 0 ) THEN
CALL URXINF( ‘PROD’, 1, CID, CNAME, IERR )
IF( IERR .EQ. 0 ) THEN
CALL URXSTR( CID, STREAM, 2, IERR )
ENDIF
IF( IERR. NE. 0 ) THEN
IPARM(2) = 9
WRITE( IOUT, 1009 ) CID
ISOLVE = 1
ISTOP = 1
GO TO 9999
ENDIF
ENDIF
!
! SET SOLVE FLAG
!
ISOLVE = 10
!
9999 CONTINUE
END SUBROUTINE USER42

U42OUT.FOR—User-Added Output Routine

SUBROUTINE U42OUT( IPARM, RPARM, SUPPLE, HEAT, IDATA )
!
! Output routine for pressure drop unit operation
!
INTEGER(4) :: IPARM(*), IDATA(*)
REAL(4) :: RPARM(*), SUPPLE(*), HEAT(*)
CHARACTER(LEN=10) :: CPHASE
CHARACTER(LEN=12) :: CID
CHARACTER(LEN=40) :: CNAME
!
1001 FORMAT(‘ Unit ID - ‘, A12, ’ Name - ‘, A40 //
& ‘ **** PRESSURE DROP CORRELATIONS - ‘
& ‘STEEL PIPE *** ‘/)
1002 FORMAT(
& 10X,’ PIPE DIAMETER = ‘,F15.2, ’ INCHES’/
& 10X,’ PIPE LENGTH = ‘,F15.1, ’ FEET’ /
& 10X,’ PRESSURE DROP = ‘,F15.2, ’ PSI’ //
& 10X,’ INLET PRESSURE = ‘,F15.2, ’ PSIA’ /
& 10X,’ INLET TEMPERATURE = ‘,F15.2, ’ DEG F’ /
& 10X,’ INLET COMPRESSIBILITY = ‘,F15.4 //

PRO/II User-Added Subroutine User Guide 18-27

 & 10X,’ OUTLET PRESSURE = ‘,F15.2, ’ PSIA’ /
& 10X,’ OUTLET TEMPERATURE = ‘,F15.2, ’ DEG F’ /
& 10X,’ OUTLET COMPRESSIBILITY = ‘,F15.4 //
& 10X,’ PHASE = ‘,5X, A10 //
& 10X,’ VELOCITY = ‘,F15.4 ’ FT/SEC’ /
& 10X,’ REYNOLDS NUMBER = ‘,F15.1 /
& 10X,’ FRICTION FACTOR = ‘,F15.6 // )
!
1003 FORMAT(10X,’ FEED STREAM - ’, A12 / )
1004 FORMAT(10X,’ PRODUCT STREAM - ’, A12 / )
!
1010 FORMAT(‘** FEED STREAM MISSING **’)
1020 FORMAT(‘** MIXED PHASE FEED ***’)
1030 FORMAT(‘** COMPRESSIBILITY FACTOR CALCULATION ‘,
& FAILED **’)
1040 FORMAT(‘** PIPE DIMENSIONS NOT AVAILABLE **’)
1050 FORMAT(‘** CALC DELTA P EXCEEDS 40 % OF INLET ‘,
& ‘FOR VAPOR **’)
1060 FORMAT(‘** AVERAGE PROPERTIES USED FOR ABOVE ‘,
& ‘CALCULATIONS **’)
1070 FORMAT(‘** PRODUCT FLASH FAILED **’)
1080 FORMAT(‘** PHASE CHANGE AT OUTLET INVALIDATES ‘,
& ‘CALCULATIONS**’)
1090 FORMAT(‘** ERROR SETTING UP PRODUCT STREAM **‘)
!
! Retrieve data from arrays
!
NOP = IDATA(2)
IOUT = IDATA(6)
ISW = IPARM(2)
!
! Write the output report page header
!
CALL HEAD
!
! Write the unit operation TITLE
!
CALL URXINF( ‘UNIT’, 0, CID, CNAME, IERR )
WRITE( IOUT, 1001 ) CID, CNAME
!
! Skip the output report if error code 1 - 5 applies
!
IF( ISW .EQ. 0 .OR. ISW .GT. 5 ) THEN
IF( IPARM(3) .EQ. 1 ) THEN
CPHASE = ‘VAPOR’
ELSE
CPHASE = ‘LIQUID’
END IF
WRITE( IOUT, 1002 )
& RPARM(1), RPARM(2), RPARM(11),
& RPARM(4), RPARM(3), RPARM(5),
& RPARM(7), RPARM(6), RPARM(8), CPHASE,
& RPARM(9), RPARM(10), RPARM(12)

18-28 Classic Unit Operations February 2009

 END IF
CALL URXINF( ‘FEED’, 1, CID, CNAME, IERR )
WRITE( IOUT, 1003 ) CID
IF( NOP .NE. 0 ) THEN
CALL URXINF( ‘PROD’, 1, CID, CNAME, IERR )
WRITE( IOUT, 1004 ) CID
END IF
ISW = ISW + 1
IF( ISW .EQ. 1 ) THEN
CONTINUE
ELSE IF( ISW .EQ. 2 ) THEN
WRITE(IOUT,1010)
ELSE IF( ISW .EQ. 3 ) THEN
WRITE(IOUT,1020)
ELSE IF( ISW .EQ. 4 ) THEN
WRITE(IOUT,1030)
ELSE IF( ISW .EQ. 5 ) THEN
WRITE(IOUT,1040)
ELSE IF( ISW .EQ. 6 ) THEN
WRITE(IOUT,1050)
ELSE IF( ISW .EQ. 7 ) THEN
WRITE(IOUT,1060)
ELSE IF( ISW .EQ. 8 ) THEN
WRITE(IOUT,1070)
ELSE IF( ISW .EQ. 9 ) THEN
WRITE(IOUT,1080)
ELSE IF( ISW .EQ. 10 ) THEN
WRITE(IOUT,1090)
END IF
!
END SUBROUTINE U42OUT

PRO/II Keyword Input File

TITLE PROB=USERADD, PROJ=U42, USER=SIMSCI, DATE=JUN06
$
$ TESTS USER42 AND U42OUT
$
DIME LIQV=BBL
COMPONENT DATA
LIBID 1, C1/ 2, C2/ 3, C3
TBPCUTS 100, 1500, 10
THERMO DATA
METHODS KVALUE=SRK, ENTHALPY=SRK, ENTROPY=SRK, &
TRANSPORT=PETRO, NAME=DEFAULT, &
DENS(L)=API, DENS(V)=SRK
METHODS KVALUE=GS, ENTHALPY=CP, ENTROPY=SRK, &
TRANSPORT=PETRO, NAME=M2, &
DENS(L)=API, DENS(V)=SRK
STREAM DATA
PROP STRM=1, TEMP=40, PRES=1300, PHASE=V, &
RATE(G)=4.3E6, COMP=75/ 21/ 4

PRO/II User-Added Subroutine User Guide 18-29

 PROP STRM=2, TEMP=60, PRES=150, RATE(V)=1900, &
ASSAY=LV
API STRM=2, AVG=30.6
TBP STRM=2, DATA=0,100/ 10,275/ 30, 475/ &
50,620/ 70,840/ 100,1500
NAME 1,NATL GAS/ 2,CRUDE OIL
UNIT OPERATIONS
$ Natural gas flowing through 10 mile pipeline
US2 UID=P2, NAME=NATL GAS DP
FEED 1
PROD P2V
RPARM 13.376, 52800
$ Natural gas flowing through 100 mile pipeline
US2 UID=P3, NAME=NATL GAS
FEED 1
RPARM 13.376, 528000
$ Crude oil flowing through 5 mile line
US2 UID=P1, NAME=CRUDE DP
FEED 2
RPARM 12.09, 26400
METHODS ID=M2
END

Partial PRO/II Output

SIMULATION SCIENCES INC. R PAGE P-2
PROJECT U42 PRO/II UAS 386/EM
PROBLEM USERADD OUTPUT SIMSCI
CALCULATION SEQUENCE AND RECYCLES JUN06
===============================================================
CALCULATION SEQUENCE
SEQ UNIT ID UNIT TYPE
——— ——————— —————————
1 P2 USER-ADDED
2 P3 USER-ADDED
3 P1 USER-ADDED
===============================================================
UNIT 1, ‘P2’, ‘NATL GAS DP’
UNIT ID - P2 NAME - NATL GAS DP
**** PRESSURE DROP CORRELATIONS - STEEL PIPE ***
PIPE DIAMETER = 13.38 INCHES
PIPE LENGTH = 52800.0 FEET
PRESSURE DROP = 37.41 PSI
INLET PRESSURE = 1300.00 PSIA
INLET TEMPERATURE = 40.00 DEG F
INLET COMPRESSIBILITY = 0.6543
OUTLET PRESSURE = 1262.59 PSIA
OUTLET TEMPERATURE = 37.61 DEG F
OUTLET COMPRESSIBILITY = 0.6540
PHASE = VAPOR
VELOCITY = 8.7047 FT/SEC
REYNOLDS NUMBER = 7157016.5

18-30 Classic Unit Operations February 2009

 FRICTION FACTOR = 0.012972
FEED STREAM - 1
PRODUCT STREAM - P2V

UNIT 2, ‘P3’, ‘NATL GAS’

UNIT ID - P3 NAME - NATL GAS
**** PRESSURE DROP CORRELATIONS - STEEL PIPE ***
PIPE DIAMETER = 13.38 INCHES
PIPE LENGTH = 528000.0 FEET
PRESSURE DROP = 378.16 PSI
INLET PRESSURE = 1300.00 PSIA
INLET TEMPERATURE = 40.00 DEG F
INLET COMPRESSIBILITY = 0.6543
OUTLET PRESSURE = 921.84 PSIA
OUTLET TEMPERATURE = 11.09 DEG F
OUTLET COMPRESSIBILITY = 0.6642
PHASE = VAPOR
VELOCITY = 9.7048 FT/SEC
REYNOLDS NUMBER = 7157016.5
FRICTION FACTOR = 0.012972
FEED STREAM - 1
** AVERAGE PROPERTIES USED FOR ABOVE CALCULATIONS **

UNIT 3, ‘P1’, ‘CRUDE DP’

UNIT ID - P1 NAME - CRUDE DP
**** PRESSURE DROP CORRELATIONS - STEEL PIPE ***
PIPE DIAMETER = 12.09 INCHES
PIPE LENGTH = 26400.0 FEET
PRESSURE DROP = 28.08 PSI
INLET PRESSURE = 50.00 PSIA
INLET TEMPERATURE = 60.00 DEG F
INLET COMPRESSIBILITY = 0.1229
OUTLET PRESSURE = 121.92 PSIA
OUTLET TEMPERATURE = 59.94 DEG F
OUTLET COMPRESSIBILITY = 0.0999
PHASE = LIQUID
VELOCITY = 3.7112 FT/SEC
REYNOLDS NUMBER = 101227.2
FRICTION FACTOR = 0.013232
FEED STREAM - 2

PRO/II User-Added Subroutine User Guide 18-31

User-Added Pipe Pressure Drop Utility Routines
The PIPE unit operation in PRO/II supports up to two user-added
subroutines at a time to compute the pressure drop through the pipe.
Each PIPE unit in the simulation can access one or the other of
these two routines by specifying either DP1 or DP2 as the argument
to the DPCORR keyword on the LINE statement. PRO/II already
includes sample calculation routines, so these two options may be
exercised in the version as delivered. The following table shows the
association between the input keywords and the corresponding
pressure drop routine.

DPCORR = Selects the pressure drop correlation. Arguments

DP1 and DP2 select a user-added subroutine
written and built in the User-Added Library.
DP1 PIPUS1.FOR performs pressure drop calculations.
DP2 PIPUS2.FOR performs pressure drop calculations.

Developer Information
Of course, the intended purpose is to allow you to implement and
use your own pressure drop correlation(s) instead of using those
provided by SIMSCI. To create your own pressure drop correlation
routine, you must replace the subroutine supplied by SIMSCI with
one that contains your own code. Custom routines must include the
following argument list:
SUBROUTINE PIPUS2(
& HLNS, AINCL, DIAM, AREA, RUFF,
& RNUMB, FRICT, FROUDE, NOACCL, PRES,
& RLVELN, VELSL, VELSG, QLI, QGI,
& RLDENS, VISL, RLSTEN, RVDENS, VISV,
& HL, IREG, FRGR, ELGR, ACCGR,
& DPINCR, NFOUT, IDG, NUIDD, NSAVE,
& INTAB )
The 31 arguments are defined as follows:

Name Type Brief Description UOM

HLNS DP No slip holdup
≤ 0.0 = Single-phase vapor
0.0<HLNS<1.0 = Mixed phase
(vap+liq)
≥1.0 = Single-phase liquid
1) DP indicates the argument is a double precision floating point value.
2) Chr*(*) indicates the argument is an inherited-length character string.
3) All Integer variables are type INTEGER(4)

18-32 Classic Unit Operations February 2009

 Name Type Brief Description UOM
AINCL DP Pipe inclination angle radians
DIAM DP Pipe inside diameter feet
AREA DP Pipe inside area square feet
RUFF DP Pipe roughness/diameter ratio
RNUMB DP Reynolds number
FROUDE DP Froude number
NOACCL Integer NOACCELERATION keyword
flag
0= acceleration APPLIED
1= acceleration OMITTED
PRES DP Absolute pressure psia
RLVELN DP Pipe liquid VELOCITY number
VELSL DP Pipe liquid SUPERFICIAL ft/sec
VELOCITY
VELSG DP Pipe vapor SUPERFICIAL ft/sec
VELOCITY
QLI DP Pipe liquid FLOWRATE cu.ft/sec
QGI DP Pipe vapor FLOWRATE cu.ft/sec
RLDENS DP Pipe liquid (oil+water) lb/cu.ft
DENSITY
VISL DP Pipe liquid (oil+water) cP
VISCOSITY
RLSTEN DP Pipe liquid (oil+water) dyne/cm
SURFACE TENSION
RVDENS DP Pipe vapor DENSITY lb/cu.ft
VISV DP Pipe vapor VISCOSITY cP
NFOUT Integer Fortran File Unit for printing
diagnostic messages
IDG Integer Diagnostic printout flag (DUMP
value)
0= Suppress diagnostics
1= Generate diagnostics
NUIDD Chr*(*) Character string containing ID of
(calling) unit op
1) DP indicates the argument is a double precision floating point value.
2) Chr*(*) indicates the argument is an inherited-length character string.
3) All Integer variables are type INTEGER(4)

PRO/II User-Added Subroutine User Guide 18-33

 Name Type Brief Description UOM
NSAVE Integer Not used here
INTAB Integer Not used here. Replace by IDG.
OUTPUT Variables
FRICT DP Pipe friction factor (Calculated
and returned even when no input
value is supplied)
HL DP Pipe slip holdup
IREG Integer PD method flow regime flag
1= Liquid
2= Vapor
3= Distributed
4= Intermittent
5= Segregated
6= Transition
FRGR DP Friction gradient psi/ft
ELGR DP Elevation gradient psi/ft
ACCGR DP Acceleration gradient psi/ft
DPINCR DP Total gradient FRGR + ELGR + psi/ft
ACCGR
1) DP indicates the argument is a double precision floating point value.
2) Chr*(*) indicates the argument is an inherited-length character string.
3) All Integer variables are type INTEGER(4)

Note: Be sure to include the SIMSCI-provided INCLUDE file

PRECIS.CMN as the first line of active code after the
SUBROUTINE statement. This helps ensure that all floating-
point arguments are type DOUBLE PRECISION.

18-34 Classic Unit Operations February 2009

 Chapter 19
Reaction Kinetic Subroutines

User-added reaction kinetic subroutines provide users the capability

of writing reactor rate equation subroutines for use with the CSTR
and PLUGFLOW unit operations. Users may write up to five such rou-
tines, any of which may be utilized by CSTR or PLUGFLOW reactors
throughout the flowsheet.

Note: Shorter reaction kinetic models may be more easily inte-

grated into PRO/II using the In-Line Fortran feature (see
the PRO/II Keyword Manual).

User Information
Input Description
Reaction Kinetic subroutines must be selected in each unit opera-
tion that uses them. Only the CSTR and PLUGFLOW unit operations
support their use. See the PRO/II Keyword Manual for further infor-
mation about CSTR and PLUGFLOW input data requirements.

Selecting Reaction Kinetics Subroutines

In the UNIT OPERATION section of the PRO/II keyword input file,
indicate which reactor model to use:
CSTR or PLUGFLOW UID = uid, {NAME=text}
On the CALCULATION statement, select one of the five available
kinetic models. Specify the SUBROUTINE option on the KINETICS key-
word and enter the subroutine identifier as the argument.
RXCALC KINETICS(SUBROUTINE)=U1 (or U2, U3, U4 or U5).

PRO/II User-Added Subroutine User Guide 19-1

 U1, U2, U3, Each of these keywords designates a specific user-
U4, U5 added kinetics subroutine to use for rate calculations.
Table 19-1 shows the correspondence between this
key word and the actual kinetics subroutines

Table 19-1: Keywords for User-Added Kinetics Subroutines

Input User-Added
Keyword Kinetics Subroutine
U1 USKIN1
U2 USKIN2
U3 USKIN3
U4 USKIN4
U5 USKIN5

Keywords for User Data Input

IPARM integer {, integer, ....} (Up to 10 values)
RPARM real {, real, .... } (Up to 70 values)
SUPPLEMENTAL i, reali {, ... / j, realj+1 ... } (Up to 200 values)
Users enter most reaction data for a CSTR or PLUGFLOW reactor unit
operation using the normal keywords provided by PRO/II. How-
ever, a user-added kinetics routine may require additional data for
its own use. The data requirements are defined by the developer of
the user-added subroutine; not by SIMSCI or PRO/II.
Users setting up a simulation supply this additional data by using
the IPARM, RPARM, and SUPPLEMENTAL keyword statements. Enter
integer data in the IPARM array and floating-point data in the RPARM
and SUPPLEMENTAL arrays. Alternatively, the PROVISION Graphi-
cal User Interface also supports this input through Date Entry Win-
dows of the reactor unit operations. In both the keyword and GUI
interfaces, follow the data entry instructions obtained from the
developer of the user-added subroutine.

Note: The following definitions only include limitations imposed

by PRO/II. Developers of user-added unit operations may
impose additional restrictions on data input that users must
observe.

19-2 Reaction Kinetic Subroutines February 2009

 Integer Inputs
IPARM integer {, integer, ....} (Up to 70 values)

Note: User-written subroutines may change the values of input

data.
Real Number Inputs
RPARM real {, real , .... } (Up to 70 values)
SUPPLEMENTAL i, reali {, ... / j, realj+1 ... } (Up to 200 values)

Note: User-written subroutines may change the values of RPARM

and SUPPLEMENTAL input data. RPARM’s are accessible by
the CONTROLLER, MVC, OPTIMIZER, and CALCULATOR units.
They also may be used or changed by CASESTUDYs.

User-Added Kinetics and Controllers

Parameters stored in the RPARM array for a user-written kinetic mod-
ule may be used by a feedback controller as control parameters.
They may also be used in the specification of a feed forward con-
troller (DEFINE), a feedback controller (CONTROLLER, MVC), or a
flowsheet OPTIMIZER. Only values stored in the RPARM array are
available as flowsheet parameters.
See Chapters 10.5 and 10.6 of the PRO/II Keyword Manual for
more details on the CONTROLLER unit and DEFINE feature.

Developer Information
Guidelines
Most data is communicated to the user-added kinetics subroutine
through the argument list. There are no streams, although the input
includes data that defines the thermal condition of the reacting
fluid.
Developers may wish to retrieve pure component data from com-
mon block /XPROPX/ or /XPROPY/, dimensional unit conversion fac-
tors from /FACTOR/, and stream properties through subroutine
TTPROP (see Chapter 15, ”Interfacing Software”).

PRO/II User-Added Subroutine User Guide 19-3

 Note: Interface subroutine URXSTR, used to store and retrieve
stream data, is not available in USKINn subroutines, since
streams are not used.

Calculation Routines -- Fortran Coding Conventions

Calling sequence:
CALL USKINn( RSDAT1, RSDAT2, RRDAT1, IRDAT1,
& RPARM, IPARM, SUPPLE, STOICH,
& ORDER, IDBASE, ACTIVE, PREEXP,
& RATES, IERR )
where:

USKINn The name of a pre-defined kinetics subroutine. It must

be one of USKIN1, USKIN2, USKIN3, USKIN4, or USKIN5

The data shown in Table 19-2 are supplied by PRO/II through the
argument list and should not be altered in subroutine USKINn. Many
of the variables in the argument list for routines USKINn are accessi-
ble through in-line kinetic procedure variables (see Chapter 10.7,
Procedure Data, in the PRO/II Keyword Manual). Also see
Table 19-3 for additional data that may be required by individual
kinetics routines.
Table 19-2: USKINn Input Data Supplied by PRO/II
Input In-Line
Argument Description Procedure
RSDAT1( 1-50 )
Element Reacting Fluid Properties Variable

1 Temperature of reacting fluid RTEMP

2 Pressure of reacting fluid RPRES
3 Molecular weight of reacting fluid RMW
4 Specific gravity (60/60) of reacting fluid RSPGR
5 Molar flow rate of reacting fluid RMRATE
6 Weight flow rate of reacting fluid RWRATE
7 Standard volumetric flow rate of reacting fluid RSVRAT
(LIQVOL units if OPERATION PHASE=L,
VAPVOL units if OPERATION PHASE=V)

19-4 Reaction Kinetic Subroutines February 2009

 Table 19-2: USKINn Input Data Supplied by PRO/II
Input In-Line
Argument Description Procedure
8 Actual volumetric flow rate of reacting fluid RAVRAT
(LIQVOL units if OPERATION PHASE=L else
VAPVOL units if OPERATION PHASE=V)
9 Liquid mole fraction of reacting fluid RLFRAC
10 Vapor viscosity RVVISC
11 Liquid viscosity RLVISC
12 Vapor conductivity RVCOND
13 Liquid conductivity RLCOND
14 Vapor specific heat (wt. basis) RVCP
15 Liquid specific heat (wt. basis) RLCP
16 Surface tension RSURF
17 Temperature in absolute input units RTABS
18-50 Not used
RSDAT1( 51-67 )
PFR Utility Stream Properties
Same as RSDAT1(1-17) for PFR heating/cooling stream. Variable names use
to U replace R to indicate utility side.
Element Variable
51 Temperature of reacting fluid UTEMP
52 Pressure of reacting fluid UPRES
53 Molecular weight of reacting fluid UMW
54 Specific gravity (60/60) of reacting fluid USPGR
55 Molar flow rate of reacting fluid UMRATE
56 Weight flow rate of reacting fluid UWRATE
57 Standard volumetric flow rate of reacting fluid USVRAT
(LIQVOL units if OPERATION PHASE=L,
VAPVOL units if OPERATION PHASE=V)
58 Actual volumetric flow rate of reacting fluid UAVRAT
(LIQVOL units if OPERATION PHASE=L else
VAPVOL units if OPERATION PHASE=V)
59 Liquid mole fraction of reacting fluid ULFRAC
60 Vapor viscosity UVVISC
61 Liquid viscosity ULVISC

PRO/II User-Added Subroutine User Guide 19-5

 Table 19-2: USKINn Input Data Supplied by PRO/II
Input In-Line
Argument Description Procedure
62 Vapor conductivity UVCOND
63 Liquid conductivity ULCOND
64 Vapor specific heat (wt. basis) UVCP
65 Liquid specific heat (wt. basis) ULCP
66 Surface tension USURF
67 Temperature in absolute input units UTABS
68-100 Not used

RSDAT2( 1-300 )
Element Reacting Fluid Component Data Variable
1-50 Total stream fractions for components 1-50 of XTOTAL
reacting fluid
51-100 Concentrations for components 1-50 in the XCONC
reacting fluid (weight-moles/liquid volume for
OPERATION PHASE=L else weight moles/vapor
volume)
101-150 Vapor fugacities for components 1-50 in the XVFUG
reacting fluid
151-200 Liquid phase activities XLACT
201-250 Vapor phase component mole fractions XVAP
251-300 Liquid phase component mole fractions XLIQ

RRDAT1( 1-10 )
Element Reactor Configuration Data Variable
1 Tube diameter, in. (English) or mm (metric, TDIAM
SI). (PLUGFLOW only)
2 Total tube length, ft. (English) or m (metric, TLEN
SI). (PLUGFLOW only)
3 Cumulative tube length (position of finite CUMLEN
element from reactor front end), ft. (English)
or m (metric, SI). (PLUGFLOW only)
4 Current step size (delta X), in. (English) or DELX
mm (metric, SI). (PLUGFLOW only)

19-6 Reaction Kinetic Subroutines February 2009

 Table 19-2: USKINn Input Data Supplied by PRO/II
Input In-Line
Argument Description Procedure
5 Current finite element volume (DV), LIQVOL DELV
units for OPERATION PHASE=L, else VAPVOL
units. (PLUGFLOW only)
Total reactor volume, LIQVOL units for VOLUME
OPERATION PHASE=L, else VAPVOL units.
(CSTR only)
6-9 Not used
10 Gas constant, R RGAS

IRDAT1( 1-10 )
Element Miscellaneous Integer Data Variable
1 Number of components NOC
2 Number of reactions (stoichiometric NOR
equations)
3 OPERATION PHASE flag: IRPHAS
0 No errors
1 V
2 L
4 CALCULATION flag: ICPF
0 Concentration
1 Partial Pressure
2 Fugacity
3 Activity
5 Current integration step number ISTEP
6 Standard output file Fortran unit number IOUT
7 Index file Fortran unit number INDX
8-10 Not used

STOICH Stoichiometry of each component in each -

(50,15) reaction

ORDER Order of reaction for each component in each -

(50,15) reaction

IDBASE Base component for each reaction -

(1-15)

PRO/II User-Added Subroutine User Guide 19-7

 Table 19-2: USKINn Input Data Supplied by PRO/II
Input In-Line
Argument Description Procedure
ACTIVE Activation energy for each reaction -
(1-15)
PREEXP Pre-exponential factor for each reaction -
(1-15)

Additional Subroutine-Specific Input Data

Developers of user-added kinetics routines may require additional
data input from the user. PRO/II support this and makes the data
available through additional array in the subroutine argument list.
Table 19-3 lists the data arrays in the argument list that transmit this
additional data. Any or all of the data values in these arrays may be
changed to different values inside the user-added-kinetics routine if
desired.
Table 19-3: USKINn Additional Subroutine-Specific Input
Data
Additional In-Line
Input Procedure
Argument Description Variable
RPARM Subroutine-specific Real data required RDATA
(1-70) by the subroutine developer (available
to other unit operations in the flow
sheet).
IPARM Subroutine-specific Integer data IDATA
(1-10) required by the subroutine developer.
SUPPLE Subroutine-specific Real data required -
(1-200) by the subroutine developer (available
only within the kinetics subroutine).

19-8 Reaction Kinetic Subroutines February 2009

 Required Output Data
The purpose of a kinetics subroutine is to compute the overall reac-
tion rate of each reaction. These results are returned through the
argument list. In addition, PRO/II requires the subroutine to return a
status flag indicating whether or not the returned results are valid.
The data shown in Table 19-4 must be calculated and returned to
PRO/II (through the argument list).
Table 19-4: USKINn Output Arguments & In-Line Procedure
Variables
In-line
Required Procedure
Returned Data Description Variable
RATES(1-15) Reaction rates for all defined RRATES
reactions (Wt-moles/time)
IERR Error flag -
0 No errors, results are valid.
1 Error, calculations failed.

Coding Guidelines
Use the following type declaration statements inside the kinetics
subroutine for variables in the argument list.
REAL(4), INTENT(IN) :: &
& RSDAT1(100), RSDAT2(300), RRDAT1(10)
& STOICH(50,15), ORDER(50,15), ACTIVE(15),
& PREEXP(15), RATES(15)
!
INTEGER(4), INTENT(IN) ::
& IRDAT1(10), IDBASE(15)
!
INTEGER(4), INTENT(INOUT) :: IPARM(10)
REAL(4), INTENT(INOUT) ::
& RPARM(70), SUPPLE(200

Output Reports
PRO/II does not provide any mechanism to report the results from
user-added kinetics subroutines. Typically, users inspect the results
of the unit operations that employ user-added kinetics to validate
the calculations. Developers may designate an element of the IPARM
array as a print flag, and use it to write intermediate output from the
kinetics calculation routine.

PRO/II User-Added Subroutine User Guide 19-9

Example Problem—Allyl Chloride Production in a PFR
The following example illustrates the use of user kinetics rate
expressions for a simple power law model. The program allows the
user to choose between expressions based on partial pressures, con-
centrations, vapor phase fugacities, or liquid phase activities.
Fortran Listing
USKIN1—User-Added Power Law Kinetic Routine
SUBROUTINE USKIN1 (RSDAT1, RSDAT2, RRDAT1, IRDAT1,
1 RPARM, IPARM, SUPPLE, STOICH,
2 ORDER, IDBASE, ACTIVE, PREEXP,
4 RATES, IERR)
!
REAL(4) :: RSDAT1(100), RSDAT2(300), RRDAT1(10),
1 RPARM(70), SUPPLE(200), STOICH(50,15),
2 ORDER(50,15), ACTIVE(15), PREEXP(15),
4 RATES(15)
INTEGER(4) :: IRDAT1(10), IPARM(10), IDBASE(15)
REAL(8) :: RJ
!
! POWER LAW KINETICS - Concentrations (Default)
! - Partial Pressures (use calculated Partial Pres)
! - Vapor Fugacities (use IPARM 1, e.g.,IRDAT1(4))
!
! Code Begins Here
!
NC = IRDAT1(1) ! Total number of components
NRX = IRDAT1(2) ! Number of reactions
ATEMP = RSDAT1(1) ! Temperature (input)
RTABS = RSDAT1(17) ! Temperature on absolute basis
RGAS = RRDAT1(10) ! Universal Gas Constant
!
! Initialize rates to zero. Determine dimensionless
! Activation Energy, calculate Temperature Dependent Term
!
DO 500 J = 1,NRX
RATES(J) = 0.0 ! Initialize rates to zero.
ACTENG = ACTIVE(J) ! Reaction Activation Energy
!
! Convert Activation Energy from thousands to unit values
!
ACTENG = ACTENG * 1000.0
ERT = -ACTENG / (RGAS * RTABS)
RJ = PREEXP(J) * EXP( ERT )
DO 400 I = 1, NC
!
! Skip non-reactants (i.e., skip all products and
! components not in this reaction).
IF ((STOICH(I,J) .LT. 0.0) .AND.
& (ABS(ORDER(I,J)) .GE. 1.0E-20)) THEN

19-10 Reaction Kinetic Subroutines February 2009

 !
! Skip reaction if any reactant mole frac = 0.0
IF (RSDAT2(I) .LE. 0.0) GO TO 500
!
! Compute Rates using Partial Pressures
IF (IRDAT1(4) .EQ. 1) THEN
RJ = RJ * (RSDAT2(I)*RSDAT1(2))**ORDER(I,J)
!
! Compute Rates using vapor fugacities.
ELSEIF (IRDAT1(4) .EQ. 2) THEN
RJ = RJ * (RSDAT2(I+100)) ** ORDER(I,J)
!
! Compute Rates using Liquid Activities
ELSEIF (IRDAT1(4) .EQ. 3) THEN
RJ = RJ * (RSDAT2(I+150)) ** ORDER(I,J)
!
! Compute Rates using Concentrations (default)
ELSE
RJ = RJ * (RSDAT2(I+50)) ** ORDER(I,J)
END IF
END IF
400 CONTINUE
IB = IDBASE(J)
RATES(J) = RJ * STOICH(IB,J)
500 CONTINUE
!
END SUBROUTINE USKIN1

PRO/II User-Added Subroutine User Guide 19-11

PRO/II Keyword Input File
TITLE PROB=USPLUG, PROJ=USER-ADD, USER=BDC, DATE=JUN2008
COMPONENT DATA
LIBI 1,CL2/2,PRLN/3,ACL/4,12PR/5,HCL/6,H2O &
BANK= PROII_8.2:SIMSCI, PROII_8.2:PROCESS
THERMO DATA
METH SYST=PR, TRANS=LIBR
STREAM DATA
PROP STRM=1, TEMP=450, PRES=29.4, RATE=85, COMP=0.2/0.8
PROP STRM=1A, TEMP= 80, PRES=29.4, RATE=85, COMP=0.2/0.8
RXDATA
RXSET ID=RS1
REACTION ID=1
$ - GLOBAL DATA -
STOIC 1,-1/2,-1/3,1/5,1
HORX HEAT=-48,REFC=1,REFP=V,REFT=179
$ - KINETIC DATA -
KPARAMETER PEXP=2.1E11 , ACTIV=27.0096
KPHASE DEFAULT=VAPOR
KBASIS VAPOR=MOLAR
REACTION ID=2
$ - GLOBAL DATA -
STOIC 1,-1/2,-1/4,1
HORX HEAT=-79.2,REFC=1,REFP=V,REFT=179
$ - KINETIC DATA -
KPARAMETER PEXP=1.19E7 , ACTIV=6.81198
KPHASE DEFAULT=VAPOR
KBASIS VAPOR=MOLAR
UNIT OPS
PLUGFLOW UID=RX
FEED 1
PROD V=2
COLD FEED=1A, V=1B, TOUT=400, U=3.72
RXCA KINETICS(SUBR)=U1, NSTEPS=50
OPER LENG=20.0, DIAM=11.94, PHASE=V, DP=10, &
TUBE=4, COUNTER
RXSTOIC RXSET=RS1
REACTION 1
BASE COMP=1
REACTION 2
BASE COMP=1
END

19-12 Reaction Kinetic Subroutines February 2009

Output Listing
PLUGFLOW REACTOR SUMMARY JUN2008
=======================================================================
UNIT 1, 'RX'
OPERATING CONDITIONS
Reactor Flow Type Open Pipe
Thermal Specification Type Counter-Current Cooling
Duty, MM BTU/HR -0.4502
Total Heat of Reaction at 179.00 F, MM BTU/HR -0.9922
Tubes 4
Diameter, IN 11.9400
Length, FT 20.0000
Volume/Tube, FT3 15.5512
Total Volume, FT3 62.2050
U, BTU/HR-FT2-F 3.720
Residence Time, sec 5.24
Maximum Velocity at 20.00 FT from Inlet, FT/sec 4.6780
Pressure Drop From Feed Stream, PSIA 0.0000

REACTING SIDE Inlet Outlet

----------- -----------
Feed 1
VAPOR Product 2
Temperature, F 450.00 735.91
Pressure, PSIA 29.4000 19.4000

Cold Side Inlet Outlet

----------- -----------
Feed 1A
VAPOR Product 1B
Temperature, F 86.53 400.00
Pressure, PSIA 29.4000 29.4000

REACTION DATA
--------- Rates, LB-MOL/HR ----------
Fraction
Component Feed Change Product Converted
-------------------- ----------- ----------- ----------- -----------
1 CL2 17.0000 -16.9929 7.095E-03 0.9996
2 PRLN 68.0000 -16.9929 51.0071 0.2499
3 ACL 0.0000 11.3335 11.3335
4 12PR 0.0000 5.6594 5.6594
5 HCL 0.0000 11.3335 11.3335

Total 85.0000 -5.6594 79.3406

PRO/II User-Added Subroutine User Guide 19-13

 LB-MOL/HR Fraction
Base Component Reaction Converted Converted
-------------------- ----------- ----------- -----------
1 CL2 1 11.3335 0.6667
1 CL2 2 5.6594 0.3329
REACTOR MASS BALANCE
----------- Rates, LB/HR ------------ Fraction
Component Feed Change Product Converted
------------------ ----------- ----------- ----------- -----------
1 CL2 1205.3919 -1204.8888 0.5031 0.9996
2 PRLN 2861.4834 -715.0723 2146.4112 0.2499
3 ACL 0.0000 867.2976 867.2976
4 12PR 0.0000 639.4380 639.4380
5 HCL 0.0000 413.2252 413.2252
Total 4066.8753 0.0000 4066.8750

REACTOR PROFILES
Reacting Side Cold
Distance Temp Pres Temp
FT F PSIA F
----------- ----------- ----------- -----------
0 0.0000 450.00 29.4000 400.00
1 2.0000 565.61 28.4000 394.17
2 4.0000 703.25 27.4000 380.22
3 6.0000 822.73 26.4000 357.23
4 8.0000 868.01 25.4000 327.09
5 10.0000 862.72 24.4000 293.19
6 12.0000 842.55 23.4000 256.94
7 14.0000 818.20 22.4000 218.49
8 16.0000 792.05 21.4000 177.61
9 18.0000 764.60 20.4000 133.83
10 20.0000 735.91 19.4000 86.53
-- Component Mole Fractions vs. Distance from Inlet
Distance 1 3 4 2 5
FT CL2 ACL 12PR PRLN HCL
--------- ----------- ----------- ----------- ----------- -----------
0 0.0000 0.20000000 0.00000000 0.00000000 0.80000000 0.00000000
1 2.0000 0.16379562 0.01328580 0.02864823 0.78098455 0.01328580
2 4.0000 0.10707946 0.05075851 0.05270253 0.73870098 0.05075851
3 6.0000 0.04383621 0.10352300 0.06580099 0.68331680 0.10352300
4 8.0000 0.01198179 0.13208931 0.06991112 0.65392846 0.13208931
5 10.0000 0.00330047 0.13997237 0.07090894 0.64584584 0.13997237
6 12.0000 0.00110792 0.14194970 0.07117797 0.64381470 0.14194970
7 14.0000 0.00045995 0.14252608 0.07126746 0.64322043 0.14252608
8 16.0000 0.00023015 0.14272677 0.07130384 0.64301246 0.14272677
9 18.0000 0.00013461 0.14280830 0.07132136 0.64292743 0.14280830
10 20.0000 0.00008943 0.14284574 0.07133104 0.64288805 0.14284574

19-14 Reaction Kinetic Subroutines February 2009

 Chapter 20
UAS Refinery Reactor Simulation
The subroutines described in this chapter provide data and methods
for modeling pseudo components. To model behavior over broad
temperature and pressure ranges, refinery fluids are “characterized”
by taking fractionation cuts and creating “pseudo components”.
Pseudo components exhibit the average bulk properties of various
petroleum fractions. By creating pseudo components and knowing
just a few of their basic properties, good models can be created to
accurately model fluid behavior in refinery processes.

User Utility Subroutines

Table 20-1 is a quick reference to the subroutines described in this
chapter.
Table 20-1: Refinery Reactor Subroutines
Name Description See ...
UDEFNC Retrieves a component’s input (print) or 20-3
internal sequence number given the ID
and Library number.

USTHER Sets the current Thermodynamic method 20-5

to that of a given PRO/II stream. Resets
component properties in common /
XPROPY/.

DUPSEUC Retrieves start and end components, and 20-4

all cut-point temperatures, from a blend
as double precision values.
UPSEUC Single precision version of DUPSEUC. 20-4

PRO/II User-Added Subroutine User Guide 20-1

 Table 20-1: Refinery Reactor Subroutines
Name Description See ...
DUSTPRP Double precision routine that retrieves 20-6
properties from a PRO/II stream, one
scalar property value per call.
USTPRP Single precision version of DUSTPRP. 20-6

DUSTRIP Retrieves any scalar Refinery Inspection 20-7

Property from a PRO/II stream
USTRIP Single precision version of DUSTRIP. 20-7

DUDIST Generates a 21 point distillation cut-point 20-9

array. Temperature arrays in and out are
always in degrees Kelvin.
UDIST SIngle precision version of DUDIST. 20-9
Temperature arrays in and out use input
units of temperature.

URATE Retrieves flow rates of pseudo- 20-12

components from TBP distillation data.
UCURVE Computes pseudo-component properties 20-15
for current thermodynamics Methods set.
(2 data points required).
UPETMD Estimates missing component fixed 20-22
properties. Updates /XPROPY/ data.
UBULK Analog of UCURVE, when only a single 20-19
data point is available.
Common Blocks
/XPROPY/ Pure component data - may change for 20-23
each thermodynamic Methods set

20-2 "UAS Refinery Reactor Simulation" February 2009

 UDEFNC
This routine gets the position of a specified component based on
user input (print order) or, alternatively, the PRO/II internal order.
This component must be declared in the component section of the
flowsheet. Based on this information, the feed and product data of
the component can be correctly retrieved and stored regardless of its
input order declared in the input file. See also “Internal Component
Order vs. Print Order” on page 15-40.
Usage:
CALL UDEFNC( CompID, LibNo, iOpt, iCoNum )

Table 20-2: Arguments for Utility Subroutine UDEFNC()

Variable I/O Type Description
CompID In CHAR ID of a component declared in the
*16 component section of input.
LibNo In INT PRO/II library number uniquely
designated for the specified component.
It can be found using Modular
Thermodynamics. This number is used
only if cName is a blank string.
iOpt In INT Basis of component order. Since most
arrays in the UAS system use PRO/II
internal order, PRO/II internal order is
the default.
1 PRO/II internal order (default)
2 User input order (print order)
iCoNum Out INT Position of the specified component in
input order or PRO/II internal order. If
the component is not found, a zero
value is returned.

Example: Retrieve Internal Order Number of Hydrogen

CHARACTER(LEN=16) :: CompID
INTEGER(4) :: LibNo, iCoNum
...
CompID = ‘H2’
CALL UDEFNC( CompID, LibNo, 1, iCoNum )
iCoNum returns the internal order number of hydrogen.

PRO/II User-Added Subroutine User Guide 20-3

 DUPSEUC double precision
UPSEUC single precision
This routine gets the range of components in the specified blend set.
The returned range is based on PRO/II’s internal component order.
The initial and end boiling points of each petro narrow cut in the
blend are also retrieved. Once this component range is known, the
reactor product stream data can be stored in the components of the
specified blend set. The name of the blend set is specified at the
NAME of the user-added unit in the flowsheet.

Calling sequence:
CALL UPSEUC( IDATA, BP, IBEGIN, IEND, &
& BPTIP, BPTEP, IERR )

Table 20-3: Arguments for Utility Subroutine UPSEUC()

Variable I/O Type Description
IDATA I INTEGER This is the IDATA array in the user-added
(*) subroutine USERXX. If the blend set name
is not available in the IDATA(8-10), the
default set will be used.
BP I REAL The vector of normal boiling point.
(MAXCN)
IBEGIN O INTEGER The PRO/II internal order of the first
component in the blend.
IEND O INTEGER The PRO/II internal order of the last
component in the blend.
BPTIP O REAL The vector of initial boiling point of
(MAXCN) pseudo components in the blend.
BPTEP O REAL The vector of end boiling point of pseudo
(MAXCN) components in the blend.
IERR O INTEGER Error flag:
0 Successful
All other values indicate failure.

Example:
INCLUDE ‘PMXUSR.CMN’
INCLUDE ‘XPROPY.CMN’
...
REAL BPTIP(MAXCN), BPTEP(MAXCN)
...
CALL UPSEUC( IDATA, BP, IBEGIN, IEND, &
BPTIP,
BPTEP, IERR)

20-4 "UAS Refinery Reactor Simulation" February 2009

 USTHER
More than one thermodynamic set may be specified in the same
PRO/II flowsheet. Each set may have different component proper-
ties. This feature is very important to refinery reactors, because the
component properties of the product can be very different from
those of the feed. This routine sets up the thermodynamic data for
the selected stream so that the component properties corresponding
to the selected stream can be retrieved or stored properly. The com-
ponent data stored in the common block /XPROPY/ can also be
updated after the setup.

Note: To use this feature, it is required to declare CDATA = VARY

in the flowsheet (see General Data section in the PRO/II
Keyword Manual).
Calling sequence:
CALL USTHER( CID, ISETUP, JMETHD, IERR )

Table 20-4: Arguments for Utility Subroutine USTHER( )

Variable I/O Type Description
CID I CHAR The stream ID of the specified stream
*12
ISETUP I INT Property copy flag:
0 Do not copy the new component
properties to the XPROPY common
block (default)
1 Copy the new component properties
to the XPROPY common block
JMETHD O INT PRO/II internal thermo set number; -1
returned if thermo not set up successfully.
IERR O INT Error flag:
0 Successful
All other values = Failure

Example:
CHARACTER*12 CID
CHARACTER*40 CNAME
...
CALL URXINF(‘FEED’, 1, CID, CNAME, IERR)
...
ISETUP = 1
CALL USTHER( CID, ISETUP, JMETHD, IERR )

PRO/II User-Added Subroutine User Guide 20-5

 DUSTPRP double precision
USTPRP single precision
This routine retrieves a selected stream property from the specified
stream phase. Stream property values return in PRO/II internal
dimensional units, as shown in Table 20-5.
Usage (double precision):
CALL DUSTPRP(cSid, cPhase, cProp, DValue, iErr)
Usage (single precision):
CALL USTPRP(cSid, cPhase, cProp, DValue, iErr)

Table 20-5: Arguments for Utility Subroutine USTPRP()

Variable I/O Type Description
cSid In C*12 Character ID of selected stream, 12
characters maximum
cPhase In C*12 Phase of the property to be retrieved:
Character
‘TOTAL’ Total stream
‘VAPOR’ Vapor phase
‘LIQUID’ Bulk Liquid phase
‘MWS’ Molecular weight Solid phase
‘NMWS’ Non-molecular weight Solid
phase
cProp In C*12 The property to retrieve when the phase is
‘TOTAL’, ‘VAPOR’, ‘LIQUID’, or ‘MWS’:
‘TC’ Critical temperature, K
‘PC’ Critical pressure, kPa
‘VC’ Critical volume, m3
‘ZC’ Critical compressibility factor
‘OMEG’ Acentric factor
‘MW’ Molecular weight, kg/m3
‘SDEN’ Standard density, kg/m3
‘DENS’ Actual density, kg/m3
‘TCON’ Thermal conductivity, Watt/
(m-K)
‘VISC’ Viscosity, Pascal
‘SURF’ Surface tension, Newton/meter
‘RVP’ Reid vapor pressure, kPa
‘TVP’ True vapor pressure, kPa
‘ENTR’ Entropy, kJ/(kg-mole-K)
‘GIBB’ Gibbs free energy, kJ/(kg-
mole)

20-6 "UAS Refinery Reactor Simulation" February 2009

 Table 20-5: Arguments for Utility Subroutine USTPRP()
Variable I/O Type Description
cProp In C*12 The property to retrieve when the phase is
‘NMWS’ (non-molecular weight solid):
‘DENS’ Actual density, kg/m3
‘ENTR’ Entropy, kJ/(kg-K)
DVALUE Out Dbl Double precision stream property value
SVALUE Out Dbl Single precision stream property value
IERR Out Int Returned error flag:
0 Successful
≠0 Failed

Example:
CHARACTER(LEN=12) :: cSID, cPhase, cProp
CHARACTER(LEN=40) :: cName
REAL(8) :: DValue
... ! obtain ID of first feed stream
CALL URXINF( ‘FEED’, 1, cSID, cName, IERR )
... ! DValue returns total stream molecular weight
cPhase = ‘TOTAL’
cProp = ‘MW’
CALL DUSTPRP( cSID, cPhase, cProp, DValue, IERR )

DUSTRIP double precision

USTRIP single precision
In the refinery reactor simulation, refinery inspection properties are
frequently used to characterize the feed. This routine retrieves the
selected refinery property from the specified stream. The retrieved
refinery property must be declared in the thermodynamic METHOD
set used by the user-added subroutine. The property data can be
estimated by PRO/II or supplied by the user in the component,
thermo and stream data sections. Note that not all the refinery spe-
cial properties can be estimated by PRO/II.
Usage (double precision):
CALL DUSTRIP(cSid, cProp, iSProp, DVal, iErr)
Usage (single precision):
CALL USTRIP( cSid, cProp, iSProp, SVal, iErr )

PRO/II User-Added Subroutine User Guide 20-7

 Table 20-6: Arguments for Utility Subroutine USTRIP()
Variable I/O Description
cSid In The ID of the selected stream (12 characters max)
C*12
cProp In The property keyword (listed in Appendix Table
C*12 A-1) of the selected refinery property. Examples
are:
‘KVIS’ Kinematic viscosity
‘POUR’ Pour point
‘SULF’ Sulfur content
‘NICK’ Nickel content
For properties with more than one sub-type, add a hyphen
sign followed by the first two letters of the sub-type to the
property ID. Examples are:
‘REFR-C2’ Refractive index at 20C
‘REFR-C7’ Refractive index at 70C
‘AROM-TO’ Total aromatics content
‘AROM-RI’ Content of aromatics with ring structure
For user defined special properties, e.g., SPROP(I), pass a
blank string as the value of cProp (i.e., “ “).
iSProp In The property number of user special property
INT SPROP(i):
0 PRO/II predefined special property
1-9999 User special property
DVal Out Returned double precision property value
R*8
SVal Out Returned single precision property value
R*4
iErr Out Error flag:
INT
0 Successful
1 Property was not declared in the Thermo
section of input
All other values indicateFailure

Example:
...
CHARACTER*12 CID, ATEXT
CHARACTER*40 CNAME
...
CALL URXINF(‘FEED’, 1, CID, CNAME, IERR)
...
ATEXT = ‘SULF’
ISPROP = 0
CALL USTRIP( CID, ATEXT, ISPROP, VALUE, IERR)

20-8 "UAS Refinery Reactor Simulation" February 2009

 DUDIST double precision
UDIST single precision
Distillation data probably is the most important data for feed char-
acterization. This routine retrieves the distillation data for the speci-
fied stream. The distillation type, range, and basis can all be
specified.
Note this difference: DUDIST temperature arrays DBPIN and
DTempO always pass Kelvin values. UDIST temperature arrays
SBPIn and STempO always pass temperature values in temperature
units defined for problem input.
Usage (double precision):
CALL DUDIST( DStVec, DXMW, DBPIn, DSpGr, &
ITYPE, ICONV, IBASIS, DVIP, &
DVEP, NUMCOP, DTempO, IERR )
Usage (single precision):
CALL UDIST( SStVec, SXMW, SBPIn, SSpGr, &
ITYPE, ICONV, IBASIS, SVIP, &
SVEP, NUMCOP, STempO, IERR )

Table 20-7: Arguments for Utility Subroutine UDIST()

Variable I/O Data Type Description
DStVec In REAL*8 The standard user vector of stream data. DStVec is
(10+MAXCN) double precision and SStVec is single precision.
SStVec REAL*4
Only rates (element 1 and elements 11 to
(10+MAXCN)
10+NOC) are used here. See “User Stream Vector”
on page 15-10.
DXMW In REAL*8 Array of component molecular weights in internal
(MAXCN) component order. DXMW is double precision and
SXMW REAL*4
SXMW is single precision.
(MAXCN)
DBPIn In REAL*8 DBPIn is a double precision array of component
(MAXCN) normal boiling point temperatures in internal
component order. Values are passed in as Kelvin.
SBPIn REAL*4 SBPIn is a single precision array of temperatures,
(MAXCN) passed using temperature input units.
DSpGr In REAL*8 Array of component specific gravities at standard
(MAXCN) conditions in internal component order. Values are
SSpGr REAL*4
dimensionless. DSpGr is double precision and
(MAXCN)
SSpGr is single precision.

PRO/II User-Added Subroutine User Guide 20-9

 Table 20-7: Arguments for Utility Subroutine UDIST() (Continued)
Variable I/O Data Type Description
ITYPE In INTEGER Distillation type:
1 TBP (default)
2 D86
3 D86 with cracking
4 D86 at 10 mmHg
5 D1160 at 10 mmHg
6 D1160
7 D2887
ICONV In INTEGER Conversion method:
1 API63
2 API87
3 Edmister-Okamoto
6 API94
IBASIS In INTEGER Conversion basis: (applies to DVIP, DVEP, SVIP,
and SVEP
0 LV basis
1 WT basis
DVIP In REAL*8 The initial wt% or vol% (based on value of IBASIS
SVIP REAL*4 above). The value must be less than 5%. It is used
to determine the initial boiling point temperature
(IP). DVIP is double precision and SVIP is single
precision.
DVEP In REAL*8 The final wt% or vol% (based on value of IBASIS
SVEP REAL*4 above). It is used to determine the end boiling
point (EP). The value must be greater than 95%
and less than 99%. DVEP is double precision and
SVEP is single precision.
NUMCOP In INTEGER Total component number. This number can be
obtained from IDATA(4) in the USERXX routine.
Note that this number cannot be greater than
MAXCN in common block PMXUSR.CMN.
DTempO Out REAL*8 (21) Array of 21 boiling point temperatures of the 21
STempO REAL*4 (21) distillation curve points (IP, 5%, 10%, 15%, 20%,
… 85%, 90%, 95% and EP). Initial point IP is
supplied by argument DVIP or SVIP; end point EP is
supplied by argument DVEP or SVEP, above.
DTempO is double precision and returns all
temperature values as Kelvin.
STempO is single precision and returns
temperatures using input temperature units.

20-10 "UAS Refinery Reactor Simulation" February 2009

 Table 20-7: Arguments for Utility Subroutine UDIST() (Continued)
Variable I/O Data Type Description
IERR Out INTEGER Returned error flag:
0 No errors, successful
All other values indicate failure

Example:
...
INCLUDE ‘…\PMXUSR.CMN’
INCLUDE ‘…\XPROPY.CMN’
...
REAL STREAM(10+MAXCN), TDIST(21)
CHARACTER*12 CID, ATEXT
CHARACTER*40 CNAME
...
NUMCOP = IDATA(4)
CALL URXINF(‘FEED’, 1, CID, CNAME, IERR)
CALL URXSTR(CID, STREAM, 1, IERR)
...
ITYPE = 1
ICONV = 2
IBASIS = 1
WVIP = 0.2
WVEP = 99.0

CALL UDIST(STREAM, XMW,BP, DENS, ITYPE,

ICONV, IBASIS,WVIP, WVEP, NUMCOP,
TDIST, IERR)

PRO/II User-Added Subroutine User Guide 20-11

 DURATE double precision
URATE single precision
The pseudo components used in the refinery reactor simulation may
not be the same as that in the flowsheet simulation. In the reactor
simulation, the pseudo components are determined by the reaction
network that describes the reaction behavior. In the flowsheet simu-
lation, the pseudo components are determined by the assay data and
the blend cut points specified in the flowsheet (see ASSAY and
CUTPOINTS in the component data and stream data sections of the
PRO/II Keyword Manual). Due to the lack of one-to-one relation-
ship between the pseudo components in reactor and flowsheet simu-
lations, it is necessary to map the reactor product composition via
the product distillation data. This routine uses the TBP distillation
data of the reactor product stream predicted by the reactor simula-
tion to determine the flow rate of each pseudocomponent in the
product stream of the flowsheet.
Usage (double precision):
CALL DURATE( DTVEC, DYVEC, NCPSEU, &
ICUMUL, DFOUT, IBEGIN, &
IEND, DBPTIP, DBPTEP, &
IMETHD, IMAPED, DFRATE, &
IERR )
Usage (single precision):
CALL URATE( STVEC, SYVEC, NCPSEU, &
ICUMUL, SFOUT, IBEGIN, &
IEND, SBPTIP, SBPTEP, &
IMETHD, IMAPED, SFRATE, &
IERR )
Note that the flow rates of defined components such as H2, H2S,
CH4, C2H6, etc. should not be included here. The flow rates of
those defined components should be assigned to the STREAM array
directly without the need of component mapping.
Table 20-8: Arguments for Utility Subroutine URATE()
Variable I/O Data Type Description
DTVEC In REAL*8 Array of boiling point temperatures
(NCPSEU) of reactor pseudo-components in
STVEC REAL*4
(NCPSEU) PRO/II internal order. DTVEC is
double precision and STVEC is
single precision.

20-12 "UAS Refinery Reactor Simulation" February 2009

 Table 20-8: Arguments for Utility Subroutine URATE()
Variable I/O Data Type Description
DYVEC In REAL*8 Array of either liquid volume or
(NCPSEU) weight distribution data that
SYVEC REAL*4
(NCPSEU) correspond to temperatures in TVEC.
See curve option ICUMUL. DYVEC is
double precision and SYVEC is
single precision.
NCPSEU In INTEGER The number of reactor pseudo-
components. This also sizes arrays
DTVEC, STVEC, DYVEC, and DYVEC.
ICUMUL In INTEGER Cumulative curve data flag.
0 YVEC is a cumulative data array
(default)
1 YVEC is a distribution data array
DFOUT In REAL*8 Total liquid volume or weight flow
rate of the reactor pseudo-
SFOUT REAL*4
components included in temperature
range of TVEC. When this is greater
than zero, flow rates are normalized
to this value.
IBEGIN In INTEGER The component number (position)
of the first component in the blend
(in PRO/II internal order).
IEND In INTEGER The component number (position)
of the last component in the blend
(in PRO/II internal order).
DBPTIP In REAL*8 The vector of initial boiling point of
(MAXCN) pseudo components in the blend.
SBPTIP REAL*4
(MAXCN)
DBPTEP In REAL*8 The vector of end boiling point of
(MAXCN) pseudo components in the blend.
SBPTEP REAL*4
(MAXCN)
IMETHD In INTEGER Interpolation option:
1 Linear
2 Quadratic
3 Cubic spline
IMAPED Out INTEGER Array of component mapping flag:
(MAXCN)
0 Get zero flow rate from the
mapping
1 Get positive flow rate from the
mapping

PRO/II User-Added Subroutine User Guide 20-13

 Table 20-8: Arguments for Utility Subroutine URATE()
Variable I/O Data Type Description
DFRATE Out REAL*8 Array of mapped component flow
(MAXCN) rates
SFRATE REAL*4
(MAXCN)
IERR Out INTEGER Error flag:
0 Successful
≠0 Failed

Example:
...
INCLUDE ‘PMXUSR.CMN’
INTEGER(4), PARAMETER :: NCPSEU=7
INTEGER(4) :: IMAPED(MAXCN)
REAL(4) :: TVEC(NCPSEU), YVEC(NCPSEU)
REAL(4) :: FRATE(MAXCN), BPTIP(MAXCN),
REAL(4) :: BPTEP(MAXCN), FOUT
...
TVEC(1) = 15
TVEC(2) = 100
TVEC(3) = 350
TVEC(7) = 680
YVEC(1) = 0.0
YVEC(2) = 10.0
YVEC(3) = 30.0
YVEC(7) = 100.0
ICUMUL = 0
FOUT = 100.0
IMETHD = 3
CALL URATE( TVEC, YVEC, NCPSEU, ICUMUL,
& FOUT, IBEGIN, IEND, BPTIP,
& BPTEP, IMETHD, IMAPED, FRATE,
& IERR )

20-14 "UAS Refinery Reactor Simulation" February 2009

 DUCURVE double precision
UCURVE single precision
The refinery special properties are likely to be changed by the refin-
ery reactions. The property values in the same boiling range can be
very different between the feed and product. For instance, the sulfur
content is largely reduced in the hydro-treating reactions, the aro-
matics content is increased in the catalytic cracking reactions and
the molecular weight is changed by most refinery reactions. There-
fore, different thermodynamic METHOD sets (see Thermodynamic
Data section in the PRO/II Keyword Manual) should be used to
store the feed and product component properties separately.
CDATA=VARY (see General Data Section in the PRO/II Keyword
Manual) should also be declared in the flowsheet to support this
feature. This UCURVE routine can be used to determine the new
component properties for the pseudo components in the thermody-
namic set specified for the product stream. Note that this routine
should only be called when more than one data point is available
from the reactor simulation for the property to be mapped.
Usage (double precision):
CALL DUCURVE( cProp, ISPROP, DTVEC, &
DCPROP, NCPSEU, DBP, &
DFRATE, IBEGIN, IEND, &
DTMINI, dTMAXI, DYLOW, &
DYHIGH, IFILL, ITREND, &
IMETHD, IUPDAT, DSCALE, &
IMAPED, DTGYV, DSUMPRP, &
IERR )
Usage (single precision):
CALL UCURVE( cProp, iSProp, STVEC, &
SCPROP, NCPSEU, SBP, &
SFRATE, IBEGIN, IEND, &
STMINI, STMAXI, SYLOW, &
SYHIGH, IFILL, ITREND, &
IMETHD, IUPDAT, SSCALE, &
IMAPED, STGYV, SSUMPRP, &
IERR )

PRO/II User-Added Subroutine User Guide 20-15

 Table 20-9: Arguments for Utility Subroutine UCURVE()
Variable I/O Type Description
cProp I CHAR*12 The property keyword identifier
‘MW’ Molecular weight
‘SG60’ Specific gravity at 60F (15.5C)
‘OMEG’ Acentric factor
‘TC’ Critical temperature
‘PC’ Critical pressure
‘VC’ Critical volume
‘ZC’ Critical compressibility
‘RAKT’ Rackett parameter
‘CNUM’ Carbon number
‘ZNUM’ Hydrogen deficiency number
‘WATK’Watson K value
For refinery special properties, see cProp
explained in USTRIP routine.
iSProp I INTEGER The property number of user special property
SPROP(i):
0 PRO/II defined special property
1-9999 User special property (SPROP(i))
DTVEC I REAL*8 Array of end boiling points of reactor pseudo
(NCPSEU) components
STVEC REAL*4
(NCPSEU)
DCPROP I REAL*8 Array of property distribution data, one value
(NCPSEU) for each reactor pseudocomponent, in PRO/II
SCPROP REAL*4 internal component order. DCPROP is double
(NCPSEU) precision and SCPROP is single precision.
NCPSEU I INTEGER Number of reactor pseudo components. This is
also the size of TVEC and CPROP arrays.
DBP I REAL*8 Array of component normal boiling point
(MAXCN) temperatures in PRO/II internal component
SBP REAL*4 order. DBP is double precision and SBP is
(MAXCN) single precision.
See XPROPY common block for definition.
DFRATE O REAL*8 Array of mapped component flow rates in
(MAXCN) PRO/II internal component order. DFRATE is
SFRATE REAL*4 double precision and SFRATE is single
(MAXCN) precision.
IBEGIN I INTEGER The PRO/II internal order number of the first
component in the blend.
IEND I INTEGER The PRO/II internal order number of the last
component in the blend.

20-16 "UAS Refinery Reactor Simulation" February 2009

 Table 20-9: Arguments for Utility Subroutine UCURVE() (Continued)
Variable I/O Type Description
DTMINI I REAL*8 The initial temperature of the temperature
STMINI REAL*4 range on which CPROP is determined.
DTMINI is double precision and STMINI is
single precision.
DTMAXI I REAL*8 The final temperature of the temperature range
STMAXI REAL*4 on which CPROP is determined. DTMAXI is
double precision and STMAXI is single
precision.
DYLOW I REAL*8 Lower bound value of the mapped property.
SYLOW REAL*4 DYLOW is double precision and SYLOW is
single precision.
DYHIGH I REAL*8 Upper bound value of the mapped property.
SYHIGH REAL*4 DYHIGH is double precision and SYHIGH is
single precision.
IFILL I INTEGER Mapping option for components with BP
outside the given[TMINI,TMAXI] range:
0 Assign the same property value as the nearest
neighboring component which is inside the
[TMINI,TMAXI] range (default)
1 Ignore; do not assign a new value
2 Linear extrapolation (see SSCALE also)
3 Assign a zero value
ITREND I INTEGER Trend of the CPROP data:
0 Monotonically increase or decrease (default)
1 Random or unknown.
IMETHD I INTEGER Interpolation option:
0 To be determined by program.
1 Linear (Use if CPROP=2)
2 Quadratic (Use if CPROP=3)
3 Cubic spline (Use if CPROP>3)
IUPDAT I INTEGER Option to update the XPROPY common block:
0 Do not update (default)
1 Update
DSCALE I REAL*8 Scaling factor for linear interpolation. DSCALE
SSCALE REAL*4 is double precision and SSCALE is single
precision.
IMAPED O INTEGER Array of component mapping flag:
(MAXCN) 0 Get zero flow rate from the mapping
1 Get positive flow rate from the mapping

PRO/II User-Added Subroutine User Guide 20-17

 Table 20-9: Arguments for Utility Subroutine UCURVE() (Continued)
Variable I/O Type Description
DSTGYV 0ut REAL*8 Result of mapped component property table.
(MAXCN) DSTGYV is double precision and SSTGYV is
SSTGYV REAL*4 single precision.
(MAXCN)
DSUMPRP 0ut REAL*8 Sum of FRATE(I)*STGYV(I), where I is a
SSUMPRP REAL*4 component in the [IBEGIN, IEND] range.
DSUMPRP is double precision and SSUMPRP
is single precision.
IERR Out INTEGER Returned error flag:
0 Successful
All other values indicate failure

Example:
INCLUDE 'PMXUSR.CMN'
INCLUDE 'XPROPY.CMN'
INTEGER(4), PARAMETER :: NCPSEU=7
CHARACTER(LEN=12) :: cProp
REAL(8) :: DTVEC(NCPSEU), DCPROP(NCPSEU)
REAL(8) :: DFRATE(MAXCN), DSTGYV(MAXCN)
REAL(8) :: IMAPED(MAXCN), DBP(MAXCN)
REAL(8) :: DTMINI, DTMAXI, DSCALE
…
! Variables DTVEC, DCPROP, NCPSEU are from
! reactor module
! BP is from XPROPY common block
! BEGIN and IEND are from UPSEUC()
! FRATE is from URATE()
…
cProp = 'MW'
ISPROP = 0
DTMINI = 350.0D0
DTMAXI = 575.0D0
DYLOW = 0.0D0
DYHIGH = 1000.0D0
IFILL = 0
ITREND = 0
IMETHD = 3
IUPDAT = 1
DSCALE = 1.0D0
DBP(1:MAXCN) = BP(1:MAXCN)
…
CALL DUCURVE( cProp, ISPROP, DTVEC, &
DCPROP, NCPSEU, BP, DFRATE, &
IBEGIN, IEND, DTMINI, DTMAXI, &
DYLOW, DYHIGH, IFILL, &
ITREND, IMETHD, IUPDAT, DSCALE, &
IMAPED, DSTGYV, DSUMPRP, IERR )

20-18 "UAS Refinery Reactor Simulation" February 2009

 DUBULK double precision
UBULK single precision
The purpose of this routine is similar to that of UCURVE, but it is
used when there is only a single property data point available from
the reactor simulation. For example, the research octane number is
usually of interest only for naphtha. Thus, the reactor module may
only predict a single RON for the entire naphtha boiling range
[TMINI,TMAXI]. The UBULK routine handles the component mapping
for this situation. If the thermodynamic METHOD of the product
stream already has some information about the component property,
the property profile will be adjusted proportionally to match the
given bulk property value. Otherwise, due to lack of information,
the same bulk property value will be assigned to all pseudo compo-
nents within the [TMINI,TMAXI] range.
Usage (double precision):
CALL DUBULK( cSID, cProp, iSProp, DBulkP, &
DBP, IBegin, IEnd, DTmin, &
DTmax, IFill, DScale, IMAPED, &
DTGYV, IERR )
Usage (single precision):
CALL UBULK( cSID, cProp, iSProp, SBulkP, &
SBP, IBegin, IEnd, STmin, &
STmax, IFill, SScale, IMAPED, &
STGYV, IERR )

Table 20-10: Arguments for Utility Subroutine UBULK()

Variable I/O Type Description
cSID In CHAR*12 Stream ID of the processed stream
cProp In CHAR*12 The property keyword
‘MW’ Molecular weight
‘SG60’ Specific gravity at 60F (15.5C)
‘OMEG’ Acentric factor
‘TC’ Critical temperate
‘PC’ Critical pressure
‘VC’ Critical volume
‘ZC’ Critical compressibility
‘RAKT’ Rackett parameter
‘CNUM’ Carbon number
‘ZNUM’ Hydrogen deficiency number
‘WATK’ Watson K value
For refinery special properties, see
cProp explained in USTRIP routine.

PRO/II User-Added Subroutine User Guide 20-19

 Table 20-10: Arguments for Utility Subroutine UBULK()
Variable I/O Type Description
iSProp In INTEGER See ISPROP explained in USTRIP
routine
SBulkP In REAL The bulk property value
SBP In REAL Array of component NBP.
See XPROPY common block for
(MAXCN) definition
IBegin In INTEGER The PRO/II internal order of the first
component in the blend
IEnd In INTEGER The PRO/II internal order of the last
component in the blend
STmin In REAL The initial temperature of the
temperature range based on which
SVALSP is determined.
STmax In REAL The end temperature of the temperature
range based on which SVALSP is
determined.
IFill In INTEGER Mapping option for components whose
BP values are outside the given
[TMINI,TMAXI] range.
0 Assign the same property value of
the nearest neighboring component
inside the [TMINI,TMAXI] range.
(default)
1 Ignore; do not assign a new value.
2 Assign SVALSP*SSCALE.
3 Assign a zero value
4 Assign SVALSP
SScale I REAL Scaling factor for IFILL = 2
IMAPED Out INTEGER Array of component mapping flag
0 Get zero flow rate from the mapping
(MAXCN) 1 Get positive flow rate from the
mapping
STGYV 0ut REAL Result of mapped component property
table
(MAXCN)
IERR Out INTEGER Returned integer error flag
0 Successful
≠0 Failed

INCLUDE '…\PMXUSR.CMN'
INCLUDE '…\XPROPY.CMN'

20-20 "UAS Refinery Reactor Simulation" February 2009

 CHARACTER*(*) ATEXT
REAL STGYV(MAXCN), IMAPED(MAXCN)
…
C CID is from the URXINF function call
C SVALSP is from the reactor module
C BP is from XPROPY common block
C IBEGIN and IEND are from UPSEUC()
…
ATEXT = 'RON'
ISPROP = 0
TMINI = 5.0
TMAXI = 220.0
IFILL = 0
SSCALE = 1.0
…
CALL UBULK(CID,ATEXT, ISPROP,SVALSP,BP,
IBEGIN, IEND,TMINI,TMAXI, IFILL,
SSCALE,IMAPED,STGYV, IERR)

PRO/II User-Added Subroutine User Guide 20-21

 UPETMD
This routine updates all component properties in the current ther-
modynamic METHOD set based on a subset of the component prop-
erties declared to be invariant (fixed).
The reactor module normally predicts only a few component or
stream properties. Many component properties, such as Tc, Pc, and
acentric factor, typically required by the thermodynamic calcula-
tions, usually are not computed by the reactor simulation. Fortu-
nately, these component properties can be estimated from three
primary component properties: NBP, specific gravity, and molecu-
lar weight. In this refinery reactor interface, the NBP is treated as a
fixed component property, since its value is usually near the middle
of the cut and won't be significantly changed by the refinery reac-
tions. The other two primary component properties, specific gravity
and molecular weight, are allowed to change. The UPETMD routine
should be called to update all the secondary thermodynamic proper-
ties after the specific gravity and molecular weight component
properties are updated with the reactor simulation results.
Calling sequence for UPETMD is:
CALL UPETMD( cProp, nProps, iErr )

Table 20-11: Arguments for Utility Subroutine UPETMD( )

Variable I/O Type Description
cProp In CHAR*12 Fixed component properties that are used as the
3 element basis to determine the other component properties.
array The component properties allowed to be fixed are:
‘MW’ Molecular weight
‘SPGR’ Specific gravity
‘NBP’ Normal boiling point
nProps In Integer Input integer number of component properties
specified in the cProp array.
iErr Out Integer Output variable; Integer scalar. It is the error flag.
0= Successful All other values indicate failure.

Example:
...
CHARACTER(LEN=12) :: cProp(3)
INTEGER(4) :: nProps, iErr
...
cProp(1) = ‘NBP’
cProp(2) = ‘MW’
cProp(3) = ‘SPGR’

20-22 "UAS Refinery Reactor Simulation" February 2009

 nProps = 3
CALL UPETMD( cProp, nProps, iErr )
...

Common Block /XPROPY/

This single-precision common block is very similar to the /XPROPX/
common block previously defined in Chapter 15 on page 15-56 of
this manual. The only difference is that the component property
variables in this common block can be dynamically updated with
the reactor simulation. Property data stored here are automatically
refreshed whenever the USTHER or UPETMD function is called. The
data can be refreshed again when UCURVE function is called.
This common block can be accessed by including XPROPY.CMN in
the program. Refer to “/DXPROPX/ double precision” in Chapter
15, page 15-56 for a description of the variables in this COMMON
block
COMMON/XPROPY/ XMW(MAXCN), BP(MAXCN),
& DENS(MAXCN), TC(MAXCN), PC(MAXCN),
& VC(MAXCN), ZC(MAXCN), OMEGA(MAXCN),
& HFORM(MAXCN, GFORM(MAXCN), LIBNO(MAXCN),
& KOCMOL, KOCTOT, KOCVL,
& KOCVLS, KOCLS, KOCV,
& KOCL, KOCS

PRO/II User-Added Subroutine User Guide 20-23

 Sample User-Added Reactor Module
In the example shown in Figure 20-1, the refinery reactor has two
feed streams. The first is a hydrocarbon stream represented by assay
pseudo components created from the assay data. Refinery inspec-
tion properties such as sulfur, nitrogen, bromine number, refractive
index, and CCR are defined in the stream so the reactor interface
can retrieve and send these data to the reactor module. The second
feed is a recycle stream containing only hydrogen and light compo-
nents C1 to C4. The recycle stream is handled and converged by
PRO/II.
Figure 20-1: Process Flow Diagram of User-added Reactor Module

Except for the fact that the input data are entered through the IPARM,
RPARM and SUPPLE vectors in accordance with the UAS structure,
the interfaced reactor unit in every sense behaves like a regular
PRO/II unit.
Note that the reactor feed stream need not be an external source
stream. It can be the product stream of a distillation column. Simi-
larly, the reactor product stream can be a final product or a feed to
other units in the flowsheet. Once the refinery inspection properties
are assigned to a stream at input time or generated by the reactor
simulation at the calculation time, they can be carried with the
stream to other units.

20-24 "UAS Refinery Reactor Simulation" February 2009

 Example Input File
TITLE
DESCRIPTION DEMO CASE - PRO/II WITH User’s REACTOR MODULE
DIMENSION ENGLISH, PRESS=PSIG, LIQVOL=BBL
OUTDIMENSION REPLACE, TIME=DAY, WT=LB, LIQVOL=BBL
CALC CDATA=VARY

COMPONENT DATA
LIBID 1,H2/2,H2S/3,NH3/4,H2O/5,C1/ *
6,C2/7,C3/8,IC4/9,NC4/10,IC5/ *
11,ETLN/12,PRLN/13,1BUTENE/14,1PENTENE/ *
15,BENZENE
CUTPOINT TBPCUTS=0,1600,80, BLEND=BLEND1

$ Paraffin
PARA(LV) DATA= *
1,0/2,0/3,0/4,0/5,100/ *
6,100/7,100/8,100/9,100/10,100/ *
11,0/12,0/13,0/14,0/15,0
$ Olefin
SPROP(50,LV) DATA= *
1,0/2,0/3,0/4,0/5,100/ *
6,0/7,0/8,0/9,0/10,0/ *
11,100/12,100/13,100/14,100/15,0
$ Naphthene
NAPH(LV) DATA= *
1,0/2,0/3,0/4,0/5,0/ *
6,0/7,0/8,0/9,0/10,0/ *
11,0/12,0/13,0/14,0/15,0
$ Aromatics
AROM(LV) DATA= *
1,0/2,0/3,0/4,0/5,0/ *
6,0/7,0/8,0/9,0/10,0/ *
11,0/12,0/13,0/14,0/15,100

THERMODYNAMIC DATA
METHODS SYSTEM= GS,COND=PETR, VISC(V)=PETR, VISC(L)=API,
SET=GS-1, DEFAULT, &
SULFUR(WT)= SUM, NITR(TOTA,WT)= SUM, &
BROM(WT)= SUM, REFR(WT)= SUM, &
CCR(WT)= SUM, NICK(WT)= SUM, &
VANA(WT)= SUM

METHODS SYSTEM= GS,COND=PETR, &

VISC(V)=PETR, VISC(L)=API, &
SET=GS-2, &
SULFUR(WT)= SUM, NITR(TOTA,WT)= SUM, &
BROM(WT) = SUM, REFR(WT)= SUM, &
CCR(WT) = SUM, SPROP(50,WT)= SUM, &
SPROP(51,WT)= SUM, SPROP(52,WT)= SUM, &
NICK(WT) = SUM, VANA(WT)= SUM, &
AROM(TOTAL,LV)= SUM, &
NAPH(LV) = SUM, PARA(LV)= SUM, &
H2(WT) = SUM, &
RON(LV) = SUM, MON(LV)= SUM, &
CETN(WT) = SUM, ANIL(LV)= SUM, &
FREZ(LV) = INDEX, POUR(LV)= INDEX, &
PRO/II User-Added Subroutine User Guide 20-25
 SMOK(LV) = SUM
POUR(LV) NCFILL=NOFILL
REFR(WT) NCFILL=NOFILL
H2(WT) NCFILL=NOFILL
SMOK(LV) NCFILL=NOFILL
FREZ(LV) GAMMA=1.0, REFINDEX=1.0, REFVALUE=1.0

STREAM DATA
$ Crude feed
PROP STREAM=1,TEMP=450,PRES=14,PHASE=L,RATE(V)=12075, &
ASSAY=LV, BLEND=BLEND1, SET=GS-1
TBP STREAM=1,PRES(MMHG)=760, &
DATA=3,97/5,149/10,208/20,330/30,459/40,590/ &
50,690/60,770/70,865/80,980/100,1600
API STREAM=1,AVG=29.2
LIGHT STREAM=1,PERCENT(V)=3, &
COMP(V)=6,0.1/7,0.2/8,0.3/9,0.7/10,1.7,NORMALIZE
SULF STREAM=1, DATA= 10,0.1/50,1.4/90,3.3
NITR STREAM=1, DATA= 10,0.005/50,0.03/90,0.09
BROM STREAM=1, DATA= 10,1.5/50,2.8/90,4.5
REFR STREAM=1, DATA= 10,1.41/50,1.47/90,1.58
CCR STREAM=1, DATA= 10,0.01/50,0.05/90,0.24
$
PROP STREAM=2,TEMP=600,PRES=60,PHASE=V,RATE(W)=24151, &
COMP=4,100
PROP STREAM=3,TEMP=600,PRES=60,PHASE=V,RATE(W)=3623, &
COMP=4,100
PROP STREAM=4,TEMP=600,PRES=60,PHASE=V,RATE(W)=10868, &
COMP=4,100
PROP STREAM=5,TEMP=600,PRES=60,PHASE=V,RATE(W)=9660, &
COMP=4,100
$ Vacuum tower
PROP STREAM=R1B,TEMP=330,PRES=8000,RATE(V)=138.4, &
COMP=6,75/7,25
PROP
STREAM=R1C,TEMP=330,PRES=8000,RATE(W)=5154,COMP=4,100
PROP
STREAM=W1,TEMP=355,PRES=8500,RATE(W)=14718,COMP=4,100
$ Recycle gas initial guess
PROP STRM=RECYCLE, TEMP=100.0000, PRES=244.6959, &
COMP= 1,25000/2,2000/3,2000/4,2000/5,500/ &
6, 500/7, 500/8, 500

UNIT OPERATIONS
$
$ Crude process
$
.....
$
$ Refinery Reactor
$
US10 UID=RX1, NAME=BLEND1
FEED F1,RECYCLE
PROD REACT
$ Description of input data is shown in the reactor program
IPARM 1, , , , , &
, , , , , &
51, 52, 50

20-26 "UAS Refinery Reactor Simulation" February 2009

 RPARM 940.0, 30.0, 12000.0, 0.952, , &
, , 85.5, 120.5, 210.8, &
1.4E-4, , , , , &
, , , , , &
1.452
DEFINE RPARM(2) AS COMPRESSOR=CMP1, PRES(PSIG)
METHOD SET= GS-2

FLASH UID=FLA1
FEED REACT
PROD V=VAPPRD, L=LIQPRD
ISOTHERMAL TEMP=100, PRES=244.696
METHOD SET= GS-2
SPLITTER UID=SPL1
FEED VAPPRD
PRODUCT V=V_SPL1, V=H2OUT
SPEC STREAM= V_SPL1, RATE(GV,FT3/D), RATIO, &
STREAM=F1, RATE(TS/D), VALUE=56294
METHOD SET= GS-2
COMPRESSOR UID=CMP1
FEED V_SPL1
PROD V=RECYCLE
OPER PRES=315, EFF=92
METHOD SET= GS-2
$
$ Purification
COLUMN UID=COL1
PARAM TRAY=21
FEED LIQPRD,17
PROD OVHD=OVERHEAD, BTMS= BOTTOM,80000
COND TYPE=PART, PRESS=65
HEAT 1,1/2,21
PRESS 1,65/2,70/21,75
ESTI MODEL=CONVENTION
SPEC STREAM= OVERHEAD,RATE,COMP=10, OVER, *
STREAM=LIQPRD, RATE,COMP=10, VALUE=0.1
SPEC STREAM= BOTTOM,RATE,COMP=6, OVER, *
STREAM=LIQPRD, RATE,COMP=6, VALUE=0.1
VARY HEAT=1,2
METHOD SET= GS-2
$
$ Print component properties in each thermo method
CREPORT UID=CREP1
$
$ Recycle algorithm
$
RECYCLE DATA
ACCELERATION TYPE=BROYDEN
END

PRO/II User-Added Subroutine User Guide 20-27

 Example of PRO/II User-Added Subroutine
C *** EXAMPLE OF REACTOR INTERFACE PROGRAM ***
C
SUBROUTINE USER50(IPARM, RPARM, SUPPLE, HEAT, IDATA,
1 ISOLVE, ISTOP)
C
C----------------------------------------------------------------
C-
C - INCLUDE and DIMENSION blocks
C-
INCLUDE '...\PMXUSR.CMN'
INCLUDE '...\XPROPY.CMN'
C Common block XPROPY has the following variables
C COMMON /XPROPY/XMW(MAXCN), BP(MAXCN), DENS(MAXCN),
C 1 TC(MAXCN), PC(MAXCN), VC(MAXCN),
C 2 ZC(MAXCN), OMEGA(MAXCN), HFORM(MAXCN),
C 3 GFORM(MAXCN), LIBNO(MAXCN), KOCMOL,
C 4 KOCTOT, KOCVL, KOCVLS,
C 5 KOCLS, KOCV, KOCL,
C 6 KOCS
C
C User's parameters
PARAMETER (LIXIN=100, LRXIN=100, LRXOUT=100,
1 LFDDAI=10, LFDDAJ=100, LPDDA=100,
2 ZERO=0.0, MAXPSU=100, MAXPRP=20,
3 IMISS=-2111111111,
4 RMISS=-1.5E35, RTEST=-1.0E35)
C
C PRO/II vectors
DIMENSION IPARM(*), RPARM(*), SUPPLE(*), HEAT(*)
1 IDATA(*)
DIMENSION STREAM(MAXCN+10), VAPOUT(MAXCN+10),
1 XL1OUT(MAXCN+10), XL2OUT(MAXCN+10),
2 XKVALU(MAXCN+10)
CHARACTER*12 CID
CHARACTER*40 CNAME
C
C User's reactor interface vectors
DIMENSION IXIN(LIXIN), RXIN(LRXIN), RXOUT(LRXOUT),
1 FDDATA(LFDDAI,LFDDAJ), PDDATA(LPDDA),
2 PDCURV(MAXPSU,MAXPRP),
3 BPTIP(MAXCN), BPTEP(MAXCN)
C
C Local vectors
DIMENSION IONUMB(10), CRC(10), REFRAC(10), IDCOMP(20),
1 IMAPED(MAXCN)
DIMENSION TDIST(21), FRATE(MAXCN), RXMW(MAXCN),
1 RXSPGR(MAXCN), RXSULF(MAXCN), RXNAPH(MAXCN),
2 RXRON(MAXCN)
DIMENSION CTMID(MXPSEU), CWTPCT(MXPSEU),
1 CMWT(MXPSEU), CSPGR(MXPSEU), CSULF(MXPSEU),
2 CNITR(MXPSEU), CNAPH(MXPSEU), CAROM(MXPSEU),

20-28 "UAS Refinery Reactor Simulation" February 2009

 3 CTMIN(MXPSEU), CTMAX(MXPSEU)
DIMENSION TVEC(MXPSEU), YVEC(MXPSEU)
CHARACTER*12 ATEXT
CHARACTER*12 PPTEXT(10)
CHARACTER*16 CPNAME
C-
C - Initialization of variables
C-
DO 40 I= 1, LIXIN
IXIN(I) = IMISS
40 CONTINUE
DO 42 I= 1, LRXIN
RXIN(I) = RMISS
42 CONTINUE
.....
DO 50 I= 1, MXPSEU
CTMID(I) = ZERO
CTMWT(I) = ZERO
.....
50 CONTINUE
.....
C
NFEDIN = IDATA(1)
NUMCOP = IDATA(4)
.....
C-
C - Assign IPARM, RPARM, SUPPLE to local variables
C-
C The data can be:
C 1. User's reactor configuration data
C 2. User's reactor operating condition data such as reactor
C temperature and pressure
C 3. User's reaction data such as kinetic parameters, update
C factors and catalyst data
C 4. If the refinery inspection property data, such as sulfur,
C nitrogen, refractive index, were not defined in the
C stream, they can be input here locally.
C
C Hydrogen recycle position flag
IH2IN = IPARM(1)
C Position of SPROP() for naphthene carbon fraction
NSNAPH = IPARM(11)
C Position of SPROP() for aromatics carbon fraction
NSAROM = IPARM(12)
C Position of SPROP() for olefin wt%
NSOLEF = IPARM(13)
.....
C Reactor inlet temperature
TIN = RPARM(1)
C Reactor inlet pressure
PIN = RPARM(2)
C Reactor catalyst amount
CATWT = RPARM(3)
PRO/II User-Added Subroutine User Guide 20-29
 C Catalyst activity
CATACT = RPARM(4)
C Product cut points
TCUT1 = RPARM(8)
TCUT2 = RPARM(9)
TCUT3 = RPARM(10)
C Conradson carbon data
CRC(1) = RPARM(11)
.....
C Refractive index data
REFRAC(1) = RPARM(21)
.....
C
C----------------------------------------------------------------
C Note that many of the following data can be saved at unused
C IPARM, RPARM or SUPPLE after the processing and retrieved for
C use during the recycle iterations to avoid repeated calculation the
C first time.
C
C-
C - Get component position orders for all defined components
C - involved in the reactor simulation
C-
ITYPE = 1
C Find 'H2'
LIBH2 = 16020090
CALL UDEFNC(CPNAME, LIBH2, ITYPE, JPLACE)
IF (JPLACE .GT. 0) THEN
IDCOMP(1) = JPLACE
ELSE
C (error message)
ENDIF
C Find 'C1'
LIBC1 = 9010090
CALL UDEFNC(CPNAME, LIBC1, ITYPE, JPLACE)
IF (JPLACE .GT. 0) THEN
IDCOMP(2) = JPLACE
ELSE
C (error message)
ENDIF
.....
C----------------------------------------------------------------
C-
C - Determine the index range and initial and end boiling points
C - of PRO/II's assay pseudocomponents. These data will be used
C - when saving the reactor product result to PRO/II's product
C - stream. The range is determined by the "BLEND" specified by
C - the user under the "NAME" of the reactor unit. The blend has
C - to be declared in the "COMPONENT" section
C-
CALL UPSEUC(IDATA, BP, IBEGIN, IEND, BPTIP,
1 BPTEP, IERR)
C Check error flag IERR

20-30 "UAS Refinery Reactor Simulation" February 2009

 .....
C
C----------------------------------------------------------------
C-
C - Get file open numbers for user's own file I/O purpose
C-
DO 100 I= 1, 5
CALL FIGETU(1,LUN)
IONUMB(I) = LUN
100 CONTINUE
.....
C
C Open user's own data file
OPEN(UNIT=IONUMB(1), FILE='C:\REACTOR\FCC\INPUT.DAT',
1 STATUS='OLD', ERR=5000)
C
C Read data from user's own data file
.....
C
C
C----------------------------------------------------------------
C-
C - Get feed stream data from PRO/II
C-
DO 300 I= 1, NFEDIN
CALL URXINF('FEED', I, CID, CNAME, IERR)
C Check error flag IERR
CALL URXSTR(CID, STREAM, 1, IERR)
C Check error flag IERR
C
C Set up the component properties XPROPY for this feed stream
C This is required only if CDATA=VARY is applied
ISETUP = 1
CALL USTHER(CID, ISETUP, JMETHD, IERR)
C
C Get molecular wt
CALL USTPRP(CID, 'TOTAL', 'MW', STMW, IERR)
C Check error flag IERR
C Get spgr
CALL USTPRP(CID, 'TOTAL', 'SDEN', STDENS, IERR)
C Check error flag IERR
C Get sulfur wt%
CALL USTRIP(CID, 'SULF', 0, STSULF, IERR)
C Check error flag IERR
C Get nitrogen wt%
CALL USTRIP(CID, 'NITR', 0, STNITR, IERR)
C Check error flag IERR
C Get naphthene carbon fraction from SPROP(NSNAPH)
CALL USTRIP(CID, '', NSNAPH, STNAPH, IERR)
C Check error flag IERR
C Get aromatics carbon fraction from SPROP(NSAROM)
CALL USTRIP(CID, '', NSAROM, STAROM, IERR)
C Check error flag IERR
PRO/II User-Added Subroutine User Guide 20-31
 .....
C
C Get distillation curve data
C TBP curve from 0.1% to 99.9%
ITYPE = 2
ICONV = 2
IBASIS = 0
WVIP = 0.1
WVEP = 99.9
CALL UDIST(STREAM, XMW, BP, DENS, ITYPE,
1 ICONV, IBASIS, WVIP, WVEP, NUMCOP,
2 TDIST, IERR)
C Check error flag IERR
C
C Assign feed data to interface variables which can be accessed
C by the reactor simulation program
C Assume:
C FDDATA(*,1)= total flowrate
C FDDATA(*,2)= stream density
C FDDATA(*,3)= stream sulfur content
C FDDATA(*,4)= stream nitrogen content
C FDDATA(*,5)= stream naphthene carbon content
C FDDATA(*,6)= stream aromatics carbon content
C FDDATA(*,7)= stream CRC content
C FDDATA(*,8)= stream refractive index
C .....
C FDDATA(*,11-17)= distillation data at IP,10%,30%,50%,70%,
C 90%,EP (7 points)
C FDDATA(*,21)= H2 flowrate
C FDDATA(*,22)= C1 flowrate
C
FDDATA(I,1) = STREAM(1) * STMW
FDDATA(I,2) = STDENS
FDDATA(I,3) = STSULF
FDDATA(I,4) = STNITR
FDDATA(I,5) = STNAPH
FDDATA(I,6) = STAROM
FDDATA(I,7) = CRC(I)
FDDATA(I,8) = REFRAC(I)
.....
C Distillation curve data at IP,10%,30%,50%,70%,90%,EP points
FDDATA(I,11) = TDIST(1)
FDDATA(I,12) = TDIST(3)
FDDATA(I,13) = TDIST(7)
FDDATA(I,14) = TDIST(11)
FDDATA(I,15) = TDIST(15)
FDDATA(I,16) = TDIST(19)
FDDATA(I,17) = TDIST(21)
.....
C H2, C1 and other light component flowrates
FDDATA(I,21) = STREAM(10+IDCOMP(1))
FDDATA(I,22) = STREAM(10+IDCOMP(2))
.....

20-32 "UAS Refinery Reactor Simulation" February 2009

 C Any required error checks for feed stream properties
.....
300 CONTINUE
.....
C
C
C----------------------------------------------------------------
C-
C - Assign all other desired data to the interface variables
C - The data can be reactor operating condition, catalyst
C - activity, etc.
C-
IXIN(1) = IH2IN
.....
C
RXIN(1) = TIN
RXIN(2) = PIN
RXIN(3) = CATWT
RXIN(4) = CATACT
RXIN(5) = TCUT1
RXIN(6) = TCUT2
RXIN(7) = TCUT3
.....
C
C----------------------------------------------------------------
C-
C - Execute user's reactor simulation
C-
C =====================================================
CALL USER_REACTOR(IXIN, RXIN, RXOUT, FDDATA, PDDATA,
1 PDCURV, IERR)
C =====================================================
C Check error flag IERR
C
C----------------------------------------------------------------
C-
C - Store reactor effluent data to PRO/II product stream
C-
CALL URXINF('PROD', 1, CID, CNAME, IERR)
C Check error flag IERR
CALL URXSTR(CID, STREAM, 1, IERR)
C Check error flag IERR
C
C Set up the component properties XPROPY for the product stream
C This is required only if CDATA=VARY is applied in the .inp file
ISETUP = 1
CALL USTHER(CID, ISETUP, JMETHD, IERR)
C Check error flag IERR
C
C Get reactor pseudocomponent data
C Assume:
C PDCURV(*,1)= (reserved)
C PDCURV(*,2)= mid boiling point of the pseudocomponent
PRO/II User-Added Subroutine User Guide 20-33
 C PDCURV(*,3)= wt% of the pseudocomponent
C PDCURV(*,4)= MW of the pseudocomponent
C PDCURV(*,5)= SPGR of the pseudocomponent
C PDCURV(*,6)= sulfur wt% of the pseudocomponent
C PDCURV(*,7)= nitrogen wt% of the pseudocomponent
C PDCURV(*,8)= naphthene carbon fraction of the pseudo
C component
C PDCURV(*,9)= aromatics carbon fraction of the pseudo
C component
C PDCURV(*,10) = initial boiling point of the data point
C PDCURV(*,11) = end boiling point of the data point
C .....
C
C Get number of reactor pseudocomponents
NCPSEU = INT(RXOUT(1))
C
DO 320 J= 1, NCPSEU
CTMID(J) = PDCURV(J,2)
CWTPCT(J) = PDCURV(J,3)
CMWT(J) = PDCURV(J,4)
CSPGR(J) = PDCURV(J,5)
CSULF(J) = PDCURV(J,6)
CNITR(J) = PDCURV(J,7)
CNAPH(J) = PDCURV(J,8)
CAROM(J) = PDCURV(J,9)
CTMIN(J) = PDCURV(J,10)
CTMAX(J) = PDCURV(J,11)
.....
320 CONTINUE
C
C Get reactor data such as reactor temperature, pressure, ...
TOUT = RXOUT(2)
POUT = RXOUT(3)
FWOUT = RXOUT(4)
.....
ICUMUL = 1
IMETHD = 4
C
C Match the weight flowrate of pseudocomponent
CALL URATE(TMAX, CWTPCT, NCPSEU, ICUMUL,
1 FWOUT, IBEGIN, IEND, BPTIP,
2 BPTEP, IMETHD, IMAPED, FRATE,
3 IERR)
C Check error flag IERR
C
C Match the component properties based on curve data
C
C Use the molecular weight curve determined by the reactor
C simulation to determine the molecular weight of all assay
C pseudocomponents that were selected to store the reactor
C product data.
ATEXT = 'MW'
ISPROP = 0

20-34 "UAS Refinery Reactor Simulation" February 2009

 TMINI = CTMIN(1)
TMAXI = CTMAX(NCPSEU)
YLOW = 2.0
YHIGH = 1000.0
IFILL = 2
ITREND = 0
IMETHD = 3
IUPDAT = 0
SSCALE = 1.0
CALL UCURVE(ATEXT, ISPROP, CTMID, CMW, NCPSEU,
1 BP, FRATE, IBEGIN, IEND, TMINI,
2 TMAXI, YLOW, YHIGH, IFILL, ITREND,
3 IMETHD, IUPDAT, SSCALE, IMAPED, RXMW,
4 SUMMW, IERR)
C Check error flag IERR
C
C Use the specific gravity curve determined from the reactor
C simulation to determine the specific gravity of all assay
C pseudocomponents that were selected to store the reactor
C product data.
ATEXT = 'SPGR'
ISPROP = 0
TMINI = CTMIN(1)
TMAXI = CTMAX(NCPSEU)
YLOW = 0.5
YHIGH = 1.5
IFILL = 2
ITREND = 0
IMETHD = 3
IUPDAT = 0
SSCALE = 1.0
CALL UCURVE(ATEXT, ISPROP, CTMID, CSPGR, NCPSEU,
1 BP, FRATE, IBEGIN, IEND, TMINI,
2 TMAXI, YLOW, YHIGH, IFILL, ITREND,
3 IMETHD, IUPDAT, SSCALE, IMAPED, RXSPGR,
4 SUMSPG, IERR)
C
C Update all required secondary component properties, such as Tc,
C Pc, and Zc, based on the NBP, MW, and SPGR
PPTEXT(1) = 'NBP'
PPTEXT(2) = 'MW'
PPTEXT(3) = 'SPGR'
NPTEXT = 3
CALL UPETMD(PPTEXT, NPTEXT, IERR)
C
C Use the sulfur wt% curve determined from the reactor
C simulation to determine the sulfur wt% of all assay
C pseudocomponents that were selected to store the reactor
C product data.
ATEXT = 'SULF'
ISPROP = 0
TMINI = CTMIN(1)
TMAXI = CTMAX(NCPSEU)
PRO/II User-Added Subroutine User Guide 20-35
 YLOW = 0.0
YHIGH = 100.0
IFILL = 2
ITREND = 0
IMETHD = 3
IUPDAT = 0
SSCALE = 1.0
CALL UCURVE(ATEXT, ISPROP, CTMID, CSULF, NCPSEU,
1 BP, FRATE, IBEGIN, IEND, TMINI,
2 TMAXI, YLOW, YHIGH, IFILL, ITREND,
3 IMETHD, IUPDAT, SSCALE, IMAPED, RXSULF,
4 SUMSUL, IERR)
C
C Similarly for NITROGEN mapping here
...

C Use the naphthene fraction curve determined from the reactor

C simulation to determine the naphthene fraction of all assay
C pseudocomponents that were selected to store the reactor
C product data.
C Assuming that the reactor predicts this property for only
C four points and they are located at index 2 to 5 of NCPSEU:

ATEXT = ''
ISPROP = NSNAPH
TMINI = CTMIN(2)
TMAXI = CTMAX(5)
YLOW = 0.0
YHIGH = 100.0
IFILL = 2
ITREND = 0
IMETHD = 0
IUPDAT = 0
SSCALE = 1.0
CALL UCURVE(ATEXT, ISPROP, CTMID, CNAPH, NCPSEU,
1 BP, FRATE, IBEGIN, IEND, TMINI,
2 TMAXI, YLOW, YHIGH, IFILL, ITREND,
3 IMETHD, IUPDAT, SSCALE, IMAPED, RXNAPH,
4 SUMNAP, IERR)
C
C Similarly for AROMATICS mapping here
C
C Map the component product rate
C
DO 330 J= 1, MAXCN
STREAM(10+J) = ZERO
330 CONTINUE
C
C Match flowrate of defined component
C Assume PDDATA(30-31) store the weight flowrates of H2 and C1
STREAM(10+IDCOMP(1)) = PDDATA(30)
STREAM(10+IDCOMP(2)) = PDDATA(31)
.....

20-36 "UAS Refinery Reactor Simulation" February 2009

 C
C Match the weight flowrate of pseudocomponent
DO 340 J= IBEGIN, IEND
STREAM(10+J) = FRATE(J)
340 CONTINUE
C
C CONVERT WT TO MOLAR FLOWRATE
DO 340 J= IBEGIN, IEND
STREAM(10+J) = STREAM(10+J) / XMW(J)
340 CONTINUE
C
C SUM up stream molar rate
FTOTAL = ZERO
DO 380 J= 1, MAXCN
FTOTAL = FTOTAL + STREAM(10+J)
380 CONTINUE
C
C Assign product stream rate, temperature and pressure
STREAM(1) = FTOTAL
STREAM(2) = TOUT
STREAM(3) = POUT
C
CALL UFLSH(STREAM, VAPOUT, XL1OUT, XL2OUT, XKVALU, 1, IERR)
C ERROR CHECK:
C
STTH = VAPOUT(4) + XL1OUT(4) + XL2OUT(4)
STREAM(4) = STTH
C
C Save the product stream data
CALL URXSTR(CID, STREAM, 2, IERR)
C
C Match the bulk stream property for a defined boiling range of
C the reactor effluent stream.
C
C RON NUMBER
C
ATEXT = 'RON'
ISPROP = 0
BRON = RXOUT(11)
TMINI = RXOUT(12)
TMAXI = RXOUT(13)
IFILL = 4
SSCALE = 1.0
CALL UBULK(CID, ATEXT, ISPROP, BRON,
1 BP, IBEGIN, IEND, TMINI,
2 TMAXI, IFILL, SSCALE, IMAPED,
3 RXRON, IERR)
C
C Similarly for other bulk properties
.....
C----------------------------------------------------------------
C-
C - Determine the solution flag value
PRO/II User-Added Subroutine User Guide 20-37
 C-
9000 CONTINUE
C CLOSE USER'S I/O FILES
CLOSE(IONUMB(1))
CLOSE(IONUMB(2))
.....
C
IF (IERR .EQ. 0) THEN
ISOLV = 10
ISTOP = 0
GO TO 9999
ELSEIF .....
.....
ISTOP = 1
ENDIF
C
9999 RETURN
END

20-38 "UAS Refinery Reactor Simulation" February 2009

 C *** Example of User’s Reactor Main Subroutine ***
C
C The main interface routine on the user's side for the reactor
C interface with PRO/II
C
SUBROUTINE USER_REACTOR(IXIN, RXIN, RXOUT, FDDATA, PDDATA,
1 PDCURV, IERR)
C-
C - Block of INCLUDE and DIMENSION
C-
PARAMETER (LIXIN=100, LRXIN=100, LRXOUT=100,
1 LFDDAI=10, LFDDAJ=100, LPDDA=100,
2 ZERO=0.0, TCUT0=32.0, MAXPSU=100, MAXPRP=20)
C
C Interface variables
DIMENSION IXIN(LIXIN), RXIN(LRXIN), RXOUT(LRXOUT),
1 FDDATA(LFDDAI,LFDDAJ), PDDATA(LPDDA),
2 PDCURV(MAXPSU,MAXPRP)
C
C Reactor module variables
DIMENSION COPRXN(100,20)
C-
C - Create reaction pseudocomponents
C-
C The reaction pseudocomponents are created based on TBP
C data, and bulk properties such as gravity, molecular wt,
C sulfur content, nitrogen content, and refractive index.
C These data are available in the FDDATA().
C COPRXN(I,J) stores the pseudocomponent data created from these data,
C where I= pseudocomponent index;
C J=1 for molar flowrate;
C J=2 for initial boiling point;
C J=3 for end boiling point;
C J=4 for molecular wt;
C J=5 for SPGR;
C J=6 for paraffin carbon fraction;
C J=7 for naphthene carbon fraction;
C J=8 for aromatics carbon fraction;
C J=9 for sulfur wt%;
C J=10 for nitrogen wt%
C
CALL USER_PSEUDOCOMPONENT( FDDATA, NCPSEU, COPRXN)
C
C NCPSEU IS DECIDED BY THE REACTION MECHANISM
RXOUT(1) = NCPSEU
C-
C - Calculate the reaction result
C-
C Calculate the reaction result based on the given reactor inlet
C temperature and pressure, catalyst amount and activity, and the
C pseudocomponent data. In this example the reaction mechanism
C and kinetic data are all defined in the USER_RXN subroutine.
PRO/II User-Added Subroutine User Guide 20-39
 C The result of reactor effluent is also stored at COPRXN().
C
TIN = RXIN(1)
PIN = RXIN(2)
CATWT = RXIN(3)
CATACT = RXIN(4)
.....
CALL USER_RXNCALCULATION(NCPSEU, COPRXN, TIN, PIN, CATWT,
1 CATACT, TOUT, POUT, RATE ...)
C-
C - Write reaction results to the interface variables RXOUT,
C - PDDATA, and PDCURV
C-
RXOUT(2) = TOUT
RXOUT(3) = POUT
RXOUT(4) = RATE
.....
C
DO 100 J= 1, NUMCOP
PDCURV(J,1) = COPRXN(J,1)
PDCURV(J,2) = (COPRXN(J,2)+COPRXN(J,3))/2
PDCURV(J,3) = COPRXN(J,1) * COPRXN(J,4)
PDCURV(J,4) = COPRXN(J,4)
PDCURV(J,5) = COPRXN(J,5)
PDCURV(J,6) = COPRXN(J,9)
PDCURV(J,7) = COPRXN(J,10)
PDCURV(J,8) = COPRXN(J,7)
PDCURV(J,9) = COPRXN(J,8)
PDCURV(J,10) = COPRXN(J,2)
PDCURV(J,11) = COPRXN(J,3)
.....
100 CONTINUE
C-
C - Determine the bulk refinery inspection properties
C-
C Generate bulk properties
C
TCUT1 = RXIN(5)
TCUT2 = RXIN(6)
TCUT3 = RXIN(7)
C
CALL USER_BULKPROPERTY(NUMCOP, COPRXN, TOUT, POUT, TCUT1,
1 TCUT2, TCUT3, STBRON, ...)
C
RXOUT(11) = STBRON
RXOUT(12) = TCUT0
RXOUT(13) = TCUT1
C
C Write similar code for other bulk properties
.....
RETURN
END

20-40 "UAS Refinery Reactor Simulation" February 2009

 Chapter 21
UAS Solid Components
Overview
The subroutines and other interfaces described in this chapter are
designed explicitly to handle components and streams that form
solid phases in PRO/II simulations. Table 21-1 summarizes the
interfaces discussed in this chapter. Most of them were not available
prior to PRO/II version 8.3
Table 21-1: Solids Handling Interfaces in PRO/II Version 8.3
Solids Handling See ...
GETNCOMP Retrieves various component counts (for 21-2
solids problems).
USOLSTR Retrieves and stores streams containing 21-3
solids.
UFLSHSOL Performs vapor/liquid flash for streams 21-5
with solids. May be used in place of
UFLSH and U3FLSH.
USOLDENS Calculates the solid stream density 21-8
UHSSOLID Calculates solid molar heat capacity, molar 21-9
enthalpy, and molar entropy
USOLCDAT Retrieves pure solid component heat of 21-10
fusion, normal melting point temperature,
triple point temperature, or triple point
pressure.
GETPSDC Retrieves the number of Particle Size 21-11
Distribution (PSD) cuts for any single
component.
USOLPSD Retrieves or stores the Particle Size 21-11
Distribution data
UPDSCPY Copies all Particle Size Distribution data 21-12

PRO/II User-Added Subroutine User Guide 21-1

User Information
In the past, most user-added interfaces in PRO/II supported only
vapor and liquid phases in streams. This section describes the cur-
rent user-added interfaces that support solids phases. They are
intended for use inside user-written subroutines, such as unit opera-
tions. Refer to the example routine USER57.FOR for some code
demonstrations that use these solids-handling routines. This typi-
cally is installed in \SIMSCI\PROII82\USER\UAS\EXAMPLES\EXAM7.
Most of the material in this chapter is of interest to developers of
user-added subroutines. Users running a simulation in PRO/II have
no direct access to these interfaces through keywords or ProVision.

Developer Information
GETNCOMP
Subroutine GETNCOMP retrieves component counts in simulations
that include solid-phase components. Often the first interface used
when dealing with solids components, it allows developers to iden-
tify solids components in the PRO/II component lists.
Calling sequence:
CALL GETNCOMP( NOCR, NOCMOLR, NOCTOTR,
& NOCSR, NOCIR, MICSR,
& MACSR, MICIR, MACIR )
Where the following scalar integers are returned:
NOCR The number of Vapor-Liquid (VL) components
NOCMOLR The number of molecular weight-based components
NOCTOTR The total number of components, including non-
molecular weight solids
NOCSR The number of molecular weight solids components
NOCIR The number of non-molecular weight solids components
MICSR The index to the first molecular weight solid
MACSR The index to the last molecular weight solid
MICIR The index to the first non-molecular weight solid
MACIR The index to the last non-molecular weight solid

21-2 UAS Solid Components February 2009

 USOLSTR
This routine is an extension of URXSTR. Use it to store or retrieve
data for streams that contain solids. All floating-point arguments are
double precision, and data transfer uses the dimensional units of
measure used for problem input data. Set argument IOTYPE = 1 to
retrieve data from a PRO/II stream and set IOTYPE = 2 to store data
from a PRO/II stream.
Calling sequence:
CALL USOLSTR( CSID, DStVec,
& DMRate, DCoMRate, SMWENTH,
& SNMWRATE, SNMWCRATE, SNMWENTH,
& IOTYPE, IERR )
Where:

CSID Input character string that identifies a PRO/II stream

to which data is stored or from which data is retrieved.
It may be a quoted literal string or a character variable
containing a maximum of 12 characters.
DStVec A standard (user) stream array1 that transfers data
between the user subroutine and PRO/II. When
IOTYPE = 1, it retrieves values in elements
STREAM(1) through (7), as well as the component
mole rates beginning in DStVec(11). When IOTYPE =
2, data in the same elements are stored in the PRO/II
stream identified by CSID. Dimension DStVec as
follows:
REAL(8) :: DStVec( NOCTOTR2 + 10 )
DMRate Output double precision scalar that returns the total
mole rate of the molecular weight solids in stream
CSID. This value is not used when storing data (i.e.,
when IOTYPE = 2).
DCoMRate Double precision array of mole rates for molecular
weight solids components. Units are mole rate, for
example, kg-mole / hr. Used to store and retrieve data.
Dimension this array as:
REAL(8) :: SMWRATE( NOCTOTR2 )
SMWENTH Double precision scalar value for total enthalpy rate of
molecular weight solids in the stream. Uses the same
units of measure as STREAM(4). Used for both storage
and retrieval.
Notes:
1 See routine URXSTR for a description of a standard stream array.
2 Retrieve NOCTOTR by using routine GETNCOMP.

PRO/II User-Added Subroutine User Guide 21-3

 SNMWRATE Output double precision scalar that returns the total
weight rate of the non-molecular weight solids in
stream CSID (for example, lb / hr). This value is not
used when storing data (i.e., when IOTYPE = 2).
SNMWCRATE Double precision array of weight rates for non-
molecular weight solids components. Units are weight
rate, for example, lb / hr. Used to store and retrieve
data. Dimension this array as:
REAL(8) :: SMWCRATE( NOCTOTR2 )
SNMWENTH Double precision scalar value for total enthalpy rate of
non-molecular weight solids in the stream. Uses the
same units of measure as STREAM(4). Used for both
storage and retrieval.
IOTYPE Integer input option flag that controls data transfer
1 = Retrieve data
2 = Store data
IERR Integer output status flag
0 = Success, no errors
1 = Failure, IOTYPE is invalid (not 1 or 2)
2 = Failure, stream not found (CSID is invalid).
3 = Failure, CSID is not a product of this user unit
when storing data (IOTYPE=2).
4 = Failure storing data (IOTYPE = 2) due to one of:
(A) Stream rate (STREAM(1)) less than zero.
(B) Stream temperature invalid (STREAM(2))
(C) Stream pressure invalid (STREAM(3))
(D) At least one negative stream component
mole rate encountered (in STREAM).
5 = Failure retrieving data (IOTYPE = 1). Stream
CSID may not yet be properly set or saved.
Notes:
1 See routine URXSTR for a description of a standard stream array.
2 Retrieve NOCTOTR by using routine GETNCOMP.

Total stream mole rate must be supplied in STREAM(1). This rate

includes all molecular weight solids that are included in SMWRATE.
STREAM(1) does not include any non-molecular weight solids.

For any molecular weight component i, the mole rate in STREAM

(10+i) includes solid and non-solid rates. The non-solid rate of com-
ponent i is found by STREAM (10+i) - SMWCRATE(i).
Total stream enthalpy in STREAM(4) includes enthalpy for both molec-
ular weight solids (SMWENTH) and non-molecular weight solids
(SNMWENTH).

21-4 UAS Solid Components February 2009

 UFLSHSOL
Subroutine UFLSHSOL is an extension of DU2FLSH and DU3FLSH.
As with DU2FLSH, it performs a vapor/liquid flash. It then keeps
track of solid component rates and enthalpy. It supports the same
flash types as DU2FLSH.
All floating point variables and arrays in the argument list are dou-
ble precision. The dimensional units used to transfer all data are the
units declared and used for input data in the simulation. For isen-
tropic flashes only, this routine requires passing in total stream
entropy through variable SISENV that is explicitly declared single
precision in common CSPEC.CMN.
When using this routine, the total stream to flash is loaded into
STREAMIN, a standard double precision stream vector (See “User
Stream Vector” on page 15-10 in chapter 15). Before calling UFLSH-
SOL, load the molar solids rates into the SMWCRATE vector and the
non-molar solids rates into the SNMWCRATE vector. Components
are ordered in PRO/II internal order (See “Internal Component
Order vs. Print Order” on page 15-40 in chapter 15). Load the
enthalpy rate of the non-molar solids into argument variable SNM-
WENTH. Refer to the documentation of routines URXSTR and USOL-
STR for further discussion.

The vapor and liquid return in standard double precision stream

vectors VAPOUT, XL1OUT, and XL2OUT, the same as from
DU2FLSH. Molar solids return in SOLIDOUT, and the non-molar
solids enthalpy rate returns in OUTNMWENTH. All arguments
use input dimensional units of measure.
Calling sequence:
CALL UFLSHSOL( STREAMIN, SMWCRATE, SNMWCRATE,
& SNMWENTH,
& VAPOUT, XL1OUT, XL2OUT,
& SOLIDOUT, OUTNMWENTH,
& XK1VAL, XK2VAL,
& ITYPE, IFVLLE, IERR )

PRO/II User-Added Subroutine User Guide 21-5

 Where:
STREAMIN Input double precision standard stream array2
dimensioned:
REAL(8) :: STREAM( NOCTOTR1 + 10 )
SMWCRATE Input double precision array of molecular weight
solids component mole rates in input units of measure
for mole rates (e.g., kg-mol/hr). dimension: REAL(8) ::
SMWCRATE( NOCTOTR1 ).
SNMWCRATE Input double precision array of NON-MW solids
component weight rates in input units of measure for
weight rates (e.g., kg/hr). dimension:
REAL(8) :: SMWCRATE( NOCTOTR1 ).
SNMWENTH Input double precision scalar enthalpy rate of the
NON-MW solids at the inlet of the flash. Uses the
same dimensional units as STREAM(4).
VAPOUT Output double precision standard stream array2 that
returns the vapor product. Dimensioned:
REAL(8) :: VAPOUT( NOCTOTR1 + 10 ).
XL1OUT Output double precision standard stream array2 that
returns the primary (light, L1 sub-phase) liquid
product. Dimensioned:
REAL(8) :: XL1OUT( NOCTOTR1 + 10 )
XL2OUT Output double precision standard stream array2 that
returns the second liquid product. When water is a
separate system, this array contains the decanted water.
Dimensioned:
REAL(8) :: XL2OUT( NOCTOTR1 + 10 )
SOLIDOUT Output double precision standard stream array2 that
returns the molar solids. SOLIDOUT(4) is the total
enthalpy rate of all the solids, including that of both
MW and NON-MW solids. Dimensioned:
REAL(8) :: SOLIDOUT( NOCTOTR1 + 10 )
OUTNMWENTH Output double precision scalar that returns the
Enthalpy rate of the NON-MW solids at the outlet of
the flash. It has the same units of measure as
STREAMIN(4).

Notes:
1 Retrieve NOCTOTR by using routine GETNCOMP.
2 See routine URXSTR for a description of a standard stream array.

21-6 UAS Solid Components February 2009

 XK1VAL Output double precision array that returns the
component equilibrium K-values for the L1 (first)
liquid phase. Dimensioned:
REAL(8) :: XK1VAL( NOCTOTR1 )
XK2VAL Output double precision array that returns the
component equilibrium K-values for the L2 (second)
liquid phase. Dimensioned:
REAL(8) :: XK2VAL( NOCTOTR1 )
ITYPE Input integer flag for the type of flash requested:
1 or 101 Isothermal flash (temp and press
specified)
2 or 102 Adiabatic flash (temperature specified)
3 or 103 Adiabatic flash (pressure specified)
4 or 104 Dew point (temperature specified)
5 or 105 Dew point (pressure specified)
6 or 106 Bubble point (temperature specified)
7 or 107 Bubble point (pressure specified)
8 or 108 Isentropic (temperature specified)
9 or 109 Isentropic (pressure specified)
10 or 110 Aqueous dew point (temp. specified)
11 or 111 Aqueous dew point (pressure specified)
IFVLLE Returned Integer. This returns a value of 1 if the
thermodynamics method is a VLLE method and the
flash predicted two liquid phases. XK2VAL is
meaningful only when IFVLLE = 1.
IERR Returned Integer flash calculations status flag
0 = Success, no errors
1 = Failure, flash did not converge
2 = Failure, ITYPE requested an invalid flash
3 = Failure, Flow rates of STREAMIN,
SMWCRATE, and SNMWCRATE are all zero.
4 = Failure, the flow rate of MW solids exceeds
total stream rate declared in STREAMIN(1).

Notes:
1 Retrieve NOCTOTR by using routine GETNCOMP.
2 See routine URXSTR for a description of a standard stream array.

PRO/II User-Added Subroutine User Guide 21-7

 USOLDENS
Subroutine USOLDENS calculates the solid stream density at a spec-
ified temperature. It returns the Molecular Weight Solids mole and
weight densities, the NON-MW solids weight density, and the
weight density of the total solids. All arguments use input dimen-
sional units of measure.
Calling sequence:
CALL USOLDENS( TEMPIN, SMWCRATE, SNMWCRATE, &
DENSMOLE, DENSWT, DENSNMW, &
DENSTOT, IERR )
Where:

TEMPIN Input temperature in input units of measure. This is a

double precision scalar value.
SMWCRATE Input double precision array of molecular weight solids
component mole rates ( e.g., kg-mol/hr ). Dimension:
REAL(8) :: SMWCRATE(NOCTOTR1)
SNMWCRATE Input double precision vector of NON-MW solids
component weight rates (e.g., kg-mol/hr).
Dimension: REAL(8) :: SNMWCRATE(NOCTOTR1)
DENSMOLE Output double precision scalar returns molar density of
the molecular weight solids in moles / volume units
(e.g., kg-mol/m3).
DENSWT Output double precision scalar returns weight density
of the molecular weight solids in weight / volume units
(e.g., kg/m3).
DENSNMW Output double precision scalar returns weight density
of the NON-MW solids in weight / volume units (e.g.,
kg/m3).
DENSTOT Output double precision scalar returns weight density
of the total solids in weight/volume units (e.g., kg/m3).
IERR Output integer scalar returns the error status flag:
0 Success, no errors
1 Failure. Flow rates of SMWCRATE and
SNMWCRATE are all zero.
2 Failure. TEMPIN is outside the system limits.
3 Failure. Density calculation failed.

Notes:
1 Retrieve NOCTOTR by using routine GETNCOMP.
2 See routine URXSTR for a description of a standard stream array.

21-8 UAS Solid Components February 2009

 UHSSOLID
The solid molar heat capacity, molar enthalpy or molar entropy for
a specified molar solid composition may be determined with this
subroutine. The composition is loaded into a vector of mole rates
sized to NOCTOTR elements (see subroutine GETNCOMP). Supply
all input values using problem input dimensional units.
Calling sequence:
CALL UHSSOLID( ITYPE, TEMPIN, PRESIN,
& SMWCRATE, SMOLARCP,
& SMOLENTH, SMOLENTRO, IERR )
Where:
ITYPE Property requested:
1 Enthalpy and/or heat capacity
2 Entropy
3 Compressibility factor on a dry basis
calculated from the density method(s)
declared on the METHODS statement.
TEMPIN Input temperature in input units of measure; a
double precision scalar value.
PRESIN Input pressure in input units of measure; a
double precision scalar value.
SMWCRATE Input double precision array of molecular
weight solids component mole rates (e.g., kg-
mol/hr). Dimension:
REAL(8) :: SMWCRATE(NOCTOTR1)
SMOLARCP Input solid molar heat capacity (when ITYPE
= 1). Specific heat is reported in energy units
per mole per temperature unit. This is a
double precision scalar value.
SMOLENTH Input solid molar enthalpy (in input enthalpy
units. For example, kcal / kg-mole.) This is a
double precision scalar value.
SMOLENTRO Input solid molar entropy (in input entropy
units. For example, kcal / kg-mol K). This is a
double precision scalar value.
IERR Error flag:
0 Success, no errors.
1 Failure, ITYPE not in range 1-2
2 Failure in Cp or enthalpy calculations
3 Failure in entropy calculations

PRO/II User-Added Subroutine User Guide 21-9

 4 Failure due to one of the following:
Zero or negative stream flow rate,
Temperature or pressure out of bounds,
A negative value in SMWCRATE.
No Solid component specified.

USOLCDAT
Subroutine USOLCDAT is used to retrieve these pure solid compo-
nent fixed properties:
Heat of fusion,
Normal melting point temperature,
Triple point temperature, and
Triple point pressure.
All property values return using appropriate units of measure used
for problem input.
Calling sequence:
CALL USOLCDAT( ICNO, IPROP, VALUE, IERR )
Where :
ICNO Input integer component (internal order) sequence
number. (See routines COINUM and COPNUM.)
IPROP Input integer flag indicating the requested property.
1 Heat of fusion, energy / weight
2 Temperature at Normal Melting point
3 Triple point temperature
4 Triple point pressure
VALUE Output property value; a double precision scalar.
IERR Output integer status flag that returns:
0 Success, no errors
1 Failure, requested property not found.

21-10 UAS Solid Components February 2009

 GETPSDC
This subroutine may be used to retrieve the number of Particle Size
Distribution cuts (NCUTS) for a single specified component.
NCUTS is required by the Particle Size Distribution retrieval/stor-
age subroutine (see USOLPSD).
Calling sequence:
CALL GETPSDC( ICNO, NCUTS )

where:

ICNO Input integer that specifies the internal order number1 of

the component of interest.
NCUTS Output integer returns the number of cuts for component
ICNO in the Particle Size Distribution data tables.
Note 1: See routine COINUM to access component internal order numbers.

USOLPSD
This subroutine retrieves or stores the Particle Size Distribution
attributes for a solid component in a given stream.
Calling sequence:
CALL USOLPSD( CSID, ICNO, LENPSD, PSD,
& IOTYPE, IERR )
Where
CSID Input character string that identifies a PRO/II stream to
which data is stored or from which data is retrieved. It may
be a quoted literal string or a character variable containing a
maximum of 12 characters.
ICNO Input integer that specifies the internal order number1 of the
component of interest.
LENPSD Input integer that declares the size of argument array PSD.
LENPSD must equal the number of PSD cuts for the
component (NCUTS - 1). Obtain NCUTS by using interface
routine GETPSDC.
PSD Double precision array of PSD values for component ICNO
(in stream CSID). Used to store or retrieve data. Usually,
this as an ALLOCATABLE array.

PRO/II User-Added Subroutine User Guide 21-11

 IOTYPE Integer input option flag that controls data transfer.
1 = Retrieve data
2 = Store data
IERR Integer output status flag.
0 = Success, no errors
1 = Failure, unspecified errors encountered

Example:
Assume we wish to retrieve PSD data for component 3, and the
stream of interest already is declared in variable CSID. SIMSCI
recommends declaring data transfer array PSD as a local ALLO-
CATABLE array.

REAL(8), ALLOCATABLE :: PSD( : )

INTEGER(4) :: LENPSD, ICNO, NCUTS, ifOK
INTEGER(4) :: IOTYPE, IERR
CHARACTER(LEN=12) :: CSID
. . .
ICNO = 3
CALL GETPDSC( ICNO, NCUTS )
LENPSD = NCUTS - 1
ALLOCATE( PSD( LENPSD ), STAT=ifOK )
. . .
IOTYPE = 1 ! option to retrieve data

CALL USOLPSD( CSID, ICNO, LENPSD, PSD,

& IOTYPE, IERR )
. . . ! use date, then free array PSD
IF( ALLOCATED( PDS ) ) DEALLOCATE( PSD )

UPSDCPY
This subroutine copies all particle size distribution data from one
PRO/II stream to another. No data values pass through the argument
list.
Calling sequence:
CALL UPSDCPY( FromSID, ToSID, IERR )
Where:
FromSID Input 12 character stream ID from which data is copied.
ToSID Input 12 character stream ID into which data is copied.
IERR Integer return status flag.
0 = Success, no errors
1 = Failed for unspecified reasons.

21-12 UAS Solid Components February 2009

 Chapter 22
Pressure Drop Subroutines
The User-Added Pressure Drop subroutines described in this chap-
ter allow users and other independent developers to supplement the
PRO/II-supplied pressure drop methods. Only the PIPE and PLUG
Flow reactor models in PRO/II support user-added pressure drop
subroutines.
The PIPE unit can use only one of the PIPUSn pressure drop routines.
When the PLUG model runs in OPENPIPE mode, it also uses only the
PIPUSn routines. However, a PLUG model with the PACKING option
uses only the PACUSn routines. The two types of pressure drop rou-
tine have different data requirements. To accommodate these differ-
ences, separate pressure drop interfaces are provided for the PIPE
and the PLUG Flow Reactor models. Both the keyword input facili-
ties and the ProVision Graphical User Interface fully support these
subroutines.

PIPE Pressure Drop Subroutines

User Information
The PIPE unit operation in PRO/II supports up to two user-added
subroutines to compute the pressure drop through a pipe. Each PIPE
unit in a simulation can access one or the other of these two routines
by specifying either DP1 or DP2 as the argument of the DPCORR key-
word on the LINE statement. PRO/II already includes sample calcu-
lation routines, so these two options may be exercised in the version
as delivered.

PRO/II User-Added Subroutine User Guide 22-1

 Pipe Pressure Drop Method Selection Using ProVision
The ProVision GUI makes it simple to access user-added pressure
drop methods in PIPE units. Figure 22-1 illustrate how selection is
accomplished with just a few mouse clicks.
Figure 22-1: Pipe Pressure Drop Methods in ProVision

22-2 Pressure Drop Subroutines February 2009

 Pipe Pressure Drop Method Selection Using Keywords
PIPE UID=<unit ID>, {NAME=<name>}
LINE DPCORR= DP1 or DP2 ...

Users must explicitly select either DP1 or DP2 to use a user-added

pressure drop routine. See Table 22-1. If the selection is omitted, the
pipe unit uses internal correlation to compute pressure drop.
where:
Table 22-1: Selecting A User-Added Pressure Drop In A PIPE
Unit
DPCORR = Selects the pressure drop correlation. Arguments
DP1 and DP2 select a user-added subroutine written
and built in the User-Added Library.
DP1 PIPUS1.FOR computes pressure drop of a PIPE
DP2 PIPUS2.FOR computes pressure drop of a PIPE

Input Data Requirements

There are no input data values for the user to supply. The PIPE
model in PRO/II uses internal calculation values to satisfy all the
data requirements of the user-added subroutine.

Output Reporting
PRO/II does not provide any reporting from user-added pressure
drop subroutines.

Developer Information
Of course, the intended purpose is to allow you to implement and
use your own pressure drop correlation(s) instead of using those
provided by SIMSCI. To create your own pressure drop correlation
routine, you must replace a subroutine supplied by SIMSCI with
one that contains your own code. Sample routines PIPUS1.FOR and
PIPUS2.FOR are made available when the user-added add-on is
installed during PRO/II installation. Replace the code in these rou-
tines with your own code.

Guidelines for Coding

Developers should acquire a reasonably thorough understanding of
using user-added subroutines before beginning code development.

PRO/II User-Added Subroutine User Guide 22-3

 All the previous information for users is relevant. This section high-
lights areas of concern that developers may encounter.
Here are a couple of tips about general coding practices.
1. Check the input data for completeness and consistency, and
perform any necessary error processing. If desired, call UAERR
to register a warning in the PRO/II error system. Do this before
starting the calculations.
2. Perform the calculations, returning the results in the seven out-
put variables of the subroutine argument list. Normally utilities
such as pressure drop calculations should generate fatal errors.
Always try to return reasonable values, even after encountering
problems. For example, when calculations are impossible,
return dP as zero and issue a warning. Let the calling unit oper-
ation decide if it needs to fail.
3. Intermediate results may be printed as desired. Use variable IDG
as a diagnostic print flag. It is passed in for this purpose.

Subroutine Naming Conventions

PRO/II associates input keywords with specific user-added subrou-
tines. These associations are implemented through a pre-defined set
of the subroutine naming conventions. Developers must use the
subroutine names shown in Table 22-1 on page 22-3 to achieve a
successful implementation for PIPE units.

Calculation Routines -- Fortran Coding Conventions

Information is communicated to the user subroutine through the
subroutine’s argument list and the common blocks listed in Table
15-2, “Interface Common Blocks,” on page 15-6.
Calling sequence:
CALL PIPUSn(
& HLNS, AINCL, DIAM, AREA, RUFF,
& RNUMB, FRICT, FROUDE, NOACCL, PRES,
& RLVELN, VELSL, VELSG, QLI, QGI,
& RLDENS, VISL, RLSTEN, RVDENS, VISV,
& HL, IREG, FRGR, ELGR, ACCGR,
& DPINCR, NFOUT, IDG, NUIDD, IDUM1,
& IDUM2 )
where:

22-4 Pressure Drop Subroutines February 2009

 n in PIPUSn is a digit, either 1 or 2. It is part of the subroutine
name, as shown above in Table 22-1.
All data available to the pressure drop routine is passed through the
argument variables in the call list by each PIPE unit that uses the
pressure drop subroutine. The data are specific to the PRO/II pipe
model, so the pressure drop routine is suitable for use only with
PRO/II PIPE unit operations.
Table 22-2 describes the 31 arguments in the call list.
Table 22-2: PIPUSn Argument List
Name Type Brief Description UOM

Input Variables
HLNS DP1 No slip holdup
≤ 0.0 = Single-phase vapor
0.0<HLNS<1.0 = Mixed phase
(vap+liq)
≥1.0 = Single-phase liquid
AINCL DP Pipe inclination angle radians
DIAM DP Pipe inside diameter feet
AREA DP Pipe inside area square feet2
RUFF DP Pipe roughness/diameter ratio
RNUMB DP Reynolds number
FROUDE DP Froude number
3
NOACCL Integer NOACCELERATION option
flag
0= acceleration APPLIED
1= acceleration OMITTED
PRES DP Input. Absolute pressure psia
RLVELN DP Pipe liquid VELOCITY number
VELSL DP Pipe liquid SUPERFICIAL ft/sec
VELOCITY
VELSG DP Pipe vapor SUPERFICIAL ft/sec
VELOCITY
QLI DP Pipe liquid FLOWRATE cu.ft/sec
QGI DP Pipe vapor FLOWRATE cu.ft/sec
1) DP indicates the argument is a double precision floating point value.
2) Chr*(*) indicates the argument is an inherited-length character string.
3) INT indicates variables are type INTEGER(4)

PRO/II User-Added Subroutine User Guide 22-5

 Table 22-2: PIPUSn Argument List
Name Type Brief Description UOM
RLDENS DP Pipe liquid (oil+water) lb/cu.ft
DENSITY
VISL DP Pipe liquid (oil+water) cP
VISCOSITY
RLSTEN DP Pipe liquid (oil+water) dyne/cm
SURFACE TENSION
RVDENS DP Pipe vapor DENSITY lb/cu.ft
VISV DP Pipe vapor VISCOSITY cP
NFOUT Integer Fortran File Unit for printing
diagnostic messages
IDG Integer Diagnostic printout flag (DUMP
value)
0= Suppress diagnostics
1= Generate diagnostics
NUIDD Chr*(*)2 Character string containing ID of
(calling) unit op
IDUM1 Integer Not used here
IDUM2 Integer Not used here

OUTPUT Variables
FRICT DP Pipe friction factor (Calculated
and returned even when no input
value is supplied)
HL DP Pipe slip holdup
IREG Integer dP method flow regime flag
1= Liquid
2= Vapor
3= Distributed
4= Intermittent
5= Segregated
6= Transition
FRGR DP Friction gradient psi/ft
ELGR DP Elevation gradient psi/ft
ACCGR DP Acceleration gradient psi/ft
DPINCR DP Total gradient FRGR + ELGR + psi/ft
ACCGR
1) DP indicates the argument is a double precision floating point value.
2) Chr*(*) indicates the argument is an inherited-length character string.
3) INT indicates variables are type INTEGER(4)

22-6 Pressure Drop Subroutines February 2009

 Note: Be sure to declare all floating-point argument variables as
double precision REAL(8), or include the SIMSCI-pro-
vided INCLUDE file PRECIS.CMN as the first line of active
code after the SUBROUTINE statement.

Availability of Data
The PIPE unit delivers current values of its ongoing calculations to
the subroutine through variables in the call argument list. The argu-
ment list variables essentially constitute the entire universe of PIPE
data available to the subroutine. Other simulation data not specific
to the PIPE unit, such as component data, may be accessed using
any of the interfaces listed in chapter 15, ”Interfacing Software”,
Table 15-1 and Table 15-2. In most cases, stream data is of little use
in pressure drop calculations; so use of stream interfaces probably
should be avoided.

Returning Results to PRO/II

Return all calculated results through the seven output variables in
the subroutine’s argument list. Refer to Table 22-2 on page 22-5.

Output Subroutines
PRO/II does not provide any support for output from user-added
pressure drop subroutines.

Sample Code Listings

PRO/II Keyword Input File
TITLE PROJ=PipeDp, PROB=Ex8-1, USER=SimSci, DATE=Mar-2008
$
$ Sample Pipe using User-added Pressure drop routine
$
PRINT INPUT=ALL
DIMENSION ENGLISH, PRES=PSIG, LIQVOL=GAL, TIME=MIN
COMPONENT DATA
LIBID 1, WATER
THERMO DATA
METHODS SYSTEM=LIBRARY, TRANSPORT=PURE, &
DENSITY(L)=LIBRARY
STREAM DATA
$ 40 gpm of condensate water at 50 psig
PROP STRM=F40P2, PHASE=L, PRES=50, COMP=1, RATE(V)=40
PROP STRM=F40DP1, PHASE=L, PRES=50, COMP=1, RATE(V)=40
UNIT DATA
PIPE UID=PipeProII, NAME=300 FT LINE
FEED F40P2

PRO/II User-Added Subroutine User Guide 22-7

 PROD M=ProdProII $ Internal dP
LINE DIAM=3.26, LENGTH=300, DPCORR=BBM
PIPE UID=PipeUser1, NAME=300 FT LINE
FEED F40DP1
PROD M=ProdUser1 $ dP from PIPUS1
LINE DIAM=3.26, LENGTH=300, DPCORR=DP1

This example runs two pipe units that are identical except for one
difference: the first uses an internal PRO/II correlation, while the
second uses a user-added subroutine to calculate pressure drop.

Fortran Source Listing

See file PIPUS1.FOR for a listing of the code used in this example.
The file is located in the ..\USER\Uas\examples\ directory tree of
the PRO/II installation.

Partial Output Listing

The partial output listing that follows demonstrates the differences
in the results.
This first unit uses a PRO/II internal pressure drop correlation.
UNIT 1, 'PIPEPROII', '300 FT LINE'

OPERATING CONDITIONS

DUTY, MM BTU/MIN 0.00000

PRESSURE DROP SUMMARY
LINE FRICTION, PSI 0.50257
ELEVATION, PSI 0.00000
ACCELERATION, PSI 3.12162E-05
TOTAL, PSI 0.50260
CALC TOTAL PRESSURE DROP, PSI 0.50260
CALC MAX LINE FLUID VELOCITY, FT/SEC 2.05859

UNIT 2, 'PIPEUSER1', '300 FT LINE'

The second pipe used user-added subroutine PIPUS1.FOR to per-
form the pressure drop calculations.
OPERATING CONDITIONS

DUTY, MM BTU/MIN 0.00000

PRESSURE DROP SUMMARY
LINE FRICTION, PSI 0.52551
ELEVATION, PSI 0.00000
ACCELERATION, PSI 3.83041E-05
TOTAL, PSI 0.52555
CALC TOTAL PRESSURE DROP, PSI 0.52555
CALC MAX LINE FLUID VELOCITY, FT/SEC 2.07656

22-8 Pressure Drop Subroutines February 2009

Plug Flow Reactor Pressure Drop Subroutines
User Information
The PLUG Flow Reactor unit operation (PFR) in PRO/II supports
two sets of user-added subroutines to compute the pressure drop
through the reactor; the PIPUSn routines and the PACUSn routines. In
OPENPIPE mode, the PLUG reactor uses the PIPUSn user-added pres-
sure drop subroutines described earlier in this chapter. They are not
discussed further here.
PLUG units model packed-bed reactors when they include the
PACKING and CATALYST statements in keyword input. In ProVision,
setting the Pressure Specification to Packed-Bed Pressure Drop
results in the same packed-bed configuration. In this mode, only the
PACUSn subroutines are available. This section only describes the
PACUSn subroutines.

Each PLUG unit in a simulation can access only one of the pressure
drop routines. PRO/II already includes a sample calculation routine,
PACUS1.FOR. That means the DPCORR=DP1 option for a packed-bed
PLUG reactor may be exercised in the version as delivered.

Open Pipe Pressure Drop Methods Using Keywords

PLUG UID=<unit ID>, {NAME=<name>}
OPENPIPE DPCORR= DP1 or DP2 ...
Table 22-3 relates the input options to pressure drop routines that
perform the calculations in a PLUG reactor running in OPENPIPE
mode.

Table 22-3: UAS Pressure Drop Options In Open Pipe Plug

Reactors
OPENPIPE Selects a packed-bed pressure drop correlation.
DPCORR = Arguments DP1 and DP2 select a user-added
subroutine written and built in the User-Added
Library.
DP1 PIPUS1.FOR computes reactor pressure drop
DP2 PIPUS2.FOR computes reactor pressure drop

PRO/II User-Added Subroutine User Guide 22-9

 Packed-Bed Pressure Drop Methods Using Keywords
PLUG UID=<unit ID>, {NAME=<name>}
PACKING DPCORR= DP1 or DP2

Table 22-4 relates the input options to calculation routines that per-
form the calculations in a PLUG reactor running in PACKING mode:
Table 22-4: UAS Pressure Drop Options In A Packed-Bed
PLUG Unit
PACKING Selects a packed-bed pressure drop correlation.
DPCORR = Arguments DP1 and DP2 select a user-added
subroutine written and built in the User-Added
Library.
DP1 PACUS1.FOR computes packed-bed pressure drop
DP2 PACUS2.FOR computes packed-bed pressure drop

Users must explicitly select either DP1 or DP2 to use a user-added

pressure drop routine. If the selection is omitted, the pipe unit uses
internal correlation to compute pressure drop.

PFR Pressure Drop Method Selection Using ProVision

Accessing user-added pressure drop methods for PLUG reactors
using ProVision is simple. The procedure is almost identical for an
open pipe or a packed-bed reactor.
Right-click a PLUG flow reactor icon in the Flowsheet window
and select Data Entry ... from the pop-up action menu.
In the Plug Flow Reactor window, click the Pressure button on
the plug-flow icon on the right-hand side of the window.
In the Plug Flow Reactor-Pressure window that opens, choose
the pressure drop option for the desired reactor configuration.
For an OPENPIPE reactor, click the Pressure Drop Method radio
button. Or,
For a packed-bed reactor, click the Packed-bed Pressure Drop
radio button.
With the radio button active, click Enter Data just to the right.
This opens the PFR Pressure Drop Method DEW.
Select User-1 or User-2 to specify a user-added pressure drop
method.

22-10 Pressure Drop Subroutines February 2009

 Click OK to confirm the selection and return to the parent Data
Entry Window.
Figure 22-2 illustrates the selection process.
Figure 22-2: User-Added PFR Pressure Drop Methods in ProVision

PRO/II User-Added Subroutine User Guide 22-11

 Input Data Requirements
There are no input data values for the user to supply to the pressure
drop routine. The PLUG model in PRO/II uses internal calculation
values to satisfy all the data requirements of the user-added
subroutine.

Output Reporting
PRO/II does not provide any reporting from user-added pressure
drop subroutines.

Developer Information
This section discusses implementing user-added pressure drop cor-
relation(s) as alternatives to those within PRO/II. To implement a
pressure drop correlation routine, you must replace a subroutine
supplied by SIMSCI with one that contains your own code.

Subroutine Naming Conventions

PRO/II associates input keywords with specific user-added subrou-
tines. These associations are implemented through a pre-defined set
of subroutine naming conventions. Developers must conform to the
subroutine names shown in Table 22-4 on page 22-10 to achieve a
successful implementation of pressure drop routines for PLUG reac-
tors.

Guidelines
Refer to the general “Guidelines for Coding” on page 3 of this
chapter. They also apply when coding Plug flow pressure drop
routines.

Calculation Routines -- Fortran Coding Conventions

Reactor data is passed in, and results are returned to PRO/II,
through the subroutine’s argument list.
Calling sequence:
CALL PACUS1(
& HLNS, DIAM, AREA, RNUMB, FROUDE,
& PRES, VELSL, VELSG, QLI, QGI,
& RLDENS, VISL, RLSTEN, RVDENS, VISV,
& HL, IREG, DPINCR, NFOUT, IDG,
& NUIDD, IDUM1, IDUM2, CDIAM, CVOID,
& CSPER, ISTOP )

22-12 Pressure Drop Subroutines February 2009

 where:
n in PACUSn is a digit, either 1 or 2. It is part of the subroutine
name, as shown in Table 22-4 on page 22-10 of this chapter.
The 27 arguments in the call list are defined in Table 22-5.
Table 22-5: PACUSn Argument List
Name Type Brief Description UOM

Input Variables
HLNS DP1 No slip holdup
≤ 0.0 = Single-phase vapor
0.0<HLNS<1.0 = Mixed phase
(vap+liq)
≥1.0 = Single-phase liquid
DIAM DP Packed plug inside diameter feet
AREA DP Packed plug inside area feet2
RNUMB DP Reynolds number of flowing fluid
(using superficial velocity)
FROUDE DP Froude number
PRES DP Absolute pressure psia
VELSL DP Packed plug liquid SUPERFICIAL ft/sec
VELOCITY
VELSG DP Packed plug vapor SUPERFICIAL ft/sec
VELOCITY
QLI DP Packed plug liquid FLOWRATE cu.ft/sec
QGI DP Packed plug vapor FLOWRATE cu.ft/sec
RLDENS DP Packed plug liquid (oil+water) lb/cu.ft
DENSITY
VISL DP Packed plug liquid (oil+water) cP
VISCOSITY
RLSTEN DP Packed plug liquid (oil+water) dyne/cm
SURFACE TENSION
RVDENS DP Packed plug vapor DENSITY lb/cu.ft
VISV DP Packed plug vapor VISCOSITY cP
NFOUT INT Input Fortran File Unit for printing
diagnostic messages
1) DP indicates the argument is a double precision floating point value.
2) CHR* indicates the argument is an automatic-length character string.
3) INT indicates variables are type INTEGER(4)

PRO/II User-Added Subroutine User Guide 22-13

 Table 22-5: PACUSn Argument List
Name Type Brief Description UOM
IDG INT Diagnostic printout flag (DUMP
value)
0= Suppress diagnostics
1= Generate diagnostic
NUIDD Chr*2 Character string containing ID of
(calling) unit op
IDUM1 INT Not used here
IDUM2 INT Not used here
CDIAM DP Particle diameter
CVOID DP Void fraction of the bed
CSPER DP Sphericity

Output Variables
HL DP Packed plug slip holdup
IREG INT dP method flow regime flag
1= Liquid
2= Vapor
3= Distributed
4= Intermittent
5= Segregated
6= Transition
DPINCR DP Total gradient FRGR + ELGR + psi/ft
ACCGR
ISTOP INT Returned error status flag
0 = Success, no errors
1 = Failure, results may be invalid.
1) DP indicates the argument is a double precision floating point value.
2) CHR* indicates the argument is an automatic-length character string.
3) INT indicates variables are type INTEGER(4)

Note: Be sure to declare all floating-point argument variables as

double precision REAL(8), or include the SIMSCI-pro-
vided INCLUDE file PRECIS.CMN as the first line of active
code after the SUBROUTINE statement.

Availability of Data
Each PLUG reactor that uses the pressure drop subroutine delivers
current values from its ongoing calculations through the subroutine
argument list. Thus, the argument list variables essentially consti-

22-14 Pressure Drop Subroutines February 2009

 tute the entire universe of PLUG reactor data available to the subrou-
tine. Other simulation data not specific to the PLUG unit, such as
component data, may be accessed using any of the interfaces listed
in chapter 15, ”Interfacing Software”, Tables 15-1 and 15-2. In
most cases, stream data is of little use in pressure drop calculations;
so use of stream interfaces probably should be avoided.

Returning Results
All calculated results return to PRO/II through the output variables
in the argument list of the subroutine. The 4 required results
include: HL, IREG, DPINCR, and ISTOP. Refer to Output Variables in
Table 22-5 on page 22-13.

Output Subroutines
PRO/II does not provide any support for output from user-added
pressure drop subroutines.

Sample Code Listings

This example runs two PLUG reactors with these differences: The
first is an OPENPIPE plug reactor. The OPENPIPE DPCORR=DPI state-
ment specifies user-added subroutine PIPUS1.FOR to calculate the
pressure drop.
The second is a packed-bed reactor. The PACKING DPCORR=DP1
statement specifies user-added subroutine PACUS1.FOR to calculate
pressure drop.

PRO/II Keyword Input File

TITLE PROB=USERADD, PROJ=dPPlug, USER=SIMSCI,
DATE=Mar2006
$ This file tests user-added Pressure Drop
$ subroutines in Plug-Flow reactors
$ US1Open uses PIPUS1 in an OPENPIPE reactor
$ US2Pack uses PACUS1 in an PACKED reactor
PRINT INPUT=ALL, STREAM=PART
DBASE DATA=PC1
COMP DATA
LIBI 1,H2O/ 2,HCL/ 3,CL2/ 4,PROPYLEN/ &
5,ALLYLCL/ 6,12DCLPRP/ 7,13DCLPRE
THERMO DATA
METH KVAL=SRK, ENTH=SRK, ENTR=SRK, TRANS=LIBR, &
DENS(V)=IDEAL, DENS(L)=IDEAL
STREAM DATA
PROP STRM=X100, TEMP=852.4933, PRES=1500.0, &

PRO/II User-Added Subroutine User Guide 22-15

 COMP=0.0000/0.1/172.5399/1010.4196/1.75
PROP STRM=X200, TEMP=852.4933, PRES=1500.0, &
COMP=0.0000/0.1/172.5399/1010.4196/1.75
PROP STRM=X300, TEMP=852.4933, PRES=1500.0, &
COMP=0.0000/0.1/172.5399/1010.4196/1.75
RXDATA
RXSET ID=SET01
REACTION ID=REAC01
STOI 4,-1/3,-1/5,1/2,1
KINETICS PEXP=2.1E11, ACTI=27.0096
KPHASE DEFAULT=V
REACTION ID=REAC02
STOI 4,-1/ 3,-1/ 6,1
KINETICS PEXP=1.19E7, ACTI=6.81198
KPHASE DEFAULT=V
REACTION ID=REAC03
STOI 5,-1/ 3,-1/ 7,1/ 2,1
KINETICS PEXP=4.69E14, ACTI=4.23E1
KPHASE DEFAULT=V
UNIT OPERATIONS
PLUGFLOW UID=US1Open
FEED X100
PROD L=USOpen
RXCALC KINETICS(SUBROUTINE)=U1, NSTEPS=100
OPER LENG=5.0,DIAM=10.0,PHASE=V,TEMP=850

OPENPIPE DPCORR=DP1 $ User-added PACUS1

RXSTOIC RXSET=SET01
REACTION REAC01
BASE COMPONENT=3
REACTION REAC02
BASE COMPONENT=3
REACTION REAC03
BASE COMPONENT=3
SUPPLE 199,1234.0

PLUGFLOW UID=Us2Pack
FEED X200
PROD L=USPack
RXCALC KINETIC(SUBROUTINE)=U1, NSTEPS=100
OPER LENG=5.0,DIAM=10.0,PHASE=V,TEMP=850

PACKING DPCORR=DP1 $ User-added PACUS1

CATALYST POROSITY=0.99, PDIAM=0.5
RXSTOIC RXSET=SET01
REACTION REAC01
BASE COMPONENT=3
REACTION REAC02

22-16 Pressure Drop Subroutines February 2009

 BASE COMPONENT=3
REACTION REAC03
BASE COMPONENT=3
SUPPLE 199,1234.0
END

Fortran Source Listing

See files PIPUS1.FOR and PACUS1.FOR for listings of the pressure
drop code used in this example. The files located in the
..\USER\Uas\examples\ directory tree of the PRO/II installation.

Partial Output file

The partial output listing that follows demonstrates the differences
in the pressure drop results.
The first unit is an open pipe reactor that uses the PIPUS1 pressure
drop routine.
UNIT 1, 'US1OPEN'

OPEN PIPE REACTOR DETAILS

REACTING SIDE Inlet Outlet

----------- -----------
Feed X100
VAPOR Product USOPEN
Temperature, F 852.49 850.00
Pressure, PSIA 1500.0000 1499.9985

The second unit is a packed-bed reactor that uses the PACIS1 pres-
sure drop routine.
UNIT 2, 'US2PACK'

PACKED BED REACTOR DETAILS

REACTING SIDE Inlet Outlet

----------- -----------
Feed X200
VAPOR Product USPACK
Temperature, F 852.49 850.00
Pressure, PSIA 1500.0000 1103.2132

PRO/II User-Added Subroutine User Guide 22-17

22-18 Pressure Drop Subroutines February 2009
 Appendix A
Special Property Key Words
Named Special Properties
This appendix lists the named special properties supported by the
User-added Subsystem in PRO/II. Some interface routines that use
these key words include: UCoPrp on page 15-44.
Table A-1 lists the key words that identify named Special Properties
supported by PRO/II user-added interface routines. These key
words are used only inside user-added subroutines. They may be
different from the key words used in PRO/II keyword input files.
Table A-1: Keywords for Named Special Properties

Keyword Property
KVIS Kinematic Viscosity
CLOU Cloud Point
POUR Pour Point
FLPC Flash Point (Closed Cup)
SULF Sulfur Content
CETN Cetane Number
SMOK Smoke Point
ARO1 Mono Aromatics
ARO2 Di-Aromatics
ARO3 Tri-Aromatics
ARO4 Tetra-Aromatics
ARO5 Penta-Aromatics
ARO7 Hepta-Aromatics

PRO/II User-Added Subroutine User Guide A-1

 Keyword Property
AROT Total Aromatics
NAPH Naphthene
PARN Normal Paraffin
PARI Iso-Paraffin
PARA Alkyl-Paraffin
PARP Poly-Paraffin
PART Total Paraffin
OLE1 Mono Olefin
OLEB Branched Olefin
OLEC Cyclic Olefin
H2 Hydrogen
CARB Carbon
VANA Vanadium
NICK Nickel
SODI Sodium
OXGY Oxygen
N2TO Total Nitrogen
N2BA Basic Nitrogen
N2NB Nonbasic Nitrogen
ASC5 Asphaltene C5
ASC7 Asphaltene C7
V50 V50 Value
VIND Viscosity Index
PEN Penetration Index
FRZP Freeze Point (temperature)
CCR Conradson Carbon Residue
RCR RAM Carbon Residue
CHRA Carbon-Hydrogen Weight Ratio
TAN Total Acid Number
WAX Wax Content
ASH Ash Content

A-2 Special Property Key Words February 2009

 Keyword Property
RON Research Octane Number
MON Motor Octane Number
REFI Refractive Index
RIND Ring Index
ARIN Aromatic Index
GIND Grade Index
SIND Structure Index
LUMI Luminometer Number
NOAC Noack Volatility
JT Joule-Thompson, K/kPa
EXPN Expansivity, 1/K
VSOU Velocity of Sound, m/s
BULK Bulk Modulus, kPa
CVOL CVOL
CETA Cetane Index
IBP Initial Boiling Point (temperature)
FBP Final BP (temperature)
MERC Mercaptan
NPHL Naphthalene
ANIL Anilne Point
BROM Bromine Number
ANEU Neutralize Number
CFPP CFPP
ICI Icing Index
STUI Startup Index
WUI Warm-up Index
SOFT Softening Point
PHEN Phenol Content
MON3 MON at 3 ml TEL
RON3 RON at 3 ml TEL
ASUL Aliphatic Sulfur

PRO/II User-Added Subroutine User Guide A-3

 Keyword Property
RI70 Refractive Index at 70C
AROG Aromatic Rings
IRON Iron Content
WTAR Weight Aromatics
WTPA Weight Paraffins
WTNA Weight Naphthenes
FLPO Flash Point (Open Cup)
CVLU Car Vapor Lock (USA)
CVLE Car Vapor Lock (Europe)
MEAB Mean Average Boiling Point (temp)
CABP Cubic Average Boiling Point (temp)
MOAB Molal Average Boiling Point (temp)
NHV Net Heating Value
IDLT IDL Type
PEPT Peptising Power
PVAL P Value
FRMX FR Maximum
FLOC Flocculation Ratio
CPWX Congealing Point of Wax
PWAX Paraffinic Wax Content
CPPW Congealing Point of Paraffinic Wax
ARI1 Initial Point Mono-Aromatics
ARI2 Initial Point Di-Aromatics
ARI3 Initial Point Tri-Aromatics
ARIP Initial Point Total Aromatics
MERS Mercaptan Sulfur
TRS Total Reactive Sulfur
FLPW Flash Point (Wong Closed Cup)

A-4 Special Property Key Words February 2009

Numbered Special Properties
Several interface routines that may be called from user-added sub-
routines require a key word argument to identify a component prop-
erty or a named special property. However, some special properties
are defined by the user, and so do not have a name assigned to them
that PRO/II can recognize universally. Typically, such numbered
(user-defined) properties are designated in PRO/II keyword input
files using keyword SPROP(nn), where “nn” represents the prop-
erty number.
To allow accessing these properties from user-added subroutines,
these properties are identified by supplying an ID number. Here are
the general usage conventions.
Whenever the character string argument (cProp) for a named
property is non-blank, PRO/II attempts to process that property.
When the string is not resolvable into a recognized property ID,
an error results.
When the character string argument (cProp) for a property is
blank or zero length, PRO/II tests an additional integer argu-
ment (iProp) in an attempt to identify a numbered user-defined
special property.
If the property identified by the iProp argument is found to be
available, PRO/II processes that numbered property.
When iProp is not resolvable into a recognized property ID, or
the property cannot be found, an error results.

PRO/II User-Added Subroutine User Guide A-5

A-6 Special Property Key Words February 2009