Sunteți pe pagina 1din 536

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 ro