PROII User-Added Subroutines User Guide

PRO/II 8.3User-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 Keyword Manual

Copyright Notice

Copyright © 2009 Invensys Systems, Inc. All rights reserved. The material protected by this copyright may be reproduced or utilized 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 LEGENDThe 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-1User Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-6Software Requirements for PRO/II UAS . . . . . . . . . . . . . . . . .1-7Hardware Requirements for PRO/II UAS . . . . . . . . . . . . . . . . . .1-8Program Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-9 Upgrading Legacy User-Added Subroutines . . . . . . . . . . . . .1-10Source Code Changes for Intel Fortran: . . . . . . . . . . . . . . . . .1-13

Chapter 2: Modular UAS Build Procedures

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1User Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1Developer Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-17

Chapter 3: Modular Interface Software

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-1Contexts in PRO/II . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-3

ISOLVE Return Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-4Call-back Routines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-5

Chapter 4: Modular Utility Subroutines

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-1User Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-1Developer Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-2Definition of class_ UASOBJ.mod . . . . . . . . . . . . . . . . . . . . . .4-10class_Fluid.mod and class_FluidPhase.mod . . . . . . . . . . . . . .4-30

Chapter 5: Modular Unit Operations

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-1Keyword Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-2

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

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

Chapter 6: UAS Modular Fluids

Interface Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2User Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2Developer Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2Fluid Guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-21class_Fluid.mod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-25class_FluidPhase.mod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-34

Chapter 7: User-Added Units of Measure

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

Chapter 8: UAUOP AutoGUI

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

Chapter 9: UAUOP Icons

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

Chapter 10: UAUOP INI File

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

ToC - ii February 2009

Chapter 11: Interfacial Area Utility

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-1Available Interfacial Area Data - Developers . . . . . . . . . . . . .11-1

Chapter 12: Binary Mass Transfer Utility

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-1Available Mass Transfer Data - Developers . . . . . . . . . . . . . .12-2

Chapter 13: Heat Transfer Utility

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-1Available Heat Transfer Data - Developers. . . . . . . . . . . . . . .13-2

Chapter 14: Classic UAS Introduction

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

Chapter 15: Interfacing Software

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

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

Chapter 16: User-Added Thermodynamic Property Methods

Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-1Communicating with PRO/II . . . . . . . . . . . . . . . . . . . . . . . . . . 16-3Handling Water Decant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-11Enthalpy and Entropy Calculations . . . . . . . . . . . . . . . . . . . 16-22Density Calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-36

Chapter 17: Transport and Special Property SubroutinesUser-Added Transport Property Subroutines . . . . . . . . . . . . 17-1User-Added Special Property Subroutines . . . . . . . . . . . . . . 17-11

Chapter 18: Classic Unit Operations

Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-1User Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-2Developer Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-9User-Added Pipe Pressure Drop Utility Routines . . . . . . . . 18-32

Chapter 19: Reaction Kinetic Subroutines

User Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-1Developer Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-3Example Problem—Allyl Chloride Production in a PFR . . 19-10

Chapter 20: UAS Refinery Reactor Simulation

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

Chapter 21: UAS Solid Components

Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-1User Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-2Developer 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-1Numbered Special Properties . . . . . . . . . . . . . . . . . . . . . . . . . . A-5

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

ToC - vi February 2009

Chapter 1Modular 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 InformationThis 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.

NomenclaturePRO/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

Procedural InterfacesThe 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 InterfacesThis 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.

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.

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 SubroutinesModular 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.


Modular User-Added Unit OperationsUAUOP 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 UtilitiesCertain 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.


Modular Interface Call-backsModular 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 InterfacesGenerally, 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.


User InformationThis 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/IIPRO/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’sModular 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 LimitsEvery 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.


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 UASThe 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 LinkersDevelopers 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.

Hardware Requirements for PRO/II UASPRO/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.


Program LimitsAlthough 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 LimitationsCalculation/Model Component/Variable

Maximum

Classic User-Added Calculations1

2500 Components in Flowsheet

Classic User-Added Unit Operations

IPARM (250) RPARM (500) HEAT (10) SUPPLE (10000)

User-Added Kinetic Models 50 Components in Flowsheet IPARM (10) RPARM (70) SUPPLE (200)

Modular User-Added Calculations

Dynamic allocation, no fixed limits.

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.

1) Except user-added kinetics


Upgrading Legacy User-Added SubroutinesStarting 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 BlocksNote: 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.


Replacement Source CodeImportant: 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\ UasLb.sln UasLb.vfproj

\User\Uas\Examples\VF6\ uaslb.DSW UASLB.dsp

\User\Uas\Examples\Exam1\USER42_IF8.INPUSER42.FORU42OUT_IF8.FOR

\User\Uas\Examples\Exam1\USER42.INPUSER42.FORU42OUT.FOR

\User\Uas\Examples\Exam2\UKHS4.INPUKHS4.FOR

\User\Uas\Examples\Exam2\identicalidentical

\User\Uas\Examples\Exam3\USKIN1.INPUSKIN1.FOR


\User\Uas\Examples\exam4\UTRAN2.INPUTRAN2.FOR

\User\Uas\Examples\exam4\identicalidentical





\User\Uas\Examples\Exam7\USER57.FORU57OUT.FOR

New solids handling unit opera-tion example. No older code to replace.


\User\Uas\Examples\Exam8\ExUkhs7.INPExUkhs7.CHKUKHS7.FOR

New example of user-added method for water enthalpy. No older code to replace.

\User\Uas\UasF90\IVF\ ExUasF90.sln ExUasF90.vfproj ExUop.sln ExUop1.vfproj

\User\Uas\UasF90\VF6\ ExUasF90.dsw ExUasF90.dsp ExUop.dsw ExUop1.dsp

\User\Uas\UasF90\AreaMain.f90AreaCalc.f90AreaRepo.f90

MassMain.f90MassCalc.f90MassRepo.f90

HeatMain.f90HeatCalc.f90HeatRepo.f90

Uop1Main.f90Uop1Cros.f90Uop1Calc.f90Uop1Repo.f90FluidOut.f90FluidRep.f90UdmRepo.f90

Ex1Uop.iniEx1UopIcon.datEx1Uop.xml

\User\Uas\UasF90\identical RATEFRACidentical Interfacial areaidentical utility

identical RATEFRACidentical Mass Transferidentical utility

identical RATEFRACidentical Heat Transferidentical utility

identicalidentical Modular identical User-Addedidentical Unit Operationidentical source codeidenticalidentical

identical Modular UaUopidentical configurationidentical files

Table 1-2: Replacement UAS Solutions and Projects

New Code for PROII 8.2 Replaced Obsolete Code


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)


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.


Chapter 2Modular UAS Build Procedures

OverviewWhen 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 InformationThis 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.


Building A UAS DLL Using Visual Studio .NET 2003Building 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\IVFThe 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.


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.


Registering a UAS with PRO/IIBefore 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 FileThe 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.INIThis may be different on machines that installed PRO/II using some of the custom installation options.

Syntax in P2UasReg

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.

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.


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 UtilitiesPRO/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 FileUtility 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:


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 TransferKeyword System of Units

PROII PRO/II internal units

ENGLISH English units

METRIC Metric system units

SI System International


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.


Registering a Path to a User-Added DLLA 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.

“%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.

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.


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\”


Registering [UAUOP] User-Added Unit OperationsRegister 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.


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.


Troubleshooting Registration ErrorsPRO/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.


Using a User-Added Modular Utility in PRO/IIThis 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 UsersThis 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 UtilityAs delivered, PRO/II includes a working sample of an interfacial area utility that demonstrates a working interfacial area utility. The


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 ENGLISHCOMPONENT DATA LIBID 1,METHANOL / 2,WATER / 3,ETHANOL / & 4,PROPANOL / 5,BUTANOL / 6,NITROGENTHERMODYNAMIC DATA METHOD SYSTEM=WILSON, TRANSPORT=PURESTREAM 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.0UNIT 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.


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 UtilityUse 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 UtilityUse 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.


Developer InformationThis 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/IIPRO/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/IIContext UAUTIL UAUOP Description Need

INPUT No No Initialize input data (file or GUI)

Optional

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.


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 ValuesWhenever 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 Returns

Description

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 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.


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 RoutinesEach 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,


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 Operationsclass_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.


Resources for All Modular User-Added Subroutinesclass_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.


Compiler and Linker Project SettingsProjects 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 CompilerFortran 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.


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 LinkerUSERLB6.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:


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.


Chapter 3 Modular Interface Software

OverviewThis 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, History file, or display terminal. 3-5

UAWRITE Write a single line of text to any File Unit 3-7

UAERROR Records an Error, Warning, or Message in the PRO/II error-handling subsystem. 3-8

Modular Utility Routines (UAUTIL)

class_UASOBJ Data transfer object and member functions for manipulating utility subroutine data Chapter 4

Modular Unit Operations (UAUOP)

class_UAUOP Data transfer object and member functions for manipulating unit operation data. Chapter 5

Fluid and Fluid Data Modules

class_Fluid Data transfer and member functions that manipulate fluids, perform flashes, etc. 6-25

class_FluidPhase Data transfer and member functions to manipulate data in each phase of a fluid. 6-34

Dimensional Units Module

class_DMUOM Class containing member functions that access dimensional units conversion factors. Chapter 7


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 ClassesPRO/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 RoutinesModular 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 ListsWhen 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/IIDuring 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 or AutoGUI)

Optional

CROSS-CHECK

No Yes Validate Input data Optional

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.


ISOLVE Return ValuesWhenever 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 Returns Description

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


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 RoutinesIn 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

UAOUTPurpose: 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).


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.

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


UAWRITEThis 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, IvalREAL(8) :: RvalCHARACTER(LEN=133) :: cLine. . .CALL FIGETU( 1, LFU )Rval = 23.4Ival = 3cLIne = “The value of RVAL( ) is:”WRITE( cline(19,21), “( I3 )” ) IvalWRITE( cLine(29:39), “(F9.4)” ) RvalCALL UAWRITE( LFU, TRIM(cLine) )

The single line of output would be:

The value of RVAL( 3) is : 23.4000

CALL UAWRITE( UopObj%LFUout, TRIM( cLine ) )

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:


UAERRORPurpose: 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


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.


class_UASOBJ.modThis 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.modThis 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.modThis 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.modThis 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.


Chapter 4 Modular Utility Subroutines

OverviewUser-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 InformationThe 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 SummaryRFTRANSFERSECTION = 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.


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

Utility Output ReportsPRO/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 RegistrationIt 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 InformationThe 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 RoutinesEach 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 GuidelinesEach 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.


Contexts in Utility SubroutinesPRO/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 ValuesPRO/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 ValuesPRO/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,


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 UnitsEach 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.


Coding A Utility Interface RoutineEach 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 class12 !13 IMPLICIT NONE ! Require explicit variable declarations14 !15 TYPE(UASOBJ), INTENT(INOUT) :: DataObj ! Instantiate Obj16 !17 CHARACTER :: context*12 ! local character variable18 !19 ! --------------------- Code Begins here --------------------20 !21 context = TRIM( UASOBJ%Context ) Evaluate Context flag 22 !23 IF( context(1:4) .EQ. "CALC" ) THEN24 CALL UasCalc( DataObj ) ! Perform calculations25 ELSE IF( context(1:6) .EQ. "REPORT" ) THEN26 CALL UasReport( DataObj ) ! Generate report27 ELSE ! Handle unsupported contexts28 UasObj%ISOLVE = 0 ! Set ISOLVE to “Never Solved”29 ENDIF30 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


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.


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.


Coding A Utility Calculation RoutineTypically, 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.


Definition of class_ UASOBJ.modThis 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_ UASOBJPRO/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.


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_UASOBJDirect 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


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_UASOBJThis 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.


GETUASVALThis 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 DataCalling 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:


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 ElementsCalling 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.


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


Double Precision Named Array ElementCalling 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.


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) :: WeirHeightierr = GETUASVAL( "HTWIER", IfObj, WeirHeight )

The value for the height of the weir returns in variable WeirHeight. The error code returns in variable ierr.


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.


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


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 DataCalling 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, mVersionmType = UasGetChar( "MODT" )mVersion = UasGetChar( "MODV" )


Data Structure of class_UASOBJTable 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 DescriptionUasType C 12 Identifies the type of utility subroutine being

called UasPath C 256 Path to DLL directory from P2UasReg.iniUasName C 32 Actual name of subroutine called, from

P2UasReg.iniUasID C 32 PRO/II ID of the called UAS, from

P2UasReg.iniUasVersion C 12 Version of the UAS set by the developer of the

UAS.

General DataMember Type DescriptionThermoFl 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


UASOBJ Data MembersMember 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 OperationExist L4 Logical. True if UASOBJ contains valid data.

Component DataMember Type DescriptionNOC I4 Total number of components in problemCompIndex(i) I4 Internal component numbers, in input order. I =

1, NOC

Fluid DataMember Type Description

FlVapor Fluid Vapor phase fluid data objectFlLiquid Fluid Liquid phase fluid data objectFlIface Fluid Interface phase fluid data objectFlFeed Fluid Liquid phase fluid data objectFlProd 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 FlVaporValidFlLiquid I4 Validation flag for fluid FlLiquidValidFlIface I4 Validation flag for fluid FlIfaceValidFlIFeed I4 Validation flag for fluid FlFeedValidFlProd I4 Validation flag for fluid FlProd

Subroutine-specific DataMember Type Description

IS1 I4 An array containing scalar integer data. Contents may change for each type of utility subroutine.



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 DS1ValidDA2 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 DescriptionResults DP Calculated Results returned to PRO/II. Number

of elements and dimensional units are different for each type of user-added subroutine.



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 DataMember Type DescriptionLenINT I4 Size of INTdata arrayLenPAR I4 Size of PARdata arrayLenDBL I4 Size of DBLdata arrayINTdata I4 User-supplied integer dataPARdata I4 User-supplied PARAMETER dataDBLdata I4 User-supplied supplementary data

Logical File UnitsMember Type DescriptionLfuInput I4 A logical file unit to be used for data inputLfuData I4 A logical file unit to be used for intermediate

data storageLfuOutput 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



Module Identification DataThe 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.

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


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.


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

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.

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 = SIThis member is read from the P2UasReg.ini file. The user needs to enter this when registering the subroutine.


Component DataThe 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.

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 REPORTThe 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.

NOC Total number of components in problem


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 InternalOrder Component CompIndex Order 1 EBENZENE (1) = 2 2 PS (2) = 3 3 H2 (3) = 1

Fluid DataA 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

CompIndex(i) Internal component numbers, in input order. i = 1, NOC.


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.

Each flag may have any of the following values.

ValidFlVapor Validation flag for fluid FlVaporValidFlLiquid

Validation flag for fluid FlLiquid

ValidFlIface Validation flag for fluid FlIfaceValidFlIFeed Validation flag for fluid FlIFeedValidFlProd Validation flag for fluid FlProd

Values of Validation Flags


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 DataEach 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.

A one-dimension array containing scalar integer data. Contents defined by each UAS.

A two-dimension array for integer array data. Contents defined by each UAS.

Another two-dimension array for integer array data. Contents defined by each UAS.

A one-dimension array of double precision floating-point data. Contents defined by each UAS.

A two-dimension array for floating point array data. Often contains binary diffusion coefficients. Contents defined by each UAS.

A two-dimension array for floating point array data. Often contains binary mass transfer coefficients. Contents defined by each UAS.

A two-dimension array for floating point array data. Contents defined by each UAS.

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.

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

IS1

IA2

IA3

DS1

DA2

DA3

DA4

DA5


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 DS1ValidDA2 Validation flag for array DA2ValidDA3 Validation flag for array DA3 ValidDA4 Validation flag for array DA4ValidDA5 Validation flag for array DA5

Each flag may have any of the following values.

Values of Validation Flags

Value Description

Array is allocated and populated with valid data.

Array is allocated but empty. Do not retrieve data from the array.

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:

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.

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.

10

-1

ISOLVE

Results(1,1)


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

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

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 UnitsDevelopers 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.modThese 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.

SizeR1SizeR2


Chapter 5 Modular Unit Operations

OverviewModular 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.


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 DataINT( name or seqno ) intval1 {, intval2, .... }

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

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

Text DataTEXT( 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 InputData 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.

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

Table 5-1: Bypass OptionsBypass 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.


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


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.

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 DataINT( name or seqno ) intval1 {, intval2, .... }

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.


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

Double DataDBL( 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.0Alternatively, several PAR statements could be used:PAR( First ) 1.1PAR( Second ) 2.1, 2.2, 2.3PAR( Third ) 3.1, 3.2PAR( Fourth ) 4.0Statements may use sequence numbers instead of ID names.PAR( 1 ) 1.1PAR( 2 ) 2.1, 2.2, 2.3PAR( 5 ) 3.1, 3.2PAR( 7 ) 4.0Enter 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


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 DataTEXT( 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


TEXT( 2 ) 2.1, 2.2, 2.3TEXT( 3 ) 3.1, 3.2Values 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”

orTEXT( 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 ParametersDEFINE <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.


Importing Scalar ParametersDEFINE 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.


PROVISION InputFigure 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


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.


UAUOP User Options

Calculation OptionsPRO/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 ReportsPRO/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 ReportsThe 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 RegistrationIt 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.


Developer InformationThe 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 RoutinesAlmost 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 UAUOPPRO/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


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 UAUOPWhenever 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 Returns Description

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.

INPUT Not called Called Read and Store input data

CROSS-CHECK

Called Not called Verify input data

CALCULATE Called Not called Perform calculations

OPASS Called Not called Perform calculations

REPORT Called Not called Generate final output report

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


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 copyThe 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 ValuesOther 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.


Dimensional UnitsEach 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 GuidelinesEach 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


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 RoutineEach 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 UAUOP18 !19 IMPLICIT NONE20 CHARACTER(LEN=*), INTENT(IN) :: CONTEXT21 TYPE(UAUOP), INTENT(INOUT) :: UopObj ! define dataobj !22 INTEGER(4), INTENT(OUT) :: iSolve23 !24 IF( CONTEXT(1:9) .EQ. "CALCULATE" ) THEN25 CALL Uop1Calc( UopObj, iSolve )26 ELSE IF( CONTEXT(1:10) .EQ. "CROSSCHECK" ) THEN27 CALL Uop1Cros( UopObj, iSolve )28 ELSE IF( CONTEXT(1:5) .EQ. "OPASS" ) THEN29 iSolve = 0 ! not supported in this example30 ELSE IF( CONTEXT(1:6) .EQ. "REPORT" ) THEN31 CALL Uop1Repo( UopObj, iSolve )32 ELSE33 iSolve = 034 ENDIF35 !36 UopObj%ISOLVE = ISOLVE37 END SUBROUTINE UASMAIN


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.


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 RoutineTypically, 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.


Definition of class_ UAUOP.modThis 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_ UAUOPPRO/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) :: ISOLVEThe 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_UAUOPDirect member addressing accesses data by direct reference to the data member. Fortran 90 defines the percent symbol % as the mem-


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 componentsnumSides = 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 2UserPar3 = 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)%FeedCountcFeed = 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.


Indirect Access in class_UAUOPThe 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_UAUOPTable 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 DataModType 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.



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 DataNOC I4 Total number of components in the

simulationNOCMW I4 Number of molecular weight componentsCompIndex(n)

I4 Internal component numbers, in input order. n = 1, NOC

Dimensional Units of MeasureFactors 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.




INT Input and Results DataIntExtent I4 Total INT storage available (32 bit words)IntCount I4 Number of defined INT variablesIntValue( 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 DataParExtent 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.




DBL Input and Results DataDblExtent 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 DataTxtExtent 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



Module DataThe 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 DataThe variables in this section allow developers to add their own iden-tification information and make it available inside the user-added

Member Type DescriptionTxtWidth( 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 entryC nnn Character string containing up to nnn charactersI4 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



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.


General DataData in this section includes various flags that inform the subroutine what actions PRO/II expects it to perform.

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.

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)=ivalwhen Context = CALC, CalOpContext = 1

Context = OUT, CalOpContext = 2CalOpValue 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)=ivalwhere ival is the value of CalOpValue. Developers define the significance of CalOpValue (if any).


Component Data

Total number of components in a simulation

Number of molecular weight components in a simulation. NMWSolids are excluded. When no NMWSolids are in the simulation, NOCMW = NOC.

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

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=2This 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=2This 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, PLOTThe 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.

NOCNOCMW

CompIndex(i)


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 OrderingInput Order Component CompIndex Internal Order

1 EBENZENE (1) 22 PS (2) 33 H2 (3) 1

Dimensional Units of Measure DataDimensional 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..

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 DataEvery 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.

Factors


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 ResultsAll 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


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 DataThe 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) valueiVal3 = UopObj%IntValue( iLoc3 ) ! get INT(3) valuecNam3 = UopObj%IntName( 3 ) ! get name of INT(3)LimLo = UopObj%IntLower(3 ) ! get lower boundLimHi = UopObj%IntUpper(3 ) ! get upper boundIF( 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) locationiSize = 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 IFcNam4 = UopObj%IntName( 4 ) ! get name of INT(4)


PARAMETER User Data and Calculated ResultsParameter 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.


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 DataThe 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) valuecNam3 = UopObj%ParName( 3 ) ! get name of PAR(3)boundLo = UopObj%ParLower(3 ) ! get lower boundboundHi = UopObj%ParUpper(3 ) ! get upper boundIF( 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


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 ResultsDBL 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


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 ResultsText 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


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.


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

Data Structure of One SideEach 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 MembersMember Type Description

IdentificationName C 32 Descriptive name of the Side

Exist L4 Logical side validity flag. TRUE= valid data

Feed DataMaxFeed 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 DataMaxProd 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 SetTherSetID 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


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.


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


Chapter 6 UAS Modular Fluids

Interface SoftwareThis 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.modFunction Calculation Routines See . . .

flash_Fluid Calculates the thermodynamic state of a fluid 6-3

Kcalc_Fluid Computes K-values, dK/dT, fugacity coefficients, liquid activities, and compressibility.

6-11

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.modFunction Phase Manipulation Functions See . . .

zero_FluidPhase Sets all data in one phase to zero 6-20

Data Storage Structures

TYPE FluidPhase

Secondary fluid data storage. Each phase in a fluid is stored in a separate FluidPhase

6-34


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.

OverviewFluids 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 InformationUsers 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 RequirementsThere 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 ReportsPRO/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 InformationThe 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_FluidThe 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_FluidcTypeIn 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.


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.

“PDUTY” Duty (i.e., enthalpy change) flash at specified pressure and enthalpy change.

Table 6-4: Return Codes from flash_FluidiRet 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

Table 6-3: Flash types Supported By Function flash_Fluid


Usage NotesThe 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 ModelsThe 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 TypesIn 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

-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)

Table 6-4: Return Codes from flash_FluidiRet iErr Description


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

ISO FlashAn “ISO” flash specifies both temperature and pressure. Set both tem-perature and pressure before calling flash_Fluid. For example:

FLOBJ%TEMP = 100.0FLOBJ%PRES = 15.5iRet = flash_Fluid( “ISO”, “ “, FLOBJ, iERR )

All other flash types specify either temperature or pressure, plus one other variable.

TADIA, PADIA FlashesThese 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.0iRet = 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.

orFLOBJ%PRES = 15.0iRet = 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.0FLOBJ%PRES = 15.0iRet = 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 FlashesThese 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


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

FLOBJ%DUTY = 2468531.0FLOBJ%PRES = 15.0iRet = flash_Fluid(“PDUTY”, “ “, FLOBJ, iERR)

orFLOBJ%DUTY = 2468531.0FLOBJ%TEMP = 15.0iRet = 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 FlashesSpecify 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.0iRet = flash_Fluid(“TBUB”, “ “, FLOBJ, iERR)

The calculated bubble point pressure returns in FLOBJ%PRES.or

FLOBJ%PRES = 15.0iRet = flash_Fluid(“PBUB”, “ “, FLOBJ, iERR)

Data member FLOBJ%TEMP returns the calculated bubble point temperature.

TDEW, PDEW FlashesSpecify 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.0iRet = flash_Fluid(“PDEW”, “ ”, FLOBJ, iERR)

The calculated dew point temperature returns in FLOBJ%TEMP.or

FLOBJ%TEMP = 100.0iRet = flash_Fluid(“TDEW”, “ ”, FLOBJ, iERR)


The calculated dew point pressure returns in FLOBJ%PRES.

TWDEW, PWDETThese 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.0iRet = flash_Fluid(“PWDEW”,“ ”, FLOBJ, iERR)

The calculated temperature returns in FLOBJ%TEMP.or

FLOBJ%TEMP = 100.0iRet = flash_Fluid(“TWDEW”,“ ”, FLOBJ, iERR)

The calculated pressure returns in FLOBJ%PRES.

THCDEW, PHCDEWThese 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.0iRet = flash_Fluid(“PHCDEW”, “ ”,FLOBJ,iERR)

The calculated temperature returns in FLOBJ%TEMP.or

FLOBJ%TEMP = 100.0iRet = flash_Fluid(“THCDEW”, “ ”,FLOBJ, iERR)

The calculated pressure returns in FLOBJ%PRES.

TISEN, PISEN FlashesThese 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


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.0FLOBJ%PRES = 15.0iRet = flash_Fluid(“PISEN”, “ ”,FLOBJ, iERR)

The calculated temperature is available in FLOBJ%TEMP.

orFLOBJ%ENTROPY = 97531.0FLOBJ%TEMP = 15.0iRet = flash_Fluid(“TISEN”, “ ”,FLOBJ, iERR)

The calculated pressure is available in FLOBJ%PRES.

Using Temperature and Pressure EstimatesFlash 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+0FLOBJ%PRES = 15.0D+0iRet = flash_Fluid( “ISO”, “ “, FLOBJ, iErr ). . .FLOBJ%DUTY = 1234.5D+0FLOBJ%EstTEMP = FLOBJ&TEMP + 10.0D+0FLOBJ%PRES = FLOBJ%PRES + 1.2D+0iRet = flash_Fluid( “DUTY”, “ “, FLOBJ, iErr )


Retrieving Flash ResultsAfter 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

Phase Name

Equilibrium Model

iRet = 1 iRet = 2 iRet = 3

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)


Kcalc_FluidIn 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.


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.

Retrieving ResultsAfter 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-

Table 6-6: Return Codes from Kcalc_FluidiRet 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


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_FluidSummary of Data Returned from Kcalc_Flash

Property

Phases that Return Data for Various Equilibria

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

ZKvalV

L1, L2V

L1, L2VL

VL

VL

VL

XFug( NOC )V

L1, L2V V

LV V

LV

XLact( NOC ) L1, L2 L L

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 vaporLine 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.

L = Bulk liquid, L1 = Non-decant (light) liquid sub-phase, L2 = DECANT (heavy) liquid sub-phase EOS = Equation of State, LACT = Liquid Activity method

NOC = number of components


Fluid Manipulation FunctionsThe 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_FluidThis 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.


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) :: ieStat10 !11 TYPE( FLUID ) :: myFluid ! required12 !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.


load_FluidThis 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:

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.

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

0 Success (never returned).

-1 Failure, could not load data into the fluid.


copy_FluidData 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:

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:

+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.).

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.


store_FluidUse 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.


The safest strategy for generating complete fluid properties is to flash the fluid before storing it in a PRO/II stream.

+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.


free_FluidThis 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.


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.

+1 Success, all resources successfully released.

0 Success, all resources successfully released.

-1 Failure, unspecified resources were not released.


zero_FluidPhasePurpose: 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.


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.

+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 Guidelines

Project RequirementsAny 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 RequirementsUser-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


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_FluidAfter 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.


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.


Dimensional UnitsFluids 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 ComponentsModule 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.


class_Fluid.modThis 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_FluidDirect 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%Temp10 Pres = FluidObj%Pres11 !12 IF( FluidObj%Status .GE. 1 ) THEN13 RmoleTot = FluidObj%Total%RateM14 c6MFTot = FluidObj%Total%XFracM( 6 )15 !16 IF( FluidObj%VapStatus .GE. 1 .AND. &17 FluidObj%L1Status .GE. 1 ) THEN18 c6MFVap = FluidObj%Vapor%XFracM( 6 )


19 RmoleV = FluidObj%Vapor%RateM20 Ratec6 = RmoleV * c6MFVap21 FluidObj%Vapor%XFracM( 6 ) = 0.0D+022 RmoleV = RmoleV - Ratec622 FluidObj%Vapor%RateM = RmoleV23 FluidObj%Vapor%FracM = &24 RmoleV / RmoleTot25 FluidObj%Total%RateM = &26 RmoleTot - Ratec627 END IF28 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.


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_FluidThe 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_FluidTable 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


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


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



Fluid IdentificationThe 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 DataEach 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

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 PropertiesA 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 IdentificationPRO/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.


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 MembersFluids 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.


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

Fluid NamePhases Present in a Fluid

Total Vapor Liquid L1 L2

Vapor Yes Yes - - -

Liquid Yes - Yes - -

Iface Yes Yes Yes - -

Validation FlagsFluid 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.


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

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.


class_FluidPhase.modThis 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_FluidPhaseDirect 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_FluidPhaseThe class_FluidPhase module does not implement accessor func-tions. For this reason, indirect member addressing is not supported for data in phases.


Data Structure of class_FluidPhaseTable 6-11 lists all the data members in a FluidPhase storage struc-ture.

Table 6-11: class_FluidPhase Data MembersPhase 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

SpVolMStd

DP Standard specific mole volume, vol / wt*mole

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

SpEntroWt

DP Specific weight entropy, 1000’s energy / wt

CpM DP Average Specific Heat of phase, energy / wt-mole


Fluid Phase ExampleAs 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

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

Table 6-11: class_FluidPhase Data Members


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.


Chapter 7 User-Added Units of Measure

Overview of User Dimensional UnitsAll 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 MeasurePRO/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: 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

Base Systems of Dimensional Units


Dimensional Classes in the Base System of UnitsThe 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

Class DescriptionUOM Keywords

English Metric SI PRO/II

TEMP Temperature F C K K

TDIF Temperature change

PRES Pressure PSIA KG/CM KPA KPAPDIF Pressure change PSI KG/CM KPA KPAWT Weight LB KG KG KGTIME Time HR HR HR SECLENG Length FT Meter Meter MeterFLEN Fine Length INch MM MM MeterAREA Area FT2 M2 M2 M2FAREA Fine Area IN2 MM2 MM2 M2VELO Velocity, LENG/TIME FT/S M/S M/S M/SCAKELIQV Liquid Volume FT3 M3 M3 M3VAPV Vapor Volume FT3 M3 M3 M3EQVO Equivalent Volume, LIQV/

LENGFT3/F M3/M M3/M M3/M

LDEN Liq. Density, WT/LIQV LB/FT KG/M KG/M KG/MVDEN Vap. Dens., WT/VAPV LB/FT KG/M KG/M KG/MXDEN Petro Density, WT/LIQV LB/FT KG/M KG/M KG/MSPVO Specific Volume, LIQV/WT-

moleFT3/LB M3/KG M3/KG M3/KG

ENER Energy BTU KCAL KJ KJWORK Work, ENER/TIME HP KW KW KJ/SDUTY Duty, ENER/TIME * 1.0e6 BTU/HR KC/HR KJ/HR KJ/SENTH Enthalpy, ENER/WT BTU/LB KC/KG KJ/KG KJ/KG

7-2 User-Added Units of Measure February 2009

ENTR Entropy, ENER/(WT*TEMP)

BTU/LB KC/KG KJ/KG KJ/KG

CP Heat Capacity, ENER/(WT*TEMP)


MRAT Mole Rate, (WT*mole) / TIME

LBM/HR KGM/HR KGM/HR KGM/S

WTRA Weight Rate, WT/TIME LB/HR KG/HR KG/HR KG/SLVRA Liquid Volume Rate, LIQV/

TIMEFT3/HR M3/HR M3/HR M3/S

GVRA Gas Volume Rate, VAPV/TIME

FT3/HR M3/HR M3/HR M3/S

COND Thermal Conductivity BTU/HR KC/HR W/MK W/MKVISC Viscosity CP CP PAS PASKINE Kinematic Viscosity CST CST CST CSTSURF Surface Tension D/CM D/CM N/M N/M

HTCO Heat Transfer, ENER/(TIME*AREA*TEMP)

BTU/HR KC/HR KW/MK KW/MK

FOUL Fouling Coefficient HFF/B HMC/K MK/KW MK/KWUA U*A value, ENER/

(TIME*TEMP)BTU/HF KC/HC KW/K KW/K

SPHT Specific Heat, ENER/(WT*TEMP)


FRAC Fraction FRAC FRAC FRAC FRACPCT Percentage PCT PCT PCT PCTPPM Parts per million PPM PPM PPM PPMANGL Angle RAD RAD RAD RADDIPO Dipole Moment DEB DEB DEB DEBHVAL Heating Value, ENER/

VAPVBTU/FT3 KC/M3 KJ/M3 KJ/M3

RUA Radial U*A coefficient

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

Class DescriptionUOM Keywords

English Metric SI PRO/II


UAUTIL User DimensionsPRO/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.


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 DimensionsUser-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 UAUOPEach 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.


Definition of class_DMUOM.modThis 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_DMUOMThe 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”.


“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:


“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.

ExamplesThe 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-1Subroutine 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”, &


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

END IFEnd 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.


Chapter 8 UAUOP AutoGUI

OverviewEach 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 ChapterTo 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”


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 StructureTable 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">  </Spec>

<Spec Name="Tab 2 name" Type="Normal" UseNewSchema="1">  </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 OperationThe 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 UAUOPFile 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.


XML Schema ReferenceThe 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

XML Element

Attribute of XML

Element Child Elements of

XML Element

Text Valueof Element

or Attribute<SpecList> None

Name= (R) “String”

<Spec> (1 or more) None

<Spec> None


Type= (R) “Normal”

<Group> (0 or more) None

<Parameter> (0 or more)

None

<Variable> (0 or more)

None


<Constraint> (0 or more)

None

<Group> None


Type= (R) “Normal”,“Weak”,“Strong”

<Count> (0 or 1) Integer

<Desc> (0 or 1) String

<ShowTitleHeader> (0 or 1)

String or false

<NoLabel> (0 or 1)

true or false

<Group> (0 or more) None

<Parameter> (0 or more)

None

<Variable> (0 or more)

None

<Constraint> (0 or more)

None


XML Element

Attribute of XML


XML Element


or Attribute


<Parameter> None


Type= (R) “Choice”, “Option”, “Selection”“Real”, “Integer”, “String”


<ValueDomain>(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


<CreateSideBySide> (0 or 1)

True or false

<ToolTip> (0 or 1) String


String or “false”

<Variable> None



<ReadOnly> (0 or 1) True or false

<Required> (0 or 1) Req or opt or none

<NoLabel> (0 or 1) True or false



True or false


XML Element

Attribute of XML


XML Element


or Attribute


<Variable> <MilanoAttribute> (0 or 1)

I orL


String or false

<ToolTip> (0 or 1) String

<Value> None


Type= “Real”, “Integer”, “String”


<DependentGroup> (0 or more)

“Name” of Group element

<Constraint> None

<Desc> (exactly 1) String


True or false

<Image> None

Name= (R) String

<FileName> (exactly 1)

String

<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


XML Element

Attribute of XML


XML Element


or Attribute


Notes

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

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

CountThe <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.

CreateSideBySideThe <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.

<Required> Req oropt ornone

<ShowTitleHeader> String or false

<ToolTip> String

<ValueDomain> String

<SpecList> None


<Spec> (1 or more) None


XML Element

Attribute of XML


XML Element


or Attribute


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

DependentGroupThe <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.

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

GroupThe <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.


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.

ImageThe <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.

MilanoAttributeThe <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.


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

NoLabelThe <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.

ParameterThe <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.


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.

ReadOnlyThe <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.

RequiredThe <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.

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


SpecEach <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.

SpecListThe <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.

ToolTipThe <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.

ValueOne 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.


ValueDomainThe <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.

VariableThe <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 NamesAutoGUI 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.


Table 8-4: AutoGUI XML Access to PRO/II UAUOP AttributesName= 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]”

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


AutoGUI ExamplesThis 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 FieldsThis 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>


</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.

ResultThe resulting AutoGUI display is shown in Figure 8-2.

Figure 8-2: Example 1 AutoGUI Display


Example 2: Display Vector Edit FieldsThis 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>


ResultThe 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.


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.


Example 3: Display Check box, Radio Button, List Box ControlsThis 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>


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

ResultFigure 8-5: AutoGUI Tab of Example 3

Example 4: Implementing automated interactionsThis 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">


<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">


<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.

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


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.


Example 5: Assigning Thermodynamic METHOD Sets to SidesThis 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.)


ResultFigure 8-9: AutoGUI Tab of Example 5


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 StructureThe structure of an Icon data file is shown in Table 9-1.

Table 9-1: Basic Structure of an Icon Data FileGROUP 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.


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 OperationThe 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 UAUOPFile name Location DescriptionmyUaUop.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.xmlSpecifically,

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 ReferenceThe 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.


Statements

GROUP StatementThe 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 StatementEach 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.


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 StatementThis 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.


Shape StatementsShape 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 CodesValue Color Value Color Value Color

Default Brown Magenta

Black Light Gray Yellow

Blue Dark Gray White

Green Light Blue Light Yellow

Cyan Light Green Dark White

Red Cyan

Magenta Light Red

<fill> Fill flag, -1 for default. See Table 9-5, ”Fill Style Codes”.

Table 9-5: Fill Style CodesValue 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”.

-1 6 130 7 141 8 152 9 163 10 174 115 12


Table 9-6: Line Style CodesValue Line Style

DefaultSolidDashDashDotDashDotDotDot

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

-10123

4

Shape DefinitionDATA

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 arrow line.

x1, y1, x2, y2,... The line has an arrow at the end of each segment. See LINE

RLI Repeating line

x1, y1, x2, y2, dx, dy, number

The first four values give the 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


PORT statementThe 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.

RECT Rectangle xmin, ymin, xmax, ymax

Automatically closed shape

ELLIPSE Ellipse xc, yc, xr, yr Automatically closed shape

CIRCLE Circle xc, yc, radius Automatically closed shape

ARC Arc xc, yc, xr, yr, angle1, angle2

Elliptic arc, angles are 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.


PLINThe 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 PLINDATA <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


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 StatementThe BEGOUTLINE statement defines the start of an arbitrary enclosed region.

BEGOUTLINE


The statement has no arguments.

ENDOUTLINE StatementThe 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 ExamplesThe following sections contain various icon examples.

Example 1: Box icon, two point ports, feed on the leftDemonstrates 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 = 1SIDE 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 110 PORT 102 -1 0 -1 -1 -1 "PRODID" "Product Port"11 DATA 0 1 0 0 0 0 0 0 0 0 1 1 012 DATA 10 113 ID -1 -1 -1 -1 -1 -114 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


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).

ResultThe 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 feedsThis 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 = 1SIDE 1 Side_1 1 1 1 1


.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 110 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 012 DATA 10 113 ID -1 -1 -1 -1 -1 -114 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.

ResultFigure 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


Example 3: Two ports, multiple feeds, one productThis example demonstrates multiple feeds to a single port. The basic icon still is the simple box of example 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 110 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 012 DATA 10 113 ID -1 -1 -1 -1 -1 -114 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.

ResultIn 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


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 portsOnce 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.


.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 010 DATA 0 0 0 211 LINE -1 -1 -1 -1 -1 -112 DATA 0 2 10 213 PLIN 102 -1 0 -1 -1 -1 "PRODID" "Product Port"14 DATA 0 1 0 0 0 1 0 0 0 0 1 1 015 DATA 10 2 10 016 ENDOUTLINE -1 -1 -1 -1 -1 -117 ID -1 -1 -1 -1 -1 -118 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.

ResultThe 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.


Figure 9-4: Example 4 - Line Ports

Example 5: More complex icon, two line portsThis demonstrates the statements required to create a more complex shape. This example also uses line ports.


.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 010 DATA 0 2 0 1011 ARC -1 -1 -1 -1 -1 -112 DATA 5 10 5 2 180 013 PLIN 102 -1 0 -1 -1 -1 "PRODID" "Product"14 DATA 0 1 0 0 0 1 0 0 0 0 1 1 015 DATA 10 10 10 216 ENDOUTLINE -1 -1 -1 -1 -1 -117 LINE -1 -1 -1 -1 -1 -118 DATA 0 2 10 219 LINE -1 -1 -1 -1 -1 -120 DATA 0 10 10 1021 ID -1 -1 -1 -1 -1 -122 DATA 5 14

The BEGOUTLINE/ENDOUTLINE construct (from line 5 to 16) defines the enclosed area. The drawing starts at the upper right,


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.

ResultFigure 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 operationThis demonstrates the specification required for a two-sided unit operation.

.ini fileMAXSides = 2SIDE 1 Side_1 1 1 1 1SIDE 2 Side_2 1 1 1 1

.dat file 1 // Two sides, point ports 2 GROUP 420001 "IconEx6" "UaUOP" 1 "ICONEXAMPLE06"


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 110 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 012 DATA 10 113 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 015 DATA 0 316 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 018 DATA 10 319 ID -1 -1 -1 -1 -1 -120 DATA 11 5

The <side> value is set to 1 or 2 depending on the side to which the feed/product will be associated.

ResultFigure 9-6: Example 6 - Two-sided Icon

abc


Chapter 10 UAUOP INI File

OverviewEach 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 UAUOPSection 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=librarynameROUTINENAME=routinenameUATYPE=uoptype

Recommended Statements

PATH=%P2Install%SYSTEMPROTOCOL=DLL SYNTAX=FORTRAN { CPP | VB }

Optional Statements

ICON=iconfilenameDESC=description

Unsupported Statements (Do not apply to UAUOP)Conditional for COM, DCOM, etc.


CLASS=classidPROGID=identifier

Side Data Summary[Sides] (Required)

MAXSIDES = nsidesSIDE 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 = nmaxTOTINT = ntotMAXPAR = nmaxTOTPAR = ntotMAXDBL = nmaxTOTDBL = ntotMAXTEX = nmaxTOTTEX = ntotINT idno idname isize intclass idefault ilo ihiPAR idno idname isize uomclass vdefault vlo vhiDBL idno idname isize uomclass vdefault vlo vhiTEXT idno idname isize maxchar iminname

10-2 UAUOP INI File February 2009

Input Description

Access Data SectionInformation 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 StatementDLLNAME=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 StatementROUTINENAME=routinename


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 StatementUATYPE=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 StatementPATH=%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


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 StatementPROTOCOL=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 StatementSYNTAX=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 StatementICON=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


an optional AutoGUI data entry window, the ICON statement should be omitted.

DESCRIPTION StatementDESC=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=classidNot 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=identifierNot 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 SectionThe “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]


MAXSIDES StatementMAXSIDES =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.


SIDE StatementsSIDE 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 SectionData 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


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]


BASE System StatementBASE = 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 Statementsclasskw = 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 = EnglishTEMP = KTIME = MIN

The BASE statement sets the basic system of units to English, which normally expects temperatures in Fahrenheit and time in


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 SectionThis 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]


Storage Allocation StatementsThe 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.


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


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 StatementsINT idno idname isize intclass idefault ilo ihiPAR idno idname isize uomclass vdefault vlo vhiDBL idno idname isize uomclass vdefault vlo vhiTEXT 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 MyABCINT 2 MyABC

is invalid because the same ID name is assigned to two INT variables. In contrast,

INT 1 MyABCPAR 1 MyABCDBL 1 MyABCTEXT 1 MyABC


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


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 DefinitionAssume the UAUOP has the following data requirements:

Variable ID No

Variable ID Name

Element (Size)

UOM Class/Unit Default Lower

BoundUpper Bound

INT INT1 MyInt1 1 n/a 11 1 15

2 IntArray1 3 n/a None -15 +15

3 MyInt3 1 n/a None None None

PAR PAR1 TempIn 1 Temperature

, F70 32 212

2 TempOut 1 Temperature, F

none 70 212

3 PresIn 1 Pressure, psia

14.6959 1.0 50.0

PresOut 1 Pressure, psia

none 14.0 50.0

DBL DBL1 Xval 3 Duty, Watt 0.0 None None

2 Yval 3 Surf. Tens, N/m

None None None

3 CalcOut 3 n/a none None None

TEXT TEXT Element maxchar minnam1 Mytext1 3 12 7 n/a n/a

2 MyText2 1 16 7


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 variablesTOTINT = 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 variablesTOTPAR = 4 ;; Total words of PAR storage (4 scalars)

MAXDBL = 3 ;; Allow 3 DBL variablesTOTDBL = 9 ;; Total words of DBL storage (3 arrays of

;; 3 elements in each arrayMAXTEX = 2 ;; Allow 2 TEXT variablesTOTTEX = 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 followsINT 1 “MyInt1” 1 ~ 11 1 15INT 2 “IntArray1” 3 ~ -2111111111 -15 15INT 2 “MyInt3” 1 ~ -2111111111 -2111111111 -2111111111

PAR 1 “TempIn” 1 TEMP 70.0 32.0 212.0PAR 2 “TempOut” 1 TEMP -1.5E35 70.0 212.0PAR 3 “PresIn 1 PRES 14.6959 1.0 50.0PAR 4 “PresOut” 1 PRES -1.5E35 14.0 50.0

DBL 1 “Xval” 3 DUTY 0.0 -1.5E35 -1.5E35DBL 2 “Yval” 3 -1.5E35 -1.5E35 -1.5E35DBL 3 “CalcOut” 3 ~ -1.5E35 -1.5E35 -1.5E35

TEXT 1 “Mytext1” 3 12 7TEXT 2 “MyTEXT2” 1 16 7


INI File Usage Information

PRO/II RequirementsEach 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 ConventionsBy convention, the name of the initialization file for a user-added unit operation has the form:

uauopname.INIWhere:

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 SyntaxThe 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.


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 SensitivityMost 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 MarksA 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


included as part of the text. Avoid using them in other situations, such as in data names or directory paths.

DelimitersOne 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.

PlaceholdersEvery 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 NamesThe 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.


Chapter 11 Interfacial Area Utility

OverviewThe 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 - DevelopersWhen 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.


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 MembersMember Type Description Keyword

Module DataUasType 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 DataThermoFl 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

iContext I4 Integer version of context1 "INPUT" process input2 "CROSSCHECK”3 "CALCULATION"4 "OPCALC" post

convergence5 "REPORT"

Phase I4 Phase of interest0 = Phase is not applicable

to the calculations1 = 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 DataNOC I4 Total number of

components in problem

CompIndex(i) I4 Internal component numbers, in input order, i = 1, NOC

Fluid DataValidFlVapor 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 DataIS1(1) I4 Column type flag

1 = packing 2 = traysCOLTYPE



DS1(1) DP Cross-sectional area of stage, area.

XAREA

DS1(2) DP Weir height, length HTWIER

DS1(3) DP Downcomer area, area AREADC

DS1(4) DP Flow path length, length LENGFL

Packing DataIS1(2) I4 Packing type (use only with

IS1(3), packing arrangement, below)

PTYPE

IS1(3) I4 Packing arrangement 1 = random 2 = structured

PARRANGE

IS1(4) I4 Packed stage number PSECTION

DS1(5) DP Packed section diameter, fine length

PDIAM

DS1(6) DP Packed section height, length

PHEI

DS1(7) DP Size of packing, fine length.

PSIZE

DS1(8) DP Packing specific area, area. PSPAR

DS1(9) DP Packing critical surface tension, SurfTens

PSURC

DS1(10) DP Packing factor, 1/length. PFAC

Tray DataIS1(6) I4 Tray type

1 = bubble cap2 = valve3 = sieve

TTYPE

IS1(8) I4 Stage number of stage with trays

TRAYNO

IS1(10) I4 Number of passes per tray, currently always 1

TPASS

DS1(11) DP Tray diameter, fine length TDIAM

DS1(12) DP Tray height, fine length THEI



DS1(13) DP Active tray area. The dimensional class is fine area

TACTA

DS1(14) DP Number of trays in section, dimensionless

NTRAY

Output Data to ReturnResults(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 place1 = solved (expected value)2 = errors encountered, but reasonable

results returned3 = 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 entryC 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.



Module Data, General Data, Component DataThese 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 DataThe 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-FlVapor

Valid FlLiquid

ValidFlIface

These are validation flags for the available flu-ids. Each flag normally has a value of 1 (.True.) indicating that the fluid data structure contains valid data. A value of 0 indicates the fluid and its data are not available.


Stage DataThis 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 DataThis 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.


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 )


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 Rings (plastic)

Structured M250Y

IS1(1) Column Stage Type 1 1

IS1(2) Packing Type I 5 5

IS1(3) Packing Arrangement

1 2

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.


Tray DataThis 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.


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.)


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).


Sample Interfacial Area UtilitySample 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.


Chapter 12 Binary Mass Transfer Utility

OverviewThe 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.


Available Mass Transfer Data - DevelopersWhen 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 MembersMember Type Description KeywordModule DataUasType C 12 Always "UAMASSTR"




General DataThermoFl I4 Thermodynamic method

set flag (not currently supported)

DiagnosticFl I4 Diagnostic flag (not currently supported)


12-2 Binary Mass Transfer Utility February 2009

Context C 12 Context flag "INPUT" process input"CROSSCHECK""CALCULATION""OPCALC" post

convergence"REPORT"

iContext I4 Integer version of context1 "INPUT" process input2 "CROSSCHECK"3 "CALCULATION"4 "OPCALC" post


Phase I4 Phase of interest1 = Vapor2 = Liquid





CompIndex(i) I4 Internal component numbers, in input order, I = 1, NOC

DA2(i,j) DP Binary diffusion coefficients. i = 1 to NOC, j = 1 to NOC. The dimensional units are area/time.

DIFFCO

Fluid DataValidFlVapor I4 1 = valid Vapor fluid from

PRO/II

ValidFlLiquid I4 1 = valid Liquid fluid from PRO/II

FlVapor Fluid Vapor phase fluid data object

Member Type Description Keyword


FlLiquid Fluid Liquid phase fluid data object

Stage DataIS1(1) I4 Column type flag

1 = packing 2 = traysCOLTYPE

DS1(1) DP Cross-sectional area of stage. The dimensional class is area.

XAREA

DS1(2) DP Weir height, length HTWIER

DS1(3) DP Downcomer area. The dimensional class is area.

AREADC

DS1(4) DP Flow path length, length LENGFL

DS1(15) DP Interfacial area (total). The dimensional class is area.

IFAREA

Packing DataIS1(2) I4 Packing type (use only

with IS1(3), packing arrangement, below)

PTYPE


PARRANGE


DS1(5) DP Packed section diameter. The dimensional class is fine length

PDIAM

DS1(6) DP Packed section height. The dimensional class is length.

PHEI

DS1(7) DP Size of packing. The dimensional class is fine length.

PSIZE

DS1(8) DP Packing specific area. The dimensional class is area.

PSPAR

DS1(9) DP Packing critical surface tension. The dimensional class is surface tension.

PSURC

DS1(10) DP Packing factor. The dimensional units are 1/length.

PFAC



Tray DataIS1(6) I4 Tray type:

1 = bubble cap2 = valve 3 = sieve

TTYPE

IS1(8) I4 Stage number TRAYNO


TPASS

DS1(11) DP Tray diameter, fine length TDIAM

DS1(12) DP Tray height. The dimensional class is fine length

THEI

DS1(13) DP Active tray area. The dimensional class is fine area

TACTA


NTRAY

Output Data to ReturnResults(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 place1 = solved (expected value)2 = errors encountered, but reasonable

results returned3 = 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.)




Module Data, General DataThese 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 DataFor 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

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.



Fluid DataThe 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

ValidFlLiquid

ValidFlIface

These are validation flags for the available fluids. Each flag normally has a value of 1 (.True.) indicating that the fluid data structure contains valid data. A value of 0 indicates the fluid and its data are not available.

Stage DataThis 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.



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.

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.)






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 )


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.

Data Member

Packing TypeRandom Pall Rings (plastic)

Structured M250Y



IS1(3) Packing Arrange-ment

1 2

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.


Tray DataThis 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(6) The type of tray on the stage.

1 = bubble cap tray

2 = valve tray

3 = sieve tray


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.


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.


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 UtilitySample 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:


..\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


Chapter 13 Heat Transfer Utility

OverviewPRO/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.


Available Heat Transfer Data - DevelopersWhen 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 MembersMember Type Description Keyword

Module Data

UasType C 12 Always "UAHEATTR"




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


Context C 12 Context flag "INPUT" process input "CROSSCHECK" "CALCULATION" "OPCALC" post convergence "REPORT"

iContext I4 Integer version of context1 "INPUT" process input2 "CROSSCHECK”3 "CALCULATION"4 "OPCALC" post


Phase I4 Phase of interest1 = Vapor 2 = Liquid





CompIndex(i) I4 Internal component numbers, in input order, I = 1, NOC

DA2(i,j) DP Binary diffusion coefficients. i = 1 to NOC, j = 1 to NOC. The dimensional units are area/time.

DIFFCO



DA3(i,j) DP Binary mass transfer coeffs.

i = 1 to NOC, j = 1 to NOC. Dimensional

units are wt-moles/time.

MASSCO

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 on the stage. The dimensional class is viscosity.

HTWIER

DS1(17) DP Average density of fluid on the stage. The dimensional class is density.

AREADC

DS1(18) DP Average heat capacity (Cp) of fluid on the stage. The dimensional class is Cp.

LENGFL

DS1(19) DP Average thermal conductivity of fluid on the stage. The dimensional class is ThermCond.

IFAREA

Stage Data

IS1(1) I4 Column type flag1 = packing2 = trays

COLTYPE

Packing Data

IS1(2) I4 Packing type (use only with IS1(3), packing arrangement, below)

PTYPE


PARRANGE


Tray Data

IS1(6) I4 Tray type1 = bubble cap2 = valve3 = sieve

TTYPE



IS1(8) I4 Stage number of stage with trays

TRAYNO


TPASS


NTRAY

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 place1 = solved (expected value)2 = errors encountered, but reasonable results returned3 = 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 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 DataThese 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 DataFor 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 DataThe 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.


Stage DataThis 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.


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) 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.


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 Rings (plastic)

Structured M250Y



IS1(3) Packing Arrangement 1 2


Tray DataThis 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(6) The type of tray on the stage.1 = bubble cap tray2 = valve tray3 = sieve tray


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.


Sample Heat Transfer Coefficient UtilitySample 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.


Chapter 14 Classic UAS Introduction

PRO/II User-Added SubroutinesThe 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 InterfaceThe calculation methods that may be incorporated with this inter-face include:

User-Added Thermodynamic MethodsUser-Added Transport Property Methods

RATEFRAC Transport Calculation MethodsUser-Added Unit Operations (classic and modular)User-Added Reaction KineticsUser-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-


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 LinkersDevelopers 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 UASPRO/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.


Program LimitsAlthough 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 LimitationsCalculation/Model Component/Variable

Maximum

Classic User-Added Calculations1

2500 Components in Flowsheet

Classic User-Added Unit Operations

IPARM (250) RPARM (500) HEAT (10) SUPPLE (10000)

User-Added Kinetic Models 50 Components in Flowsheet IPARM (10) RPARM (70) SUPPLE (200)

Modular User-Added Calculations

Dynamic allocation, no fixed limits.

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.

1) Except user-added kinetics


Upgrading Legacy User-Added SubroutinesStarting 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 BlocksNote: 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.


Replacement Source CodeImportant: 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 UASThis 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 CompilerBegin 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.


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\*


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 WindowTo 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.


Fortran Coding StandardsAll 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.


Fortran Programming GuidelinesThe 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.


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)


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.


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.


Table 15-1: Interface Subroutines


Output and Reporting 15-7

HEAD Heads and numbers output page 15-7

UAERR Reports an error, warning, or message to PRO/II. Also formats and writes a message.

15-7

PAWRITE PDTS subroutine that writes a single line of pre-formatted text to any logical file unit.

15-9

FIGETU Retrieves a logical file unit that does not conflict with other PRO/II file usage.

15-48

Streams and Stream Data 15-10

URXINF Retrieves 12-character stream and unit IDs and 40-character names.

15-12

GETBLNAM Returns the name of the blend from a stream-containing assay components.

15-13

DURXST Reads or stores data from a double precision classic stream vector

15-14

URXSTR Single precision version of DURXST 15-14

DURXSTR Retrieves and stores double precision stream data. Similar to DURXST.

15-15

USTHER Sets the current thermodynamic method to that of a given PRO/II stream. Resets component properties in common XPROPY.

20-5

DUSTPRP Retrieves a double precision property from a PRO/II stream, one scalar per call.

20-6

USTPRP Single precision version of DUSTPRP. 20-6

DUSTRIP Retrieves any scalar Refinery Inspection Property from a PRO/II stream.

20-7

USTRIP Single precision version of DUSTRIP. 20-7

DUCURVE Computes pseudo-component properties for current thermodynamic methods set. (2 data points required).

20-15

UCURVE Single precision version of UCURVE. 20-15

DUBULK Double precision analog of UCURVE, when only a single data point is available.

20-19

15-2 UAS Interfaces February 2009

UBULK Single precision version of DUBULK. 20-19

DUDIST Generates a 21 point distillation cut-point array. Double precision.

20-9

UDIST Single precision version of UDIST. 20-9

DUPSEUC Retrieves start and end components, and all double precision cut-point temperatures from a blend.

20-4

UPSEUC Single precision version of DUPSEUC. 20-4

DURATE Retrieves double precision pseudo-component flow rates from TBP distillation data.

20-12

URATE Single precision version of DURATE. 20-12

UPETMD Estimates missing component fixed properties. Updates /XPROPY/ data. Single precision.

20-22

Calculation Interfaces 15-16

DFLASH Double precision interface for flash calculations. Calls DU2FLSH for VLE and DU3FLSH for VLLE thermodynamics.

15-16

XFLASH Single precision interface for flash calculations. Calls UFLSH for VLE and U3FLSH for VLLE thermodynamics.

15-16

DU2FLSH Perform 2-phase (VLE) flashes (no solids) 15-19

UFLSH Single Precision version of DU2FLSH. 15-22

DU3FLSH Perform rigorous 3-phase flash calculations

15-25

U3FLSH Single Precision version of DU3FLSH. 15-27

DTTPROP Computes double precision transport and thermodynamic properties of a standard user stream.

15-29

TTPROP Single precision version of DTTPROP. 15-29

DUHS Compute density, enthalpy, heat capacity, or entropy for a single stream phase.

15-31

UHS Compute density, enthalpy, heat capacity, or entropy for stream.

15-31

DUH2OP Compute double precision water properties 15-33




UH2OP Single precision version of DUH2OP. 15-33

DUDENS Compute double precision wet and dry flowing volumes for streams.

15-35

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 standard user streams for use in user flash.

15-39

HCOMPU Single precision version of DHCOMPU. 15-39

Solids Handling 21-1

USOLSTR Retrieves and stores streams containing solids.

21-3

UFLSHSOL Performs vapor/liquid flash for streams with solids. May be used in place of UFLSH and U3FLSH

21-5

USOLDENS Calculates the solid stream density 21-8

UHSSOLID Calculates solid molar heat capacity, molar enthalpy, and molar entropy

21-9

USOLCDAT Retrieves pure solid component heat of fusion, normal melting point temperature, triple point temperature, or triple point pressure.

21-10

GETPSDC Retrieves the number of Particle Size Distribution (PSD) cuts for any single component.

21-11

USOLPSD Retrieves or stores the Particle Size Distribution data

21-11

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 number.

15-43

COPNUM Retrieves a component’s input (print)-sequence number - given the internal sequence number.

15-42

GETNCOMP Retrieves various component counts (for solids problems).

21-2




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.

UDEFNC Retrieves a component’s input (print) or internal sequence number - given the ID and Library number.

20-3

CONAME Retrieves the ID of a component - given the internal sequence number of the component.

15-43

UCOPRP Retrieve many component properties, including most refinery inspection properties.

15-44

DZMolWt Retrieve or store a double precision array of component molecular weights.

15-46

ZMW2 Single precision version of DZMolWt 15-46

DZSg60 Retrieve or store a double precision array of component specific gravities at 60F.

15-47

ZSG602 Single precision version of DZSg60. 15-47




Table 15-2: Interface Common Blocks

Name Description page...

Common Blocks/PMXUSR/ Contains integer parameter MAXCN, which

is required to dimension arrays in other common blocks.

15-49

/DFACTOR/ Double precision conversion factors for dimensional units.

15-50

/FACTOR/ Single precision version of DFACTOR. 15-50

/DOUTFAC Double precision output conversion factors and dimensions, component names.

15-52

/OUTFAC/ Single precision version of DUOTFAC. 15-52

/DUTHERX/ Transfers double-precision data between user thermodynamic functions and PRO/II

15-55

/UTHERX/ Transfers double-precision data between user thermodynamic functions and PRO/II

15-55

/DXPROPX/ Pure component data - invariant 15-56/XPROPX/ Single precision version of /DXPROPX/ -

invariant.15-56

/XPROPY/ Single precision pure component data - may change for each thermodynamic methods set.

20-23

/DCUDATA/ Double precision storage, transfers user-defined input data between PRO/II and user thermodynamic routines (UKHSx)/

15-58

/CUDATA/ Single precision version of DCUDATA. 15-58

/CSPEC/ Single precision storage of isentropic flash specification.

15-58

Note: Storage of user-calculated data is permissible only in common blocks /DCUDATA/, /CUDATA/, /UTHERX/, and /XPROPY/.


Output and Reporting Routines

HEADThis 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

UAERRPurpose: 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.


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


PAWRITEThis 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, IvalREAL(8) :: RvalCHARACTER(LEN=133) :: cLine. . .Rval = 23.4Ival = 3cLIne = “The value of RVAL( ) is :”WRITE( cline(19,21), “( I3 )” ) IvalWRITE( cLine(29:39), “(F9.4)” ) RvalCALL PAWRITE( LFU, TRIM(cLine) )

The single line of output would be:

The value of RVAL( 3) is : 23.4000


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 VectorThe 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 rate2 Temperature in input units of temperature3 Pressure in input units of pressure4 Total enthalpy in 103 input energy units per time5 Total liquid mole fraction including liquid water6 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/II11-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


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.CMNREAL(8) :: DStrVec( MAXCN + 10 )REAL(4) :: StrVec( MAXCN + 10 )

Internal Data ArrayThese 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.CMNREAL(8) :: DIntArray( MAXCN )REAL(4) :: SIntArray( MAXCN )

External Data ArrayThese 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.CMNREAL(8) :: DExtArray( MAXCN )REAL(4) :: SExtArray( MAXCN )

The following chapter sections describe the stream data interface routines, many of which use these array constructs.


URXINFThis 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.


GETBLNAMThis 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.


DURXST double precisionURXSTR 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).

DStrVecSStrVec

Double precision user stream vector used by DURXSTSingle precision user stream vector used by URXSTRContains 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 errors1 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).


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 precisionCalling 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/secondTemperature KelvinsPressures kilo-PascalsEnthalpies kilo-Joules/secondComponent 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.


Flash Calculation Interfaces

DFLASH double precision

XFLASH single precisionBoth 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:

DFLASH calls DU3FLSH DU2FLSHXFLASH calls U3FLSH UFLSH

Calculation Routines Used by DFLASH and XFLASH

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.

Interface Routine

Calculation Routine Used For

VLLE Thermo VLE Thermo


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:

STRMINor STRM

Input STRMIN is a double precision and STRM is a single 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(DFLASH only)

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. 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.


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 errors1 Flash convergence failure2 ITYPE invalid, not in range 1-73 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.


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)


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.


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.

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 errors1 Flash convergence failure2 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.


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)) * SVCALL 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


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)


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

10 or 110 Water dew point (T defined, P calculated)11 or 111 Water dew point (P defined, T calculated)


IERR The error flag:0 No errors1 Flash convergence failure2 ITYPE is not in range 1-113 The flowrate of STREAM is zero


Note: IERR should be checked after each calculation and appropri-ate action taken.


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


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.


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.

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 errors1 Flash convergence failure2 ITYPE invalid, not in range 1-73 The flow rate in SStVecIn( 1 ) is zero or negative



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).


Note: For dew point flashes (types 4 and 5), this flash method is the same as UFLSH since, by definition, no liquids can exist.

This routine does not support any isentropic flashes.

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 errors1 Flash convergence failure2 ITYPE invalid, not in range 1-73 The flow rate in SStVecIn( 1 ) is zero or negative



Property Calculation Interfaces

DTTPROP double precision

TTPROP single precisionCall this subroutine to calculate any of the following properties:

Pure component vapor pressures in input units.Pure component molar ideal gas enthalpies (Hi

*) (103 energy units per mole).Transport properties for a single phase of a stream in input units.

Data from the stream for which properties are desired is loaded into a standard user stream vector and passed as an argument to DTTPROP. (See “User Stream Vector” on page 15-10)

Calling sequence:


CALL DTTPROP( ITYPE, IPHASE, DPrOut, & DStVecIn, IERR )


CALL TTPROP( ITYPE, IPHASE, SPrOut, & SStVecIn, IERR )

Where:

ITYPE Integer input flag for desired property:1 Vapor pressures of pure components2 Ideal gas enthalpies of pure components3 Transport properties of requested phase (5 max)4 Thermal conductivity of requested phase5 Viscosity of requested phase6 Surface tension of liquid, only when IPHASE=2

IPHASE Integer input flag for Stream phase of interest:1 Vapor phase2 Liquid phase

DPrOutorSPrOut

Returned floating point array that returns the calculated properties. DPrOut is a double precision local array, and SPrOut is a single precision local array. The minimum dimension of this array depends on the value of ITYPE.

ITYPE Size of DPrOut (or SPrOut) 1 or 2 NOC 3, 4, 5, or 6 5


ITYPE = 1 returns NOC values of pure component vapor pressures in PRO/II internal component order (input pressure units).

ITYPE = 2 returns NOC values of ideal gas enthalpy values in PRO/II internal component order.

ITYPE = 3-6 use the first five positions of DPROPS, based on IPHASE and ITYPE, as shown.

IPHASE=2 (liquid)PROP(1) Liquid surface tension (ITYPE=3 or 6)PROP(2) Liquid viscosity (ITYPE=3 or 5) PROP(3) Liquid thermal conductivity (ITYPE=3 or 4)

IPHASE=1 (vapor)PROP(4) Vapor viscosity (ITYPE=3 or 5)PROP(5) Vapor thermal conductivity (ITYPE=3 or 4)

DStVecInorSStVecIn

DStVecIn is a double precision and SStVecIn is a single precision input standard user stream vector containing data from the stream of interest. See “User Stream Vector” on page 15-10 All values are in problem input dimensional units. Component rate values are in PRO/II internal order.

IERR Returned integer error condition flag:0 No errors1 IPHASE not equal to 1 or 22 ITYPE not in the range 1-63 Flowrate of stream is zero4 Property requested is not available

The error flag should be tested after each call to DTTPROP or TTPROP.

Note: All result values return in problem input dimensional units. Also, the thermodynamic METHOD set used by TTPROP must declare methods for computing transport properties.

Note: To request vapor pressures when assay fractions are present, a KVALUE= LIBRARY method (need not be used) should be used to insure setup of vapor pressure data for PETROLEUM components.


DUHS double precision

UHS single precisionThese routines compute the enthalpy, entropy, molar heat capacity, or compressibility for a single specified phase of a stream. When the stream is known to be single phase, these routines may be called to compute a property for the bulk stream. Separate calls should be made for each phase of a mixed-phase stream. Data for the stream phase is loaded into a standard user stream vector (See “User Stream Vector” on page 15-10) All data values are transferred using problem input dimensional units.

Calling sequence:

CALL DUHS( ITYPE, IPHASE, DStVecIn, DValOut, & DCpOut, IERR )

CALL UHS( ITYPE, IPHASE, SStVecIn, SValOut, & SCpOut, IERR )

Where:

ITYPE Input integer flag for property requested:1 Enthalpy and/or heat capacity2 Entropy3 Compressibility factor on a dry basis

calculated from the density method(s) declared on the METHODS statement.

IPHASE Input integer indicating phase of interest:1 Vapor2 Liquid

DStVecInor SStVecIn

Input standard user stream vector that transfers data for one stream phase. See “User Stream Vector” on page 15-10 Data is in dimensional units used for problem input. DStVecIn is double precision and SStVecIn is single precision.

DValOutorSValOut

Scalar floating point variable that returns the property requested. DValOut is double precision and SValOut is single precision. Enthalpies are reported in 103 energy units per time. Entropy is reported as energy per time per temperature using dimensional units defined for problem input.


Compressibility factors are always on a dry basis. An alternative method for calculating densities is to use subroutine DUDENS or UDENS. Those routines calculate both the wet and dry actual volume of a stream.

The error flag should be examined and appropriate action taken after each call to UHS.

DCpOutorSCpOut

A floating point scalar that returns stream molar heat capacity (specific heat) when ITYPE = 1. DCpOut is double precision while SCpOut is single precision. The value is reported as energy per mole per temperature degree using dimensional units defined for problem input.

IERR Error flag:0 No errors1 IPHASE not specified as 1 or 22 ITYPE not in range 1-33 Enthalpy/entropy calculation failed4 Compressibility factor calculation failed5 At least one of the following has been

detected: negative stream flow rate, temperature or pressure out of bounds, or a negative component molar flow rate.


DUH2OP double precision

UH2OP single precisionThese subroutines determine properties for water, either as liquid or vapor. Each call returns one specified property of water. All data in the arguments use the dimensional units declared for problem input data. While the arguments to routine UH2OP are single precision, all internal calculations are performed in double precision.

Calling sequence:

CALL DUH2OP( ITYPE, IPHASE, TempInD, & PresInD, DDum, & ValOutD, dVdTOutD )

CALL UH2OP( ITYPE, IPHASE, TempInS, & PresInS, SDum, & ValOutS, dVdTOutS )

Where:

ITYPE Integer input flag for property requested:1 Vapor volume (vapor volume units per mole)2 Enthalpy (thousands of energy units per mole)3 Entropy (energy units per mole per degree of

temperature)4 Saturation pressure (in input units of pressure)5 Saturation temperature (input temperature units)6 Liquid volume (liquid volume units per mole)

All properties are on a molar basis in the dimensional units selected for problem input.

IPHASE Integer input flag for water phase:1 Vapor2 Liquid

TempInDTempInS

Temperature of interest, input in problem input units. TempInD is double precision and TempInS is single precision.

PressInDPressInS

Pressure of interest, input in problem input units. PresInD is double precision and PresInS is single precision.

DDumSDum

No longer used. Retained only to maintain argument list compatibility with previous versions. DDum is a double precision scalar and SDum is a single precision scalar.


ValOutDValOutS

The returned value of the requested property. The value is in dimensional units declared for problem input data. ValOutD is a double precision scalar and ValOutS is a single precision scalar.

dVdTOutDdVdTOutS

The returned derivative of the property with respect to temperature (dv/dT). dVdTOutD is a double precision scalar and dVdTOutS is a single precision scalar.


DUDENS double precision

UDENS single precisionThese subroutines return the wet and dry actual volumes (at flowing temperature and pressure conditions) for a single phase of a stream as calculated using the density method(s) declared for input data of the simulation.


CALL DUDENS( IPHASE, DStVecIn, DDryVol, & DWetVol, IERR )


CALL UDENS( IPHASE, SStVecIn, SDryVol, & SWetVol, IERR )

Where:

IPHASE Input integer flag for the phase:1 Vapor2 Liquid

DStVecInSStVecIn

Input Standard stream vector containing data for the phase of interest. See “User Stream Vector” on page 15-10 DStVecIn is double precision and SStVecIn is single precision.

DDryVol SDryVol

Returned actual dry volumetric flow rate of the phase.The value uses different dimensional units depending upon the phase:IPHASE Return value uses these dimensional units

1 Vapor volume units per time2 Liquid volume units per time

DDryVol is double precision SDryVol is single precision.

DWetVol SWetVol

Returned actual wet volumetric flow rate of the phase. The value uses different dimensional units depending upon the phase:IPHASE Return value uses these dimensional units

1 Vapor volume units per time2 Liquid volume units per time

DDryVol is double precision SDryVol is single precision.

IERR 0 No error1 IPHASE is not 1 or 2, no results returned


To call these routines, load data for the phase of interest in the DStVecIn or SStVecIn argument array. For a stream known to be a single phase, these routines can compute the actual volume for the bulk stream. For mixed phase streams, a separate call is required for each phase.

These routines do not set the density calculation method and do not set the thermodynamic METHOD set to use. The assumption is that these routines are called from a user-added unit operation, and a thermodynamic method set used by the unit operation is currently in effect. If no density methods were defined in the thermodynamic method set, the K/H method is used, if applicable.

The subroutines do not directly return stream density. Users may calculate the density of a stream (phase) by dividing the weight rate of the stream (phase) by the returned value(s).

density = total weight rate / specific volumetric flow rate

= (weight/time) / (volume/time) = weight/time


KCOMPU double precision

This double precision subroutine returns K-values and temperature derivatives of K-values for use by a user-added flash subroutine. All floating point arguments are double precision.

Calling sequence:

CALL KCOMPU( TEMP, PRES, VAPIN, XL1IN, & XL2IN, XK1VAL, XK2VAL, DK1DT, & DK2DT, IXFLAG, KFLAG, KDFLAG )

Where:

TEMP Temperature, in input units, at which K-values are required. This is an input double precision scalar.

PRES Pressure, in input units, at which K-values are required. This is an input double precision scalar.

VAPIN Input double precision standard user stream vector of the vapor phase data. See “User Stream Vector” on page 15-10 Data values are in input dimensional units.

XL1IN Input double precision standard user stream vector of the L1 (light or hydrocarbon) liquid phase.

XL2IN Input double precision standard user stream vector of the L2 (heavy or aqueous) liquid phase.

XK1VAL Returned double precision array of K-values for L1 liquid phase components in PRO/II internal component order.

XK2VAL Returned double precision array of K-values for L2 liquid phase components in PRO/II internal component order.

DK1DT Returned double precision array of temperature derivatives for L1 liquid phase components in PRO/II internal component order.

DK2DT Returned double precision array of temperature derivatives for L2 liquid phase components in PRO/II internal component order.

IXFLAG Input integer composition flag:0 No composition dependencies1 Yes, calculations are composition dependent

KFLAG Input integer K-value option flag1 Consider light phase only for K-value

calculations.2 Consider both phases for K-values calculations.


There is no single precision analog of this subroutine.

KDFLAG Input integer derivative option flag1 Consider light phase only for derivative

calculations.2 Consider both phases for derivative calculations.

Note: XK1VAL, XK2VAL, DK1DT, and DK2DT must be dimensioned to NOC. For example,

REAL(8) :: XK1VAL( NOC ), XK2VAL( NOC )


DHCOMPU double precision

HCOMPU single precisionThese subroutines return enthalpies for use with a user-added flash method.

Calling sequence:

CALL DHCOMPU( TempInD, PresInD, VaporD, & XL1D, XL2D )CALL HCOMPU( TempInS, PresInS, VaporS, & XL1S, XL2S )

Where:

TempInDTempInS

Temperature at which enthalpies are required. This is an input double precision scalar that uses input units of temperature.

PresInDPresInS

Pressure at which enthalpies are required. This is an input double precision scalar that uses input units of pressure.

VaporDVaporS

A standard user stream vector for the vapor phase. VaporD is double precision and VaporS is single precision. This must be loaded with vapor phase data to pass in. The vapor results return in elements 4, 7, and 8. See “User Stream Vector” on page 15-10

XL1DXL1S

Standard user stream vector for the L1 (light or hydrocarbon) liquid phase. XL1D is double precision and XL1S is single precision. This must be loaded with L1 phase data to pass in. The L1 results return in elements 4, 7, and 8. See “User Stream Vector” on page 15-10

XL2DXL2S

Standard user stream vector for the L2 (heavy or aqueous) liquid phase. XL2D is double precision and XL2S is single precision. This must be loaded with L2 phase data to pass in. The L2 results return in elements 4, 7, and 8. See “User Stream Vector” on page 15-10

The phase enthalpy values return in element (4) of the user stream vectors. Element (7) returns the compressibility factors as calcu-lated from the K/H method. Element (8) returns the derivative of enthalpy with respect to temperature (dH/dT).

Note: Enthalpies have units of 103 energy units per time.


Interfaces for Solids The legacy interfaces in PRO/II support only vapor and liquid phases in streams. Chapter 21 describes new interfaces that support solids phases. Most of the routines were not available prior to PRO/II version 8.0. Refer to example routine USER57.FOR for some code demonstrations that use these solids-handling routines.

Component Identification Interface RoutinesMany of the user-added interface routines reference components by order number rather than by name or other text identifier. It is important to understand how PRO/II handles components to insure the interface routines handle component data properly.

Internal Component Order vs. Print Order

What Is Internal Component Order?PRO/II reorders components internally based on phase availability. This allows calculations to be performed efficiently on contiguous groups of components. Phase availability refers to the phases (vapor, liquid, solid) in which a component is allowed to exist. This usually is determined by the availability of data. For example, some components may have complete data for all three phases and be designated as VLS; while others might lack data for the solid phase and be designated as VL.

This reordering is referred to as SIMSCI Internal Component Order. By contrast, the sequence order for the components selected by the user at input and in the output reports is referred to as Print Order. This reordering impacts user-added subroutines that assume com-ponents are ordered in Internal Order. The user must take steps as described below to handle the internal component order.

The grouping of components by phase designation for internal use is as shown in Table 15-4.

Table 15-4: Component Phase Versus Internal Order

Phase Availability Internal Order

VL 1st group

VLS 2nd group

LS 3rd group

S 4th group


For example, if we compare the print order and internal order which are based on the following keyword input file extract:

COMPONENT DATA LIBID 1, N2 / 3, CH4 / 4, C2 / 5, C3 / & 6, IC4 / 7, NC4, & BANK = PROII_8.3:PROCESS LIBID 2, CO2, BANK = PROII_8.3:SIMSCI

The default PRO/II phase designations, print order, and internal order for components nitrogen through n-butane are given in Table 15-5 below.

Table 15-5: Phase Designation, Print and Internal Order for N2-NC4

Component Phase DesignationPrint Order

Internal Order

N2 VL 1 1

CO2 VLS 2 7

CH4 VL 3 2

C2 VL 4 3

C3 VL 5 4

IC4 VL 6 5

NC4 VL 7 6

Although CO2 is the 2nd component as far as the input file and printed reports are concerned (i.e., Print Order), it is the 7th compo-nent in Internal Order because the SIMSCI bank designation indi-cates that it is a VLS component, while the other components from the PROCESS databank have VL phase availability. For ease of internal calculation, the VL components are grouped ahead of VLS components.

You can see the phase availability from the component PRO/II out-put report by using the keywords INPUT=ALL on the PRINT statement in the General Data category of input. You can also force the phase designation to be uniform by using a PHASE statement in the Com-ponent Data category of input (see Chapter 1 of the SIMSCI Com-ponent Manual). Thus, in the above illustration, the user could force the internal order to match the input order by using the PHASE state-ment:

PHASE VL=1,7 or PHASE VL=2


How Order Affects User-Added SubroutinesIn user-added subroutines, compositional arrays are in Internal Order.

Note: An important exception is user-added kinetics which con-verts all compositional data to Print Order in the arrays passed to USKIN1-5.

Thus, all compositional arrays in the UTHERX and XPROPX com-mons, the stream compositions in the standard STREAM array used by TTPROP, UHS, UDENS, URXSTR, etc. are all in Internal Order. If you are assuming that components are in Print Order, then you must use the COPNUM and COINUM subroutines described below to access the Internal Order.

Component Order, Identification, and Data

COPNUMThis subroutine returns the component print order number when given the internal order number. See also ”UDEFNC”, pg 20-3

Calling sequence:

CALL COPNUM( iCint, iSlate, ICprint )

Where:

iCint Input integer Internal component number

iSlate Input integer Value = 1 always

iCprint Output integer Print component number

Example: Retrieving Component Print Order Numbers!! Retrieve Component Print Order Numbers!1001 FORMAT( “ Internal Number = “, I5, & “ Print Number = “, I5 )! DO iCint = 1, NOCX CALL COPNUM(iCint, 1, iCprint) WRITE (IOUT, 1001) iCint, iCprint END DO


COINUMThis subroutine returns component internal order numbers given the print order numbers.

Calling sequence:

CALL COINUM( iCprint, iSlate, iCint )

Where:

iCprint Input integer Print component numberiSlate Input integer Value not significant for useriCint Output integer Internal component number

Example: Retrieving Component Internal Order Numbers!! Process Data in Print Order.! Assume TDATA contains a K-Value array! in print order! DO iCprint = 1, NOCX CALL COINUM (iCprint, iSlate, iCint ) XKV(iCint) = TDATA(iCprint) END DO

CONAMEThis function retrieves the text ID of a given component. The returned value of the function is a character string of up to 16 char-acters in length.

Calling sequence:

COMPID = CONAME( iSlate, iCint )

Where:

iSlate Integer input indicating the component slate to use:1 = Normal Component, including solid components2 = Ionic component (used only for electrolytes)

iCint Integer input of the internal order number of the component of interest.

COMPID The returned 16 character component ID


UCOPRP double precision

This double precision subroutine retrieves or stores specified com-ponent property data to the current active set of component proper-ties. The property is processed for all components in each call.

Usage (Double Precision):

CALL UCOPRP( cPropKw, iPropNo, cRWflag, NDIM, DCoProp, iErrOut )

Where:

cPropKw Input key word (used if non-blank) that uniquely identifies a named component property.

For example, use "MW" for molecular weight.CALL UCOPRP( “MW”, 0, “READ”, & NOCTOT, DCoProp, iErrOut )

This call retrieves the molecular weight of all components in the simulation (except non-molecular weight components). Available fixed properties are listed in Table 15-6. Note IPropIn should be zero.Additionally, cPropKw may designate any named special property listed in Table A-1, "Keywords for Named Special Properties" in Appendix A. This entry must be a character variable or a keyword coded as a literal string enclosed in quotation marks. When blank, argument iPropNo is required to identify a numbered special property.

iPropNo Input integer value (1 - 60) identifying a user-defined special property, as in SPROP(iPropNo). This is required because SPROP's are only numbered and have no pre-defined name.

IPropNo is used only when cPropKw is blank or null; otherwise, it is ignored. For example,

CALL UCOPRP( “ ”, 3, “READ”, & NOCTOT, CpProp, iErrOut )

retrieves the value of user-defined special property 3 (SPROP(3)) for all components.

cRWflag Argument cRWflag is an input text string option flag with values of:"READ" Read (retrieve) the property values and return

them in call argument array DCoProp."WRITE" Write (store) values passed in through the

DCoProp array to the active set of component properties.


Table 15-6: Named Properties Available through UCOPRPcPropKw Description

‘NBP’ Normal Boiling Point temperature

‘MW’ Molecular weight

‘SG60’ Specific Gravity at 60 F

‘OMEGA’ Acentric factor

‘TC’ Critical Temperature

‘PC’ Critical Pressure

‘VC’ Critical Volume

‘ZC’ Critical compressibility factor

‘RAKT’ Rackett parameter

‘CNUM’ Carbon number

‘ZNUM’ Hydrogen deficiency number

‘WATK’ Watson K coefficient

See Appendix A for Special Property Keywords

NDIM Variable NDIM is the number of values to read or write. Array DCoProp contains all NDIM values to read or write. This routine always processes exactly NOCTOT values. It processes one value for each of NOCTOT components. Since this is under user control, no tests are made to ensure the values are legitimate. This could mostly be a problem during a WRITE rather than a READ. If NDIM is less than NOCTOT, then an error is returned and the READ or WRITE fails.If NDIM is greater than NOCTOT, only the first NOCTOT items are processed in DCoProp and the others are ignored. This is considered normal behavior and does not generate either an error or a warning.

DCoProp A double precision floating point array containing at least NOCTOT elements. Each element passes one property value for each of the NOCTOT components in PRO/II internal component order.

iErrOut An integer output variable that returns the error flag. A value of zero indicates successful completion with no errors. Any other value indicates failure, and the results are indeterminate. This usually means no action was performed.


DzMolWt double precision

ZMW2 single precisionThese integer functions retrieve or store the molecular weight of every component in the simulation that has a molecular weight. The returned integer value of the function is the error flag.

Usage (Double Precision): INTEGER(4) :: DZMolWt . . . ifOk = DZMolWt( IRDWT, IDIM, DVecIO )

Usage (Single Precision): INTEGER(4) :: ZMW2 . . . ifOk = ZMW2(IDIM, SVecIO, IRDWT )

where:

IRDWT Integer input read/write option flag. values are: 0 Read 1 Write

IDIM Size of data array DVecIo. Because data are ordered component input order, this size must accommo-date all components in the problem, typically NOC-TOT. See “Internal Component Order vs. Print Order” on page 15-40. See “GETNCOMP” on page 21-2 to obtain counts of various types of compo-nents.

DVecIO Data array of molecular weights, one per compo-nent, arranged in (external) component print order. The size must be large enough to store a value for every component in the simulation. (For one option, See “/PMXUSR/” on page 15-49.)

ifOk Error return. 0 = no error. >0 = array DVecIO is too small Only ifOk components were processed.

These routines may be used as alternatives to using the more gen-eral-purpose routine UCoPrp. The only real difference is:

DzMolWt and ZMW2 use an external data array to pass data in component print order. Routine UCoPrp uses an internal data array to pass data in PRO/II internal component order. See “Internal Data Array” on page 15-11for definitions of these arrays.


DzSg60 double precision

ZSg602 single precisionThese functions retrieve or store the specific gravity at standard conditions (60 degrees Fahrenheit) of every component in the simu-lation. The returned integer value of the function is the error flag.

Usage (Double Precision): INTEGER(4) :: DZSG60 . . . ifOk = DZSG60( IRDWT, IDIM, DVecIO )

Usage (Single Precision): INTEGER(4) :: ZSG602 . . . ifOk = ZSG602( IDIM, SVecIO, IRDWT )

where:

IRDWT Integer input read/write option flag. values are: 0 Read 1 Write

IDIM Size of data array DVecIo. Because data are ordered component input order, this size must accommo-date all components in the problem, typically NOC-TOT. See “Internal Component Order vs. Print Order” on page 15-40. See “GETNCOMP” on page 21-2 to obtain counts of various types of compo-nents.

DVecIO Data array of specific gravities, one per compo-nent, arranged in (external) component print order. The size must be large enough to store a value for every component in the simulation. (For one option, See “/PMXUSR/” on page 15-49.)

ifOk Error return. 0 = no error. >0 = array DVecIO too small to process all components.

These routines may be used as alternatives to using the more gen-eral-purpose routine UCoPrp. The only real difference is:

DzMolWt and ZMW2 use an external data array to pass data in component print order. Routine UCoPrp uses an internal data array to pass data in PRO/II internal component order. See “Internal Data Array” on page 15-11for definitions of these arrays.


User-Defined Data Files

FIGETUThis is a PRO/II utility that guarantees that the FORTRAN unit number passed to your FORTRAN OPEN statement will not conflict with files opened by the UAS system.

Calling sequence:

CALL FIGETU( 1, LOUT )

Where:

1 Input integer digit “1” requests a single file unit. This is the only recommended value to use.

LOUT Output Integer scalar variable that returns the first available file unit. This must be an integer variable, not a constant.

The FIGETU subroutine call returns the next available FORTRAN unit number for input or output as integer variable LOUT. A sample code extract is shown below:

CHARACTER(LEN=8) :: FNAME CHARACTER(LEN=12) :: FEXTRA1001 FORMAT(“ Enter File Name: “)1002 FORMAT( A ) . . .! Open a logical file unit for output! CALL FIGETU(1, LOUT)!! Open file ‘FNAME.OXX’ as a new, formatted ! sequential file! FEXTRA = FNAME // ‘OXX’ OPEN( UNIT=LOUT, FILE=FEXTRA, STATUS=‘NEW’, & FORM=‘FORMATTED’, ACCESS=‘SEQUENTIAL’)


Common Storage BlocksSeveral types of classic user-added subroutine use common blocks to exchange data with PRO/II. The common blocks are installed during installation of PRO/II user-added subroutines, typically in directory %p2install%\user\CMNS\. Starting with PRO/II version 8.2.1, PRO/II installs a double precision and a single precision ver-sion of each common. Previously, only single-precision versions were available. To use any of the available common blocks, access them using an INCLUDE statement in a Fortran subroutine or func-tion. Never attempt to use both the single precision and double precision version of the same common block in the same subrou-tine or function.

/PMXUSR/This include file contains a single parameter - MAXCN - that defines the maximum number of components supported by user-added sub-routines in PRO/II. Starting with PRO/II version 8.0, MAXCN = 2500. In earlier versions, MAXCN was limited to 300. MAXCN is an invariant parameter that cannot be altered by a user.

Usage:INCLUDE ‘PMXUSR.CMN’

Where:

MAXCN Maximum components allowed in a user-added subroutine by PRO/II. MAXCN is an integer parameter with a value of 2500. It’s only purpose is to dimension other arrays in common blocks UTHERX.CMN, XPROPX.CMN, and XPROPY.CMN.

Example:

The following code snippet demonstrates the proper ordering of INCLUDE statements in a user-added subroutine.

INCLUDE ‘PMXUSR.CMN’ ! Required to use others belowINCLUDE ‘UTHERX.CMN’ ! Always after PMXUSRINCLUDE ‘XPROPX.CMN’ ! Always after PMXUSRINCLUDE ‘XPROPY.CMN’ ! Always after PMXUSR

There should be no compelling reason for the user to use MAXCN directly. Instead, call interface routine GETNCOMP to obtain cur-rent component counts in a problem.

Note: User-added subroutines must include PMXUSR.CMN before they include UTHERX.CMN, XPROPX.CMN, or XPROPY.CMN.


/DFACTOR/ double precision

/FACTOR/ single precisionCommon blocks /DFACTOR/ and /FACTOR/ contain dimensional unit conversion factors and certain physical constants. These conversion factors can be used to convert input dimensional units to the base units as shown below. The variables in /DFACTOR/ and /FACTOR/ have exactly the same names and are in exactly the same order. The only difference is that /DFACTOR/ contains double precision values while /DFACTOR/ contains single precision values of the same conversion factors.

Note: Never attempt to include both /DFACTOR/ and /FACTOR/ in the same subroutine, since that would cause fatal compilation errors.

Usage (double precision):INCLUDE ‘DFACTOR.CMN’

Usage (single precision)INCLUDE ‘FACTOR.CMN’

This include file contains the following common block:

COMMON /FACTOR/ & TCONVT, TFAC, PCONVT, PFAC, & TIMFAC, WTFAC, VVFAC, ARFAC, & XLVFAC, SPGFAC, HSFAC, WKFAC, & VISFAC, TCFAC, VVFACA, STFAC, & FACA, FACB, EXPFAC, XM3FAC, & FTOR, CTOK, XKTOR, ATM, & VVTOML, RCONST, DUMMY(14)

Where:

TRankine = [(temp)p + TCONVT] · TFAC Psia = [(pres)p + PCONVT] · PFAC Sec = (time)p · TIMFAC Lb = (wt)p · WTFAC (Standard vapor volume)p · 106 = (moles)p * VVFAC Ft2 = (area)p · ARFAC Ft3 = (liquid volume)p · XLVFAC (60°F density)p = SpGr · SPGFAC Btu/(time)p = (enthalpy/time)p · HSFAC Horsepower = [(ΔH · 103)/time]p · WKFAC Centipoise = (viscosity)p · VISFAC Btu/hr-°F-Ft = (thermal conductivity)p · TCFAC


Ft3 = (vapor volume)p · VVFACA Dynes/cm = (surface tension)p · STFAC

The common includes the following conversion factors for use in user-added subroutines. Developers should not attempt to modify the values of these factors.

FACA, FACB

Reserved, not available

EXPFAC 2.3026 ln(X) = EXPFAC ( log10(X) )XM3FAC 35.314667 ft3/m3 (cubic meters to cubic feet)FTOR 459.67 (Fahrenheit to Rankine)CTOK 273.15 (Celsius to Kelvin)XKTOR 1.8 (Kelvin to Rankine)ATM 14.6959 (Atmospheres to psia)VVTOML Obsolete, not used

RCONST 1.9872 (Gas constant)

Note: Subscript p denotes problem input dimensional units.


/DOUTFAC/ double precision

/OUTFAC/ single precisionCommon block /DOUTFAC/ contains factors for scaling and conver-sion of problem output to alternate dimensional units when the OUT-DIMENSION feature of PRO/II is used. It also includes alphanumeric representations for the output dimensional units and the component names. Common block /OUTFAC/ is a single precision version that contains exactly the same data as /DOUTFAC/.

Usage:

INCLUDE ‘PMXUSR.CMN’ ! Required to use DOUTFACINCLUDE ‘DOUTFAC.CMN’

orINCLUDE ‘PMXUSR.CMN’ ! Required to use OUTFAC

INCLUDE ‘OUTFAC.CMN’

The INCLUDE file contains either common DOUTFAC or OUTFAC:

COMMON/DOUTFAC/& TXXX(20), IHOL(37), IXNAME(4, MAXCN)

The only difference is array TXXX, which is double precision in DOUTFAC.CMN and is single precision in OUTFAC.CMN. Output items may be multiplied by the TXXX array to accomplish any needed conversions to output dimensions when multiple output dimensions are used.

Weight/time = (weight/time)p · TXXX(1)Liquid volume/time = (liquid volume)p · TXXX(2)Weight = weightp · TXXX(3)Liquid volume = (liquid volume)p · TXXX(4)Liquid density = (liquid density)p · TXXX(5)Enthalpy = enthalpyp · TXXX(8)Enthalpy/time = (enthalpy/time)p · TXXX(9)Temperature base = TXXX(10)Pressure base = TXXX(11)Enthalpy/weight = (enthalpy/weight)p · TXXX(12)Scale factor1 = TXXX(13)Actual vapor vol./time = (actual vapor vol./time)p · TXXX(14)Vapor density = (Vapor density)p · TXXX(15)Thermal Conductivity = (Thermal conductivity)p · TXXX(16)


Viscosity = (Viscosity)p · TXXX(17)Surface Tension = (Surface tension)p · TXXX(18)Standard vapor volume = (Standard vapor volume)p · TXXX(20)

For temperature and pressure conversions, factors from /FACTOR/ must also be used.

Temp = (tempp + TCONVT) · TXXX(6) - TXXX(10)

Pres = (presp + PCONVT) · TXXX(7) - TXXX(11)

where TCONVT and PCONVT are from /DFACTOR/ (or /FACTOR/).

For the above conversions, the subscript p is used to represent prob-lem input dimensional units.

The IHOL array shown in Table 15-7 contains Hollerith information corresponding to the output dimensions. All entries are A4 except temperature which is A3. Blanks are denoted with b.

Table 15-7: Hollerith Array

IHOL Description Format Illustration

1 Per time unit /XXX

2 Weight unit XXb

3 Multiple weight units bXXS

4 Per weight /XXb

5 Degree bDEG

6 Temperature unit bXb

7 Pressure unit XXXX

8 Energy unit XXXX

9 Liquid volume unit XXXX

10 Per liquid volume /XXX

11 Vapor volume unit XXXX

12 Per vapor volume /XXX

13 Length unit XXbb

14 Work unit bXXb

15,16 Viscosity unit XXXX XXXX

17,19 Thermal conductivity unit

XXXX XXXX XXXX

20,21 Surface tension unit XXXX XXXX

22 Liquid bLIQ


23 UIDb

24 Vapor bVAP

25 ORbb

26 Mixed bMIX

27 EDbb

28 Mole MOLE

29 Mols MOLS

30 Wet WET

31 Dry bDRY

32 Blank bbbb

33 Zero bbb0

34 103 bbMb

35 106 bMMb

36 per 103 /Mbb

37 per 106 /MMb

Note: When the unit dimension does not require all non-blank positions as shown above, it is spaced accord-ingly. For example, a pressure unit of Pascals would be represented bPAb.

Note: The IHOL array is appropriately modified from input dimensions when alternate output dimensions are requested. The IXNAME array contains the component names in the format XXXX XXXX XXXX XXXX (4A4).

Table 15-7: Hollerith Array (Continued)

IHOL Description Format Illustration


/DUTHERX/ double precision

/UTHERX/ single precisionCommon block /DUTHERX/ and /UTHERX/ provide an interface that transfers data between user-added thermodynamic subroutines and PRO/II. See ”DUTHERX Common Block (or UTHERX)”, pg 16-3, for complete information about using these commons.

Usage:

INCLUDE ‘PMXUSR.CMN’ ! Required to use DUTHERXINCLUDE ‘DUTHERX.CMN’ ! double precision

orINCLUDE ‘PMXUSR.CMN’ ! Required to use UTHERXINCLUDE ‘UTHERX.CMN’ ! single precision

These INCLUDE file contains the following common block:

COMMON / DUTHERX /& TEMPX, TDELTX, PRESX,& XVV, XLL, XLL2, YXSAT,& XXSOL, XKV, DRVX, HSX1,& HSX2, ZXX1, ZXX2,& IFLGX, IXXFLG, JXXFLG, NOCZ,& IFPHZ, KUOUT, KDECNT, KVTYPE,& KDCALL

All the variables are fully described in ”DUTHERX Common Block (or UTHERX)”, pg 16-3. Only variable KDCALL is described here.

KDCALL This flag controls whether or not PRO/II stores data returned in the common block. PRO/II initializes this flag to zero just prior to each call to a user-added subroutine. When a user-added subroutine alters data in this common with the intent of having PRO/II store it, that user-added subroutine must set KDCALL = 1. Upon return to PRO/II, all data is stored when KDCALL = 1. For any other returned value of KDCALL, any and all returned data are discarded.


/DXPROPX/ double precision

/XPROPX/ single precisionCommon /DXPROPX/ contains double-precision values for the pure component properties for the components declared in the problem input data. Common /XPROPX/ contains single-precision values for the same properties using exactly the same variable names in exactly the same order.

Note: The property values must not be altered in any way by user-added subroutines.

Note: Never attempt to use both /DXPROPX/ and /XPROPX/ in the same subroutine or function.


INCLUDE ‘PMXUSR.CMN’ ! Required to use DXPROPXINCLUDE ‘DXPROPX.CMN’

or (single precision):INCLUDE ‘PMXUSR.CMN’ ! Required to use XPROPXINCLUDE ‘XPROPX.CMN’

This INCLUDE file contains the following common block:

COMMON /DXPROPX/ & XMW(MAXCN), BP(MAXCN), DENS(MAXCN),& TC(MAXCN), PC(MAXCN), VC(MAXCN),& ZC(MAXCN), OMEGA(MAXCN), HFORM(MAXCN),& GFORM(MAXCN), & LIBNO(MAXCN), KOCMOL, KOCTOT,& KOCVL, KOCVLS, KOCLS,& KOCV, KOCL, KOCS

Where:

Floating Point Values In CommonXMW Molecular weights

BP Normal boiling points in problem input units

DENS Component liquid densities at 60ºF (15.55ºC) and one atmosphere in problem input units.

TC Critical temperatures, absolute input temperature units

PC Critical pressures, absolute input pressure units

VC Critical volumes, cc/gm mole

1) PETROLEUM and NONLIB components are given a LIBNO of ‘0’. Library ID numbers for all Library components may be found in the Modular Thermodynamics User Manual.


ZC Critical compressibility (Z’s)

OMEGA Acentric factors

HFORM Heat of formation in energy units/mole

GFORM Energy of formation in energy units/mole

Integer Values in CommonLIBNO Library ID numbers for components.1

KOCMOL Number of molar weight-based components

KOCTOT Total number of normal components.

KOCVL Number of components that can exist in vapor and liquid phases.

KOCVLS Number of components that can exist in vapor, liquid, and solid phases.

KOCLS Number of components that can exist in liquid and solid phases.

KOCV Number of components that can exist in the vapor phase.

KOCL Number of components that can exist in the liquid phase.

KOCS Number of components that can exist in the solid phase.

1) PETROLEUM and NONLIB components are given a LIBNO of ‘0’. Library ID numbers for all Library components may be found in the Modular Thermodynamics User Manual.


/DCUDATA/ double precision

/CUDATA/ single precisionCommon block /DCUDATA/ is a single-vector double precision stor-age area for various groups of stream, unit, and component data. Common /CUDATA/ is a single precision version of the same com-mon. Extensive discussion of usage is presented in Chapter 16, DCUDATA Common Block, page 16-8.

Usage (double precision):INCLUDE ‘DCUDATA.CMN’ ! double precision

or (single precision): INCLUDE ‘CUDATA.CMN’ ! single precisionThe INCLUDE file contains the following common block:

COMMON /DCUDATA/ TDATA(2600) Where:

/CUSPEC/Common block /CUSPEC/ is required only in any subroutine calling UFLSH to perform an isentropic flash. This common transfers the stream entropy to the UFLSH call interface program for use in the isentropic flash.

INCLUDE ‘CUSPEC.CMN’

This INCLUDE file contains the following common block:

COMMON/CUSPEC/ IX1(10),SISENV,RX1(7)

Where:

SISENV Entropy of the stream to be used as the target entropy for the call to UFLSH. The value should be obtained by calling subroutine UHS and transferred to SISENV without any dimensional or other conversion. Variable SISENV is explicitly declared single precision.

Note: None of the double-precision subroutines use the CUSPEC common or variable SISENV. Instead, all of them include an addi-tional variable in the argument list of the call to pass in the stream entropy.

TDATA Real constants, entered in the Thermodynamic Data category of input (see Chapter 16, User-Added Thermodynamic Property Methods).


Chapter 16 User-Added Thermodynamic

Property MethodsOverview

PRO/II supports user-added subroutines that perform K-value, enthalpy, entropy, or density calculations. To indicate to PRO/II that a user-added thermodynamic property method is being used instead of a built-in method in a keyword file, you must specifically declare module using the METHOD statement. For example, to use a user-added K-value method in a keyword input file:

METH KVALUE=U1,ENTH=CP,ENTR=CP,DENS(V)=SRK, & DENS(L)=API, TRANS=PETRO, SET=1

In the ProVision Graphical User interface, navigate to the Input menu -> Thermodynamic data to open the SIMSCI - Thermody-namic Data dialog box. Scroll the Category list and select User-Added Methods. The available user-added methods will populate the Primary Methods list box. Highlight the user-added method of choice and click the Add button to move the selection to the Defined Systems list box. To match the preceding keyword example, select “User-added 1” from he Primary Methods list box and click the Add button.

Next, click the Modify button to open the Thermodynamic - Modifi-cation dialog box. Ensure “User-added 1” is the Current Method for the “K-value (VLLE)” property. Make any other necessary adjust-ments to inform PRO/II of exactly which properties the user-added subroutine can (and cannot) calculate. When satisfied with the con-figuration, press the OK button on each dialog box to return to the main PFD window.

The examples above indicate that the previously linked user-added K-value method, U1, is to be used in thermodynamic method set


“1.” The valid entries for the KVALUE keyword are U1, U2, U3, ..., U15. Each entry corresponds to a specific user-added subroutine. Keyword entry U1 corresponds to the Fortran subroutine named UKHS1.FOR, U2 corresponds to UKHS2.FOR, and so on.

Note: These subroutines may be used to calculate K-values, enthalpies, entropies, or densities and may call all other subroutines.

To use this K-value method in a unit operation calculation, you would use a similar keyword construct. For example, to perform an isothermal flash at 30°F:

FLASH UID=FL1 FEED 1 PROD V=2, L=3 ISOT TEMP=30, DP=0 METHOD SET=1

Rigorous VLLE CalculationsWhen calling a user-added subroutine for VLLE K-values, PRO/II passes the compositions of the light and heavy liquid phases in the XLL and XLL2 arrays, respectively. You must, however, make sure that the user-added subroutine for VLE K-values works with a sin-gle-liquid phase composition via the XLL vector.

For enthalpy, entropy, and density calculations, the user-added sub-routine is called for the two liquid phases individually. There is no need to worry about dealing with two liquid compositions at once, and later combining the results into a single bulk value. PRO/II does this combination for you at a higher level.

Component Internal Order vs. Print Order?PRO/II reorders components internally based on phase availability. This is done so that calculations can be performed efficiently on contiguous groups of components. This reordering is referred to as SIMSCI Internal Component Order. By contrast, the sequence order for the components selected by the user at input and in the output reports is referred to as Print Order. This reordering impacts user-added subroutines that assume components are ordered in Print Order. Developers must include code to handle the internal compo-nent order. Refer to subroutines COINUM and COPNUM in Chapter 15 for information about properly handling component data accessed through the PRO/II interface routines.

16-2 User-Added Thermodynamic Property Methods February 2009

Communicating with PRO/IIMost PRO/II interface subroutines communicate with the user-added subroutine through argument lists in the subroutine call; however, there is no argument list for any of the 15 thermodynamic property subroutines UKHS1.FOR through UKHS15.FOR. For all of these routines, data exchange with PRO/II is via two double preci-sion common storage blocks: DUTHERX.CMN and DCUDATA.CMN, or their single precision alternatives UTHERX.CMN and CUDATA.CMN

DUTHERX Common Block (or UTHERX)The DUTHERX common block passes double precision variables to and from the PRO/II calculation engine. These variables include temperature, pressure, vapor and liquid composition, entropy, enthalpy, and density values. Alternatively, the UTHERX common provides a single precision version of the common using exactly the same variable names.

Each UKHSxx.FOR routine must include the following lines of code:

INCLUDE ‘PMXUSR.CMN’ ! brings in MAXCNINCLUDE ‘DUTHERX.CMN’ ! double precision

orINCLUDE ‘PMXUSR.CMN’INCLUDE ‘UTHERX.CMN’ ! single precision

The common block includes the following variables:

COMMON / DUTHERX /& TEMPX, TDELTX, PRESX,& XVV, XLL, XLL2, YXSAT,& XXSOL, XKV, DRVX, HSX1,& HSX2, ZXX1, ZXX2,& IFLGX, IXXFLG, JXXFLG, NOCZ,& IFPHZ, KUOUT, KDECNT, KVTYPE,& KDCALL

All variables are scalars except the following:

REAL*8 XVV(MAXCN), XLL(MAXCN), XLL2(MAXCN), & XKV(MAXCN), DRVX(MAXCN)

INTEGER IFLGX(15)

The order of variables is different in DUTHERX and UTHERX. How-ever, both use exactly the same variable names. Accessing the com-mon by using one of the INCLUDE statements illustrated above eliminates concerns about the declared order of variables.


Storing Returned Data Both commons include integer variable KDCALL to control storing or discarding data returned from the user-added subroutine in the common block.

KDCALL This flag controls whether or not PRO/II stores data returned in the common block. PRO/II initializes this flag to zero just prior to each call to a user-added subroutine. When a user-added subroutine alters data in this common with the intent of having PRO/II store it, that user-added subroutine must set KDCALL = 1. Upon return to PRO/II, all data is stored when KDCALL = 1. For any other returned value of KDCALL, any and all returned data are discarded.

Common DUTHERX and UTHERX both include a KDCALL variable. PRO/II processes these independently. Users should avoid using both DUTHERX and UTHERX in the same application.

The input variables passed into the user-added subroutine routine from PRO/II depend on what thermodynamic property is being cal-culated by that routine and are shown in Table 16-1.

Note: The size of the arrays dimensioned above (by MAXCN from PMXUSR.CMN) corresponds to the 2500 component maxi-mum limit discussed in “/PMXUSR/” on page 49 of Chap-ter 15.

Table 16-1: UTHERX Input Variables Passed Into UKHSxx (xx = 1-15)

Name DescriptionK-

Value H S rho

IXXFLG Flag indicating what data is requested by PRO/II (see below).

valid valid valid valid

JXXFLG Returned flag conveying information back to PRO/II based on IXXFLG request. IXXFLG and JXXFLG are discussed below.


NOCZ Number of components in problem—must not exceed MAXCN


IFPHZ Phase Flag n/a valid valid valid

KUOUT FORTRAN file unit number for writing to default output file.


n/a Not applicable


TEMPX, PRESX and TDELTX are all in input units, i.e., their tempera-ture and pressure units correspond to the choices made on the DIMENSION statement in the General Data Category of input. If con-version to another system of units is required by the user-added methods, then this can be accomplished using values available in the common block FACTOR (see “/DFACTOR/ double precision” on page 50 of Chapter 15).

The output variables passed from the user-added subroutine into PRO/II also depend on what thermodynamic property is being cal-culated by that routine and are shown in Table 16-2.

TEMPX Temperature at which to generate property values (Input Units).


TDELTX Temperature increment in Input units for calculating derivatives.

valid valid valid n/a

PRESX Pressure at which property values are to be generated (Input Units).

valid valid valid n/a

XVV Array of vapor phase composition in mole fractions.


XLL Array of liquid phase compositions in mole fractions.


XLL2 Array of 2nd liquid phase composition in mole fractions (if water decant is ON, this is decanted water only).


Table 16-1: UTHERX Input Variables Passed Into UKHSxx (xx = 1-15) (Continued)

Name DescriptionK-

Value H S rho

n/a Not applicable

Table 16-2: UTHERX Output Variables Passed From UKHSxx. (xx = 1-15)

Name DescriptionK-

Value H S rho

YXSAT Saturated vapor mole fraction for water at TEMPX and PRESX. Required if water decant is ON (KDECNT > 0).

valid n/a n/a n/a

XXSOL Solubility of water in the non-aqueous liquid phase expressed as molal fraction of water at saturation. Required if water decant is ON. May be set equal to 1.0 if decant is OFF.

valid n/a n/a n/a

n/a Not applicable


Variables IXXFLG and JXXFLGThese DUTHERX common flags communicate information about the calculation status between the user-added subroutine and PRO/II.

IXXFLG PRO/II passes this flag to the user-added subroutine to indi-cate which properties to compute (e.g., K-values, enthalpies, etc.).

JXXFLG is returned to PRO/II from the user-added subroutine to indicate which property values are being returned, or whether a calculation error occurred.

XKV Array of the calculated component K-values

valid n/a n/a n/a

DRVX Array of derivatives of property values, Y, with temperature, T (dY/ dT). (If property value derivatives are needed, TDELTX will be greater than zero. If so, the user-added routine must place the derivatives in the DRVX array.)


HSX1 Enthalpy and entropy values at TEMPX and PRESX

n/a valid valid n/a

HSX2 Enthalpy and entropy values at TEMPX + TDELTX and PRESX

n/a valid valid n/a

ZXX1 Vapor compressibility factor valid valid valid valid

ZXX2 Liquid compressibility factor valid valid valid valid

IFLGX Array of 15 Integer parameters initialized to zero and available to the user as counters, flags, etc.


KDECNT Position of water in the component list, if water decant is ON. Otherwise = 0.

valid n/a n/a n/a

KVTYPE Set to 1 if PRO/II requires VL K-values, 2 for LL K-values, 0 for all other cases.

valid n/a n/a n/a

KDCALL Set equal to 1 to store returned data. This variable differentiates the UTHERX common from the older UTHERM common.


Table 16-2: UTHERX Output Variables Passed From UKHSxx. (xx = 1-15) (Continued)

Name DescriptionK-

Value H S rho

n/a Not applicable


For example, PRO/II often passes a value of -1 in IXXFLG to the user-added subroutine. This is a request for information on the type of K-value method used by the user-added routine. If the user-added routine calculates K-values using a liquid activity method (such as the NRTL method), it should return a value of 3 in JXXFLG to PRO/II. This indicates the K-value method is strongly composition-dependent.

Table 16-3: Values of IXXFLG, JXXFLG for Thermodynamic Property Methods

PropertyValue ofIXXFLG Description

Value ofJXXFLG Description

K-Value -1 Requests type of K-value method being supplied.

1 K-value method not compositional dependent (i.e., not an equation of state or liquid activity coefficient method.)

2 K-value method is based on an equation of state.

3 K-value method is based on liquid activity coefficients.

K-Value 0 Initial estimates of K-values needed by PRO/II, i.e., values not yet available in arrays XVV, XLL, or XLL2.

0 Initial K-value estimates calculated using SIMSCI initial estimate methods. Note: Critical properties (Tc, Pc, w must be available for all components).

1 The user-added K-value method will return initial K-value estimates via the XKV array.

99 Calculation error occurred.

K-Value 1 - K-values are needed and are available in arrays XVV, XLL, and XLL2. Use for all subsequent calls to the user-added routine.

Enthalpy 2 Enthalpy values requested

0 Enthalpy values are being returned in the form, i.e., H-H*/RT.

1 Enthalpy values are being returned in the form H/RT.


Entropy 3 Entropy values requested

0 Entropy values are being returned in the form, i.e., S-S*/RT.


After JXXFLG is set, the user-added routine should return to the call-ing routine as illustrated below for a routine UKHS1 calculating K-values using an equation of state method:

SUBROUTINE UKHS1 . . . INCLUDE ‘PMXUSR.CMN’ INCLUDE ‘UTHERX.CMN’ . . . IF ( IXXFLG .LE. -1 ) THEN JXXFLG = 2 GO TO 9999 ENDIF . . .9999 CONTINUE END SUBROUTINE UKHS1

In this example, IXXFLG is equal to -1, indicating a request from PRO/II for the user-added subroutine to specify the degree of com-positional dependency. In this case the subroutine sets and returns JXXFLG equal to 2. This indicates the user-added subroutine imple-ments a composition-dependent equation of state method.

DCUDATA Common BlockCUDATA Common Block

The DCUDATA common block is used to pass user-supplied double precision data to the user-added property routine via the UDATA key-word in the PRO/II keyword input file. The CUDATA common block is a single precision alternative to DCUDATA. Both versions of the common contains one variable, TDATA. TDATA is an array that may contains 2600 elements available to transfer floating point values.

1 Entropy values are being returned in the form S/RT.


Density 4 Density values requested.


Table 16-3: Values of IXXFLG, JXXFLG for Thermodynamic Property Methods

PropertyValue ofIXXFLG Description

Value ofJXXFLG Description


COMMON / DCUDATA / TDATA(2600)or COMMON / CUDATA / TDATA(2600)

For example, assume the user-added enthalpy method UKHS1.FOR (designated by the keyword entry ENTH=U1 on the METHOD state-ment) requires input data that may change from one run to another (e.g., constants from regressed data). The UDATA statement may be used to pass these values to the user-added routine.

METHOD KVAL=SRK, ENTH=U1, ENTR=SRK, & DENS(V)=SRK, DENS(L)=API, & TRANS=PETRO, SET=A ENTH UDATA 1, 0.5 / 2, 1.0 / 3, 1.5 . . .

To enter values in the PRO/II GUI,

navigate to Input menu -> ThermoDynamic Data. Refer to Figure 16-1.

Figure 16-1: Selecting A User-Added Subroutine in Provision

Scroll the Category list box and select User-Added Methods to populate the Primary Methods list box. In the Primary Methods list, highlight User-Added 1, then click the Add button (1) to add it to the Defined Systems list (2) box (as entry U101). With


U101 highlighted, click the Modify button (3) to open the Ther-moDynamic Data - Modification dialog box. See Figure 16-2.

Figure 16-2: Preparing to Enter Thermodynamic User Data

Click an Enter Data button on any row that displays User-added-1 as the Current Method to open the Thermodynamic Data - User Added... window.

Figure 16-3 shows the window with the sample data filled in. All the data is shared among all the properties that the User-added 1 method computes. Note the Parameter Numbers correspond to the storage elements of the TDATA array in common CUDATA.


Figure 16-3: User-Added Thermodynamics Data Entry

PRO/II passes these values to the user-added subroutine through the TDATA array in the CUDATA common block:

SUBROUTINE UKHS1 . . . INCLUDE ‘PMXUSR.CMN’ INCLUDE ‘UTHERX.CMN’ INCLUDE ‘CUDATA.CMN’

By adding two lines of code to echo the values in CUDATA:

1001 FORMAT( “ TDATA = “, 5F10.4 ) WRITE(IOUT, 1001)( TDATA(I), I = 1, 5 )

The following results could be written to the output file:

TDATA = 0.5000 1.0000 1.5000 . . .

Handling Water DecantIn PRO/II, water may be treated as a separate decant phase or as a regular component. Using water DECANT is an alternative to using


rigorous VLLE thermodynamics. Use the WATER statement in key-word input as shown below:

METH KVAL=U1,ENTH=U1,ENTR=CP,DENS(V)=SRK, & DENS(L)=API, TRANS=PETRO, SET=1 WATER DECANT=ON

In the above input example, water decanting is turned ON. Thus, water will be treated as a separate (decanted) pure component. In normal VLE thermodynamics with DECANT=OFF, water is not dif-ferentiated and is treated as any other component. Starting first in version 8.1, the default used in previous versions of PRO/II is dis-abled. PRO/II now requires an explicit WATER statement to set DECANT=ON. Regardless of whether or not water decant is desired, Invensys Process Systems recommends always using an explicit WATER statement when using user-added thermodynamic methods.

To set the WATER DECANT option through the GUI Open the Input menu and select Thermodynamic Data.

In the dialog box that opens, highlight any thermodynamic method from the Defined Systems list box and click the Modify button.

In the Thermodynamic Data - Modification dialog box that opens, click the Water Options button to open the Thermody-namic Data - Water Options dialog box.

To set DECANT=OFF, un-check the Decant Water as a Pure Phase check box.

This option is available only when the METHOD set (selected in the Defined System list box) supports water decanting.

When water is treated as a separate system (i.e., DECANT=ON), the system pressure is reduced by the corresponding water partial pres-sure and all computations are carried out on a water-free basis. The water vapor is assumed to form an ideal vapor mixture with the hydrocarbon and light gas vapor. When water partial pressure reaches the saturation pressure, an ideal liquid phase consisting of pure water will be formed. Water will dissolve in the hydrocarbon liquid phase up to the saturation limit.

The expression for water K-values is as follows:

KwPw

0

Xs∏--------------= (16-1)


where:

Pw0 =vapor pressure of water

Π =system pressure

XS =solubility of the water in the hydrocarbon liquid

Use of KDECNT FlagInteger flag KDECNT in common UTHERX allows a user-added sub-routine to determine if water DECANT is ON or OFF, and also locates the position of water in the component list. Table 16-4 shows the significance of the KDECNT value.

Table 16-4: Significance of KDECNT ValueValue of KDECNT Significance

Zero Water decant is OFF

Non-Zero(positive)

Water decant is ON. The value of KDECNT is the internal order number of water in the component list.

Note: Water decant does not require water to be in component posi-tion number 1. Therefore, it is important to know the posi-tion of water in the component list.

Water Decant In User-Added K-Value MethodsVapor and liquid compositions pass to user-added K-value subrou-tines through arrays XVV and XLL in common UTHERX. The values in these arrays are on a dry basis when DECANT is ON.

Note: Compositions will be normalized to be on a water-free basis when water DECANT is ON.

When water decant is ON, the user must return the following:

XKV( KDECNT ) K-value of water.

DRVX( KDECNT ) Derivative for water (as required).

YXSAT Saturation vapor mole fraction for water at TEMPX and PRESX.

XXSOL Solubility of water in non-aqueous liquid phase expressed as molar fraction of water at saturation at TEMPX and PRESX.


Water Decant In Other User-Added Thermodynamic PropertiesWhen water DECANT is ON, all thermodynamic properties of the free water decant phase (enthalpy, entropy, etc.) are calculated using special water property methods. This includes streams containing H2O as the only (single) component.

Compositions of vapor and non-aqueous liquid phases are com-puted on a wet basis. Compositions include (dissolved) water.

Therefore, when water is present in the vapor or liquid, the user should calculate the property values for the water component using subroutine UH2OP. The internal-order position of water when decant is ON is available in variable KDECNT.

User-added Water Enthalpy With DECANT=ON

User-added subroutines UKHSx allow calculating k-values, enthalpy, and entropy with user-supplied methods. The calculations include water when DECANT=OFF. However, with DECANT=ON, water properties normally are computed independently using inter-nal correlation. Routine UH2OP calls the declared property methods to compute properties for pure water, which historically did not include user-added methods.

Starting with PRO/II version 8.2, it now is possible to use the same user-added water enthalpy method when DECANT=ON. In keyword input, declare a user-added method to compute enthalpy for all components. Then, set DECANT=ON and declare the enthalpy method for water as USER. The following is a keyword example.

THERMOMETHOD SYSTEM=SRK, ENTHALPY=U6

WATER DECANT=ON, ENTHALPY=USERIn the input sample above, ENTHALPY=U6 on the METHOD statement

specifies user-added subroutine UKHS6 to compute enthalpy.

The ENTHALPY=USER entry on the WATER statement specifies com-puting water enthalpy using the user-added subroutine declared for the METHOD statement. In this sample, that is user-added subroutine UKHS6. Now, routine UKHS6 will com-puter water enthalpy when DECANT = ON or OFF.

Example 16-1: Water Decant Property CalculationsThis example assumes water DECANT is ON, so free water is han-dled as a separate phase. This example also illustrates use of the FACTOR common for unit conversion, the XPROPX common for


access to component library numbers, and subroutine UH2OP to cal-culate pure water properties. Specific usage information, including descriptions of the argument call lists, appears in Chapter 15, Inter-facing Software.

SUBROUTINE UKHS1 . . . INCLUDE ‘PMXUSR.CMN” ! Brings in MAXCN INCLUDE ‘UTHERX.CMN’ ! Brings in thermo data INCLUDE ‘XPROPX.CMN’ ! Brings in component data INCLUDE ‘FACTOR.CMN’ ! Brings in conversion factors!! Perform this calculation ONLY if DECANT is ON! IF( KDECNT .GT. 0 ) THEN!! Use subroutine UH2OP to get water Vapor Pressure! CALL UH2OP( 4, 1, TEMPX, PRESX, & TDELTX, VPW, TDERIV )!! Use TCONVT and TFAC from common FACTOR to! convert TEMPX to degrees F! TDEGF = (TEMPX + TCONVT)* TFAC - 459.6D+0 IF( TDEGF .LE. 0.0D+0 ) TDEGF = 0.01D+0!! Compute XXSOL (exponent XEXP is REAL(4))! XEXP = (-9.0306 + 3.072 * ALOG10( TDEGF)) XXSOL = 10.0D+0 ** XEXP!! Compute YXSAT! YXSAT = VPW / PRESR!! Compute Water K-value and derivative dK/dT! XKV(KDECNT) = YXSAT / XXSOL DRVX(KDECNT) = XKV(KDECNT) * TDERIV END IF

Example 16-2: Regular Solution Theory K-Value Method This subroutine calculates equilibrium K-values with the expression:

KiγiPi

o

P----------= (16-2)

where:


γi = liquid phase activity coefficient for component i

Pio = vapor pressure for component i

P = system pressure

Activity coefficients are calculated with the Hildebrand equation:

γilnVi

L δi δm–( )2

RT-------------------------------= (16-3)

where:

ViL = liquid molal volume for component i

δi = solubility parameter for component i

R = gas constant

T = temperature

and:

δmΣXiVi

Lδi

ΣXiViL

--------------------= (16-4)

Liquid molal volumes and solubility parameters for each compo-nent are entered as constants through the PRO/II keyword input file with liquid molal volumes entered as TDATA( 1 ) - (300) and solubil-ity parameters as TDATA( 301 ) - (600).

Allowance has been made to treat free water as a separate phase.

FORTRAN Listing

UKHS4.FOR—User-Added K-Value Method Using Regular Solution Theory SUBROUTINE UKHS4! INCLUDE ‘PMXUSR.CMN’! This subroutine calculates K-values using! Regular Solution Theory. Water may be! handled as a separate phase by using the! DECANT=ON option.! INCLUDE ‘FACTOR.CMN’ ! Conversion factors INCLUDE ‘UTHERX.CMN’ ! Thermo data! INCLUDE ‘CUDATA.CMN’ ! User-input data!


REAL(4) :: STREAM(MAXCN+10), VPS(MAXCN), & VMOLE(MAXCN), SOLU(MAXCN)! KDCALL = 1 ! Requests using new UTHERX! JXXFLG = 0 ! Initialization ZXX1 = 0.0D+0 ZXX2 = 0.0D+0!! Handle PRO/II request for component! dependency status.! Setting JXXFLG = 3 informs PRO/II that! this is a liquid activity method.! IF( IXXFLG .EQ.-1 ) THEN JXXFLG = 3 GO TO 999 END DO! ! Initialize local variables and arrays! TDERIV = 0.0D+0 STREAM( 1 : MAXCN + 10 ) = 0.0D+0 VPS( 1 : MAXCN ) = 0.0D+0 VMOLE( 1 : MAXCN ) = 0.0D+0 SOLU( 1 : MAXCN ) = 0.0D+0! ! Set up component data! Molar Volume are in TDATA( 1-300)! Solubility parameters in TDATA(301-600)! but! The data are in PRINT order. Rearrange! into INTERNAL order. Use routine! COINUM to obtain internal numbers.! DO iCPrint = 1, NOCZ CALL COINUM( iCPrint, IS, iCintern ) VMOLE(iCintern) = TDATA(iCPrint) SOLU( iCintern) = TDATA(iCPrint + 300) END DO! ! Case 0: PRO/II requested initial K values! IF( IXXFLG .EQ. 0 ) THEN JXXFLG = 0 ! Tell PRO/II to generate GO TO 999 ! initial K-values! ! Case N : PRO/II requested a property other


! than K-values ! ELSE IF( IXXFLG .NE. 1 ) THEN JXXFLG = 99 ! fatal error return flag GO TO 999 END IF!! Case 1: PRO/II requested K-values! First fetch Component Vapor Pressures! from PRO/II.! STREAM(1) = 1.0D+0 ! Initialize STREAM STREAM(2) = TEMPX STREAM(3) = PRESX DO I = 4, 10 STREAM(I) = 0.0D+0 END DO DO I = 1, NOCZ STREAM(I+10) = 1.0D+0 END DO ITYPE = 1 IFAZE = 1! CALL TTPROP( ITYPE,IFAZE,VPS,STREAM, IERR )! ! Compute Mixture Properties! SOLM = 0.0D+0 VOLM = 0.0D+0 DO I=1,NOCZ VOLI = XLL(I) * VMOLE(I) VOLM = VOLM + VOLI SOLM = SOLM + VOLI * SOLU(I) END DO IF( VOLM .GT. 0.0D+0 ) SOLM = SOLM / VOLM PPHC = PRESX!! - If WATER DECANT = ON, subtract the partial! pressure of the free water! IF( KDECNT .GT. 0 ) THEN CALL H2OP( 4, 1, TEMPX, PRESX, & TDELTX, VPS(KDECNT), TDERIV ) PPHC = PRESX * (1.0D+0 - XVV(KDECNT)) END IF! ! Compute K-values


! TDEGK = (TEMPX + TCONVT) * TFAC / XKTOR! DO I=1,NOCZ GAMMA = EXP(VMOLE(I) & * ( SOLU(I)-SOLM)**2 & / (RCONST * TDEGK) ) XKV(I) = GAMMA * VPS(I) /PPHC END DO!! - Handle DECANTED WATER, if applicable! IF( KDECNT .GT. 0 ) THEN DEGF = (TEMPX + TCONVT) * TFAC - FTOR DEGF = AMAX1(DEGF, 0.01D+0) xLogF = LOG10( DEGF ) xExp = -9.0306D+0 + 3.072D+0 * XLogF Base10= 10.0D+0 XXSOL = Base10 ** ( xExp ) YXSAT = VPS( KDECNT ) / PRESX XKV( KDECNT ) = YXSAT / XXSOL END IF!! Compute temperature derivatives from! the analytical expression (dKdT)! Skip calculations if delta T is near zero! IF( ABS( TDELTX ) .GT. 1.0D-25 ) THEN DO I = 1, NOCZ DRVX(I) = -XKV(I) * VMOLE(I) & * (SOLU(I) - SOLM)**2 & / (RCONST * TDEGK**2) END DO!! Adjust for any Water Decant! IF( KDECNT .GT. 0 ) THEN DRVX(KDECNT) = XKV(KDECNT) * TDERIV END IF END IFC 999 CONTINUE ! Error return point END SUBROUTINE UKHS4

PRO/II Keyword Input FileTITLE PROB=UKHS4, PROJ=UKHS4, USER=SIMSCI, & DATE=MAR-2006


$ TESTS UKHS4 DESC TEST A USER REGULAR SOLUTION METHOD DESC THE FIRST AND THIRD FLASHES SHOULD GIVE DESC THE SAME RESULTS WHILE THE SECOND FLASH DESC SHOULD DECANT WATERCOMPONENT DATA LIBID 1,H2O/2,C1 /3,C2/4,IC4/5,NC4/ & 6,IC5/7,NC5/ 8,NC8,, C6 PLUS, & BANK=PROII_8.3:SIMSCI, PROII_8.3:PROCESSTHERMO DATA METHOD KVALUE=U4, ENTH=LK, DENS=LK, SET=U4REG WATER DECANT=OFF KVALUE$ Liquid Volumes stored in 1-300,$ Solubility parameters in 301-600$ UDATA 1,18.069/ 37.97/ 59.23/ 105.24/ 96.48/ & 117.1 /116.05/ 163.01 / & 301, 23.37/ 5.67/ 6.06 / 6.145/ 6.697/ & 6.775/ 7.04/ 7.53$ METHOD SYSTEM=U4, ENTH=LK, DENS=LK, & ENTR=NONE, SET=U4DEC WATER DECANT=ON KVALUE$ Liquid Volumes stored in 1-300,$ Solubility parameters in 301-600$ UDATA 1,18.069/37.97/ 59.23/105.24/ 96.48/ & 117.1 /116.05/ 163.4/ & 301,23.37/ 5.67/ 6.06/ 6.145/ 6.697/ & 6.775/ 7.04/ 7.53$ METHOD SYSTEM=REGULAR, ENTH=LK,DENS=LK, & ENTR=NONE, NAME=REGUSTREAM DATA$ Feeds for User Thermo Method PROP STRM=1, TEMP=200, PRES=150, & COMP=2,100/3,100/4,75/5,75/ & 6, 54/7, 45/8,10 PROP STRM=20, TEMP=350, PRES=150, COMP=1,1000$ Feeds for PRO/II thermo method PROP STRM=1A, TEMP=200, PRES=150, & COMP=2,100/3,100/4,75/5,75/ & 6, 54/7, 45/8,10 PROP STRM=20A, TEMP=350, PRES=150, COMP=1,1000UNIT OPERATIONS FLASH KPRINT, NAME=USER DRY, UID=F1


FEED 1 PROD L=2, V=3 ISO TEMP=150,PRES=100 METHOD SET=U4REG FLASH KPRINT,NAME=USER DECANT,UID=F2 FEED 1,20 PROD L=4,V=5,W=6 ISO TEMP=150,PRES=100 METHOD SET=U4DEC FLASH KPRINT,NAME=REGULAR DRY,UID=F3 FEED 1A PROD L=7,V=8 ISO TEMP=150,PRES=100 METHOD SET=REGUEND

Partial PRO/II Output FileSIMULATION SCIENCES INC. R PAGE P-3PROJECT UKHS4 PRO/II 5.0 UAS 386/EMPROBLEM UKHS4 OUTPUT SIMSCI FLASH DRUM SUMMARY JUN99====================================================================== FLASH ID F1 F2 F3 NAME USER DRY USER DECANT REGULAR DRY FEEDS 1 1 1A 20 PRODUCTS VAPOR 3 5 8 LIQUID 2 4 7 WATER 6 TEMPERATURE, F 150.000 150.000 150.000 PRESSURE, PSIA 100.000 100.000 100.000 PRESSURE DROP, PSI 50.000 50.000 50.000 MOLE FRAC VAPOR 0.93136 0.30654 0.93132 MOLE FRAC LIQUID 0.06864 0.69346 0.06868 MOLE FRAC MW SOLID 0.00000 0.00000 0.00000 DUTY, MM BTU/HR -0.70081 -4.00258 -0.70084 FLASH TYPE ISOTHERMAL ISOTHERMAL ISOTHERMAL VAPOR-LIQUID COMPOSITIONS AND K-VALUES FOR UNIT 1, ‘F1’ COMPONENT VAPOR LIQUID K-VALUE --------- -------- ------- ---------- 1 H2O 0.00000 0.00000 4.9000E+01 2 C1 0.23373 0.00255 9.1770E+01 3 C2 0.23270 0.01663 1.3992E+01 4 IC4 0.16776 0.10422 1.6097E+00 5 NC4 0.16418 0.15278 1.0746E+00 6 IC5 0.10901 0.23485 4.6417E-01


7 NC5 0.08754 0.24053 3.6393E-01 8 C6 PLUS 0.00508 0.24844 2.0454E-02

VAPOR-LIQUID COMPOSITIONS AND K-VALUES FOR UNIT 2, ‘F2’ COMPONENT VAPOR LIQUID K-VALUE ----------- -------- -------- ---------- 1 H2O 0.03697 0.00451 8.1945E+00 2 C1 0.22344 0.00243 9.2033E+01 3 C2 0.22258 0.01586 1.4036E+01 4 IC4 0.16136 0.09973 1.6180E+00 5 NC4 0.15835 0.14710 1.0765E+00 6 IC5 0.10622 0.22847 4.6492E-01 7 NC5 0.08566 0.23540 3.6389E-01 8 C6 PLUS 0.00543 0.26651 2.0360E-02 VAPOR-LIQUID COMPOSITIONS AND K-VALUES FOR UNIT 3, ‘F3’ COMPONENT VAPOR LIQUID K-VALUE --------- --------- ------- ---------- 1 H2O 0.00000 0.00000 4.9053E+01 2 C1 0.23374 0.00255 9.1757E+01 3 C2 0.23270 0.01673 1.3912E+01 4 IC4 0.16776 0.10422 1.6097E+00 5 NC4 0.16418 0.15279 1.0746E+00 6 IC5 0.10900 0.23485 4.6415E-01 7 NC5 0.08753 0.24052 3.6393E-01 8 C6 PLUS 0.00508 0.24835 2.0446E-02

Enthalpy and Entropy CalculationsEnthalpies and entropies may be calculated for streams based on temperature, pressure, and composition (either liquid or vapor). See “User-added Water Enthalpy With DECANT=ON” on page 16-14 for more information about computing water enthalpy.

Calculated enthalpies must be returned to PRO/II in dimensionless form, that is, divided by the quantity RT where:

R= gas constant in units consistent with the problem input dimensional units for enthalpy and those units used for temperature.

T= temperature

Calculated enthalpies may be given in either of two forms, namely:

H H*–RT

----------------- HΔRT--------= (16-5)

or


HΔRT-------- (16-6)

where:

H*= ideal gas enthalpy

When form (16-5) is used, PRO/II will always compute H*:

H* xiHi*

i 1=

No. Comps.

∑= (16-7)

and

xi = mole fraction for component

Hi* = ideal gas enthalpy for component

Two enthalpy values must be computed, with one at a temperature increment above the stated temperature, where the increment is passed through a common block. These two values are used by PRO/II to calculate the heat capacity for the stream at the stated temperature.

User-computed enthalpies may be used for any unit operation cal-culation, either user- or PRO/II defined. When rigorous distillation is to be used in conjunction with user-computed enthalpies, it is mandatory that dimensionless partial derivatives of enthalpy with respect to composition be computed for each component:

H xiΔ⁄ΔRT

-------------------

Entropies may also be computed for streams based on temperature, pressure, and composition. Calculated values are returned on a per mole basis in dimensionless form, that is, divided by the gas con-stant, R.

Entropies may be computed in two forms (similar to enthalpies):

SΔ xiΔ⁄RT

------------------Si

* S–RT

--------------= (16-8)

where:

S*= ideal gas entropy

or

S/R (16-9)


When equation (16-8) is used, PRO/II computes the ideal gas entropy:

S* xiSi*

i 1=

No. Comps.

∑= (16-10)

where:

xi = mole fraction for component i

Si* = ideal gas entropy for component i

Note: S* is computed from the ideal gas enthalpy equation. Ideal gas enthalpy equations must be available for all compo-nents when S* is to be computed.

Example 16-3: Petroleum Liquid and Vapor Enthalpy Calcula-tions

Enthalpies for saturated liquids and vapors are to be generated using the following relationships:

Liquid heat capacities are calculated using equation (16-11):

Cp 0.6811 0.308SG–( ) 0.000815T 0.000306SG–+[ ] .

0.055K 0.35+( )= (16-11)

where:

Cp= heat capacity, Btu/lb °F

SG = specific gravity at 60°F

K = Watson K factor = ABP( ) SG( )⁄3

T = temperature, °F

ABP = average boiling point, R

The latent heat at the normal boiling point is calculated using the following:

λb = NBP (8.75 + 4.571 log (NBP)) (16-12)

where:

λb = latent heat, cal/g-mole

NBP = normal boiling point, K


Finally, the latent heat at any temperature T is calculated using the following:

λλb-----

Tc T–Tc Tb–-----------------⎝ ⎠

⎛ ⎞.38

= (16-13)

where:

Tc = critical temperature, R

T = temperature, R

Tb = normal boiling point, R

Liquid enthalpies are calculated by integration of equation (16-11) from 32°F to the desired temperature. Vapor enthalpies are derived by adding the latent heat to the liquid enthalpies.

The mixture critical temperature and normal boiling point are calcu-lated as mole-average properties.

The Watson K factor is computed based on the average normal boil-ing point of the mixture.

PRO/II furnishes (ΔH/Δxi) terms based on the calculated enthalpy and the component ideal gas enthalpies as supplied from the library (for defined components) or generated by PRO/II’s petroleum char-acterization methods. Allowance has been made to calculate water as a separate phase.

FORTRAN Listing

UKHS3.FOR — User-Added Enthalpy Method SUBROUTINE UKHS3! REAL(8), PARAMETER :: DZ0 = 0.0D+0 INCLUDE ‘FACTORS.CMN’! conversion factors INCLUDE ‘PMXUSR.CMN’ ! brings in MAXCN INCLUDE ‘XPROPX.CMN’ ! component data INCLUDE ‘UTHERX.CMN’ ! thermo data! CHARACTER(LEN=78) :: cLine REAL(8) :: SGL, BPL, WTL, & TCL, WATERX, TOT!! - Statement function to calculate enthalpy! from the Cp equation


XXXH(T,XK,SG) = (0.055*XK + 0.35) & * ( (0.6811 - 0.308*SG) * (T-32) & + 0.5 * ( 0.000815D+0 - 0.000306D+0 & * SG) * (T * T - 1024.0D+0) )! -!! - Set JXXFLG to indicate H/RT is returned JXXFLG = 1 KDCALL = 1! - Test for correct use of this subroutine! Error if request is not for enthalpy IF( IXXFLG .NE. 2 ) THEN cLine = “*** ERROR-User Method U3 “ & // “ calculates enthalpies only -” WRITE( KUOUT, “( A )” ) cLine cLIne = “ but IXXFLG = “ WRITE( KUOUT, “(A,I3)” ) cLine, IXXFLG JXXFLG = 99 GO TO 99 END IF!! - Compute Liquid Enthalpy! SGL = DZ0 ! initialize summation BPL = DZ0 ! variables WTL = DZ0 TCL = DZ0 WATERX = DZ0 TOT = DZ0 Setup : DO I = 1, NOCZ ! Skip decant component IF( I .EQ. KDECNT) CYCLE Setup ! Test IFPHZ for Vapor phase IF( IFPHZ .EQ. 1 ) THEN FLO = XVV( I ) ! Vapor phase ELSE FLO = XLL( I ) ! Liquid phase END DO SGL = SGL + XMW(I) * FLO / DENS(I) WTL = WTL + XMW(I) * FLO BPL = BPL + BP(I) * FLO TCL = TCL + TC(I) * FLO TOT = TOT + FLO END DO Setup SGL = ( WTL / SGL ) / SPGFAC! ! Normalizing Molec Wt, NBP, and TC


! Handle water when DECANT = ON by ! Variable WATERX = water mole fraction! IF( KDECNT .GT. 0 ) THEN WTL = WTL / TOT ! molec wt BPL = BPL / TOT ! NBP TCL = TCL / TOT ! Tcrit IF( IFPHZ .EQ. 1 ) THEN WATERX = XVV( KDECNT ) ELSE WATERX = XLL( KDECNT ) END IF END IF!! Convert Tcrit and Tbp to Rankine! Note Tcrit and Tbp already are in! absolute temperature units ! TCL = TCL * TFAC BPL = ( BPL + TCONVT ) * TFAC!! Compute Watson K of the mixture! WK = BPL ** 0.33333 / SGL!! Convert temperatures to Fahrenheit for! use in the Cp equation! T1 = ( TEMPX + TCONVT ) * TFAC - FTOR T2 = ( TEMPX + TDELTX + TCONVT ) * TFAC & - FTOR! ! Integrate Cp equation to compute enthalpy! Basis is 32 F liquid ! HSX1 = XXXH ( T1, WK, SGL ) HSX2 = XXXH ( T2, WK, SGL )! ! Convert temperatures back to Rankine ! for Latent Heat calculations ! T1 = T1 + FTOR T2 = T2 + FTOR! ! Convert enthalpy to dimensionless form! ( H/RT ) ! HSX1 = HSX1 * WTL / ( RCONST * T1 )


HSX2 = HSX2 * WTL / ( RCONST * T2 )!! Vapor! 1. Compute Latent Heat in Btu/lb-mole! at NBP using Kistiakowski eqn! XLAMBP = latent heat! 2. Use Watson corr. to determine! DH1 = latent heat at T1! DH2 = latent heat at T2! 3. Add latent heat to liquid! HSX1 = vapor enthalpy at T1! HSX2 = vapor enthalpy at T2! IF ( IFPHZ .EQ. 1 ) THEN XLAMBP = BPL * ( 8.75 + & 4.571*LOG10( BPL / XKTOR ) )! DH1 = XLAMBP * ( (1.0D+0 - T1 / TCL) & / (1.0D+0 - BPL/TCL) ) ** 0.38 DH2 = XLAMBP * ( (1.0D+0 - T2 / TCL) & / (1.0D+0 - BPL/TCL) ) ** 0.38 HSX1 = HSX1 + DH1 / ( RCONST * T1 ) HSX2 = HSX2 + DH2 / ( RCONST * T2 ) END IF!! Decant Water (only when DECANT = ON)! 1. Call H2UOP for water enth at T1, T2! 2. Convert H2O H to dimensionless form! 3. Add water H to get total enthalpy! IF( KDECNT .GT. 0 ) THEN DELTA = DZ0 CALL UH2OP( 2, IFPHZ, TEMPX, & PRESX, DELTA, HW1, T3 ) CALL UH2OP( 2, IFPHZ, TEMPX+TDELTX, & PRESX, DELTA, HW2, T3 ) HW1 = HW1 * HSFAC / (RCONST * T1) HW2 = HW2 * HSFAC / (RCONST * T2) HSX1 = HSX1*TOT + HW1*WATERX HSX2 = HSX2*TOT + HW2*WATERX END IF 99 CONTINUE END SUBROUTINE UKHS3


PRO/II Keyword Input FileTITLE PROB=USERADD, PROJ=UKHS3, USER=SIMSCI, & DATE=Mar-2006 DESC Input to test sample UKHS3 routineCOMPONENT DATA LIBID 1,H2OTHERMO DATA METHOD KVALUE=GS, ENTHALPY=U3, ENTR=NONE, & DENS(L)=IDEAL, DENS(V)=SRKSTREAM DATA PROP STREAM=1, RATE(V)=16, TEMP=300, & PRES=25 D86 STREAM=1, DATA=0,150/10,230/50,273/ & 90,320/100,395 API STREAM=1, AVG=51.3$ PROP STREAM=2, TEMP=300, PRES=150, & COMP=1, 100, RATE(W)=200 UNIT OP DATA FLASH UID=F-1 $ DRY FLASH FEED 1 PROD L=3,V=4 ADIA FLASH UID=F-2 $ WET FLASH FEED 1,2 PROD L=5,V=6 ADIAEND


Partial PRO/II OutputPROJECT UKHS3 PRO/II UAS 386/EMPROBLEM USERADD OUTPUT SIMSCI STREAM MOLAR COMPONENT RATES ============================================================== FLASH ID F-1 F-2 NAME FEEDS 1 1 2 PRODUCTS VAPOR 4 6 LIQUID 3 5 TEMPERATURE, F 300.000 219.166 PRESSURE, PSIA 25.000 25.000 PRESSURE DROP, PSI 0.000 0.000 MOLE FRAC VAPOR 0.32590 0.28149 MOLE FRAC TOTAL LIQUID 0.67410 0.71851 MOLE FRAC H/C LIQUID 0.67410 0.28919 MOLE FRAC FREE WATER 0.00000 0.42933 DUTY, MM BTU/HR 0.00000 0.00000 FLASH TYPE ADIABATIC-P ADIABATIC-P

PROJECT UKHS3 PRO/II UAS 386/EMPROBLEM USERADD OUTPUT SIMSCI STREAM MOLAR COMPONENT RATES ============================================================== STREAM ID 1 2 3 4 NAME PHASE MIXED WATER DRY LIQ DRY VAP FLUID RATES, LB-MOL/HR 1 H2O 0.0000 11.1019 0.0000 0.0000 2 NBP 116 0.2066 0.0000 0.0566 0.1501 3 NBP 140 0.2544 0.0000 0.0839 0.1705 4 NBP 166 0.2384 0.0000 0.0949 0.1435 5 NBP 189 0.2362 0.0000 0.1100 0.1261 6 NBP 213 0.3354 0.0000 0.1807 0.1547 7 NBP 239 0.5490 0.0000 0.3391 0.2100 8 NBP 266 2.1353 0.0000 1.4901 0.6452 9 NBP 281 1.7531 0.0000 1.2936 0.4596 10 NBP 311 0.4020 0.0000 0.3248 0.0771 11 NBP 337 0.2575 0.0000 0.2208 0.0367 12 NBP 362 0.2016 0.0000 0.1807 0.0209 13 NBP 387 0.1810 0.0000 0.1676 0.0134 14 NBP 402 0.0295 0.0000 0.0277 1.7748E-03 TOTAL RATE, LB-MOL/HR 6.7800 11.1019 4.5704 2.2096 TEMPERATURE, F 300.0000 300.0000 300.0000 300.0000 PRESSURE, PSIA 25.0000 150.0000 25.0000 25.0000 ENTHALPY, MM BTU/HR 0.1393 0.0538 0.0763 0.0630


MOLECULAR WEIGHT 113.9263 18.0150 117.5334 106.4653 MOLE FRAC VAPOR 0.3259 0.0000 0.0000 1.0000 MOLE FRAC TOTAL LIQ 0.6741 1.0000 1.0000 0.0000 MOLE FRAC H/C LIQUID 0.6741 0.0000 1.0000 0.0000 MOLE FRAC FREE WATER 0.0000 1.0000 0.0000 0.0000

PROJECT UKHS3 PRO/II UAS 386/EMPROBLEM USERADD OUTPUT SIMSCI STREAM MOLAR COMPONENT RATES ============================================================== STREAM ID 5 6 NAME PHASE WET LIQUID WET VAPOR FLUID RATES, LB-MOL/HR 1 H2O 7.7220 3.3799 2 NBP 116 0.0620 0.1446 3 NBP 140 0.0948 0.1596 4 NBP 166 0.1095 0.1289 5 NBP 189 0.1282 0.1080 6 NBP 213 0.2105 0.1249 7 NBP 239 0.3915 0.1576 8 NBP 266 1.6908 0.4446 9 NBP 281 1.4514 0.3018 10 NBP 311 0.3560 0.0460 11 NBP 337 0.2374 0.0202 12 NBP 362 0.1910 0.0106 13 NBP 387 0.1747 6.2863E-03 14 NBP 402 0.0287 7.9667E-04 TOTAL RATE, LB-MOL/HR 12.8483 5.0335 TEMPERATURE, F219.1656219.1656 PRESSURE, PSIA 25.0000 25.0000 ENTHALPY, MM BTU/HR 0.0831 0.1100 MOLECULAR WEIGHT 57.5859 46.1978 MOLE FRAC VAPOR 0.0000 1.0000 MOLE FRAC TOTAL LIQUID 1.0000 0.0000 MOLE FRAC H/C LIQUID 0.4025 0.0000 MOLE FRAC FREE WATER 0.5975 0.0000


PROJECT UKHS3 PRO/II UAS 386/EMPROBLEM USERADD OUTPUT SIMSCI STREAM SUMMARY====================================================================== STREAM ID 1 2 3 4 NAME PHASE MIXED WATER DRY LIQ DRY VAP

——- TOTAL STREAM ——- ---------- ---------- ---------- ---------- RATE, LB-MOL/HR 6.780 11.102 4.570 2.210 M LB/HR 0.772 0.200 0.537 0.235 TEMPERATURE, F 300.000 300.000 300.000 300.000 PRESSURE, PSIA 25.000 150.000 25.000 25.000 MOLECULAR WEIGHT 113.926 18.015 17.533 106.465 ENTHALPY, MM BTU/HR 0.139 5.38E-02 7.63E-02 6.29E-02 BTU/LB 180.359 269.082 142.126 267.665 MOLE FRACTION LIQUID 0.67410 1.000 1.000 0.000 MOLE FRAC FREE WATER 0.000 1.000 0.000 0.000

——- TOTAL VAPOR ——— RATE, LB-MOL/HR 2.210 N/A N/A 2.210 M LB/HR 0.235 N/A N/A 0.235 M FT3/HR 0.681 N/A N/A 0.681 STD VAP RATE(1), M FT3/HR 0.839 N/A N/A 0.839 MOLECULAR WEIGHT 106.465 N/A N/A 106.465 ENTHALPY, BTU/LB 267.665 N/A N/A 267.665 CP, BTU/LB-F 0.440 N/A N/A 0.440 DENSITY, LB/M FT3 345.276 N/A N/A 345.276 Z (FROM DENSITY) 0.9456 N/A N/A 0.9456

——- TOTAL LIQUID ——- RATE, LB-MOL/HR 4.570 11.102 4.570 N/A M LB/HR 0.537 0.20 0.537 N/A FT3/HR 13.058 3.490 13.058 N/A GAL/MIN 1.628 0.435 1.628 N/A STD LIQ RATE, FT3/HR 11.072 3.208 11.072 N/A MOLECULAR WEIGHT 117.533 18.015 117.533 N/A ENTHALPY, BTU/LB 142.126 269.082 142.126 N/A CP, BTU/LB-F 0.607 1.013 0.607 N/A DENSITY, LB/FT3 41.137 57.305 41.137 N/A Z (FROM DENSITY) 8.7614E-0 5.7842E-03 8.7614E-03 N/A (1) STANDARD VAPOR VOLUME IS 379.49 FT3/LB-MOLE (60 F AND 14.696 PSIA)


====================================================================== STREAM ID 1 2 3 4 NAME PHASE MIXED WATER DRY LIQ DRY VAP ——- DRY STREAM ——- ---------- ---------- ---------- ---------- RATE, LB-MOL/HR 6.780 N/A 4.570 2.210 M LB/HR 0.772 N/A 0.537 0.235 STD LIQ RATE, FT3/HR 16.000 N/A 11.072 4.928 MOLECULAR WEIGHT 113.926 N/A 117.533 106.465 MOLE FRACTION LIQUID 0.6741 N/A 1.0000 0.0000 REDUCED TEMP (KAYS RULE) 0.7150 N/A 0.7062 0.7339 PRES (KAYS RULE) 0.0588 N/A 0.0602 0.0561 ACENTRIC FACTOR 0.3182 N/A 0.3284 0.2973 WATSON K (UOPK) 11.618 N/A 11.618 11.618 STD LIQ DENSITY, LB/FT3 48.276 N/A 48.517 47.734 SPEC GRAVITY 0.7741 N/A 0.7779 0.7654 API GRAVITY 51.300 N/A 50.392 53.374

——— DRY VAPOR ———- RATE, LB-MOL/HR 2.210 N/A N/A 2.210 M LB/HR 0.235 N/A N/A 0.235 M FT3/HR 0.681 N/A N/A 0.681 STD VAP RATE(1), M FT3/HR 0.839 N/A N/A 0.839 SPECIFIC GRAVITY (AIR=1.0) 3.676 N/A N/A 3.676 MOLECULAR WEIGHT 106.465 N/A N/A 106.465 CP, BTU/LB-F 0.440 N/A N/A 0.440 DENSITY, LB/M FT3 345.276 N/A N/A 345.276

——— DRY LIQUID ——— RATE, LB-MOL/HR 4.570 N/A 4.570 N/A M LB/HR 0.537 N/A 0.537 N/A FT3/HR 13.058 N/A 13.058 N/A GAL/MIN 1.628 N/A 1.628 N/A STD LIQ RATE, FT3/HR 11.072 N/A 11.072 N/A SPECIFIC GRAVITY (H2O=1.0) 0.7779 N/A 0.7779 N/A MOLECULAR WEIGHT 117.533 N/A 117.533 N/A CP, BTU/LB-F 0.607 N/A 0.607 N/A DENSITY, LB/FT3 41.137 N/A 41.137 N/A (1) STANDARD VAPOR VOLUME IS 379.49 FT3/LB-MOLE (60 F AND 14.696 PSIA)


PROJECT UKHS3 PRO/II UAS 386/EMPROBLEM USERADD OUTPUT SIMSCI STREAM SUMMARY============================================================== STREAM ID 5 6 NAME PHASE WET LIQUID WET VAPOR ——- TOTAL STREAM ——- RATE, LB-MOL/HR 12.848 5.033 M LB/HR 0.740 0.233 TEMPERATURE, F 219.166 219.166 PRESSURE, PSIA 25.000 25.000 MOLECULAR WEIGHT 57.586 46.198 ENTHALPY, MM BTU/HR 8.311E-02 0.110 BTU/LB 112.335 473.109 MOLE FRACTION LIQUID 1.00000 0.00000 MOLE FRACTION FREE WATER 0.59752 0.00000 ——- TOTAL VAPOR ——— RATE, LB-MOL/HR N/A 5.033 M LB/HR N/A 0.233 M FT3/HR N/A 1.439 STD VAP RATE(1), M FT3/HR N/A 1.910 MOLECULAR WEIGHT N/A 46.198 ENTHALPY, BTU/LB N/A 473.109 CP, BTU/LB-F N/A 0.440 DENSITY, LB/M FT3 N/A 161.601 Z (FROM DENSITY) N/A 0.9810 ——- TOTAL LIQUID ——- RATE, LB-MOL/HR 12.848 N/A M LB/HR 0.740 N/A FT3/HR 16.039 N/A GAL/MIN 2.000 N/A STD LIQ RATE, FT3/HR 14.621 N/A MOLECULAR WEIGHT 57.586 N/A ENTHALPY, BTU/LB 112.335 N/A CP, BTU/LB-F 0.645 N/A DENSITY, LB/FT3 46.129 N/A Z (FROM DENSITY) 4.2840E-03 N/A (1) STANDARD VAPOR VOLUME IS 379.49 FT3/LB-MOLE (60 F AND 14.696 PSIA)


PROJECT UKHS3 PRO/II UAS 386/EMPROBLEM USERADD OUTPUT SIMSCI STREAM SUMMARY============================================================== STREAM ID 5 6 NAME PHASE WET LIQUID WET VAPOR ——— DRY STREAM ——— RATE, LB-MOL/HR 5.126 1.654 M LB/HR 0.601 0.172 STD LIQ RATE, FT3/HR 12.389 3.611 MOLECULAR WEIGHT 117.193 103.801 MOLE FRACTION LIQUID 1.0000 0.0000 REDUCED TEMP (KAYS RULE) 0.6317 0.6623 PRES (KAYS RULE) 0.0601 0.0551 ACENTRIC FACTOR 0.3274 0.2897 WATSON K (UOPK) 11.618 11.618 STD LIQ DENSITY, LB/FT3 48.492 47.535 SPECIFIC GRAVITY 0.7775 0.7622 API GRAVITY 50.485 54.151 ——— DRY VAPOR ———- RATE, LB-MOL/HR N/A 1.654 M LB/HR N/A 0.172 M FT3/HR N/A 0.471 STD VAP RATE(1), M FT3/HR N/A 0.628 SPECIFIC GRAVITY (AIR=1.0) N/A 3.584 MOLECULAR WEIGHT N/A 103.801 CP, BTU/LB-F N/A 0.596 DENSITY, LB/M FT3 N/A 364.571 ——— DRY LIQUID ——— RATE, LB-MOL/HR 5.126 N/A M LB/HR 0.601 N/A FT3/HR 13.707 N/A GAL/MIN 1.709 N/A STD LIQ RATE, FT3/HR 12.389 N/A SPECIFIC GRAVITY (H2O=1.0) 0.7775 N/A MOLECULAR WEIGHT 117.193 N/A CP, BTU/LB-F 0.561 N/A DENSITY, LB/FT3 43.829 N/A (1) STANDARD VAPOR VOLUME IS 379.49 FT3/LB-MOLE (60 F AND 14.696 PSIA)


Density Calculations

Example 16-4: Gunn-Yamada Liquid Density CalculationsFor this example, the Gunn-Yamada method is used to calculate actual liquid densities. Vapor densities correspond to those com-puted by the enthalpy or K-value subroutine (based on the correla-tions used).

For the Gunn-Yamada method:

VVr----- C

Cr------= (16-14)

where:

V, Vr=volume at desired and reference temperatures

C, Cr=density factors at desired and reference temperatures

and

C V 0( )Tr 1 ωΓTr–( )= (16-15)

where:

Γ 0.29607 0.09045Tr– 0.04842Tr2–= (16-16)

Tr = reduced temperature

ω = acentric factor

and (for 0.2 ≤ Tr ≤ 0.8)

V 0( ) 0.33593 0.33953Tr– 1.51941Tr2+=

2.02512Tr3– 1.11422Tr

4+ (16-17)

and (for 0.8 < Tr ≤ 0.99)

V 0( ) 1 1.3 1 Tr– 1 Tr–( )log 0.50879 1 Tr–( )–+=0.91534 1 Tr–( )2– (16-18)

Mixture critical temperatures are evaluated with Kay’s rule, and the method is limited to a range: 0.2 ≤ Tr ≤ 0.99. Reference densities are computed using the pure component specific gravities at 60°F, as provided in the component data.

Reference: Gunn, R. D. and Yamada, T., 1971, AIChE J., 17:1341


FORTRAN Listing

UKHS1.FOR — User-Added Liquid Density Method SUBROUTINE UKHS1!! Compute Liquid Densities at flowing! conditions using the GUNN-YAMADA method!- INCLUDE ‘PMXUSR.CMN’ ! brings in MAXCN INCLUDE FACTOR.CMN’ ! conversion factors INCLUDE ‘XPROPX.CMN’ ! component data INCLUDE ‘UTHERX.CMN’ ! Thermo data! REAL(4) :: XVV(MAXCN), XLL(MAXCN), & XLL2(MAXCN), XKV(MAXCN), & DRVX(MAXCN) INTEGER(4) :: IFLGX(15)!! Statement functions to evaluate GAMMA and! V0 terms at given Tr’s! XXXGAM(TR) = 0.29607D+0 - 0.09045 * TR & - 0.04842 * TR * TR!! Tr from 0.2 to 0.8! XXXZOL(TR) = 0.33593D0 & - 0.33953D0 * TR + 1.51941D0 *TR * TR & - 2.02512D0 * TR * TR * TR & + 1.11422D0 * TR * TR * TR * TR!! Tr from 0.8 to 0.99! XXXZOH(TR) = 1.0D0 + 1.3D0 * (1.0D0-TR) & **0.5*LOG10(1.-TR) & -0.50879D0 * (1.0D0 - TR) & -.91534D0 * (1.-TR)*(1.0D0 - TR)!! Test that Liquid Density was requested! IF( IXXFLG .NE. 4 .OR. IFPHZ .NE. 2 )THEN JXXFLG = 99 GO TO 9999 ENDIF!! Set KDCALL = 1 (used common UTHERX)! KDCALL = 1


!! Convert pressure to psia! PSIA = (PRESX + PCONVT) * PFAC!! Convert flowing temperature to deg Rankine! TDEGR = (TEMPX + TCONVT) * TFAC!! Compute mixture molec wt, Tcrit, acentric! factor and sp.gr at 60F WTM = 0.0D0 ACEN = 0.0D0 TCRM = 0.0D0 DENM = 0.0D0 DO I = 1, NOCZ ACEN = ACEN + XLL(I) * OMEGA(I) TCRM = TCRM + XLL(I) * TC(I) DENM = DENM + XLL(I) * XMW(I)/DENS(I) WTM = WTM + XLL(I) * XMW(I) END DO! DENM = WTM / DENM!! Convert mixture density to SPGR at 60 F! SPGM = DENM / SPGFAC!! Convert TCRM to deg R (Note Tcs already! are in absolute temperature units) TCRM = TCRM * TFAC!! Evaluate Tr and compute density factor! at flowing conditions! TRF = TDEGR / TCRM!! Reset Tr if .GE. 1.! IF (TRF .GE. 1.0D0) TRF = 0.99D+0 IF (TRF .LE. 0.8D0) VZERO = XXXZOL(TRF) IF (TRF .GT. 0.8D0) VZERO = XXXZOH(TRF) CFLOW = VZERO * TRF * (1.0D0 & - (ACEN * TRF * XXXGAM(TRF)))!

! Correct Tr and correction factor at! 60 deg F (Reference temperature)


! TRR = (60.0D0 + FTOR) / TCRM!! Reset Tr if it is .GE. 1.! IF( TRR .GE. 1.0D0 ) TRR = 0.99 IF( TRR .LE. 0.8D0 ) VZERO = XXXZOL(TRR) IF( TRR .GT. 0.8D0 ) VZERO = XXXZOH(TRR) CREF = VZERO * TRR & * (1.0D0 - (ACEN *TRR *XXXGAM(TRR)))!!! Compute the flowing density in lb/ft3! DENSE = CFLOW * SPGM * 62.2997D0 / CREF!! Convert flowing density to ft3/lb mole! VOLU = WTM / DENSE!! Convert flowing density to a Z factor! ZXX2 = PSIA * VOLU / 10.731D0 / TDEGR! 9999 CONTINUE! END SUBROUTINE UKHS1


PRO/II Keyword Input FileTITLE PROB=USERADD, PROJ=UKHS1, USER=SIMSCI, & DATE=Mar-2006$$ TESTS UKHS1$COMP DATA LIBID 1, C2 / 2, C3 / 3, NC4 / 4, NC5THERMO DATA METHODS KVALUE=GS, ENTH=SRK, DENS(L)=U1, & DENS(V)=SRKSTREAM DATA PROP STRM=1, TEMP=150, PRES=150, & COMP= 25 / 25 / 25 / 25UNIT OPERATIONS FLASH FEED 1 PROD L=2, V=3 ISO TEMP=150, PRES=200 FLASH FEED 1 PROD L=4, V=5 ISO TEMP=200, PRES=150END

Partial PRO/II Output File SIMULATION SCIENCES INC. R PAGE P-5 PROJECT UKHS1 PRO/II UAS 386/EM PROBLEM USERADD OUTPUT SIMSCI STREAM SUMMARY Mar-2006============================================================== STREAM ID 1 2 3 5 NAME PHASE MIXED LIQUID VAPOR VAPOR ——- TOTAL STREAM ——- ---------- ---------- ---------- ---------- RATE, LB-MOL/HR 100.000 54.570 45.430 100.000 M LB/HR 5.111 3.134 1.977 5.111 STD LIQ RATE, FT3/HR 154.342 88.242 66.100 154.342 TEMPERATURE, F 150.000 150.000 150.000 200.000 PRESSURE, PSIA 150.000 200.000 200.000 150.000 MOLECULAR WEIGHT 51.111 57.437 43.511 51.111ENTHALPY, MM BTU/HR 0.778 0.221 0.398 1.164 BTU/LB 152.246 70.536 01.417 227.785


MOLE FRACTION LIQUID 0.3247 1.0000 0.0000 0.0000 REDUCED TEMP(KAYS RULE) 0.8629 0.8116 0.9338 0.9337 PRES(KAYS RULE) 0.2538 0.3582 0.3172 0.2538 ACENTRIC FACTOR 0.1759 .1986 0.1485 0.1759 WATSON K (UOPK) 14.467 13.816 15.501 14.467 STD LIQ DEN, LB/FT3 33.115 5.520 29.905 33.115 SPEC. GRAVITY 0.5310 0.5695 0.4795 0.5310 API GRAVITY 134.991 116.949 163.598 134.991

———— VAPOR ————- RATE, LB-MOL/HR 67.53 N/A 45.430 100.000 M LB/HR 3.142 N/A 1.977 5.111 M FT3/HR 2.554 N/A 1.250 4.133 STD VAP RATE(1), M FT3/HR 5.627 N/A 17.240 37.948 SPECIFIC GRAVITY (AIR=1.0) 1.606 N/A 1.502 1.765 MOLECULAR WEIGHT 46.52 N/A 43.511 51.111 ENTHALPY, BTU/LB 204.446 N/A 201.417 227.785 CP, BTU/LB-F 0.486 N/A 0.501 0.509 DENSITY, LB/M FT3 230.509 N/A 1581.297 1236.654 Z (FROM DENSITY) 0.8669 N/A 0.8411 0.8757 ———— LIQUID ———— RATE, LB-MOL/HR 32.470 54.570 N/A N/A M LB/HR 1.969 3.134 N/A N/A FT3/HR 41.561 7.341 N/A N/A GAL/MIN 5.182 8.396 N/A N/A STD LIQ RATE, FT3/HR 53.889 88.242 N/A N/A SPECIFIC GRAVITY (H2O=1.0) 0.5858 0.5695 N/A N/A MOLECULAR WEIGHT 60.638 57.437 N/A N/A ENTHALPY, BTU/LB 68.941 70.536 N/A N/A CP, BTU/LB-F 0.665 0.686 N/A N/A DENSITY, LB/FT3 47.373 46.544 N/A N/A Z (FROM DENSITY) 0.0293 0.0377 N/A N/A

(1) STANDARD VAPOR VOLUME IS 379.49 FT3/LB-MOLE (60 F AND 14.696 PSIA)

THE FOLLOWING ZERO-RATE STREAMS WERE NOT PRINTED 4


Chapter 17 Transport and Special Property Subroutines

Each transport property subroutine has the capability of calculating viscosity, thermal conductivity, and surface tension for a given stream phase. Viscosity and thermal conductivity are supported by liquid and vapor phases. Surface tension applies to liquid phases only.

Note: Liquid diffusivities cannot be calculated by a user-added transport subroutine.

Roughly the first half of this chapter discusses user-added transport properties. The latter half discusses user-added special property subroutines.

User-Added Transport Property SubroutinesUser Information

As a user, it is your responsibility to ensure that there is a corre-spondence between the method selected in the input data and the properties supported by the subroutine.

Transport Method Selection Using KeywordsTable 17-1 shows the correspondence between PRO/II keyword input property methods and user-added transport property methods.

Table 17-1: PRO/II Keywords for User-Added TransportStatement Keyword Entry

METHOD TRANSPORT U1, U2, U3, U4, or U5

or VISCOSITY= U1, U2, U3, U4, or U5

or VISCOSITY(V)= U1, U2, U3, U4, or U5

or VISCOSITY(L)= U1, U2, U3, U4, or U5


Transport Method Selection Using ProVisionSelecting user-added transport property methods in the ProVision GUI is simple. Figure 17-1 shows the Transport Properties Dialog box used for transport property methods selection.

Figure 17-1: Selecting User-added Transport Properties

Figure 17-1 shows an example of using the U1 method to compute liquid viscosity, liquid thermal conductivity, and surface tension. Follow these steps to obtain this configuration using ProVision.

or CONDUCTIVITY= U1, U2, U3, U4, or U5

or CONDUCTIVITY(V)= U1, U2, U3, U4, or U5

or CONDUCTIVITY(L)= U1, U2, U3, U4, or U5

or SURFACE= U1, U2, U3, U4, or U5

Note: The keywords VISCOSITY and CONDUCTIVITY may have qual-ifiers (V) or (L) associated with them. The qualifiers limit the property calculations to the vapor or liquid phase, respectively. When no qualifier is present, the property method applies to both liquid and vapor calculations.

Table 17-1: PRO/II Keywords for User-Added TransportStatement Keyword Entry

17-2 Transport and Special Property Subroutines February 2009

Select Thermodynamic Data from the Input menu.

Highlight any methods group in the Category list box to popu-late the Primary Methods list box.

Highlight the desired system in the Primary Methods list box and click the Add button to move it to the Defined Systems list box.

Highlight a method in the Defined Systems list and click the Modify button to open the Modification dialog box.

In the drop-down list boxes for Liquid Viscosity, Liquid Ther-mal Conductivity, and Surface Tension, select User-added 1.

Users need to know which properties each user-added subroutine supports. PRO/II cannot determine this. Any properties not sup-ported by a user-added subroutine may be computed by selecting an alternative PRO/II method from each drop-down list box.

Each user-added transport method available through input (U1, U2, U3, U4, or U5 in keywords, User-added 1 through User-added 5 in the GUI) corresponds to a particular transport property subroutine. Table 17-2 shows the transport property subroutine that corresponds to each keyword entry.

Table 17-2: Subroutine to Keyword to GUI Input Correspondence

KeywordMethod GUI Method

User-addedSubroutine

U1 User-added 1 UTRAN1U2 User-added 2 UTRAN2U3 User-added 3 UTRAN3U4 User-added 4 UTRAN4U5 User-added 5 UTRAN5


Transport Property Developer InformationThis section presents information primarily of interest to developers of user-added Transport Properties subroutines. Following these guidelines helps ensure a successful implementation.

Only subroutine developers can decide which properties a subrou-tine calculates. However, they also have the responsibility of pro-viding this information to their intended end-users.

Transport Property Subroutine Coding GuidelinesEach call from PRO/II expects the subroutine to return a single value for one property of the specified phase. If the subroutine does not calculate a property value, it should return a value of zero in variable VALUE.

Calling sequence:

SUBROUTINE UTRANn( IPHASE, ICODE, STRM, VALUE )

n The number of the transport property routine ( 1 to 5 ).

IPHASE Input Integer scalar flag indicating the requested phase.

1 Vapor property requested2 Liquid property requested

ICODE Input Integer scalar flag indicating the requested property.

1 Thermal conductivity requested2 Viscosity requested3 Surface tension requested (only when IPHASE = 2)

STRM Input single-precision standard user stream vector that contains the phase data that serve as the basis for the calculations. Inside the subroutine, this should be dimensioned as an automatic array (use an asterisk for the number of elements). All stream values are passed in from PRO/II in problem input dimensional units.

VALUE Output double precision scalar. This variable returns the calculated value of the requested property in problem input units.

where:

Note: Each UTRANn subroutine may use any of the user-added capabilities documented in Table 15-1 on page 15-2 of this manual with the following exception: Do not call subrou-tine TTPROP with ITYPE=3 or greater from within UTRANn.


Pure component data may be retrieved from the /XPROPX/ common block as described in Chapter 15. In special situations, pure compo-nent data also may be available in common /XPROPY/, described in Chapter 20, UAS Refinery Reactor Simulation.

Note: The subroutine should convert returned values to input units before returning them in variable VALUE. The /FACTOR/ common block provides conversion factors for this purpose. However, you must first convert them to cen-tipoise (for viscosity), Btu/hr./oF/ft (for conductivity), and dynes/cm (for surface tension) as documented in Chapter 16, User-Added Thermodynamic Property Methods.

Example ProblemsExample 17-1: Calculating Transport Properties Using User-Supplied

Transport Data PointsSometimes it might be desirable to directly input the value of a transport property to be used in PRO/II calculations rather than have it be predicted by the simulator. An example might arise in modeling rigorous heat exchangers in a refinery pre-heat train. If you know the viscosity of your crude oil as a function of tempera-ture (and if you know that none of it vaporizes in the exchangers), you might want to put in those viscosities directly for use in the rig-orous HX calculations. This can be easily accomplished with a user-added subroutine.

In this example, subroutine UTRAN2 calculates any transport prop-erty by interpolating or extrapolating tabular property data (up to 10 points) supplied by the user. Interpolation and extrapolation may be linear or may be specified to be ln(prop) vs. 1/T. The required infor-mation is entered through keyword input using the UDATA statement. The values are stored and available in the UTRAN2 routine from array TDATA of common block /CUDATA/. The element numbers in UDATA correspond to the same element numbers in TDATA. The input data is defined as follows:

TDATA( 1 ) NPTS = number of tabular data points

TDATA( 2 ) Interpolation/extrapolation flag1 = linear2 = ln(prop) vs. 1/T

TDATA( 11 to 10 + NPTS )

Temperatures in input units, in ascending order


FORTRAN Listing

UTRAN2.FOR — User-Added Calculation RoutineSUBROUTINE UTRAN2(IPHASE, ICODE, STREAM, VALUE)! INCLUDE ‘PMXUSR.CMN’ ! brings in MAXCN INCLUDE ‘FACTOR.CMN’ ! conversion factors INCLUDE ‘XPROPX.CMN’ ! component properties INCLUDE ‘UTHERX.CMN’ ! thermodynamics data!! Argument declarations INTEGER(4), INTENT(IN) :: IPHASE, ICODE REAL(4) :: STREAM(*) ! automatic array sizing REAL(4), INTENT(OUT) :: VALUE!! Local declarations! REAL(8) :: TK(10), TEMPK, THI, TLO, & VHI. VLO INTEGER(4) :: NPTS, ifErr, INFLG CHARACTRER(LEN=212) :: cLine ! for errors!! ---------- Code begins here ----------! VALUE = 0.0D+0 ! initialize return value ifErr = 0 ! error counter!! Error return if requested property is not! viscosity or phase is not liquid.! IF( ICODE .NE. 2 .OR. IPHASE .NE. 2 ) THEN JXXFLG = 99 ! error flag in /UTHERX/ GO TO 999 ENDIF!! Error if number of points is invalid! ( must be between 2 and 10 )! NPTS = ANINT( TDATA( 1 ) ) ! handle round-off IF( NPTS .LT. 2 ) THEN cLine = “ERROR - At least 2 points “ & // “are required.” CALL UAERR( “E”, 0, cLine ) ifErr = ifErr + 1

TDATA( 21 to 20 + NPTS )

Corresponding property values in input units


ELSE IF( NPTS .GT. 10 ) THEN cLine = “ERROR - No more than 10 “ & // “points are required.” CALL UAERR( “E”, 0, cLine ) ifErr = ifErr + 1 ENDIF!! Error if Interp/Extrap flag is not 1 or 2! INFLG = ANINT( TDATA( 2 ) ) IF( INFLG .LE. 1 ) THEN INFLG = 1 ELSE IF( INFLG .GT. 2 ) THEN cLine = “ERROR - Extrapolation flag “ // “is invalid (exceeds 2).” CALL UAERR( “E”, 0, cLine ) ifErr = ifErr + 1 ENDIF!! Error any zero or negative data.! Error if any temperatures do not increase.! DO I = 1, NPTS TK(I) = (TDATA(10+I)+TCONVT)*TFAC/XKTOR IF( TK(I) .LE. 0.0D0 ) THEN cLine = “ERROR - Invalid value in “ & // “data item “ WRITE(cLine(36:38),”(I3)”) I CALL UAERR( “E”, 0, cLine ) ifErr = ifErr + 1 ELSE IF (TDATA(20+I) .LE. 0.0D0) THEN cLine = “ERROR - Invalid value in “ & // “data item “ WRITE(cLine(36:38),”(I3)”) I CALL UAERR( “E”, 0, cLine ) ifErr = ifErr + 1 ELSE IF( I .GT. 1 ) THEN IF( TK(I) .LE. TK(I-1) ) THEN cLine = “ERROR - Temperatures “ & // “must be in increasing order” CALL UAERR( “E”, 0, cLine ) ifErr = ifErr + 1 ENDIF ENDIF END DO!! Error exit if any errors were found!


IF( ifErr .GT. 0 ) THEN cLine = “[UTRAN2] found input errors” CALL UAERR( “E”, 0, cLine ) JXXFLG = 99 ! error flag in /UTHERX/ GO TO 999 END IF!! Convert stream temperature to Kelvin! TEMPK = (STREAM(2)+TCONVT) * TFAC / XKTOR!! Bracket stream temperature between 2 data! temperatures.! Use T1 & T2 if stream temp is below T1! Use last 2 temps if stream temp is above! the last data temperature! IF( TEMPK .LE. TK(1) ) THEN THI = TK(2) TLO = TK(1) VHI = TDATA(22) VLO = TDATA(21) ELSE IF (TEMPK .GE. TK(NPTS)) THEN THI = TK(NPTS) TLO = TK(NPTS-1) VHI = TDATA(20+NPTS) VLO = TDATA(19+NPTS) ELSE!! Bound temperature above and below! DO I = 2, NPTS IF (TK(I) .GE. TEMPK) THEN THI = TK(I) TLO = TK(I-1) VHI = TDATA(20+I) VLO = TDATA(19+I) ENDIF END DO END IF!! Interpolate based on flag.! INFLG = 1 means Linear interpolation! IF( INFLG .LE. 1 ) THEN SLOPE = (VHI-VLO) / (THI-TLO) VALUE = VLO + SLOPE*(TEMPK-TLO)!

! INFLG = 2 means log(prop) vs 1/Temp! ELSE IF( INFLG .EQ. 2 ) THEN VHILN = LOG(VHI) VLOLN = LOG(VLO) THIINV = 1.D0 / THI TLOINV = 1.D0 / TLO TINV = 1.D0 / TEMPK SLOPE = (VHILN-VLOLN) / (THIINV-TLOINV) VALUE = VLOLN + SLOPE * (TINV-TLOINV) VALUE = EXP( VALUE ) ENDIF! 999 CONTINUE ! error exit point END SUBROUTINE UTRAN2

PRO/II Keyword Input FileTITLE PROJECT=USERADD,PROBLEM=UTRAN2, USER=SIMSCI, DATE=03/01/2006 PRINT RATE=M, STREAM=ALL, INPUT=ALL DIME ENGLISHCOMPONENT DATA LIBID 1,ETHANE/2,PROPANE/3,IBUTANE/4,BUTANE/ 5,PENTANE TBPCUTS 115,300,6/400,10/650,8/800,4/1500,6THERMODYNAMIC DATA METHOD SYSTEM=BK10,TRAN=PETRO,VISC(L)=U2 VISC(L) UDATA 1,2/ 2,1/ 11, 200/ 12, 400/ 21, 5.0/ 22, 3.0STREAM DATA PROP STREAM=1, TEMP=375, PRES=300, PHASE=M, & RATE(V)=3125, ASSAY=WT D2887 STREAM=1, DATA=5.74, 135/ 19.55,210 / & 35.89, 370/ 60.04, 565/ 69.82,665 / & 78.38, 800/ 87.94, 990 API STREAM=1,AVG=45.37, DATA=8.33, 80.01 / & 16.89, 62.90/ 34.8,50.6 / & 55.47, 38.20/ 80.10, 27.5 MW STREAM=1, AVG=162.9, DATA=18.92,99.5/33.4,135/ & 48.4, 184.7/ 9.8, 334.8/ 100, 789 LIGHT STREAM=1,PERCENT(W)=10.4, NORMALIZE, & COMP(M)=1,0.1/2,1.4/3,0.65/4,3.15/5,5.1 NAME 1, CRUDE FEEDUNIT OPERATIONS HCURVE UID=HC1, NAME=HEATING CRV ISO STREAM=1, TEMP=375,600, PRES=300, POINTS=21 PROP TRANS

END


Partial PRO/II Output SIMULATION SCIENCES INC. R PAGE P-7 PROJECT UKHS1 PRO/II UAS 386/EM PROBLEM USERADD OUTPUT SIMSCI HEATING/COOLING CURVE JUN99

==============================================================================UNIT 1, ‘HC1’, ‘HEATING CRV’ (CONT)

TRANSPORT PROPERTIES FOR STREAM 1 - DRY VISCOSITY THERMAL CONDUCTIVITY SURFACE NO. TEMP PRES VAPOR LIQUID VAPOR LIQUID TENSION F PSIA CP BTU/HR-FT-F DYNE/CM

-------------------------------------------------------------------------------- 1 375.00 300.00 N/A 3.2500E+00 N/A 4.6893E-02 1.0539E+01 2 386.25 300.00 N/A 3.1375E+00 N/A 4.6085E-02 1.0042E+01 3 397.50 300.00 N/A 3.0250E+00 N/A 4.5276E-02 9.5479E+00 4 408.75 300.00 N/A 2.9125E+00 N/A 4.4468E-02 9.0585E+00 5 420.00 300.00 N/A 2.8000E+00 N/A 4.3660E-02 8.5735E+00 6 431.25 300.00 N/A 2.6875E+00 N/A 4.2855E-02 8.0932E+00 7 442.50 300.00 N/A 2.5750E+00 N/A 4.2053E-02 7.6176E+00 8 453.75 300.00 N/A 2.4625E+00 N/A 4.1255E-02 7.1470E+00 9 465.00 300.00 N/A 2.3500E+00 N/A 4.0464E-02 6.6815E+00 10 476.25 300.00 N/A 2.2375E+00 N/A 3.9682E-02 6.2215E+00 11 487.50 300.00 N/A 2.1250E+00 N/A 3.8912E-02 5.7672E+00 12 498.75 300.00 N/A 2.0125E+00 N/A 3.8157E-02 5.3188E+00 13 510.00 300.00 N/A 1.9000E+00 N/A 3.7420E-02 4.8768E+00 14 521.25 300.00 N/A 1.7875E+00 N/A 3.6705E-02 4.4414E+00 15 532.50 300.00 N/A 1.6750E+00 N/A 3.6018E-02 4.0132E+00 16 541.17 300.00 N/A 1.5883E+00 N/A 3.5509E-02 3.6882E+00 17 543.75 300.00 1.3555E-02 1.5625E+00 2.7197E-02 3.5409E-02 3.6450E+00 18 555.00 300.00 1.3584E-02 1.4500E+00 2.7614E-02 3.4984E-02 3.4626E+00 19 566.25 300.00 1.3612E-02 1.3375E+00 2.8023E-02 3.4575E-02 3.2885E+00 20 577.50 300.00 1.3641E-02 1.2250E+00 2.8427E-02 3.4181E-02 3.1220E+00 21 588.75 300.00 1.3671E-02 1.1125E+00 2.8826E-02 3.3801E-02 2.9623E+00 22 600.00 300.00 1.3701E-02 1.0000E+00 2.9220E-02 3.3434E-02 2.8089E+00


User-Added Special Property SubroutinesPRO/II user-added subroutines allow calculating values of special properties using user-added methods. PRO/II supports special prop-erties in two broad categories:

User-defined (or numbered, unnamed) properties referenced using SPROP(idno). Users assign these an integer ID number as part of defining the property.

Pre-defined (or named, not numbered), often referred to as Refinery Inspection Properties. The pre-defined identifiers for these properties are available in Table 17-3.

Special properties in both categories may be in the form of an Index relationship or an actual property value. User-added subroutines are available for special properties in both categories using either or both forms.

Keyword Input

Typical Usage

...COMPONENT DATA

LIBID 1,IC4/ 2,NC4/ 3,NC5THERMO DATA(Input statements for special property Index Method)

METHOD SYSTEM=setid, &SPROP( idno ) = USINDEX, or PROPID= USINDEX

andSPROP(M or WT or LV, idno) GAMMA=value, &

REFINDEX=value, REFVALUE=value {, NAME=text}or

PROPID(M or WT or LV)GAMMA=value, &REFINDEX=value, REFVALUE=value

and INDEX ixno, rvalue/ ...

or DATA icno, rvalue/...

(Input statements for special property Formula Method)METHOD SYSTEM=setid, &

SPROP( idno ) = USFORM, or PROPID= USFORMand

SPROP(M or WT or LV, idno) {, NAME=text}or

PROPID(M or WT or LV)


{ and DATA icno, pvalue/ ...and/or UIDATA ivalue/...and/or URDATArvalue/... }STREAM DATA

. . .

where:

SPROP(idno)

or

PROPID

Use the appropriate statement for the property to calculate. In keyword input, each of these statements begins a group of input. Statements that immediately follow provide data for this property. A subsequent SPROP or PROPID statement ends this group and begins a new input group.

PROPID Represents a keyword for a pre-defined, named special property. For example, to compute Wax content using a user-supplied formula method, replace this with WAX=USFORM. Refer to Table 17-3 for a complete list of keywords that identify special properties.

SPROP(idno) Indicates a numbered (unnamed) special property. The SPROP statement requires the integer qualifier to identify the numbered property.

idno This required integer qualifier is the identification number assigned to the numbered special property. For example, to compute numbered special property 5 from a user-added Index method, use SPROP(5)=USINDEX

GAMMA These entries must be supplied when using theREFINDEX USINDEX mixing method. REFVALUE All are required when using the USINDEX

method. None are allowed when using the USFORM method. Refer to “Component Invariant Special Properties” in chapter 8 of the Component Data Keyword Manual and “Special Property Methods Data” in chapter 8 of the Thermody-namic Data Keyword Manual.

NAME Use this keyword to assign an optional descriptive name to a numbered special property (only on an SPROP statement). This appears in lists of special properties that are generated in the PROVISION


Graphical User Interface. It also appears in the simulation output report.

USFORM, USINDEX

These options select a user-added method for the property.

USFORM requires Fortran routine SPUSER.FOR to be written and built in UASLB.DLL. The SPUSER routine calculates the property value using the GAMMA, REFINDEX, REFVALUE, DATA and INDEX data input on the appropriate SPROP or PROPID statement. Developer information appears later in this chapter.

USINDEX requires Fortran routine CVUSER.FOR to be written and built in UASLB.DLL. This routine converts an index value to a property value, and also converts a property value to an index value. Developer information appears later in this chapter.

Data Statements Allowed with the USINDEX Method(Exactly one of these two statements is allowed, and is required.)

INDEX ixno, rvalue / ... Supplies index values for the bulk mix-ture. Typically required when using the USINDEX to convert from given index values to property values.

icno Required to order each index value.rvalue Required non-negative floating-point index value.

orDATA icno, rvalue / ... Supplies property values for individual

components. Use it with a USINDEX index method that converts bulk property values to index values. The values are summed and the bulk property value is passed to USINDEX. Refer to the chapter 8 of either the Component or Ther-modynamic Data Input Manuals for the summa-tion equation used.

icno Required to identify the component in input order.rvalue Required non-negative floating-point index value

for component icno.


Data Statements Allowed with the USFORM Method(Any combination of these statements is allowed with USFORM.)

DATA icno, pvalue / ... Supplies property values for individual components. This array is passed to a USFORM subroutine method that converts bulk property values to index values. The input entries are counted and used to size the data array.

icno Required to identify the component in input order.pvalue Required non-negative floating-point property

value for component icno.

UIDATA Supplies integer values that pass to subroutine USFORM. (Not passed to CVUSER). The devel-oper of the USFORM subroutine specifies if this data is needed. The input entries are counted and used to size the data array.

ivalue User-supplied integer data values. At least one value should be supplied when this statement appears in the input.

URDATA Supplies floating-point values passed to subrou-tine USFORM. (Not passed to CVUSER).

rvalue User-supplied floating point data values. At least one value should be supplied when this statement appears in the input.

Table 17-3: Predefined (Named) Special Property Ordinal Numbers

Ordinal ID

Keyword

Named (Refinery Inspection) Property

1 KVIS(basis) Kinematic viscosity

2 CLOUD(basis) Cloud point temperature

3 POUR(basis) Pour point temperature

4 FLPT(CC, basis) FLAS(CC, basis) FLPO(CC, basis)

Flash point Temperature, Closed Cup Generally, these replace FLSH

5 SULF(basis) or SULP(basis)

Sulfur content

6 CETN(basis) Cetane number (replaced CNUM)

7 SMOKE(basis) Smoke point


8 AROM(MONO, basis)

Mono-Aromatics content (replaces ARO1, AR88O1)

9 AROM(DI, basis) Di-Aromatics content (replaces ARO2)

10 AROM(TRI, basis) Tri-Aromatics content (replaces ARO3)

basis = M, WT, or LV

11 AROM(TETR, basis)

Tetra-Aromatics content (replaces ARO4)

12 AROM(PENT, basis)

Penta-Aromatics content (replaces ARO5)

13 AROM(HEPT, basis)

Hepta-Aromatics content (replaces ARO7)

14 AROM(TOTAL, basis)

Total-Aromatics content (replaces AROT)

15 NAPH(basis) Naphthene content

16 PARA(NORM, basis)

Normal Paraffin content (replaces PARN)

17 PARA(ISO, basis) Iso-Paraffin content (replaces PARI)

18 PARA(ALKY, basis)

Alkyl-Paraffin content (replaces PARA)

19 PARA(POLY, basis)

Poly Paraffin content (replaces PARP)

20 PARA(TOTA, basis)

Total Paraffin content (replaces PART)


21 OLEF(MONO, or OLEF(NORM, basis)

Mono-Olefin content (replaces OLEM, OLEN)

22 OLEF(BRAN, or OLEF(ISO, basis)

Branched Olefin content (replaces OLEB)

23 OLEF(CYCL, basis)

Cyclic Olefin content (replaces OLEC)

24 H2(WT) Hydrogen content (replaces HYDR)

Table 17-3: Predefined (Named) Special Property Ordinal Numbers (Continued)

Ordinal ID

Keyword



25 CARB(WT) Carbon content

26 VA(WT) Vanadium content (replaces VANA)

27 NICK(WT) Nickel content

28 SODI(WT) Sodium content

29 OXYG(WT) Oxygen content

30 N2(TOTA, WT) or NITR(TOTA, WT)

Total Nitrogen content (replaces N2TO)

31 N2(BASI, WT) or NITR(BASI, WT)

Basic Nitrogen content (replaces N2BA)

32 N2(NONB, WT) or NITR(NONB, WT)

Non-basic Nitrogen content (replaces N2NB)

33 ASPH(C5, WT) Asphaltene C5 content (replaces ASP5)

34 ASPH(C7, WT) Asphaltene C7 content (replaces ASP7)

35 V50(basis) V50 value

36 VIND(basis) Viscosity Index

37 PENET(basis) Penetration Index

38 FRZP(basis) or FRPT(basis) or FREZ(basis)

Freeze point temperature

39 CCR(basis) Conradson carbon residue

40 RCR(basis) Ramsbottom carbon residue


41 CHRA(WT) Carbon-hydrogen ratio

42 TAN(WT) or ACID(WT)

Total acid number

43 WAX(WT) Wax content

44 ASH(WT) Ash content

45 RON(C, basis) Research octane number

46 MON(C, basis) Motor octane number


Ordinal ID

Keyword



47 REFR(C20, basis) or RI(C20, basis)

Refractive index at 20 Celsius

48 RIND(WT) Ring index

49 ARIN(WT) Aromatic index

50 GIND(WT) Grade index


51 SIND(WT) Structure index

52 LUMI(WT) Luminometer number (Luminosity)

53 NOAC(WT) Noack volatility

54 JT(WT) Joule-Thompson (replaces JOUT)

55 EXPN(WT) Expansivity (replaces EXPN)

56 VSOUND(WT) Velocity of sound (replaces VSND)

57 BULK(WT) Bulk Modulus (replaces BMOD)

58 CVOL(WT) CVOL EOS

59 CETA(basis) or CETI(basis)

Cetane index

60 IBP(basis) Initial boiling point of cut


61 FBP(basis) Final boiling point of cut

62 MERC(WT) Mercaptan content

63 NPHL(basis) Naphthalene content

64 ANIL(basis) or ANPT(basis)

Aniline point

65 BROM(WT or LV) Bromine number

66 ANEU(WT or LV) Neutralization number (replaces NEUT)

67 CFPP(basis) Cold filter plug point

68 ICI(basis) Icing index

69 STUI(basis) or STAR(basis) or SUI(basis) or SI(basis)

Startup index


Ordinal ID

Keyword




70 WUI(basis) or WARM(basis)

Warm-up index

71 SOFT(WT or LV) Softening point

72 PHEN(WT) Phenol content

73 MON(L, basis) MON at 3 ml (replaces MAT3)

74 RON(L, basis) RON at 3 ml (replaces RAT3)

75 ASUL(WT) Aliphatic Sulphur content

76 REFR(C70, basis) or RI(C70, basis)

Refractive index at 70 Celsius

77 AROM(RING, basis)

Aromatic ring content (generally replace ARRI)

78 IRON(WT) Iron content

79 WTAR(WT) Weight Aromatics (replaces WARO)

80 WTPA(WT) Weight Paraffins (replaces WPAR)

81 WTNA(WT) Weight Naphthenes (replaces WNAP)

82 FLPT(OC, basis) FLAS(OC, basis) FLPO(OC, basis)

Flash point Temperature, Open Cup Generally, these replace FLSH

83 CVLI(US, basis) Car vapor lock index (USA) (replaces CVLU)

84 CVLI(EU, basis) Car vapor lock index (Europe) (replaces CVLE)

85 MEAB Mean average boiling point temp. (replaces MEAP)

86 CABP Cubic average boiling point temp

87 MOAB Molal average boiling point temp. (replaces MOBP)

88 NHV Net heating value (replaces ANHV)

89 IDLT IDL type


90 PEPT(basis) Peptising power


Ordinal ID

Keyword



91 PVAL(basis) P value

92 FRMX(basis) FR maximum

93 FLOC(basis) Flocculation ratio

94 CPWX(basis) Congealing point of wax

95 PWAX(basis) Paraffinic wax content

96 CPPW(basis) Congealing point of Paraffinic wax

97 ARIP(MONO, basis)

IP Aromatics (mono) (replaces ARI1)

98 ARIP(DI, basis) IP Aromatics (di) (replaces ARI2)

99 ARIP(TRI, basis) IP Aromatics (tri) (replaces ARI3


100 ARIP(TOTAL) IP Aromatics (total)

101 MSUL(WT) Mercaptan sulphur (replaces MERS)

102 TRS(WT) Total reactive sulphur

103 FLPT(CC, basis) FLAS(CC, basis) FLPO(CC, basis)

Wong Closed-cup Flash Point temp. (generally replace FLPW and FLSH)

SPROP( n, basis ) User-defined (numbered) special property “n” (n = 1 to 9999, but only 60 SPROP’s are allowed.)



Ordinal ID

Keyword



Special Property Developer InformationThe remainder of this chapter presents information primarily of interest to developers of user-added Special Properties subroutines. Only subroutine developers can decide which properties a subrou-tine calculates. However, they also have the responsibility of pro-viding this information to their intended end-users.

PRO/II provides templates of two subroutines for calculating spe-cial properties:

SPUSER Used by the USFORM option.

CVUSERUsed by the USINDEX option.

As delivered, both routines contain sample calculation code. How-ever, to use them effectively, the user must re-code them and rebuild the UASLB.DLL project. Refer to “Build Procedure for Classic PRO/II UAS” in chapter 14.

Special Property Subroutine Coding GuidelinesFollowing these guidelines helps ensure a successful implementa-tion. In PRO/II, special properties are manipulated routinely in two forms:

Actual property values. These may be computed by the user-added subroutine SPUSER.FOR. SPUSER.FOR does not compute or use Index values.

Index values. These are generated by converting actual prop-erty to the index form using correlations within PRO/II. The equations involved are presented in chapter 8 of the Compo-nent Data Keyword Manual and in chapter 8 of the Thermody-namic Data Keyword Manual.

If desired, developers may write their own version of subrou-tine CVUSER.FOR as an alternative method of accomplishing the conversions.

Each call from PRO/II expects the subroutine to return a single value for one property of the specified phase. If the subroutine does not calculate a property value, it should return a value of zero as the result of the calculation.


Subroutine SPUSERThis subroutine computes special property values. It is called once for each value of each property. All data input by the appropriate DATA, UIDATA, and URDATA statements is available to the subrou-tine.

Calling sequence:

SUBROUTINE SPUSER( iStrID, IDProp, iPropType, & NCOMP, UDatIn, lenIU, IUData, & lenUR, URData, XCOMP, ValOut )where:

iStrID Input ID number of the stream for which to compute a property value. (Typically not used for calculations.)

IDProp This input integer value identifies the special property to compute. For user-defined properties, this maps to SPROP(IDProp).

For pre-defined special properties, IDProp may be found in Table 17-3. For Example, “Vanadium Content” is number 26 in the table.

After determining whether the property is an SPROP or a named property, use this argument to branch to process different properties.

iPropType Input integer scalar flag indicating the major property class of the requested property. Values include:

1 Named (Pre-defined Refinery Inspection) Property2 Numbered (User-defined) SPROP(IDProp)

Use this flag to create a logical branch between the two types of property.

NCOMP Input integer indicating the total number of components in the simulation. This also is the dimension of the UDatIn argument array.

UDatIn An optional double-precision array of input data. This is the array of values input on the DATA statement for this property. It includes up to one value for each component in the simulation; typically, the property value of each pure component. The array size is NCOMP. The component numbers used to input values have not been re-arranged, so the values effectively are in component input order.

lenIU This input integer is the size of the IUData input array.

IUData An optional integer array of data input on the UIDATA statement. The number of values is lenIU, soIUDATA(lenIU) is the proper declaration

lenUR This input integer is the size of the URData input array.


Subroutine CVUSERThis subroutine performs conversion between property values and property index values. Indexes typically are logarithmic forms of property values. Being logarithmic, they tend to linearize the behav-ior when combining properties. When coding this routine, it should be capable of converting index values to property values; and con-versely, be capable of converting property values to index values. It is called once for each value to convert. All data input by the appro-priate DATA, UIDATA, and URDATA statements is available to the subroutine.

Calling sequence:

SUBROUTINE CVUSER( iOptCvt, VIndex, VProp, GAMMA, & CONST, IDProp )where:

URDATA An optional double precision array of data input on the URDATA statement. The number of values is lenUR, so URDATA(lenUR) is the proper declaration.

XCOMP Input double precision array of pure component composition expressed as mole fraction of each component. If non-molecular weight components are to be processed, the developer should consider characterizing them using data in the UIDATA and URDATA arrays of input data.

ValOut Output double precision scalar property value. This must be the bulk property that incorporates any and all contributions of the individual components. This variable returns the calculated value of the requested property in PRO/II internal dimensional units.

iOptCvt This input integer flag indicates the conversion to perform. Set iOptCvt to one of these two values to convert a (pre-defined) named property:1 Convert the Index value (of a named special

property) passed as input in argument VIndex to a property value returned in VProp.

2 Convert the property value (of a named special property) passed as input input in argument VProp to an index value returned in VIndex.


Set iOptCvt to one of these two values to convert a user defined (numbered SPROP) property:201 Convert the Index value (of a numbered SPROP)

input in argument VIndex to a property value returned in VProp.

202 Convert the property value (of a numbered SPROP) input in argument VProp to an index value returned in VIndex.

VIndex This is the Index value of the special property. It is input when iOptCvt = 1, and must be converted to a

property value returned in VProp.Calculate VIndex from VProp when iOptCvt = 2.

VProp This is the actual value of the special property. It is input when iOptCvt = 2, and must be converted to

an Index value returned in VIndex.VIndex must be calculated and returned when

iOptCvt = 2.

GAMMA This is input and is typically used in the following formula. When not supplied through input, Gamma assumes a value of 1.0.

log10 Index( ) 1.0Gamma-------------------⎝ ⎠

⎛ ⎞ log10 VProp( ) CONST+=

(17-1)

CONST This input argument represents the Index value at reference conditions as determined by input values REFINDEX and REFVALUE.

IDProp This input integer value identifies the special property to compute. For user-defined properties, this maps to SPROP(IDProp).

For pre-defined special properties, IDProp may be found in Table 17-3. For Example, “Vanadium Content” is number 26 in the table.

After determining whether the property is an SPROP or a named property, use this argument to branch to process different properties.


Chapter 18Classic Unit Operations

OverviewThe User-Added Unit Operation interfaces described in this chapter allow users and other independent developers to supplement the PRO/II-supplied unit operations with their own unit operations. Both the keyword input facilities and the ProVision Graphical User Interface fully support these user-added unit operations.

They are fully integrated into the flowsheet sequencer, so their exe-cution is indistinguishable from that of PRO/II’s internal unit mod-els. User-added unit operations accept feed streams as input from other unit operations in the flowsheet. Calculation capabilities are limited only by the creativity of the developer. Their product streams may serve as feeds to other flowsheet units. For example, it is possible to integrate a user-added heat exchanger or solids dryer into a PRO/II flowsheet. Using the DEFINE features of PRO/II, they can directly access data for other flowsheet unit operations. The cal-culated results they store internally are available to other flowsheet units. In addition to performing calculations, user units can generate printed report and create files of data for use by programs external to PRO/II.

A user-added unit operation may execute (a) during flowsheet cal-culations only, or (b) at output-time only. User-added units called during flowsheet calculations must have at least one feed stream to satisfy flowsheet connectivity requirements. Output-time calcula-tions may be preferred for a single-pass execution after flowsheet convergence has been achieved. User-added unit operations also support an optional output subroutine having the express purpose of writing final results directly into PRO/II’s standard output report.

Starting in PRO/II version 8.0, new object-oriented unit operation interfaces vastly extend these user-added capabilities. Discussion of


those features begins in Chapter 3, "Modular Interface Software" of this manual.

User InformationKeyword Summary

Unit Identification (required)

USn UID=uid, {NAME=text}, {BYPASS=1}

Feeds and Products (conditional)

FEED sid {, sid, sid,....}PRODUCT {sid, sid, sid,....}

User Input Data (optional)

Integer Inputs

IPARM integer {, integer, ....} (Up to 250 values)

Real Number Inputs

RPARM real {, real , .... } (Up to 500 values)

SUPPLEMENTAL i, reali {, ... / j, realj+1 ... } (Up to 10000 values)

HEAT duty x 10-6, {, duty x 10-6, ... } (Up to 10 values)

Alternative Definition of Operating ParametersDEFINE RPARM( elno ) AS <unit type>=uid, <param>, {<op, <ref>}orDEFINE RPARM( elno ) AS STREAM=sid, <prop>, {<op, <ref>}

General InformationUser input data are supplied to user-added unit operations using PRO/II keyword statements or the ProVision GUI. From a users’ perspective, there is not a lot of difference between setting up a user-added unit or one of PRO/II’s internal unit operations.

The operating parameters for these user-added units may be input by the user or derived from previous unit operations through the DEFINE feature of PRO/II. See chapter 10.5 in the PRO/II Keyword Manual, or the PRO/II User’s Guide for more information. Input processing facilities are included in PRO/II for user-written unit operations. However, routines for optional output reports must always be written by the user.

18-2 Classic Unit Operations February 2009

Calculated results from user-supplied unit operations may be stored in IPARM, RPARM, and SUPPLEMENTAL arrays. Other flowsheet units may access the data stored in the RPARM array using the DEFINE con-struct described in chapter 10.5 of the PRO/II Keyword Manual.

Input DescriptionUnit Identification (required)

USnn UID=uid, {NAME=text}, {BYPASS=1}

In the Unit Operation category of a PRO/II keyword input file, you must indicate which user-added models are being used. The first statement of the declaration must be the Unit Identification state-ment. Chapter 10.2 in the PRO/II Keyword Manual describes the entries in more detail

USnn Required. A composite keyword consisting of the prefix US and a 1, 2, or 3 digit integer that identifies the specific user-subroutine that performs the calculations. Valid values of nn are 1-20 and 41-120. nn is part of the US keyword. Table 18-2, “Naming Conventions for Unit Op Subroutines,” on page 18-14 maps these keywords to actual user-added subroutines. For example, keyword US41 (where nn=41) specifies subroutine USER81.for. Note: Numbers 21-40 are reserved for PRO/II.

UID Required. A unique unit identifier containing up to 12 characters. This identifies the unit on the flowsheet.

NAME Optional descriptive text string containing no more than 40 characters.

BYPASS Optional integer scalar that acts as a flag to control when calculators are performed.1 = Normal calculations during flowsheet convergence. This is the default when an entry is omitted.2 = Perform calculations only after flowsheet has converged. The unit is skipped during flowsheet convergence calculations.

.

Note: Units that run normally (BYPASS=1, during flowsheet con-vergence calculations) require at least one feed stream to satisfy the connectivity requirements of the calculation sequencer.


The BYPASS flag does not affect any output routines (UnnOUT). Out-put routines execute only during standard report generation; never during flowsheet calculations.

For bypass units (BYPASS = 2), all feeds and products are optional.

Note: For bypass units (BYPASS = 2), the product streams cannot be stored with URXSTR or other stream storage routines.

Feeds and ProductsFEED sid, {sid, sid,....}PRODUCT {sid, ... sid, sid,....}

where:

sid A flowsheet stream identifier. It is a character string that may contain up to 12 characters. All product streams always are optional. When a unit executes in BYPASS mode (i.e., bypass=2), all feeds are optional.

The following notes describe the requirements imposed by PRO/II. Developers of specific user-added unit operations may impose other restrictions. Users must be aware of and comply with any other restrictions imposed by the developer.

Note: Units that run normally (BYPASS=1, during flowsheet con-vergence calculations) require at least one feed stream to satisfy the connectivity requirements of the calculation sequencer.

Note: For bypass units (BYPASS = 2), the product streams cannot be stored with URXSTR or other stream storage routines.

Note: There is essentially no limit on the number of feed and product streams allowed for each user-added unit opera-tion. The number of feeds and products are counted during input processing and storage is allocated dynamically.

Thermal ConditionsThe thermal conditions for feed streams to user-added unit opera-tions are defined by PRO/II. There are no provisions for the user to specify them.


Keywords for User Data Input IPARM integer {, integer, ....} (Up to 250 values)

RPARM real {, real, .... } (Up to 500 values)

HEAT duty x 10-6, {, duty x 10-6, ... } (Up to 10 values)


The following definitions only include limitations imposed by PRO/II. Developers of user-added unit operations may impose addi-tional restrictions on data input that users must observe.

IPARM Optional integer array of user input data. Each integer entry represents one scalar integer value. PRO/II imposes an absolute limit of 250 values.

RPARM Optional single-precision array of user input data. Each real entry represents one scalar single-precision value. PRO/II imposes an absolute limit of 500 values.

HEAT Optional single-precision array of user input data. Each duty x 10-6 entry represents one scalar single-precision value. PRO/II imposes an absolute limit of 10 values.

SUPPLE Optional single-precision array of user input data. Each real entry represents one scalar single-precision value. PRO/II imposes an absolute limit of 10,000 values.

PRO/II does not associate any dimensional units of measure with any of the data. All data values entered through input is passed unchanged to the user-added subroutine.

For the IPARM, RPARM, and HEAT arrays, the position of the input data determines the storage element. Numbering begins with element 1 for the first supplied value. Separate entries with commas. Use additional commas as placeholders for omitted values. For example, to store 5.0 in element 5 and 7.0 in element 7 of the RPARM array:

RPARM , , , ,5.0, ,7.0

The HEAT array originally was intended to transfer heater/cooler duties to user-added subroutines in duty units of measure (i.e., energy per time). However, it does not and never has applied dimensional units conversions to the data. It is supported only for backward compatibility, and for the convenience of developers who choose to use it.

The SUPPLEMENTAL array uses an input syntax different from the other arrays. Due to its large size, it is convenient to designate “starting elements” to facilitate entering more than one series of


data. The “i” and “j” entries represent integer starting element num-bers. If the element number is omitted, the associated real entry is stored in the next available storage element. The following exam-ples store 101.0 in element 1, 102.0 in element 2, 2031.0 in element 2031, and 2032.0 in element 2032.

SUPPLE 101.0, 102.0 / 2031, 2031.0, 2032.0or

SUPPLE 1, 101.0/ 2, 102.0/ & 2031, 2031.0/ 2032, 2032.0

Note the first value (101.0) is stored in element 1, even when the element number is missing. Supply the element number to store the first entry in a different element (other than element 1).

Dynamic Definition of RPARM ValuesDEFINE RPARM( elno ) AS <unit type>=uid,<param>,{<op,<ref>}orDEFINE RPARM( elno ) AS STREAM= sid, <prop>, {<op, <ref>}

In the keyword input for a user-added unit operation, the definition of individual RPARM elements may be deferred until the unit is called to perform calculations. This is accomplished by using the DEFINE statement described in chapter 10.5 of the PRO/II Keyword Input Manual. Available parameters are listed in chapter 10.3, Flowsheet Parameters, in the same manual.

Example 18-1: Dynamically Importing RPARM ValuesAny of the first 100 elements of the RPARM array may be set to external flowsheet values dynamically. Use a DEFINE statement in the input of the user-defined unit operation to accomplish this. Each time PRO/II calls the user-added subroutine, it auto-matically imports the external flowsheet parameter and uses it to update the specified RPARM element. The following example illustrates this use of the DEFINE statement.

RPARM element value imported from another unit operation:

CALCULATOR UID=C1 PROCEDURE R(1) = 13.376 R(2) = 52800 RETURN US2 UID=USER2 FEED ... PROD ... DEFINE RPARM(1) AS CALC=C1, RESULT(2)


DEFINE RPARM(2) AS CALC=C1, RESULT(1)

These two DEFINE statements set RPARM(1) = 52800 and RPARM(2) = 13.376.

Example 18-2: Dynamically Exporting RPARM ValuesAny of the first 100 elements of the RPARM array may be exported to reset external flowsheet parameters dynamically. Use a DEFINE statement in the input of another unit operation to accomplish this.

This actually is the same situation as import example 5-2. The difference is that the DEFINE statement appears in an external flowsheet unit operation, not within the user-added subroutine. Each time PRO/II calls the external unit operation, it automati-cally imports the specified RPARM value from the user-added unit operation and uses it to update the specified parameter. The following example illustrates this use of the DEFINE statement.

RPARM element value exported to another unit operation:

US4 UID=USER4 ! +-- temp FEED ... ! | +-- pres PROD ... ! | | RPARM 13.376, 52800, 0.0, 0.0, 0.0 ! element 1 2 3 4 5 FLASH UID=F1 FEED ... PROD ... ISO DEFINE PRES AS US4=USER4, PARA(4) DEFINE TEMP AS US4=USER4, PARA(3)

In this case, the 3rd and 4th real parameters are calculated by the user subroutine and passed to the flash unit operation.

User-Added Unit Operations and Recycle LoopsUser-added unit operations may be used within flowsheet recycle loops in exactly the same manner as any other unit operations.

User-Added Unit Operations and ControllersParameters stored in the RPARM array for a user-added unit opera-tion may be used by a feedback controller as control parameters. They may also be used in the specification of a feed forward con-troller (DEFINE), a feedback controller (CONTROLLER, MVC) or a flowsheet OPTIMIZER. Only values stored in the RPARM array are available as flowsheet parameters. Refer to example 5-3.


Example 18-3: Spec and Vary Using RPARMThe first 100 RPARM elements of the unit operation may be used as control variables or as specification values by PRO/II control units. This is illustrated by the following examples.

Control Variable

Syntax:CONTROLLER UID=C1 SPEC ... VARY <utype>=<uid>, PARA(elno)

where:

<utype> The declared type of the user added unit operation (US1, US2, US41, etc.).

<uid> The unit’s unique identifier

elno The element number of RPARM to vary. The controller permutes RPARM( elno ) to solve the problem.

Sample Code:To control RPARM(5) for unit C11, defined by user-added subrou-tine US2, the following VARY statement could be used:

VARY US2=C11, PARA(5)

Specification

Syntax:CONTROLLER UID=C1 SPEC <utype>=<uid>, PARA(elno), VALUE= rval VARY ...

where:

<utype> The declared type of the user added unit operation (US1, US2, US41, etc.).

<uid> The unit’s unique identifier

elno The element number of RPARM used as the target. The specification (RPARM( elno ) must be a calculated result in unit <uid>.

rval The calculated value of RPARM( elno ) after calculations converge.


Sample Code:To specify RPARM(3) to be 4.812 for unit H45, defined by user subroutine US42, the following SPEC statement could be used:

SPEC US42=H45, PARA(3), VALUE=4.812

Developer InformationGuidelines

Developers should acquire a reasonably thorough understanding of using user-added subroutines before beginning code development. All the previous information for users is relevant. This section high-lights areas of concern that developers may encounter.

Organizing Unit Operation CodePRO/II execution proceeds through a series of processing steps that broadly include: input processing, data cross-checks, flowsheet solution, output-pass calculations, and report writing. PRO/II does not call any user-added subroutines during input processing and cross-checking. It calls user-added calculation routines only for flowsheet solution and output-pass calculations. Finally, PRO/II calls only user-added output routines (and not the calculation rou-tines) when generating output reports.

It is important to keep these steps in mind when organizing the code. For example, if code to valid input data is desired, it should appear in the user-added calculation routines. All checking and error exits should occur before the actual calculations begin. An IPARM element might be reserved as an internal counter of the number of times the calculation routine is called from PRO/II. The flag could be used to perform the input checks only on the first entry. Similarly, all code that reports final results should reside in the output routines; not in calculation routines. Output routines typ-ically test the ISOLVE flag a successful calculation solution, and nor-mally omit more detailed data validation.

PRO/II Feed StreamsDevelopers should not attempt to change or modify any feed stream data, since that could corrupt the integrity of the flowsheet. A com-mon approach is to copy feed stream data to local internal storage, or simply copy it to a product stream and perform the calculations using that copy of the data. Routine URXSTR allows retrieving (but not storing) feed stream data from stream storage.


User-added unit operations must accept at least one feed stream to be included in flowsheet calculations. If the unit is intended to exe-cute only in the output-calculation step after the flowsheet has con-verged, then no feed streams are required.

Thermal Condition of FeedsThe thermal condition of feed streams is set by PRO/II and should not be altered by user-added unit operations. These conditions include temperature, pressure, phase state, enthalpy, compositions, and compressibility factor.

Note: It is never permissible for a user-added unit operation to replace any feed stream data in stream storage.

Product StreamsProduct streams may be created by the user-added calculation rou-tine and placed into stream storage for subsequent use by other user-added unit operations. The decision to create or use product streams is left to the developer. PRO/II never requires them in any execution step.

It is the responsibility of the developer to ensure that all necessary properties are set for all product streams before exiting a calculation routine. Typically, this involves calculating the properties and then saving the product streams using URXSTR. Conversely, an output report routine should never attempt to store stream (or any other) data, since it is by definition merely reporting completed results. Table 18-1 identifies some of the subroutines that may be used for this purpose.

Table 18-1: Interface Routines for Product Stream PropertiesSubroutine Description

UFLSH Performs flash calculations

U3FLSH Performs VLLE flash calculations

UFLSHSOL Performs flash calculations for streams that contain solids components.

UHS Generates enthalpy, entropy, and density data

URXSTR Retrieves and stores stream data in stream storage

TTPROP Calculates transport properties

UH2OP Calculates water properties

UDENS Computes wet and dry flowing volumes


Refer to Table 15-1 on page 15-2 for a complete listing of stream interface routines.

Example 18-4: Spec and Vary Using RPARM

Thermal Condition of ProductsThe thermal condition of product streams is set by user-added unit operation calculations. Often this is a primary purpose of the subroutine.

Interface subroutine USTHER allows user-added subroutines to select a specific thermodynamic method set to use when performing stream calculations. This is available only when two or more method sets exist in the simulation problem. Call USTHER before performing flashes or other stream property calculations.

Designing Data StorageData arrays IPARM, RPARM, HEAT, and SUPPLEMENTAL array are the primary storage for calculated results in addition to user input data.

Integer InputsIPARM integer,.... (Up to 250 values)

Real Number Inputs

RPARM real no,.... (Up to 500 values) SUPPLEMENTAL i,Ri/Ri+1/.../j,Rj/Rj+1... (Up to 10000 values)

Heater/Cooler dutiesHEAT duty x 10-6,.... (Up to 10 values)

When designing the storage requirements of a user-added unit oper-ation, a developer should first characterize the data as input data, calculated results, or other data used internally by the unit operation (such as flags and counters).

Generally, user input data should be mapped at the beginning of storage arrays. If used, the HEAT array typically contains only user input data. Leave some empty elements after the end of input data and map in the internal variables. After leaving a few more empty elements, map calculated results towards the end of the array. The empty elements leave room for later additions.

Separate integer data from floating-point data and map it into the IPARM array.


Identify floating-point data that may be useful in other parts of a simulation. These typically are scalar values. Map them into the RPARM array, with any user input data mapped first, at the begin-ning of the array.

The first 100 elements of the RPARM array are available for use else-where in the flowsheet through the standard SPEC, VARY, DEFINE, PARAMETER, and CONSTRAINT constructs available in controllers. They also are accessible to CASE STUDIES through the CHANGE, PARAMETER, and RESULT constructs.

Decide whether or not to store any data in the HEAT array and map it there as desired.

The remaining data should be mapped to the SUPPLEMENTAL array. This is where the larger blocks of data should be stored. Determine whether or not some of the data constitute sub-arrays. For example, multiple temperatures and multiple pressures routinely are needed.

User-Added Unit Operations and Recycle LoopsUser unit operations may be used in recycle loops in exactly the same manner as any other unit operations. If desired, the calculation subroutine may perform cross-checks of the input data, and write progress messages or intermediate calculated results. When using the output interface routines (HEAD, UAOUT, etc.) the output typically appears in the History file.

Convergence or non-convergence should be signaled from user modules. Fatal errors also should be signaled so that calculations may be aborted. Developers should use the ISOLVE and ISTOP vari-ables to return status codes to PRO/II. The calculation routine returns these variables to PRO/II when it completes execution after being called.

Note: For user-added units in recycle loops, it is important that the calculations be performed as efficiently as possible to minimize computing costs.


Calculation Routines -- Fortran Coding ConventionsInformation is communicated to the user subroutine through the subroutine’s argument list and the common blocks described in Chapter 15, "Interfacing Software".

Calling sequence:

CALL USERnn( IPARM, RPARM, SUPPLE, HEAT, & IDATA, ISOLVE, ISTOP )!! Argument Declarations! INTEGER(4) :: IPARM( * ) ! in/out 250 elements REAL(4) :: RPARM( * ) ! in/out 500 elements REAL(4) :: SUPPLE( * ) ! in/out 10000 elements REAL(4) :: HEAT( * ) ! in/out 10 elements INTEGER(4), INTENT( IN ) :: IDATA( * ) INTEGER(4), INTENT( OUT ) :: ISOLVE INTEGER(4), INTENT( OUT ) :: ISTOP

where:

nn Subroutine number, 41-60, 81-160 (Table 18-2)

IPARM1 Integer parameters (250)

RPARM1 Real parameters (500)

SUPPLE1 Real data storage (10000)

HEAT1 Heat duties x 10-6 (10)

IDATA(1) Number of feeds

IDATA(2) Number of products

IDATA(3) Number of heaters

IDATA(4) Number of components

IDATA(5) Water decant switch:1 = water is regular component2 = water is decanted

IDATA(6) Standard output file

IDATA(7) Integer representation of first 4 characters of the unit identifier for unit (A4).


Subroutine Naming ConventionsPRO/II associates input keywords with specific user-added subrou-tines. It also associates a specific output routine with each calcula-tion routine. These associations are implemented through a pre-defined set of the subroutine naming conventions. Developers must use the subroutine names shown in Table 18-2 to achieve a success-ful implementation.

Table 18-2: Naming Conventions for Unit Op SubroutinesInput

Keyword1Calculation

Routine Name1Output

Routine Name1,2

US1 USER41 U41OUT. . . through . . .

US20 USER60 U60OUT

US41 USER81 U81OUT. . . through . . .

US120 USER160 U160OUT

The following coding practices are highly recommended:

IDATA(8)-(10) Integer representation of first 12 characters of the name for unit (3A4).See Coding Practice 3, below.(IDATA(8)-(10) are available to output subroutines at printout time only.

Output Variables

ISOLVE2 Solution flag:0 No Solution, no calculations attempted

1-9 No solution10 Solution reached

ISTOP2 Fatal error switch: 0 No Fatal errors, continue calculations1 Yes, Fatal errors. Halt all calculations

1) IPARM, RPARM, SUPPLE, and HEAT arrays may contain input data, internal subroutine data, and calculated results.

2) ISOLVE and ISTOP are initialized to zero by PRO/II.

1) User-Added Units 21 through 40 are reserved for SIMSCI internal units.

2) Output subroutines are optional. However, if supplied, they must follow the correspondence shown above.


1. Verify feed streams. Use interface routine URXINF to identify required feed streams. If a feed essential to the calculations is missing, call UAERR to register an Error, Warning, or Message in the PRO/II error-processing system. Return ISOLVE with a value between 1 and 9 to indicate the unit did not solve. Devel-opers decide the significance of the values 1 - 9. It may also be desirable to return ISTOP=1 or call UAERR to register an Abort. Either option terminates all flowsheet calculations immedi-ately, but use this option with care. It is normal for feeds to units in recycle loops to start with rates of zero. In a well-formed simulation, the feed flows build up on successive recy-cle iterations to finally achieve a valid solution.

2. Verify feed stream data. Use interface routine URXSTR to retrieve feed stream data. Any required feeds having a zero rate might be an error. If so, implement appropriate error processing.

3. Use URXINF to retrieve the 12-character ID’s of other feeds, product streams, and of the unit operation itself, as desired.

4. Check the input data for completeness and consistency, and perform any necessary error processing. Call UAERR to register an error in the PRO/II error system.

5. Perform calculations, saving results in the IPARM, RPARM, SUPPLE, and HEAT heat arrays, as appropriate.

6. Intermediate results may be printed as desired. Define an IPARM element as an intermediate print flag, so users can control the printout.

7. Write intermediate printout to the PRO/II history file or the dis-play terminal using output routine UAOUT. (PRO/II may inter-cept terminal output if it conflicts with the graphical user interface display). Alternatively, use the unit number from IDATA(6) to write to the history file using routine PAWRITE. To write to a completely different file, use routine FIGETU to obtain a valid unused file unit number. Open a file on the file unit, and use the file unit number with routine PAWRITE to write data to the file. Be sure to close the file before returning to PRO/II.

8. Set properties for product streams using interfacing routines described in Chapter 15, "Interfacing Software". Performing a flash is practice to set the properties.

9. Store product streams in data stream storage by using URXSTR.


10. Set ISOLVE appropriately. ISOLVE is preserved for each execution of a user module and may be used as a counter for non conver-gence for recycle problems. When a value of 9 (or less, depend-ing on the user’s preference) is reached, a catastrophic situation may be signaled by setting ISTOP to 1.

11. When the calculations solve satisfactorily, return ISOLVE=10 and ISTOP=0.

Output SubroutinesOutput subroutines for the user-written unit operations are optional. Their purpose is to report the results of user-added unit operation calculations. PRO/II associates one output subroutine with each for user-added unit operation calculation routine. These associations are maintained through the subroutine naming conventions. Devel-opers of user-added output routines must obey the naming conven-tions listed previously in Table 18-2. For example, use output routine U59OUT to generate a report for calculation routine USER59.

As delivered, PRO/II includes an output routine for each user-added unit operation. Most of them contain no active code, so they do not produce any reports. The intent is for developers to write appropri-ate code to accurately report the results of their unit operations. When an output routine is called without first replacing it with user-written code, PRO/II typically generates the following message:

*** WARNING *** USER-ADDED SUBROUTINE ****** IS CALLED IN THIS PROBLEM BUT NO CODE WAS SUPPLIED BY THE USER.

Reporting Data in Output Dimensional UnitsOutput subroutines for user-added units must be programmed to generate results in a variety of dimensional units of measure. This can be accomplished by using the /OUTFAC/ and /FACTOR/ common blocks as described in Chapter 15, "Interfacing Software". Sample code for subroutine U42OUT.FOR appears in the examples near the end of this chapter.

Example:Assume RPARM(26-30) contains temperatures. The following partial code sample demonstrates using the /OUTFAC/ common to convert and print values in output units from a UxxOut routine.


INCLUDE 'PMXUSR.CMN' INCLUDE 'FACTOR.CMN ! brings in TCONVT factor INCLUDE 'OUTFAC.CMN ! brings in IHOL, TXXX data1010 FORMAT( / 10X, 'TEMPERATURE, ', A2, 5X, 5F13.2 ) ifOK = 0 DO I = 26, 30 IF( RPARM( I ) .GT. DZ0 ) THEN TE(I) = (RPARM(I)+TCONVT)*TXXX( 6 )-TXXX(10) ifOK = ifOK + 1 ELSE TE(I) = -1000.0D+0 ! indicates missing value ENDIF END DO IF ( NOT .GT. 0 ) THEN IOUT = IDATA( 6 ) ! LFU of standard report file WRITE( IOUT, 1010 ) IHOL(6), ( TE( K ), K = 1, NOT ) END IF

Refer to /OUTFAC/ in Chapter 15 for more discussion of using the TCONVT, TXXX( 6 ), and TXXX( 10 ) conversion factors, and IHOL data to report the units of measure.

Availability of DataPRO/II delivers the calculated results from a user-added unit opera-tion to the corresponding output subroutine in two ways:

Arguments in the subroutine call list. These include the IPARM, RPARM, SUPPLE, and HEAT arrays (described earlier).

Product streams.

The output subroutine for each user unit operation in the flowsheet is called at printout time.

All output values must be multiplied by the appropriate output con-version factors available in common block /OUTFAC/ (see Chapter 15, "Interfacing Software") to ensure that the multiple output dimension and scaling features of PRO/II execute properly for user-written output subroutines.


Output Subroutines -- Fortran Coding ConventionsCalling sequence:

CALL UnnOUT( IPARM, RPARM, SUPPLE, HEAT, IDATA )

where:

nn 41-60, 81-160 Subroutine number (Table 18-2)

IPARM, RPARM, SUPPLE, HEAT, and IDATA

These arrays are discussed at length earlier in this chapter.

Output Page LayoutUser output subroutines should follow the margin conventions used by PRO/II. In the basic layout, the first character of each row is reserved for Fortran line control characters. Beginning with the sec-ond character, the page is ruled into vertical columns, each contain-ing 13 characters. Table 18-3 defines the column character positions across a page.

Table 18-3: PRO/II Output Report Page Layout

Column Character Positions Description of Contents

1 2-14 Labels and units of measure

2 15-27 Labels and units of measure

3 28-40 1st data column

4 41-53 2nd data column

5 54-66 3rd data column

6 67-79 4th data column. Last column when WIDTH=80

7 80-92 5th data column. First column when WIDTH=120 or 132

8 93-105 6th data column

9 106-118 7th data column. Last column when WIDTH=120

10 119-131 8th data column. Available only when WIDTH=132

Standard 8½ by 11 inch paper only displays 66 rows of 80 charac-ters. Using 6 rows for headings, each page may contain up to 60 rows of output.


Example ProblemsThese examples illustrate many of the features available for user-written unit operations. Each example has a corresponding output subroutine; however, this is not a necessity unless printout in addi-tion to the standard PRO/II output is desired. (If special printout is not desired for a user-written unit operation, the dummy printout subroutine supplied by PRO/II satisfy the system requirements.)

All subroutines in the examples have been written in a general man-ner, with calculations independent of the input dimensions selected by the user.

The following details are given for each example:

Description of the subroutine.

Fortran listing for the subroutine.

Problem keyword input file.

Excerpts from the problem output.

Example 18-5: Pipe Pressure Drop ModelThis unit operation may be used to compute pressure drops for liq-uid or vapors flowing in commercial steel or wrought-iron pipe-lines. The Darcy formula for pressure drop is used:

(18-1)

where:

ΔP = pressure drop, psi ρ = density, lb/ft3

v = mean velocity, ft/sec L = length, ft d = inside diameter, in. gc = gravitational constant, 32.2 ft/sec2

f = friction factor

Friction factors are calculated using mathematical equivalents for the charts presented by L. F. Moody.

For laminar flow,

f 64 NRe⁄= (18-2)

where:

ΔP ρfLv2

12d 2gc⋅----------------------=


NRe = Reynolds number

For turbulent flow,

flog 1.666– 0.1962 dlog–= (18-3)

The Darcy formula, equation (18-1), is used for both liquid and vapor calculations.

For vapor calculations in which ΔP is less than 10% of the entering pressure, inlet conditions are used for density. For vapor pressures greater than 10% but less than 40% of the entering pressure, the average density is used. The equation is not valid for vapor when pressure drops exceed 40% of the entering pressure.

A flash calculation at outlet conditions is performed to test for phase change.

No provision has been included in the user-added unit operation for mixed-phase streams. Therefore, invalid use of the module will be signaled when calculations are requested for mixed-phase streams.

One feed stream is allowed for this unit calculation; optionally, one product stream may be requested.

The following conditions cause termination of calculations:

Zero or invalid feed.

Mixed phase feed.

Compressibility calculation failure.

Vapor which violates maximum pressure drop.

Incorrect product description.

Generation failure of product with flash or storage of product.

Phase change caused by pressure drop.

Inability to set product stream (when present).

Any of the above failures that prevent generation of a requested product stream from the unit will result in termination of all other PRO/II calculations as well.

Data to this subroutine are supplied in the RPARM array as follows:

RPARM(1) Pipe inside diameter, inches

RPARM(2) Pipe length, feet


Data for printout are passed into an output subroutine with corre-sponding names, as follows:

IPARM(2) Input Integer Print switch: 1 Missing feed2 Mixed phase feed3 Z calculation failure4 Missing diameter/length data5 Vapor too large for method6 Average properties used7 Flash failure for product generation8 Phase change occurs9 Unable to set product stream

IPARM(3) Input Integer flag specifying the inlet phase: 1 Vapor2 Liquid

RPARM(1) Inside diameter, inches

RPARM(2) Pipe length, feet

RPARM(3) Inlet temperature, °F

RPARM(4) Inlet pressure, psia

RPARM(5) Inlet Z factor

RPARM(6) Outlet temperature, °F

RPARM(7) Outlet pressure, psia

RPARM(8) Outlet Z factor

RPARM(9) Velocity, ft/sec

RPARM(10) Reynolds number

RPARM(11) Pressure drop, psi

RPARM(12) Friction factor

Note: A viscosity method must be declared in the thermodynamic METHOD set used by this module. Otherwise, viscosity data are not available for the Reynold’s number determination.

Reference: Crane Technical Paper 410, 1976.

Note: The above dimensions cannot be changed; however, all other input dimensions may be selected as desired by the user.


Fortran ListingsUSER42.FOR—User-Added Pressure Drop Routine

SUBROUTINE USER42( IPARM, RPARM, SUPPLE, HEAT, & IDATA, ISOLVE, ISTOP )!! Compute pressure drops in steel pipes for liquids ! and vapors. MIXED feeds are NOT ALLOWED.! INCLUDE ‘PMXUSR.CMN’ ! brings in MAXCN INCLUDE ‘FACTOR.CMN’ ! conversion factors INCLUDE ‘XPROPX.CMN’ ! component properties! INTEGER(4) :: IPARM(*), IDATA(*), ISOLVE, ISTOP REAL(4) :: RPARM(*), SUPPLE(*), HEAT(*)! REAL(4) :: STREAM(MAXCN+10), PROP(MAXCN), & XKAY(MAXCN), VAP(MAXCN+10), & XLIQ(MAXCN+10), XLQ2(MAXCN+10) CHARACTER*12 CID CHARACTER*40 CNAME! 1001 FORMAT(‘ERROR !! FEED STREAM ‘,A12,’ IS MISSING’) 1002 FORMAT(‘ERROR !! FEED STREAM ‘,A12, ‘ IS MIXED PHASE’) 1003 FORMAT(‘ERROR !! COMPRESSIBILTY CALCULATION FAILURE’) 1004 FORMAT(‘ERROR !! PIPE DIMENSIONS INVALID ‘ / + ‘DIAMETER = ‘,E15.6,/, + ‘LENGTH = ‘,E15.6) 1005 FORMAT(‘ERROR!! DELTA P FOR VAPOR EXCEEEDS 40% ‘, & ‘INLET PRESSURE’) 1007 FORMAT(‘ERROR !! FLASH FAILURE AT OUTLET CONDITION’) 1008 FORMAT(‘ERROR!! PHASE CHANGE AT OUTLET - CALCULATION & ‘INVALID’) 1009 FORMAT(‘ERROR !! UNABLE TO STORE PRODUCT STREAM ‘,A12)! IERR = 0 NOP = IDATA(2) NOCX = IDATA(4) IOUT = IDATA(6) DO I = 1, MAXCN+10 STREAM(I) = 0.0 END DO!! Use IPARM(2) as the output switch! IPARM(2) = 0!! Retrieve feed stream ! CALL URXINF( ‘FEED’, 1, CID, CNAME, IERR ) IF( IERR .EQ. 0 ) THEN


CALL URXSTR(CID,STREAM,1,IERR) ENDIF IF( IERR. NE. 0 .OR. STREAM(1) .LE. 0.0) THEN IPARM(2) = 1 WRITE( IOUT, 1001 ) CID ISOLVE = 1 ISTOP = 1 GO TO 9999 ENDIF!! Set Phase flag - Check for mixed-phase feed! IF( ABS(STREAM(5) - 1.0) .LT. 0.01 ) THEN IFAZE = 2 ELSE IF( STREAM(5) .LT. 0.01 ) THEN IFAZE = 1 ELSE IPARM(2) = 2 WRITE( IOUT, 1002 ) CID ISOLVE = 1 ISTOP = 1 GO TO 9999 ENDIF!! Calculate compressibility factor! CALL UHS( 3, IFAZE, STREAM, ZF, DZ, IERR )! IF( IERR .NE. 0 ) THEN IPARM(2) = 3 WRITE( IOUT, 1003 ) ISOLVE = 1 ISTOP = 1 GO TO 9999 ENDIF!! Calculate feed stream molecular weight! WT = 0.0 DO I = 1,NOCX WT = WT + STREAM(I+10) * XMW(I) END DO WT = WT / STREAM(1)!! Retrieve inlet temperature(r), pressure(psia),! and density(lb/ft3)! DEGR = (STREAM(2) + TCONVT) * TFAC PSIA = (STREAM(3) + PCONVT) * PFAC RHO = PSIA * WT / ZF / DEGR / 10.731!! Check pipe diameter and length!


DIA = RPARM(1) XLEN = RPARM(2)! IF( DIA .LE. 0.0 .OR. XLEN .LE. 0.0 ) THEN IPARM(2) = 4 WRITE( IOUT, 1004 ) DIA, XLEN ISOLVE = 1 ISTOP = 1 GO TO 9999 END IF!! CROSS-SECTIONAL AREA (FT2)! AREA = 3.14159 * DIA * DIA / 576.0!! Velocity (ft/sec)! CUFTSE = STREAM(1) * WT * WTFAC / TIMFAC / RHO VELOC = CUFTSE / AREA!! CALCULATE VISCOSITY(CP)! CALL TTPROP( 5, IFAZE, PROP, STREAM, IERR )! IF( IFAZE .EQ. 1) THEN CP = PROP(4) * VISFAC ELSE CP = PROP(2) * VISFAC END IF!! Reynolds number! REY = 123.9 * RHO * DIA * VELOC / CP!! DARCY FRICTION FACTOR! IF( REY .LE. 2100.0 ) THEN FFACT = 64. / REY ELSE XLOGF = -1.666 - 0.1962 * ALOG10(DIA) FFACT = 10.0**XLOGF ENDIF!! Pressure drop (psi)! DELTP = 0.001294 * RHO * FFACT * XLEN & * VELOC * VELOC / DIA!! Convert delta P to input units! Calculate outlet pressure! DELP = (DELTP / PFAC) - PCONVT POUT = STREAM(3) - DELP


! ! Save inlet conditions! RPARM(3) = DEGR - FTOR RPARM(4) = PSIA RPARM(5) = ZF!! Check assumptions for VAPOR! IF( IFAZE .EQ. 1 ) THEN!! Error if Delta P exceeds 40% of! inlet pressure! IF( DELTP .GT. 0.4 * PSIA ) THEN IPARM(2) = 5 WRITE( IOUT, 1005 ) ISOLVE = 1 ISTOP = 1 GO TO 9999 ELSE IF( DELTP .GT. 0.1*PSIA ) THEN!! Delta P between 10 & 40% of inlet pressure! Use average density and velocity STREAM(3) = POUT CALL UHS( 3, IFAZE, STREAM, ZF2, DZ, IERR )! IF( IERR .NE. 0 ) THEN IPARM(2) = 3 WRITE( IOUT, 1003 ) ISOLVE = 1 ISTOP = 1 GO TO 9999 END IF! DEGR = (STREAM(2) + TCONVT) * TFAC PSIA = (STREAM(3) + PCONVT) * PFAC RHO2 = PSIA * WT / ZF2 / DEGR / 10.731 RHOA = (RHO + RHO2) / 2. CUFTSE = STREAM(1) * WT * WTFAC & / TIMFAC / RHOA VELO2 = CUFTSE / AREA VELOA = (VELOC + VELO2) / 2.0 DELTP = 0.001294 * RHOA* FFACT * XLEN & * VELOA * VELOA / DIA POUT = RPARM(4) - DELTP VELOC = VELOA RHO = RHOA IPARM(2) = 6 ENDIF END IF!! Save Results


! IPARM(3) = IFAZE RPARM(9) = VELOC RPARM(10) = REY RPARM(11) = DELTP RPARM(12) = FFACT! ! Flash stream at outlet pressure! STREAM(3) = POUT CALL UFLSH( STREAM, VAP, XLIQ, XLQ2, & XKAY, 3, IERR )!! Check for flash failure! IF( IERR .NE. 0 ) THEN IPARM(2) = 7 WRITE( IOUT, 1007 ) ISOLVE = 1 ISTOP = 1 GO TO 9999 END IF!! Store results from outlet flash TCALC = VAP(2) STREAM(2) = TCALC STREAM(5) = (XLIQ(1) + XLQ2(1)) / STREAM(1) STREAM(6) = XLQ2(1) / STREAM(1) RPARM(6) = ((STREAM(2) + TCONVT) * TFAC) - FTOR RPARM(7) = ( STREAM(3) + PCONVT) * PFAC IF( ABS(STREAM(5) - 1.0) .LT. 0.01 ) THEN IFAZE = 2 ELSE IF( STREAM(5) .LT. 0.01 ) THEN IFAZE = 1 ELSE IFAZE = 0 END IF!! Check for a phase change! IF( IFAZE .NE. IPARM(3) ) THEN IPARM(2) = 8 WRITE( IOUT, 1008 ) ISOLVE = 1 ISTOP = 1 GO TO 9999 END IF!! Compute compressibility at outlet! CALL UHS( 3, IFAZE, STREAM, ZF2, DZ, IERR ) IF( IERR .NE. 0 ) THEN IPARM(2) = 3


WRITE( IOUT, 1003 ) ISOLVE = 1 ISTOP = 1 GO TO 9999 END IF STREAM(7) = ZF2 RPARM(8) = ZF2!! Set Product streams! IF( NOP .NE. 0 ) THEN CALL URXINF( ‘PROD’, 1, CID, CNAME, IERR ) IF( IERR .EQ. 0 ) THEN CALL URXSTR( CID, STREAM, 2, IERR ) ENDIF IF( IERR. NE. 0 ) THEN IPARM(2) = 9 WRITE( IOUT, 1009 ) CID ISOLVE = 1 ISTOP = 1 GO TO 9999 ENDIF ENDIF!! SET SOLVE FLAG! ISOLVE = 10! 9999 CONTINUE END SUBROUTINE USER42

U42OUT.FOR—User-Added Output Routine SUBROUTINE U42OUT( IPARM, RPARM, SUPPLE, HEAT, IDATA )!! Output routine for pressure drop unit operation! INTEGER(4) :: IPARM(*), IDATA(*) REAL(4) :: RPARM(*), SUPPLE(*), HEAT(*) CHARACTER(LEN=10) :: CPHASE CHARACTER(LEN=12) :: CID CHARACTER(LEN=40) :: CNAME! 1001 FORMAT(‘ Unit ID - ‘, A12, ’ Name - ‘, A40 // & ‘ **** PRESSURE DROP CORRELATIONS - ‘ & ‘STEEL PIPE *** ‘/) 1002 FORMAT( & 10X,’ PIPE DIAMETER = ‘,F15.2, ’ INCHES’/ & 10X,’ PIPE LENGTH = ‘,F15.1, ’ FEET’ / & 10X,’ PRESSURE DROP = ‘,F15.2, ’ PSI’ // & 10X,’ INLET PRESSURE = ‘,F15.2, ’ PSIA’ / & 10X,’ INLET TEMPERATURE = ‘,F15.2, ’ DEG F’ / & 10X,’ INLET COMPRESSIBILITY = ‘,F15.4 //


& 10X,’ OUTLET PRESSURE = ‘,F15.2, ’ PSIA’ / & 10X,’ OUTLET TEMPERATURE = ‘,F15.2, ’ DEG F’ / & 10X,’ OUTLET COMPRESSIBILITY = ‘,F15.4 // & 10X,’ PHASE = ‘,5X, A10 // & 10X,’ VELOCITY = ‘,F15.4 ’ FT/SEC’ / & 10X,’ REYNOLDS NUMBER = ‘,F15.1 / & 10X,’ FRICTION FACTOR = ‘,F15.6 // )! 1003 FORMAT(10X,’ FEED STREAM - ’, A12 / ) 1004 FORMAT(10X,’ PRODUCT STREAM - ’, A12 / )! 1010 FORMAT(‘** FEED STREAM MISSING **’) 1020 FORMAT(‘** MIXED PHASE FEED ***’) 1030 FORMAT(‘** COMPRESSIBILITY FACTOR CALCULATION ‘, & FAILED **’) 1040 FORMAT(‘** PIPE DIMENSIONS NOT AVAILABLE **’) 1050 FORMAT(‘** CALC DELTA P EXCEEDS 40 % OF INLET ‘, & ‘FOR VAPOR **’) 1060 FORMAT(‘** AVERAGE PROPERTIES USED FOR ABOVE ‘, & ‘CALCULATIONS **’) 1070 FORMAT(‘** PRODUCT FLASH FAILED **’) 1080 FORMAT(‘** PHASE CHANGE AT OUTLET INVALIDATES ‘, & ‘CALCULATIONS**’) 1090 FORMAT(‘** ERROR SETTING UP PRODUCT STREAM **‘)!! Retrieve data from arrays! NOP = IDATA(2) IOUT = IDATA(6) ISW = IPARM(2)!! Write the output report page header! CALL HEAD!! Write the unit operation TITLE! CALL URXINF( ‘UNIT’, 0, CID, CNAME, IERR ) WRITE( IOUT, 1001 ) CID, CNAME!! Skip the output report if error code 1 - 5 applies! IF( ISW .EQ. 0 .OR. ISW .GT. 5 ) THEN IF( IPARM(3) .EQ. 1 ) THEN CPHASE = ‘VAPOR’ ELSE CPHASE = ‘LIQUID’ END IF WRITE( IOUT, 1002 ) & RPARM(1), RPARM(2), RPARM(11), & RPARM(4), RPARM(3), RPARM(5), & RPARM(7), RPARM(6), RPARM(8), CPHASE, & RPARM(9), RPARM(10), RPARM(12)


END IF CALL URXINF( ‘FEED’, 1, CID, CNAME, IERR ) WRITE( IOUT, 1003 ) CID IF( NOP .NE. 0 ) THEN CALL URXINF( ‘PROD’, 1, CID, CNAME, IERR ) WRITE( IOUT, 1004 ) CID END IF ISW = ISW + 1 IF( ISW .EQ. 1 ) THEN CONTINUE ELSE IF( ISW .EQ. 2 ) THEN WRITE(IOUT,1010) ELSE IF( ISW .EQ. 3 ) THEN WRITE(IOUT,1020) ELSE IF( ISW .EQ. 4 ) THEN WRITE(IOUT,1030) ELSE IF( ISW .EQ. 5 ) THEN WRITE(IOUT,1040) ELSE IF( ISW .EQ. 6 ) THEN WRITE(IOUT,1050) ELSE IF( ISW .EQ. 7 ) THEN WRITE(IOUT,1060) ELSE IF( ISW .EQ. 8 ) THEN WRITE(IOUT,1070) ELSE IF( ISW .EQ. 9 ) THEN WRITE(IOUT,1080) ELSE IF( ISW .EQ. 10 ) THEN WRITE(IOUT,1090) END IF! END SUBROUTINE U42OUT

PRO/II Keyword Input FileTITLE PROB=USERADD, PROJ=U42, USER=SIMSCI, DATE=JUN06$$ TESTS USER42 AND U42OUT$ DIME LIQV=BBLCOMPONENT DATA LIBID 1, C1/ 2, C2/ 3, C3 TBPCUTS 100, 1500, 10THERMO DATA METHODS KVALUE=SRK, ENTHALPY=SRK, ENTROPY=SRK, & TRANSPORT=PETRO, NAME=DEFAULT, & DENS(L)=API, DENS(V)=SRK METHODS KVALUE=GS, ENTHALPY=CP, ENTROPY=SRK, & TRANSPORT=PETRO, NAME=M2, & DENS(L)=API, DENS(V)=SRKSTREAM DATA PROP STRM=1, TEMP=40, PRES=1300, PHASE=V, & RATE(G)=4.3E6, COMP=75/ 21/ 4


PROP STRM=2, TEMP=60, PRES=150, RATE(V)=1900, & ASSAY=LV API STRM=2, AVG=30.6 TBP STRM=2, DATA=0,100/ 10,275/ 30, 475/ & 50,620/ 70,840/ 100,1500 NAME 1,NATL GAS/ 2,CRUDE OILUNIT OPERATIONS$ Natural gas flowing through 10 mile pipeline US2 UID=P2, NAME=NATL GAS DP FEED 1 PROD P2V RPARM 13.376, 52800$ Natural gas flowing through 100 mile pipeline US2 UID=P3, NAME=NATL GAS FEED 1 RPARM 13.376, 528000$ Crude oil flowing through 5 mile line US2 UID=P1, NAME=CRUDE DP FEED 2 RPARM 12.09, 26400 METHODS ID=M2END

Partial PRO/II OutputSIMULATION SCIENCES INC. R PAGE P-2PROJECT U42 PRO/II UAS 386/EMPROBLEM USERADD OUTPUT SIMSCI CALCULATION SEQUENCE AND RECYCLES JUN06=============================================================== CALCULATION SEQUENCE SEQ UNIT ID UNIT TYPE ——— ——————— ————————— 1 P2 USER-ADDED 2 P3 USER-ADDED 3 P1 USER-ADDED=============================================================== UNIT 1, ‘P2’, ‘NATL GAS DP’ UNIT ID - P2 NAME - NATL GAS DP **** PRESSURE DROP CORRELATIONS - STEEL PIPE *** PIPE DIAMETER = 13.38 INCHES PIPE LENGTH = 52800.0 FEET PRESSURE DROP = 37.41 PSI INLET PRESSURE = 1300.00 PSIA INLET TEMPERATURE = 40.00 DEG F INLET COMPRESSIBILITY = 0.6543 OUTLET PRESSURE = 1262.59 PSIA OUTLET TEMPERATURE = 37.61 DEG F OUTLET COMPRESSIBILITY = 0.6540 PHASE = VAPOR VELOCITY = 8.7047 FT/SEC REYNOLDS NUMBER = 7157016.5


FRICTION FACTOR = 0.012972 FEED STREAM - 1 PRODUCT STREAM - P2V

UNIT 2, ‘P3’, ‘NATL GAS’ UNIT ID - P3 NAME - NATL GAS **** PRESSURE DROP CORRELATIONS - STEEL PIPE *** PIPE DIAMETER = 13.38 INCHES PIPE LENGTH = 528000.0 FEET PRESSURE DROP = 378.16 PSI INLET PRESSURE = 1300.00 PSIA INLET TEMPERATURE = 40.00 DEG F INLET COMPRESSIBILITY = 0.6543 OUTLET PRESSURE = 921.84 PSIA OUTLET TEMPERATURE = 11.09 DEG F OUTLET COMPRESSIBILITY = 0.6642 PHASE = VAPOR VELOCITY = 9.7048 FT/SEC REYNOLDS NUMBER = 7157016.5 FRICTION FACTOR = 0.012972 FEED STREAM - 1 ** AVERAGE PROPERTIES USED FOR ABOVE CALCULATIONS **

UNIT 3, ‘P1’, ‘CRUDE DP’ UNIT ID - P1 NAME - CRUDE DP **** PRESSURE DROP CORRELATIONS - STEEL PIPE *** PIPE DIAMETER = 12.09 INCHES PIPE LENGTH = 26400.0 FEET PRESSURE DROP = 28.08 PSI INLET PRESSURE = 50.00 PSIA INLET TEMPERATURE = 60.00 DEG F INLET COMPRESSIBILITY = 0.1229 OUTLET PRESSURE = 121.92 PSIA OUTLET TEMPERATURE = 59.94 DEG F OUTLET COMPRESSIBILITY = 0.0999 PHASE = LIQUID VELOCITY = 3.7112 FT/SEC REYNOLDS NUMBER = 101227.2 FRICTION FACTOR = 0.013232 FEED STREAM - 2


User-Added Pipe Pressure Drop Utility RoutinesThe PIPE unit operation in PRO/II supports up to two user-added subroutines at a time to compute the pressure drop through the pipe. Each PIPE unit in the simulation can access one or the other of these two routines by specifying either DP1 or DP2 as the argument to the DPCORR keyword on the LINE statement. PRO/II already includes sample calculation routines, so these two options may be exercised in the version as delivered. The following table shows the association between the input keywords and the corresponding pressure drop routine.

DPCORR = Selects the pressure drop correlation. Arguments DP1 and DP2 select a user-added subroutine written and built in the User-Added Library.

DP1 PIPUS1.FOR performs pressure drop calculations.

DP2 PIPUS2.FOR performs pressure drop calculations.

Developer InformationOf course, the intended purpose is to allow you to implement and use your own pressure drop correlation(s) instead of using those provided by SIMSCI. To create your own pressure drop correlation routine, you must replace the subroutine supplied by SIMSCI with one that contains your own code. Custom routines must include the following argument list:

SUBROUTINE PIPUS2(& HLNS, AINCL, DIAM, AREA, RUFF,& RNUMB, FRICT, FROUDE, NOACCL, PRES,& RLVELN, VELSL, VELSG, QLI, QGI,& RLDENS, VISL, RLSTEN, RVDENS, VISV,& HL, IREG, FRGR, ELGR, ACCGR,& DPINCR, NFOUT, IDG, NUIDD, NSAVE,& INTAB )

The 31 arguments are defined as follows:

Name Type Brief Description UOM

HLNS DP No slip holdup≤ 0.0 = Single-phase vapor0.0<HLNS<1.0 = Mixed phase

(vap+liq)≥1.0 = Single-phase liquid

1) DP indicates the argument is a double precision floating point value.2) Chr*(*) indicates the argument is an inherited-length character string. 3) All Integer variables are type INTEGER(4)


AINCL DP Pipe inclination angle radians

DIAM DP Pipe inside diameter feet

AREA DP Pipe inside area square feet

RUFF DP Pipe roughness/diameter ratio

RNUMB DP Reynolds number

FROUDE DP Froude number

NOACCL Integer NOACCELERATION keyword flag

0 = acceleration APPLIED 1 = acceleration OMITTED

PRES DP Absolute pressure psiaRLVELN DP Pipe liquid VELOCITY number

VELSL DP Pipe liquid SUPERFICIAL VELOCITY

ft/sec

VELSG DP Pipe vapor SUPERFICIAL VELOCITY

ft/sec

QLI DP Pipe liquid FLOWRATE cu.ft/secQGI DP Pipe vapor FLOWRATE cu.ft/secRLDENS DP Pipe liquid (oil+water)

DENSITYlb/cu.ft

VISL DP Pipe liquid (oil+water) VISCOSITY

cP

RLSTEN DP Pipe liquid (oil+water) SURFACE TENSION

dyne/cm

RVDENS DP Pipe vapor DENSITY lb/cu.ftVISV DP Pipe vapor VISCOSITY cPNFOUT Integer Fortran File Unit for printing

diagnostic messages

IDG Integer Diagnostic printout flag (DUMP value)

0 = Suppress diagnostics1 = Generate diagnostics

NUIDD Chr*(*) Character string containing ID of (calling) unit op




NSAVE Integer Not used here

INTAB Integer Not used here. Replace by IDG.OUTPUT Variables

FRICT DP Pipe friction factor (Calculated and returned even when no input value is supplied)

HL DP Pipe slip holdup

IREG Integer PD method flow regime flag1 = Liquid 2 = Vapor 3 = Distributed 4 = Intermittent 5 = Segregated6 = Transition

FRGR DP Friction gradient psi/ftELGR DP Elevation gradient psi/ftACCGR DP Acceleration gradient psi/ftDPINCR DP Total gradient FRGR + ELGR +

ACCGRpsi/ft

Note: Be sure to include the SIMSCI-provided INCLUDE file PRECIS.CMN as the first line of active code after the SUBROUTINE statement. This helps ensure that all floating- point arguments are type DOUBLE PRECISION.




Chapter 19Reaction Kinetic Subroutines

User-added reaction kinetic subroutines provide users the capability of writing reactor rate equation subroutines for use with the CSTR and PLUGFLOW unit operations. Users may write up to five such rou-tines, any of which may be utilized by CSTR or PLUGFLOW reactors throughout the flowsheet.

Note: Shorter reaction kinetic models may be more easily inte-grated into PRO/II using the In-Line Fortran feature (see the PRO/II Keyword Manual).

User InformationInput Description

Reaction Kinetic subroutines must be selected in each unit opera-tion that uses them. Only the CSTR and PLUGFLOW unit operations support their use. See the PRO/II Keyword Manual for further infor-mation about CSTR and PLUGFLOW input data requirements.

Selecting Reaction Kinetics SubroutinesIn the UNIT OPERATION section of the PRO/II keyword input file, indicate which reactor model to use:

CSTR or PLUGFLOW UID = uid, {NAME=text}

On the CALCULATION statement, select one of the five available kinetic models. Specify the SUBROUTINE option on the KINETICS key-word and enter the subroutine identifier as the argument.

RXCALC KINETICS(SUBROUTINE)=U1 (or U2, U3, U4 or U5).


U1, U2, U3, U4, U5

Each of these keywords designates a specific user-added kinetics subroutine to use for rate calculations. Table 19-1 shows the correspondence between this key word and the actual kinetics subroutines

Table 19-1: Keywords for User-Added Kinetics SubroutinesInput Keyword

User-Added Kinetics Subroutine

U1 USKIN1

U2 USKIN2

U3 USKIN3

U4 USKIN4

U5 USKIN5

Keywords for User Data Input IPARM integer {, integer, ....} (Up to 10 values)

RPARM real {, real, .... } (Up to 70 values)


Users enter most reaction data for a CSTR or PLUGFLOW reactor unit operation using the normal keywords provided by PRO/II. How-ever, a user-added kinetics routine may require additional data for its own use. The data requirements are defined by the developer of the user-added subroutine; not by SIMSCI or PRO/II.

Users setting up a simulation supply this additional data by using the IPARM, RPARM, and SUPPLEMENTAL keyword statements. Enter integer data in the IPARM array and floating-point data in the RPARM and SUPPLEMENTAL arrays. Alternatively, the PROVISION Graphi-cal User Interface also supports this input through Date Entry Win-dows of the reactor unit operations. In both the keyword and GUI interfaces, follow the data entry instructions obtained from the developer of the user-added subroutine.

Note: The following definitions only include limitations imposed by PRO/II. Developers of user-added unit operations may impose additional restrictions on data input that users must observe.

19-2 Reaction Kinetic Subroutines February 2009

Integer InputsIPARM integer {, integer, ....} (Up to 70 values)

Note: User-written subroutines may change the values of input data.

Real Number InputsRPARM real {, real , .... } (Up to 70 values)


Note: User-written subroutines may change the values of RPARM and SUPPLEMENTAL input data. RPARM’s are accessible by the CONTROLLER, MVC, OPTIMIZER, and CALCULATOR units. They also may be used or changed by CASESTUDYs.

User-Added Kinetics and ControllersParameters stored in the RPARM array for a user-written kinetic mod-ule may be used by a feedback controller as control parameters. They may also be used in the specification of a feed forward con-troller (DEFINE), a feedback controller (CONTROLLER, MVC), or a flowsheet OPTIMIZER. Only values stored in the RPARM array are available as flowsheet parameters.

See Chapters 10.5 and 10.6 of the PRO/II Keyword Manual for more details on the CONTROLLER unit and DEFINE feature.

Developer InformationGuidelines

Most data is communicated to the user-added kinetics subroutine through the argument list. There are no streams, although the input includes data that defines the thermal condition of the reacting fluid.

Developers may wish to retrieve pure component data from com-mon block /XPROPX/ or /XPROPY/, dimensional unit conversion fac-tors from /FACTOR/, and stream properties through subroutine TTPROP (see Chapter 15, ”Interfacing Software”).


Note: Interface subroutine URXSTR, used to store and retrieve stream data, is not available in USKINn subroutines, since streams are not used.

Calculation Routines -- Fortran Coding ConventionsCalling sequence:

CALL USKINn( RSDAT1, RSDAT2, RRDAT1, IRDAT1,& RPARM, IPARM, SUPPLE, STOICH,& ORDER, IDBASE, ACTIVE, PREEXP,& RATES, IERR )

where:

USKINn The name of a pre-defined kinetics subroutine. It must be one of USKIN1, USKIN2, USKIN3, USKIN4, or USKIN5

The data shown in Table 19-2 are supplied by PRO/II through the argument list and should not be altered in subroutine USKINn. Many of the variables in the argument list for routines USKINn are accessi-ble through in-line kinetic procedure variables (see Chapter 10.7, Procedure Data, in the PRO/II Keyword Manual). Also see Table 19-3 for additional data that may be required by individual kinetics routines.

Table 19-2: USKINn Input Data Supplied by PRO/IIInput

Argument DescriptionIn-LineProcedure

ElementRSDAT1( 1-50 )

Reacting Fluid Properties Variable

1 Temperature of reacting fluid RTEMP2 Pressure of reacting fluid RPRES3 Molecular weight of reacting fluid RMW4 Specific gravity (60/60) of reacting fluid RSPGR5 Molar flow rate of reacting fluid RMRATE6 Weight flow rate of reacting fluid RWRATE7 Standard volumetric flow rate of reacting fluid

(LIQVOL units if OPERATION PHASE=L, VAPVOL units if OPERATION PHASE=V)

RSVRAT


8 Actual volumetric flow rate of reacting fluid (LIQVOL units if OPERATION PHASE=L else VAPVOL units if OPERATION PHASE=V)

RAVRAT

9 Liquid mole fraction of reacting fluid RLFRAC10 Vapor viscosity RVVISC11 Liquid viscosity RLVISC12 Vapor conductivity RVCOND13 Liquid conductivity RLCOND14 Vapor specific heat (wt. basis) RVCP15 Liquid specific heat (wt. basis) RLCP16 Surface tension RSURF17 Temperature in absolute input units RTABS

18-50 Not used

RSDAT1( 51-67 )PFR Utility Stream Properties

Same as RSDAT1(1-17) for PFR heating/cooling stream. Variable names use to U replace R to indicate utility side.

Element Variable

51 Temperature of reacting fluid UTEMP52 Pressure of reacting fluid UPRES53 Molecular weight of reacting fluid UMW54 Specific gravity (60/60) of reacting fluid USPGR55 Molar flow rate of reacting fluid UMRATE56 Weight flow rate of reacting fluid UWRATE57 Standard volumetric flow rate of reacting fluid

(LIQVOL units if OPERATION PHASE=L, VAPVOL units if OPERATION PHASE=V)

USVRAT

58 Actual volumetric flow rate of reacting fluid (LIQVOL units if OPERATION PHASE=L else VAPVOL units if OPERATION PHASE=V)

UAVRAT

59 Liquid mole fraction of reacting fluid ULFRAC60 Vapor viscosity UVVISC61 Liquid viscosity ULVISC




62 Vapor conductivity UVCOND63 Liquid conductivity ULCOND64 Vapor specific heat (wt. basis) UVCP65 Liquid specific heat (wt. basis) ULCP66 Surface tension USURF67 Temperature in absolute input units UTABS

68-100 Not used

Element RSDAT2( 1-300 )

Reacting Fluid Component Data Variable

1-50 Total stream fractions for components 1-50 of reacting fluid

XTOTAL

51-100 Concentrations for components 1-50 in the reacting fluid (weight-moles/liquid volume for OPERATION PHASE=L else weight moles/vapor volume)

XCONC

101-150 Vapor fugacities for components 1-50 in the reacting fluid

XVFUG

151-200 Liquid phase activities XLACT201-250 Vapor phase component mole fractions XVAP251-300 Liquid phase component mole fractions XLIQ

ElementRRDAT1( 1-10 )

Reactor Configuration Data Variable

1 Tube diameter, in. (English) or mm (metric, SI). (PLUGFLOW only)

TDIAM

2 Total tube length, ft. (English) or m (metric, SI). (PLUGFLOW only)

TLEN

3 Cumulative tube length (position of finite element from reactor front end), ft. (English) or m (metric, SI). (PLUGFLOW only)

CUMLEN

4 Current step size (delta X), in. (English) or mm (metric, SI). (PLUGFLOW only)

DELX




5 Current finite element volume (DV), LIQVOL units for OPERATION PHASE=L, else VAPVOL units. (PLUGFLOW only)

DELV

Total reactor volume, LIQVOL units for OPERATION PHASE=L, else VAPVOL units. (CSTR only)

VOLUME

6-9 Not used

10 Gas constant, R RGAS

ElementIRDAT1( 1-10 )

Miscellaneous Integer Data Variable

1 Number of components NOC2 Number of reactions (stoichiometric

equations)NOR

3 OPERATION PHASE flag:0 No errors1 V2 L

IRPHAS

4 CALCULATION flag: 0 Concentration

1 Partial Pressure2 Fugacity3 Activity

ICPF

5 Current integration step number ISTEP6 Standard output file Fortran unit number IOUT7 Index file Fortran unit number INDX

8-10 Not used

STOICH(50,15)

Stoichiometry of each component in each reaction

-

ORDER(50,15)

Order of reaction for each component in each reaction

-

IDBASE(1-15)

Base component for each reaction -




Additional Subroutine-Specific Input DataDevelopers of user-added kinetics routines may require additional data input from the user. PRO/II support this and makes the data available through additional array in the subroutine argument list. Table 19-3 lists the data arrays in the argument list that transmit this additional data. Any or all of the data values in these arrays may be changed to different values inside the user-added-kinetics routine if desired.

Table 19-3: USKINn Additional Subroutine-Specific Input Data

AdditionalInput

Argument Description

In-Line Procedure Variable

RPARM(1-70)

Subroutine-specific Real data required by the subroutine developer (available to other unit operations in the flow sheet).

RDATA

IPARM(1-10)

Subroutine-specific Integer data required by the subroutine developer.

IDATA

SUPPLE(1-200)

Subroutine-specific Real data required by the subroutine developer (available only within the kinetics subroutine).

-

ACTIVE(1-15)

Activation energy for each reaction -

PREEXP(1-15)

Pre-exponential factor for each reaction -




Required Output DataThe purpose of a kinetics subroutine is to compute the overall reac-tion rate of each reaction. These results are returned through the argument list. In addition, PRO/II requires the subroutine to return a status flag indicating whether or not the returned results are valid. The data shown in Table 19-4 must be calculated and returned to PRO/II (through the argument list).

Table 19-4: USKINn Output Arguments & In-Line Procedure Variables

RequiredReturned Data Description

In-lineProcedureVariable

RATES(1-15) Reaction rates for all defined reactions (Wt-moles/time)

RRATES

IERR Error flag0 No errors, results are valid.1 Error, calculations failed.

-

Coding GuidelinesUse the following type declaration statements inside the kinetics subroutine for variables in the argument list.

REAL(4), INTENT(IN) :: && RSDAT1(100), RSDAT2(300), RRDAT1(10)& STOICH(50,15), ORDER(50,15), ACTIVE(15),& PREEXP(15), RATES(15)! INTEGER(4), INTENT(IN) ::& IRDAT1(10), IDBASE(15)! INTEGER(4), INTENT(INOUT) :: IPARM(10) REAL(4), INTENT(INOUT) ::& RPARM(70), SUPPLE(200

Output ReportsPRO/II does not provide any mechanism to report the results from user-added kinetics subroutines. Typically, users inspect the results of the unit operations that employ user-added kinetics to validate the calculations. Developers may designate an element of the IPARM array as a print flag, and use it to write intermediate output from the kinetics calculation routine.


Example Problem—Allyl Chloride Production in a PFRThe following example illustrates the use of user kinetics rate expressions for a simple power law model. The program allows the user to choose between expressions based on partial pressures, con-centrations, vapor phase fugacities, or liquid phase activities.

Fortran Listing

USKIN1—User-Added Power Law Kinetic Routine SUBROUTINE USKIN1 (RSDAT1, RSDAT2, RRDAT1, IRDAT1, 1 RPARM, IPARM, SUPPLE, STOICH, 2 ORDER, IDBASE, ACTIVE, PREEXP, 4 RATES, IERR)! REAL(4) :: RSDAT1(100), RSDAT2(300), RRDAT1(10), 1 RPARM(70), SUPPLE(200), STOICH(50,15), 2 ORDER(50,15), ACTIVE(15), PREEXP(15), 4 RATES(15) INTEGER(4) :: IRDAT1(10), IPARM(10), IDBASE(15) REAL(8) :: RJ !! POWER LAW KINETICS - Concentrations (Default)! - Partial Pressures (use calculated Partial Pres)! - Vapor Fugacities (use IPARM 1, e.g.,IRDAT1(4))!! Code Begins Here! NC = IRDAT1(1) ! Total number of components NRX = IRDAT1(2) ! Number of reactions ATEMP = RSDAT1(1) ! Temperature (input) RTABS = RSDAT1(17) ! Temperature on absolute basis RGAS = RRDAT1(10) ! Universal Gas Constant!! Initialize rates to zero. Determine dimensionless! Activation Energy, calculate Temperature Dependent Term! DO 500 J = 1,NRX RATES(J) = 0.0 ! Initialize rates to zero. ACTENG = ACTIVE(J) ! Reaction Activation Energy!! Convert Activation Energy from thousands to unit values! ACTENG = ACTENG * 1000.0 ERT = -ACTENG / (RGAS * RTABS) RJ = PREEXP(J) * EXP( ERT ) DO 400 I = 1, NC!! Skip non-reactants (i.e., skip all products and! components not in this reaction). IF ((STOICH(I,J) .LT. 0.0) .AND. & (ABS(ORDER(I,J)) .GE. 1.0E-20)) THEN


!! Skip reaction if any reactant mole frac = 0.0 IF (RSDAT2(I) .LE. 0.0) GO TO 500!! Compute Rates using Partial Pressures IF (IRDAT1(4) .EQ. 1) THEN RJ = RJ * (RSDAT2(I)*RSDAT1(2))**ORDER(I,J)!! Compute Rates using vapor fugacities. ELSEIF (IRDAT1(4) .EQ. 2) THEN RJ = RJ * (RSDAT2(I+100)) ** ORDER(I,J)!! Compute Rates using Liquid Activities ELSEIF (IRDAT1(4) .EQ. 3) THEN RJ = RJ * (RSDAT2(I+150)) ** ORDER(I,J)!! Compute Rates using Concentrations (default) ELSE RJ = RJ * (RSDAT2(I+50)) ** ORDER(I,J) END IF END IF 400 CONTINUE IB = IDBASE(J) RATES(J) = RJ * STOICH(IB,J) 500 CONTINUE! END SUBROUTINE USKIN1


PRO/II Keyword Input File TITLE PROB=USPLUG, PROJ=USER-ADD, USER=BDC, DATE=JUN2008 COMPONENT DATA

LIBI 1,CL2/2,PRLN/3,ACL/4,12PR/5,HCL/6,H2O & BANK= PROII_8.2:SIMSCI, PROII_8.2:PROCESS THERMO DATA METH SYST=PR, TRANS=LIBR STREAM DATA PROP STRM=1, TEMP=450, PRES=29.4, RATE=85, COMP=0.2/0.8 PROP STRM=1A, TEMP= 80, PRES=29.4, RATE=85, COMP=0.2/0.8 RXDATA RXSET ID=RS1 REACTION ID=1 $ - GLOBAL DATA - STOIC 1,-1/2,-1/3,1/5,1 HORX HEAT=-48,REFC=1,REFP=V,REFT=179 $ - KINETIC DATA - KPARAMETER PEXP=2.1E11 , ACTIV=27.0096 KPHASE DEFAULT=VAPOR KBASIS VAPOR=MOLAR REACTION ID=2 $ - GLOBAL DATA - STOIC 1,-1/2,-1/4,1 HORX HEAT=-79.2,REFC=1,REFP=V,REFT=179 $ - KINETIC DATA - KPARAMETER PEXP=1.19E7 , ACTIV=6.81198 KPHASE DEFAULT=VAPOR KBASIS VAPOR=MOLAR UNIT OPS PLUGFLOW UID=RX FEED 1 PROD V=2 COLD FEED=1A, V=1B, TOUT=400, U=3.72 RXCA KINETICS(SUBR)=U1, NSTEPS=50 OPER LENG=20.0, DIAM=11.94, PHASE=V, DP=10, & TUBE=4, COUNTER RXSTOIC RXSET=RS1 REACTION 1 BASE COMP=1 REACTION 2 BASE COMP=1 END


Output Listing PLUGFLOW REACTOR SUMMARY JUN2008 ======================================================================= UNIT 1, 'RX' OPERATING CONDITIONS Reactor Flow Type Open Pipe Thermal Specification Type Counter-Current Cooling Duty, MM BTU/HR -0.4502 Total Heat of Reaction at 179.00 F, MM BTU/HR -0.9922 Tubes 4 Diameter, IN 11.9400 Length, FT 20.0000 Volume/Tube, FT3 15.5512 Total Volume, FT3 62.2050 U, BTU/HR-FT2-F 3.720 Residence Time, sec 5.24 Maximum Velocity at 20.00 FT from Inlet, FT/sec 4.6780 Pressure Drop From Feed Stream, PSIA 0.0000 REACTING SIDE Inlet Outlet ----------- ----------- Feed 1 VAPOR Product 2 Temperature, F 450.00 735.91 Pressure, PSIA 29.4000 19.4000 Cold Side Inlet Outlet ----------- ----------- Feed 1A VAPOR Product 1B Temperature, F 86.53 400.00 Pressure, PSIA 29.4000 29.4000 REACTION DATA --------- Rates, LB-MOL/HR ---------- Fraction Component Feed Change Product Converted -------------------- ----------- ----------- ----------- ----------- 1 CL2 17.0000 -16.9929 7.095E-03 0.9996 2 PRLN 68.0000 -16.9929 51.0071 0.2499 3 ACL 0.0000 11.3335 11.3335 4 12PR 0.0000 5.6594 5.6594 5 HCL 0.0000 11.3335 11.3335 Total 85.0000 -5.6594 79.3406


LB-MOL/HR Fraction Base Component Reaction Converted Converted -------------------- ----------- ----------- ----------- 1 CL2 1 11.3335 0.6667 1 CL2 2 5.6594 0.3329 REACTOR MASS BALANCE ----------- Rates, LB/HR ------------ Fraction Component Feed Change Product Converted ------------------ ----------- ----------- ----------- ----------- 1 CL2 1205.3919 -1204.8888 0.5031 0.9996 2 PRLN 2861.4834 -715.0723 2146.4112 0.2499 3 ACL 0.0000 867.2976 867.2976 4 12PR 0.0000 639.4380 639.4380 5 HCL 0.0000 413.2252 413.2252 Total 4066.8753 0.0000 4066.8750 REACTOR PROFILES Reacting Side Cold Distance Temp Pres Temp FT F PSIA F ----------- ----------- ----------- ----------- 0 0.0000 450.00 29.4000 400.00 1 2.0000 565.61 28.4000 394.17 2 4.0000 703.25 27.4000 380.22 3 6.0000 822.73 26.4000 357.23 4 8.0000 868.01 25.4000 327.09 5 10.0000 862.72 24.4000 293.19 6 12.0000 842.55 23.4000 256.94 7 14.0000 818.20 22.4000 218.49 8 16.0000 792.05 21.4000 177.61 9 18.0000 764.60 20.4000 133.83 10 20.0000 735.91 19.4000 86.53 -- Component Mole Fractions vs. Distance from Inlet Distance 1 3 4 2 5 FT CL2 ACL 12PR PRLN HCL --------- ----------- ----------- ----------- ----------- ----------- 0 0.0000 0.20000000 0.00000000 0.00000000 0.80000000 0.00000000 1 2.0000 0.16379562 0.01328580 0.02864823 0.78098455 0.01328580 2 4.0000 0.10707946 0.05075851 0.05270253 0.73870098 0.05075851 3 6.0000 0.04383621 0.10352300 0.06580099 0.68331680 0.10352300 4 8.0000 0.01198179 0.13208931 0.06991112 0.65392846 0.13208931 5 10.0000 0.00330047 0.13997237 0.07090894 0.64584584 0.13997237 6 12.0000 0.00110792 0.14194970 0.07117797 0.64381470 0.14194970 7 14.0000 0.00045995 0.14252608 0.07126746 0.64322043 0.14252608 8 16.0000 0.00023015 0.14272677 0.07130384 0.64301246 0.14272677 9 18.0000 0.00013461 0.14280830 0.07132136 0.64292743 0.14280830 10 20.0000 0.00008943 0.14284574 0.07133104 0.64288805 0.14284574


Chapter 20UAS Refinery Reactor Simulation

The subroutines described in this chapter provide data and methods for modeling pseudo components. To model behavior over broad temperature and pressure ranges, refinery fluids are “characterized” by taking fractionation cuts and creating “pseudo components”. Pseudo components exhibit the average bulk properties of various petroleum fractions. By creating pseudo components and knowing just a few of their basic properties, good models can be created to accurately model fluid behavior in refinery processes.

User Utility Subroutines Table 20-1 is a quick reference to the subroutines described in this chapter.

Table 20-1: Refinery Reactor SubroutinesName Description See ...UDEFNC Retrieves a component’s input (print) or

internal sequence number given the ID and Library number.

20-3

USTHER Sets the current Thermodynamic method to that of a given PRO/II stream. Resets component properties in common /XPROPY/.

20-5

DUPSEUC Retrieves start and end components, and all cut-point temperatures, from a blend as double precision values.

20-4

UPSEUC Single precision version of DUPSEUC. 20-4


DUSTPRP Double precision routine that retrieves properties from a PRO/II stream, one scalar property value per call.

20-6

USTPRP Single precision version of DUSTPRP. 20-6

DUSTRIP Retrieves any scalar Refinery Inspection Property from a PRO/II stream

20-7

USTRIP Single precision version of DUSTRIP. 20-7

DUDIST Generates a 21 point distillation cut-point array. Temperature arrays in and out are always in degrees Kelvin.

20-9

UDIST SIngle precision version of DUDIST. Temperature arrays in and out use input units of temperature.

20-9

URATE Retrieves flow rates of pseudo-components from TBP distillation data.

20-12

UCURVE Computes pseudo-component properties for current thermodynamics Methods set. (2 data points required).

20-15

UPETMD Estimates missing component fixed properties. Updates /XPROPY/ data.

20-22

UBULK Analog of UCURVE, when only a single data point is available.

20-19

Common Blocks

/XPROPY/ Pure component data - may change for each thermodynamic Methods set

20-23

Table 20-1: Refinery Reactor SubroutinesName Description See ...

20-2 "UAS Refinery Reactor Simulation" February 2009

UDEFNCThis routine gets the position of a specified component based on user input (print order) or, alternatively, the PRO/II internal order. This component must be declared in the component section of the flowsheet. Based on this information, the feed and product data of the component can be correctly retrieved and stored regardless of its input order declared in the input file. See also “Internal Component Order vs. Print Order” on page 15-40.

Usage:

CALL UDEFNC( CompID, LibNo, iOpt, iCoNum )

Example: Retrieve Internal Order Number of HydrogenCHARACTER(LEN=16) :: CompIDINTEGER(4) :: LibNo, iCoNum...CompID = ‘H2’CALL UDEFNC( CompID, LibNo, 1, iCoNum )

iCoNum returns the internal order number of hydrogen.

Table 20-2: Arguments for Utility Subroutine UDEFNC()

Variable I/O Type DescriptionCompID In CHAR

*16ID of a component declared in the component section of input.

LibNo In INT PRO/II library number uniquely designated for the specified component. It can be found using Modular Thermodynamics. This number is used only if cName is a blank string.

iOpt In INT Basis of component order. Since most arrays in the UAS system use PRO/II internal order, PRO/II internal order is the default.

1 PRO/II internal order (default)2 User input order (print order)

iCoNum Out INT Position of the specified component in input order or PRO/II internal order. If the component is not found, a zero value is returned.


DUPSEUC double precisionUPSEUC single precision

This routine gets the range of components in the specified blend set. The returned range is based on PRO/II’s internal component order. The initial and end boiling points of each petro narrow cut in the blend are also retrieved. Once this component range is known, the reactor product stream data can be stored in the components of the specified blend set. The name of the blend set is specified at the NAME of the user-added unit in the flowsheet.

Calling sequence:

CALL UPSEUC( IDATA, BP, IBEGIN, IEND, && BPTIP, BPTEP, IERR )

Example:INCLUDE ‘PMXUSR.CMN’INCLUDE ‘XPROPY.CMN’...REAL BPTIP(MAXCN), BPTEP(MAXCN)...CALL UPSEUC( IDATA, BP, IBEGIN, IEND, &BPTIP, BPTEP, IERR)

Table 20-3: Arguments for Utility Subroutine UPSEUC()

Variable I/O Type DescriptionIDATA I INTEGER

(*)This is the IDATA array in the user-added subroutine USERXX. If the blend set name is not available in the IDATA(8-10), the default set will be used.

BP I REAL(MAXCN)

The vector of normal boiling point.

IBEGIN O INTEGER The PRO/II internal order of the first component in the blend.

IEND O INTEGER The PRO/II internal order of the last component in the blend.

BPTIP O REAL(MAXCN)

The vector of initial boiling point of pseudo components in the blend.

BPTEP O REAL(MAXCN)

The vector of end boiling point of pseudo components in the blend.

IERR O INTEGER Error flag:0 SuccessfulAll other values indicate failure.


USTHERMore than one thermodynamic set may be specified in the same PRO/II flowsheet. Each set may have different component proper-ties. This feature is very important to refinery reactors, because the component properties of the product can be very different from those of the feed. This routine sets up the thermodynamic data for the selected stream so that the component properties corresponding to the selected stream can be retrieved or stored properly. The com-ponent data stored in the common block /XPROPY/ can also be updated after the setup.

Note: To use this feature, it is required to declare CDATA = VARY in the flowsheet (see General Data section in the PRO/II Keyword Manual).

Calling sequence:

CALL USTHER( CID, ISETUP, JMETHD, IERR )

Example:CHARACTER*12 CIDCHARACTER*40 CNAME...CALL URXINF(‘FEED’, 1, CID, CNAME, IERR)...ISETUP = 1CALL USTHER( CID, ISETUP, JMETHD, IERR )

Table 20-4: Arguments for Utility Subroutine USTHER( )

Variable I/O Type Description

CID I CHAR*12

The stream ID of the specified stream

ISETUP I INT Property copy flag:0 Do not copy the new component

properties to the XPROPY common block (default)

1 Copy the new component properties to the XPROPY common block

JMETHD O INT PRO/II internal thermo set number; -1 returned if thermo not set up successfully.

IERR O INT Error flag:0 SuccessfulAll other values = Failure


DUSTPRP double precisionUSTPRP single precision

This routine retrieves a selected stream property from the specified stream phase. Stream property values return in PRO/II internal dimensional units, as shown in Table 20-5.

Usage (double precision):CALL DUSTPRP(cSid, cPhase, cProp, DValue, iErr)

Usage (single precision):CALL USTPRP(cSid, cPhase, cProp, DValue, iErr)

Table 20-5: Arguments for Utility Subroutine USTPRP()

Variable I/O Type DescriptioncSid In C*12 Character ID of selected stream, 12

characters maximum

cPhase In C*12 Phase of the property to be retrieved: Character

‘TOTAL’ Total stream‘VAPOR’ Vapor phase‘LIQUID’ Bulk Liquid phase

‘MWS’ Molecular weight Solid phase ‘NMWS’ Non-molecular weight Solid

phase

cProp In C*12 The property to retrieve when the phase is ‘TOTAL’, ‘VAPOR’, ‘LIQUID’, or ‘MWS’:

‘TC’ Critical temperature, K‘PC’ Critical pressure, kPa‘VC’ Critical volume, m3

‘ZC’ Critical compressibility factor‘OMEG’ Acentric factor‘MW’ Molecular weight, kg/m3 ‘SDEN’ Standard density, kg/m3

‘DENS’ Actual density, kg/m3

‘TCON’ Thermal conductivity, Watt/(m-K)

‘VISC’ Viscosity, Pascal‘SURF’ Surface tension, Newton/meter‘RVP’ Reid vapor pressure, kPa‘TVP’ True vapor pressure, kPa‘ENTR’ Entropy, kJ/(kg-mole-K)‘GIBB’ Gibbs free energy, kJ/(kg-

mole)


Example:CHARACTER(LEN=12) :: cSID, cPhase, cPropCHARACTER(LEN=40) :: cNameREAL(8) :: DValue... ! obtain ID of first feed streamCALL URXINF( ‘FEED’, 1, cSID, cName, IERR )... ! DValue returns total stream molecular weightcPhase = ‘TOTAL’cProp = ‘MW’CALL DUSTPRP( cSID, cPhase, cProp, DValue, IERR )

DUSTRIP double precisionUSTRIP single precision

In the refinery reactor simulation, refinery inspection properties are frequently used to characterize the feed. This routine retrieves the selected refinery property from the specified stream. The retrieved refinery property must be declared in the thermodynamic METHOD set used by the user-added subroutine. The property data can be estimated by PRO/II or supplied by the user in the component, thermo and stream data sections. Note that not all the refinery spe-cial properties can be estimated by PRO/II.

Usage (double precision):CALL DUSTRIP(cSid, cProp, iSProp, DVal, iErr)

Usage (single precision):CALL USTRIP( cSid, cProp, iSProp, SVal, iErr )

cProp In C*12 The property to retrieve when the phase is ‘NMWS’ (non-molecular weight solid):

‘DENS’ Actual density, kg/m3 ‘ENTR’ Entropy, kJ/(kg-K)

DVALUE Out Dbl Double precision stream property value

SVALUE Out Dbl Single precision stream property value

IERR Out Int Returned error flag: 0 Successful≠0 Failed

Table 20-5: Arguments for Utility Subroutine USTPRP()



Example:...CHARACTER*12 CID, ATEXTCHARACTER*40 CNAME...CALL URXINF(‘FEED’, 1, CID, CNAME, IERR)...ATEXT = ‘SULF’ISPROP = 0CALL USTRIP(CID, ATEXT, ISPROP, VALUE, IERR)

Table 20-6: Arguments for Utility Subroutine USTRIP()

Variable I/O DescriptioncSid In

C*12The ID of the selected stream (12 characters max)

cProp InC*12

The property keyword (listed in Appendix Table A-1) of the selected refinery property. Examples are:

‘KVIS’ Kinematic viscosity‘POUR’ Pour point‘SULF’ Sulfur content‘NICK’ Nickel content

For properties with more than one sub-type, add a hyphen sign followed by the first two letters of the sub-type to the property ID. Examples are:

‘REFR-C2’ Refractive index at 20C‘REFR-C7’ Refractive index at 70C‘AROM-TO’ Total aromatics content‘AROM-RI’ Content of aromatics with ring structure

For user defined special properties, e.g., SPROP(I), pass a blank string as the value of cProp (i.e., “ “).

iSProp InINT

The property number of user special property SPROP(i):0 PRO/II predefined special property1-9999 User special property

DVal OutR*8

Returned double precision property value

SVal OutR*4

Returned single precision property value

iErr OutINT

Error flag:0 Successful1 Property was not declared in the Thermo

section of inputAll other values indicateFailure


DUDIST double precisionUDIST single precision

Distillation data probably is the most important data for feed char-acterization. This routine retrieves the distillation data for the speci-fied stream. The distillation type, range, and basis can all be specified.

Note this difference: DUDIST temperature arrays DBPIN and DTempO always pass Kelvin values. UDIST temperature arrays SBPIn and STempO always pass temperature values in temperature units defined for problem input.

Usage (double precision):CALL DUDIST( DStVec, DXMW, DBPIn, DSpGr, & ITYPE, ICONV, IBASIS, DVIP, & DVEP, NUMCOP, DTempO, IERR )

Usage (single precision):CALL UDIST( SStVec, SXMW, SBPIn, SSpGr, & ITYPE, ICONV, IBASIS, SVIP, & SVEP, NUMCOP, STempO, IERR )

Table 20-7: Arguments for Utility Subroutine UDIST()

Variable I/O Data Type DescriptionDStVec

SStVec

In REAL*8(10+MAXCN)REAL*4(10+MAXCN)

The standard user vector of stream data. DStVec is double precision and SStVec is single precision. Only rates (element 1 and elements 11 to 10+NOC) are used here. See “User Stream Vector” on page 15-10.

DXMW

SXMW

In REAL*8 (MAXCN)REAL*4 (MAXCN)

Array of component molecular weights in internal component order. DXMW is double precision and SXMW is single precision.

DBPIn

SBPIn

In REAL*8 (MAXCN)

REAL*4 (MAXCN)

DBPIn is a double precision array of component normal boiling point temperatures in internal component order. Values are passed in as Kelvin.SBPIn is a single precision array of temperatures, passed using temperature input units.

DSpGr

SSpGr


Array of component specific gravities at standard conditions in internal component order. Values are dimensionless. DSpGr is double precision and SSpGr is single precision.


ITYPE In INTEGER Distillation type:1 TBP (default)2 D863 D86 with cracking4 D86 at 10 mmHg5 D1160 at 10 mmHg6 D11607 D2887

ICONV In INTEGER Conversion method:1 API632 API873 Edmister-Okamoto6 API94

IBASIS In INTEGER Conversion basis: (applies to DVIP, DVEP, SVIP, and SVEP

0 LV basis1 WT basis

DVIPSVIP

In REAL*8REAL*4

The initial wt% or vol% (based on value of IBASIS above). The value must be less than 5%. It is used to determine the initial boiling point temperature (IP). DVIP is double precision and SVIP is single precision.

DVEPSVEP

In REAL*8REAL*4

The final wt% or vol% (based on value of IBASIS above). It is used to determine the end boiling point (EP). The value must be greater than 95% and less than 99%. DVEP is double precision and SVEP is single precision.

NUMCOP In INTEGER Total component number. This number can be obtained from IDATA(4) in the USERXX routine. Note that this number cannot be greater than MAXCN in common block PMXUSR.CMN.

DTempOSTempO

Out REAL*8 (21)REAL*4 (21)

Array of 21 boiling point temperatures of the 21 distillation curve points (IP, 5%, 10%, 15%, 20%, … 85%, 90%, 95% and EP). Initial point IP is supplied by argument DVIP or SVIP; end point EP is supplied by argument DVEP or SVEP, above.DTempO is double precision and returns all temperature values as Kelvin.STempO is single precision and returns temperatures using input temperature units.

Table 20-7: Arguments for Utility Subroutine UDIST() (Continued)

Variable I/O Data Type Description


Example:...

INCLUDE ‘…\PMXUSR.CMN’INCLUDE ‘…\XPROPY.CMN’...REAL STREAM(10+MAXCN), TDIST(21)CHARACTER*12 CID, ATEXTCHARACTER*40 CNAME...NUMCOP = IDATA(4)CALL URXINF(‘FEED’, 1, CID, CNAME, IERR)CALL URXSTR(CID, STREAM, 1, IERR)...ITYPE = 1ICONV = 2IBASIS = 1WVIP = 0.2WVEP = 99.0

CALL UDIST(STREAM, XMW,BP, DENS, ITYPE,ICONV, IBASIS,WVIP, WVEP, NUMCOP,TDIST, IERR)

IERR Out INTEGER Returned error flag:0 No errors, successfulAll other values indicate failure

Table 20-7: Arguments for Utility Subroutine UDIST() (Continued)

Variable I/O Data Type Description


DURATE double precisionURATE single precision

The pseudo components used in the refinery reactor simulation may not be the same as that in the flowsheet simulation. In the reactor simulation, the pseudo components are determined by the reaction network that describes the reaction behavior. In the flowsheet simu-lation, the pseudo components are determined by the assay data and the blend cut points specified in the flowsheet (see ASSAY and CUTPOINTS in the component data and stream data sections of the PRO/II Keyword Manual). Due to the lack of one-to-one relation-ship between the pseudo components in reactor and flowsheet simu-lations, it is necessary to map the reactor product composition via the product distillation data. This routine uses the TBP distillation data of the reactor product stream predicted by the reactor simula-tion to determine the flow rate of each pseudocomponent in the product stream of the flowsheet.


CALL DURATE( DTVEC, DYVEC, NCPSEU, & ICUMUL, DFOUT, IBEGIN, & IEND, DBPTIP, DBPTEP, & IMETHD, IMAPED, DFRATE, & IERR )


CALL URATE( STVEC, SYVEC, NCPSEU, & ICUMUL, SFOUT, IBEGIN, & IEND, SBPTIP, SBPTEP, & IMETHD, IMAPED, SFRATE, & IERR )

Note that the flow rates of defined components such as H2, H2S, CH4, C2H6, etc. should not be included here. The flow rates of those defined components should be assigned to the STREAM array directly without the need of component mapping.

Table 20-8: Arguments for Utility Subroutine URATE()Variable I/O Data Type Description

DTVEC

STVEC

In REAL*8 (NCPSEU)REAL*4 (NCPSEU)

Array of boiling point temperatures of reactor pseudo-components in PRO/II internal order. DTVEC is double precision and STVEC is single precision.


DYVEC

SYVEC

In REAL*8 (NCPSEU)REAL*4 (NCPSEU)

Array of either liquid volume or weight distribution data that correspond to temperatures in TVEC. See curve option ICUMUL. DYVEC is double precision and SYVEC is single precision.

NCPSEU In INTEGER The number of reactor pseudo-components. This also sizes arrays DTVEC, STVEC, DYVEC, and DYVEC.

ICUMUL In INTEGER Cumulative curve data flag.0 YVEC is a cumulative data array

(default)1 YVEC is a distribution data array

DFOUT

SFOUT

In REAL*8

REAL*4

Total liquid volume or weight flow rate of the reactor pseudo-components included in temperature range of TVEC. When this is greater than zero, flow rates are normalized to this value.

IBEGIN In INTEGER The component number (position) of the first component in the blend (in PRO/II internal order).

IEND In INTEGER The component number (position) of the last component in the blend (in PRO/II internal order).

DBPTIP

SBPTIP


The vector of initial boiling point of pseudo components in the blend.

DBPTEP

SBPTEP


The vector of end boiling point of pseudo components in the blend.

IMETHD In INTEGER Interpolation option:1 Linear 2 Quadratic 3 Cubic spline

IMAPED Out INTEGER (MAXCN)

Array of component mapping flag:0 Get zero flow rate from the

mapping1 Get positive flow rate from the

mapping



Example: ... INCLUDE ‘PMXUSR.CMN’ INTEGER(4), PARAMETER :: NCPSEU=7 INTEGER(4) :: IMAPED(MAXCN) REAL(4) :: TVEC(NCPSEU), YVEC(NCPSEU) REAL(4) :: FRATE(MAXCN), BPTIP(MAXCN), REAL(4) :: BPTEP(MAXCN), FOUT ... TVEC(1) = 15 TVEC(2) = 100 TVEC(3) = 350 TVEC(7) = 680 YVEC(1) = 0.0 YVEC(2) = 10.0 YVEC(3) = 30.0 YVEC(7) = 100.0 ICUMUL = 0 FOUT = 100.0 IMETHD = 3 CALL URATE( TVEC, YVEC, NCPSEU, ICUMUL,& FOUT, IBEGIN, IEND, BPTIP,& BPTEP, IMETHD, IMAPED, FRATE,& IERR )

DFRATE

SFRATE

Out REAL*8 (MAXCN)REAL*4 (MAXCN)

Array of mapped component flow rates

IERR Out INTEGER Error flag:0 Successful≠0 Failed



DUCURVE double precisionUCURVE single precision

The refinery special properties are likely to be changed by the refin-ery reactions. The property values in the same boiling range can be very different between the feed and product. For instance, the sulfur content is largely reduced in the hydro-treating reactions, the aro-matics content is increased in the catalytic cracking reactions and the molecular weight is changed by most refinery reactions. There-fore, different thermodynamic METHOD sets (see Thermodynamic Data section in the PRO/II Keyword Manual) should be used to store the feed and product component properties separately. CDATA=VARY (see General Data Section in the PRO/II Keyword Manual) should also be declared in the flowsheet to support this feature. This UCURVE routine can be used to determine the new component properties for the pseudo components in the thermody-namic set specified for the product stream. Note that this routine should only be called when more than one data point is available from the reactor simulation for the property to be mapped.


CALL DUCURVE( cProp, ISPROP, DTVEC, & DCPROP, NCPSEU, DBP, & DFRATE, IBEGIN, IEND, & DTMINI, dTMAXI, DYLOW, & DYHIGH, IFILL, ITREND, & IMETHD, IUPDAT, DSCALE, & IMAPED, DTGYV, DSUMPRP, & IERR )


CALL UCURVE( cProp, iSProp, STVEC, & SCPROP, NCPSEU, SBP, & SFRATE, IBEGIN, IEND, & STMINI, STMAXI, SYLOW, & SYHIGH, IFILL, ITREND, & IMETHD, IUPDAT, SSCALE, & IMAPED, STGYV, SSUMPRP, & IERR )


Table 20-9: Arguments for Utility Subroutine UCURVE()

Variable I/O Type DescriptioncProp I CHAR*12 The property keyword identifier

‘MW’ Molecular weight‘SG60’ Specific gravity at 60F (15.5C)‘OMEG’ Acentric factor‘TC’ Critical temperature‘PC’ Critical pressure‘VC’ Critical volume‘ZC’ Critical compressibility‘RAKT’ Rackett parameter‘CNUM’ Carbon number‘ZNUM’ Hydrogen deficiency number‘WATK’Watson K value

For refinery special properties, see cProp explained in USTRIP routine.

iSProp I INTEGER The property number of user special property SPROP(i):0 PRO/II defined special property1-9999 User special property (SPROP(i))

DTVEC

STVEC

I REAL*8(NCPSEU)REAL*4(NCPSEU)

Array of end boiling points of reactor pseudo components

DCPROP

SCPROP

I REAL*8(NCPSEU)REAL*4(NCPSEU)

Array of property distribution data, one value for each reactor pseudocomponent, in PRO/II internal component order. DCPROP is double precision and SCPROP is single precision.

NCPSEU I INTEGER Number of reactor pseudo components. This is also the size of TVEC and CPROP arrays.

DBP

SBP

I REAL*8 (MAXCN)REAL*4 (MAXCN)

Array of component normal boiling point temperatures in PRO/II internal component order. DBP is double precision and SBP is single precision. See XPROPY common block for definition.

DFRATE

SFRATE

O REAL*8 (MAXCN)REAL*4 (MAXCN)

Array of mapped component flow rates in PRO/II internal component order. DFRATE is double precision and SFRATE is single precision.

IBEGIN I INTEGER The PRO/II internal order number of the first component in the blend.

IEND I INTEGER The PRO/II internal order number of the last component in the blend.


DTMINISTMINI

I REAL*8REAL*4

The initial temperature of the temperature range on which CPROP is determined. DTMINI is double precision and STMINI is single precision.

DTMAXISTMAXI

I REAL*8REAL*4

The final temperature of the temperature range on which CPROP is determined. DTMAXI is double precision and STMAXI is single precision.

DYLOWSYLOW

I REAL*8REAL*4

Lower bound value of the mapped property.DYLOW is double precision and SYLOW is single precision.

DYHIGHSYHIGH

I REAL*8REAL*4

Upper bound value of the mapped property. DYHIGH is double precision and SYHIGH is single precision.

IFILL I INTEGER Mapping option for components with BP outside the given[TMINI,TMAXI] range:

0 Assign the same property value as the nearest neighboring component which is inside the [TMINI,TMAXI] range (default)

1 Ignore; do not assign a new value2 Linear extrapolation (see SSCALE also)3 Assign a zero value

ITREND I INTEGER Trend of the CPROP data:0 Monotonically increase or decrease (default) 1 Random or unknown.

IMETHD I INTEGER Interpolation option:0 To be determined by program. 1 Linear (Use if CPROP=2)2 Quadratic (Use if CPROP=3)3 Cubic spline (Use if CPROP>3)

IUPDAT I INTEGER Option to update the XPROPY common block:0 Do not update (default)1 Update

DSCALESSCALE

I REAL*8REAL*4

Scaling factor for linear interpolation. DSCALE is double precision and SSCALE is single precision.

IMAPED O INTEGER (MAXCN)

Array of component mapping flag:0 Get zero flow rate from the mapping1 Get positive flow rate from the mapping

Table 20-9: Arguments for Utility Subroutine UCURVE() (Continued)



Example:INCLUDE 'PMXUSR.CMN'INCLUDE 'XPROPY.CMN'INTEGER(4), PARAMETER :: NCPSEU=7CHARACTER(LEN=12) :: cPropREAL(8) :: DTVEC(NCPSEU), DCPROP(NCPSEU)REAL(8) :: DFRATE(MAXCN), DSTGYV(MAXCN)REAL(8) :: IMAPED(MAXCN), DBP(MAXCN)REAL(8) :: DTMINI, DTMAXI, DSCALE …! Variables DTVEC, DCPROP, NCPSEU are from! reactor module! BP is from XPROPY common block! BEGIN and IEND are from UPSEUC()! FRATE is from URATE()…cProp = 'MW'ISPROP = 0DTMINI = 350.0D0DTMAXI = 575.0D0DYLOW = 0.0D0DYHIGH = 1000.0D0IFILL = 0ITREND = 0IMETHD = 3IUPDAT = 1DSCALE = 1.0D0DBP(1:MAXCN) = BP(1:MAXCN)… CALL DUCURVE( cProp, ISPROP, DTVEC, & DCPROP, NCPSEU, BP, DFRATE, & IBEGIN, IEND, DTMINI, DTMAXI, & DYLOW, DYHIGH, IFILL, & ITREND, IMETHD, IUPDAT, DSCALE, & IMAPED, DSTGYV, DSUMPRP, IERR )

DSTGYV

SSTGYV

0ut REAL*8 (MAXCN)REAL*4 (MAXCN)

Result of mapped component property table. DSTGYV is double precision and SSTGYV is single precision.

DSUMPRPSSUMPRP

0ut REAL*8REAL*4

Sum of FRATE(I)*STGYV(I), where I is a component in the [IBEGIN, IEND] range. DSUMPRP is double precision and SSUMPRP is single precision.

IERR Out INTEGER Returned error flag:0 SuccessfulAll other values indicate failure

Table 20-9: Arguments for Utility Subroutine UCURVE() (Continued)



DUBULK double precisionUBULK single precision

The purpose of this routine is similar to that of UCURVE, but it is used when there is only a single property data point available from the reactor simulation. For example, the research octane number is usually of interest only for naphtha. Thus, the reactor module may only predict a single RON for the entire naphtha boiling range [TMINI,TMAXI]. The UBULK routine handles the component mapping for this situation. If the thermodynamic METHOD of the product stream already has some information about the component property, the property profile will be adjusted proportionally to match the given bulk property value. Otherwise, due to lack of information, the same bulk property value will be assigned to all pseudo compo-nents within the [TMINI,TMAXI] range.


CALL DUBULK( cSID, cProp, iSProp, DBulkP, & DBP, IBegin, IEnd, DTmin, & DTmax, IFill, DScale, IMAPED, & DTGYV, IERR )


CALL UBULK( cSID, cProp, iSProp, SBulkP, & SBP, IBegin, IEnd, STmin, & STmax, IFill, SScale, IMAPED, & STGYV, IERR )

Table 20-10: Arguments for Utility Subroutine UBULK()

Variable I/O Type DescriptioncSID In CHAR*12 Stream ID of the processed stream

cProp In CHAR*12 The property keyword‘MW’ Molecular weight‘SG60’ Specific gravity at 60F (15.5C)‘OMEG’ Acentric factor‘TC’ Critical temperate‘PC’ Critical pressure‘VC’ Critical volume‘ZC’ Critical compressibility‘RAKT’ Rackett parameter‘CNUM’ Carbon number‘ZNUM’ Hydrogen deficiency number‘WATK’ Watson K value

For refinery special properties, see cProp explained in USTRIP routine.


INCLUDE '…\PMXUSR.CMN'INCLUDE '…\XPROPY.CMN'

iSProp In INTEGER See ISPROP explained in USTRIP routine

SBulkP In REAL The bulk property value

SBP In REAL (MAXCN)

Array of component NBP. See XPROPY common block for definition

IBegin In INTEGER The PRO/II internal order of the first component in the blend

IEnd In INTEGER The PRO/II internal order of the last component in the blend

STmin In REAL The initial temperature of the temperature range based on which SVALSP is determined.

STmax In REAL The end temperature of the temperature range based on which SVALSP is determined.

IFill In INTEGER Mapping option for components whose BP values are outside the given [TMINI,TMAXI] range.

0 Assign the same property value of the nearest neighboring component inside the [TMINI,TMAXI] range. (default)

1 Ignore; do not assign a new value.2 Assign SVALSP*SSCALE.3 Assign a zero value4 Assign SVALSP

SScale I REAL Scaling factor for IFILL = 2

IMAPED Out INTEGER (MAXCN)

Array of component mapping flag0 Get zero flow rate from the mapping1 Get positive flow rate from the

mapping

STGYV 0ut REAL (MAXCN)

Result of mapped component property table

IERR Out INTEGER Returned integer error flag0 Successful≠0 Failed

Table 20-10: Arguments for Utility Subroutine UBULK()



CHARACTER*(*) ATEXTREAL STGYV(MAXCN), IMAPED(MAXCN) …C CID is from the URXINF function callC SVALSP is from the reactor moduleC BP is from XPROPY common blockC IBEGIN and IEND are from UPSEUC()…ATEXT = 'RON'ISPROP = 0TMINI = 5.0TMAXI = 220.0IFILL = 0SSCALE = 1.0…CALL UBULK(CID,ATEXT, ISPROP,SVALSP,BP, IBEGIN, IEND,TMINI,TMAXI, IFILL, SSCALE,IMAPED,STGYV, IERR)


UPETMDThis routine updates all component properties in the current ther-modynamic METHOD set based on a subset of the component prop-erties declared to be invariant (fixed).

The reactor module normally predicts only a few component or stream properties. Many component properties, such as Tc, Pc, and acentric factor, typically required by the thermodynamic calcula-tions, usually are not computed by the reactor simulation. Fortu-nately, these component properties can be estimated from three primary component properties: NBP, specific gravity, and molecu-lar weight. In this refinery reactor interface, the NBP is treated as a fixed component property, since its value is usually near the middle of the cut and won't be significantly changed by the refinery reac-tions. The other two primary component properties, specific gravity and molecular weight, are allowed to change. The UPETMD routine should be called to update all the secondary thermodynamic proper-ties after the specific gravity and molecular weight component properties are updated with the reactor simulation results.

Calling sequence for UPETMD is:

CALL UPETMD( cProp, nProps, iErr )

Example:...CHARACTER(LEN=12) :: cProp(3)INTEGER(4) :: nProps, iErr...cProp(1) = ‘NBP’cProp(2) = ‘MW’cProp(3) = ‘SPGR’

Table 20-11: Arguments for Utility Subroutine UPETMD( )

Variable I/O Type DescriptioncProp In CHAR*12

3 element array

Fixed component properties that are used as the basis to determine the other component properties. The component properties allowed to be fixed are:

‘MW’ Molecular weight‘SPGR’ Specific gravity‘NBP’ Normal boiling point

nProps In Integer Input integer number of component properties specified in the cProp array.

iErr Out Integer Output variable; Integer scalar. It is the error flag.0 = Successful All other values indicate failure.


nProps = 3CALL UPETMD( cProp, nProps, iErr )...

Common Block /XPROPY/This single-precision common block is very similar to the /XPROPX/ common block previously defined in Chapter 15 on page 15-56 of this manual. The only difference is that the component property variables in this common block can be dynamically updated with the reactor simulation. Property data stored here are automatically refreshed whenever the USTHER or UPETMD function is called. The data can be refreshed again when UCURVE function is called.

This common block can be accessed by including XPROPY.CMN in the program. Refer to “/DXPROPX/ double precision” in Chapter 15, page 15-56 for a description of the variables in this COMMON block

COMMON/XPROPY/ XMW(MAXCN), BP(MAXCN),& DENS(MAXCN), TC(MAXCN), PC(MAXCN),& VC(MAXCN), ZC(MAXCN), OMEGA(MAXCN),& HFORM(MAXCN, GFORM(MAXCN), LIBNO(MAXCN),& KOCMOL, KOCTOT, KOCVL,& KOCVLS, KOCLS, KOCV,& KOCL, KOCS


Sample User-Added Reactor ModuleIn the example shown in Figure 20-1, the refinery reactor has two feed streams. The first is a hydrocarbon stream represented by assay pseudo components created from the assay data. Refinery inspec-tion properties such as sulfur, nitrogen, bromine number, refractive index, and CCR are defined in the stream so the reactor interface can retrieve and send these data to the reactor module. The second feed is a recycle stream containing only hydrogen and light compo-nents C1 to C4. The recycle stream is handled and converged by PRO/II.

Figure 20-1: Process Flow Diagram of User-added Reactor Module

Except for the fact that the input data are entered through the IPARM, RPARM and SUPPLE vectors in accordance with the UAS structure, the interfaced reactor unit in every sense behaves like a regular PRO/II unit.

Note that the reactor feed stream need not be an external source stream. It can be the product stream of a distillation column. Simi-larly, the reactor product stream can be a final product or a feed to other units in the flowsheet. Once the refinery inspection properties are assigned to a stream at input time or generated by the reactor simulation at the calculation time, they can be carried with the stream to other units.


Example Input FileTITLE DESCRIPTION DEMO CASE - PRO/II WITH User’s REACTOR MODULE DIMENSION ENGLISH, PRESS=PSIG, LIQVOL=BBL OUTDIMENSION REPLACE, TIME=DAY, WT=LB, LIQVOL=BBL CALC CDATA=VARY

COMPONENT DATA LIBID 1,H2/2,H2S/3,NH3/4,H2O/5,C1/ * 6,C2/7,C3/8,IC4/9,NC4/10,IC5/ * 11,ETLN/12,PRLN/13,1BUTENE/14,1PENTENE/ * 15,BENZENE CUTPOINT TBPCUTS=0,1600,80, BLEND=BLEND1

$ Paraffin PARA(LV) DATA= * 1,0/2,0/3,0/4,0/5,100/ * 6,100/7,100/8,100/9,100/10,100/ * 11,0/12,0/13,0/14,0/15,0$ Olefin SPROP(50,LV) DATA= * 1,0/2,0/3,0/4,0/5,100/ * 6,0/7,0/8,0/9,0/10,0/ * 11,100/12,100/13,100/14,100/15,0$ Naphthene NAPH(LV) DATA= * 1,0/2,0/3,0/4,0/5,0/ * 6,0/7,0/8,0/9,0/10,0/ * 11,0/12,0/13,0/14,0/15,0$ Aromatics AROM(LV) DATA= * 1,0/2,0/3,0/4,0/5,0/ * 6,0/7,0/8,0/9,0/10,0/ * 11,0/12,0/13,0/14,0/15,100

THERMODYNAMIC DATA METHODS SYSTEM= GS,COND=PETR, VISC(V)=PETR, VISC(L)=API, SET=GS-1, DEFAULT, & SULFUR(WT)= SUM, NITR(TOTA,WT)= SUM, & BROM(WT)= SUM, REFR(WT)= SUM, & CCR(WT)= SUM, NICK(WT)= SUM, & VANA(WT)= SUM

METHODS SYSTEM= GS,COND=PETR, & VISC(V)=PETR, VISC(L)=API, & SET=GS-2, & SULFUR(WT)= SUM, NITR(TOTA,WT)= SUM, & BROM(WT) = SUM, REFR(WT)= SUM, & CCR(WT) = SUM, SPROP(50,WT)= SUM, & SPROP(51,WT)= SUM, SPROP(52,WT)= SUM, & NICK(WT) = SUM, VANA(WT)= SUM, & AROM(TOTAL,LV)= SUM, & NAPH(LV) = SUM, PARA(LV)= SUM, & H2(WT) = SUM, & RON(LV) = SUM, MON(LV)= SUM, & CETN(WT) = SUM, ANIL(LV)= SUM, & FREZ(LV) = INDEX, POUR(LV)= INDEX, &


SMOK(LV) = SUM POUR(LV) NCFILL=NOFILL REFR(WT) NCFILL=NOFILL H2(WT) NCFILL=NOFILL SMOK(LV) NCFILL=NOFILL FREZ(LV) GAMMA=1.0, REFINDEX=1.0, REFVALUE=1.0

STREAM DATA$ Crude feed PROP STREAM=1,TEMP=450,PRES=14,PHASE=L,RATE(V)=12075, & ASSAY=LV, BLEND=BLEND1, SET=GS-1 TBP STREAM=1,PRES(MMHG)=760, & DATA=3,97/5,149/10,208/20,330/30,459/40,590/ & 50,690/60,770/70,865/80,980/100,1600 API STREAM=1,AVG=29.2 LIGHT STREAM=1,PERCENT(V)=3, & COMP(V)=6,0.1/7,0.2/8,0.3/9,0.7/10,1.7,NORMALIZE SULF STREAM=1, DATA= 10,0.1/50,1.4/90,3.3 NITR STREAM=1, DATA= 10,0.005/50,0.03/90,0.09 BROM STREAM=1, DATA= 10,1.5/50,2.8/90,4.5 REFR STREAM=1, DATA= 10,1.41/50,1.47/90,1.58 CCR STREAM=1, DATA= 10,0.01/50,0.05/90,0.24$ PROP STREAM=2,TEMP=600,PRES=60,PHASE=V,RATE(W)=24151, & COMP=4,100 PROP STREAM=3,TEMP=600,PRES=60,PHASE=V,RATE(W)=3623, & COMP=4,100 PROP STREAM=4,TEMP=600,PRES=60,PHASE=V,RATE(W)=10868, & COMP=4,100 PROP STREAM=5,TEMP=600,PRES=60,PHASE=V,RATE(W)=9660, & COMP=4,100$ Vacuum tower PROP STREAM=R1B,TEMP=330,PRES=8000,RATE(V)=138.4, & COMP=6,75/7,25 PROP STREAM=R1C,TEMP=330,PRES=8000,RATE(W)=5154,COMP=4,100 PROP STREAM=W1,TEMP=355,PRES=8500,RATE(W)=14718,COMP=4,100$ Recycle gas initial guess PROP STRM=RECYCLE, TEMP=100.0000, PRES=244.6959, & COMP= 1,25000/2,2000/3,2000/4,2000/5,500/ & 6, 500/7, 500/8, 500

UNIT OPERATIONS$$ Crude process$ .....$$ Refinery Reactor$ US10 UID=RX1, NAME=BLEND1 FEED F1,RECYCLE PROD REACT$ Description of input data is shown in the reactor program IPARM 1, , , , , & , , , , , & 51, 52, 50


RPARM 940.0, 30.0, 12000.0, 0.952, , & , , 85.5, 120.5, 210.8, & 1.4E-4, , , , , & , , , , , & 1.452 DEFINE RPARM(2) AS COMPRESSOR=CMP1, PRES(PSIG) METHOD SET= GS-2

FLASH UID=FLA1 FEED REACT PROD V=VAPPRD, L=LIQPRD ISOTHERMAL TEMP=100, PRES=244.696 METHOD SET= GS-2 SPLITTER UID=SPL1 FEED VAPPRD PRODUCT V=V_SPL1, V=H2OUT SPEC STREAM= V_SPL1, RATE(GV,FT3/D), RATIO, & STREAM=F1, RATE(TS/D), VALUE=56294 METHOD SET= GS-2 COMPRESSOR UID=CMP1 FEED V_SPL1 PROD V=RECYCLE OPER PRES=315, EFF=92 METHOD SET= GS-2$$ Purification COLUMN UID=COL1 PARAM TRAY=21 FEED LIQPRD,17 PROD OVHD=OVERHEAD, BTMS= BOTTOM,80000 COND TYPE=PART, PRESS=65 HEAT 1,1/2,21 PRESS 1,65/2,70/21,75 ESTI MODEL=CONVENTION SPEC STREAM= OVERHEAD,RATE,COMP=10, OVER, * STREAM=LIQPRD, RATE,COMP=10, VALUE=0.1 SPEC STREAM= BOTTOM,RATE,COMP=6, OVER, * STREAM=LIQPRD, RATE,COMP=6, VALUE=0.1 VARY HEAT=1,2 METHOD SET= GS-2$$ Print component properties in each thermo method CREPORT UID=CREP1$$ Recycle algorithm$ RECYCLE DATA ACCELERATION TYPE=BROYDENEND


Example of PRO/II User-Added SubroutineC *** EXAMPLE OF REACTOR INTERFACE PROGRAM ***C SUBROUTINE USER50(IPARM, RPARM, SUPPLE, HEAT, IDATA, 1 ISOLVE, ISTOP)CC----------------------------------------------------------------C -C - INCLUDE and DIMENSION blocksC - INCLUDE '...\PMXUSR.CMN' INCLUDE '...\XPROPY.CMN'C Common block XPROPY has the following variablesC COMMON /XPROPY/XMW(MAXCN), BP(MAXCN), DENS(MAXCN),C 1 TC(MAXCN), PC(MAXCN), VC(MAXCN),C 2 ZC(MAXCN), OMEGA(MAXCN), HFORM(MAXCN),C 3 GFORM(MAXCN), LIBNO(MAXCN), KOCMOL,C 4 KOCTOT, KOCVL, KOCVLS,C 5 KOCLS, KOCV, KOCL,C 6 KOCSCC User's parameters PARAMETER (LIXIN=100, LRXIN=100, LRXOUT=100, 1 LFDDAI=10, LFDDAJ=100, LPDDA=100, 2 ZERO=0.0, MAXPSU=100, MAXPRP=20, 3 IMISS=-2111111111, 4 RMISS=-1.5E35, RTEST=-1.0E35)CC PRO/II vectors DIMENSION IPARM(*), RPARM(*), SUPPLE(*), HEAT(*) 1 IDATA(*) DIMENSION STREAM(MAXCN+10), VAPOUT(MAXCN+10), 1 XL1OUT(MAXCN+10), XL2OUT(MAXCN+10), 2 XKVALU(MAXCN+10) CHARACTER*12 CID CHARACTER*40 CNAMECC User's reactor interface vectors DIMENSION IXIN(LIXIN), RXIN(LRXIN), RXOUT(LRXOUT), 1 FDDATA(LFDDAI,LFDDAJ), PDDATA(LPDDA), 2 PDCURV(MAXPSU,MAXPRP), 3 BPTIP(MAXCN), BPTEP(MAXCN)CC Local vectors DIMENSION IONUMB(10), CRC(10), REFRAC(10), IDCOMP(20), 1 IMAPED(MAXCN) DIMENSION TDIST(21), FRATE(MAXCN), RXMW(MAXCN), 1 RXSPGR(MAXCN), RXSULF(MAXCN), RXNAPH(MAXCN), 2 RXRON(MAXCN) DIMENSION CTMID(MXPSEU), CWTPCT(MXPSEU), 1 CMWT(MXPSEU), CSPGR(MXPSEU), CSULF(MXPSEU), 2 CNITR(MXPSEU), CNAPH(MXPSEU), CAROM(MXPSEU),


3 CTMIN(MXPSEU), CTMAX(MXPSEU) DIMENSION TVEC(MXPSEU), YVEC(MXPSEU) CHARACTER*12 ATEXT CHARACTER*12 PPTEXT(10) CHARACTER*16 CPNAMEC -C - Initialization of variablesC - DO 40 I= 1, LIXIN IXIN(I) = IMISS 40 CONTINUE DO 42 I= 1, LRXIN RXIN(I) = RMISS 42 CONTINUE ..... DO 50 I= 1, MXPSEU CTMID(I) = ZERO CTMWT(I) = ZERO ..... 50 CONTINUE .....C NFEDIN = IDATA(1) NUMCOP = IDATA(4) .....C -C - Assign IPARM, RPARM, SUPPLE to local variablesC -C The data can be:C 1. User's reactor configuration dataC 2. User's reactor operating condition data such as reactorC temperature and pressureC 3. User's reaction data such as kinetic parameters, updateC factors and catalyst dataC 4. If the refinery inspection property data, such as sulfur,C nitrogen, refractive index, were not defined in theC stream, they can be input here locally.CC Hydrogen recycle position flag IH2IN = IPARM(1)C Position of SPROP() for naphthene carbon fraction NSNAPH = IPARM(11)C Position of SPROP() for aromatics carbon fraction NSAROM = IPARM(12)C Position of SPROP() for olefin wt% NSOLEF = IPARM(13) .....C Reactor inlet temperature TIN = RPARM(1)C Reactor inlet pressure PIN = RPARM(2)C Reactor catalyst amount CATWT = RPARM(3)


C Catalyst activity CATACT = RPARM(4)C Product cut points TCUT1 = RPARM(8) TCUT2 = RPARM(9) TCUT3 = RPARM(10)C Conradson carbon data CRC(1) = RPARM(11) .....C Refractive index data REFRAC(1) = RPARM(21) .....CC----------------------------------------------------------------C Note that many of the following data can be saved at unusedC IPARM, RPARM or SUPPLE after the processing and retrieved forC use during the recycle iterations to avoid repeated calculation theC first time.CC -C - Get component position orders for all defined componentsC - involved in the reactor simulationC - ITYPE = 1C Find 'H2' LIBH2 = 16020090 CALL UDEFNC(CPNAME, LIBH2, ITYPE, JPLACE) IF (JPLACE .GT. 0) THEN IDCOMP(1) = JPLACE ELSEC (error message) ENDIFC Find 'C1' LIBC1 = 9010090 CALL UDEFNC(CPNAME, LIBC1, ITYPE, JPLACE) IF (JPLACE .GT. 0) THEN IDCOMP(2) = JPLACE ELSEC (error message) ENDIF .....C----------------------------------------------------------------C -C - Determine the index range and initial and end boiling pointsC - of PRO/II's assay pseudocomponents. These data will be usedC - when saving the reactor product result to PRO/II's productC - stream. The range is determined by the "BLEND" specified byC - the user under the "NAME" of the reactor unit. The blend hasC - to be declared in the "COMPONENT" sectionC - CALL UPSEUC(IDATA, BP, IBEGIN, IEND, BPTIP, 1 BPTEP, IERR)C Check error flag IERR


.....CC----------------------------------------------------------------C -C - Get file open numbers for user's own file I/O purposeC - DO 100 I= 1, 5 CALL FIGETU(1,LUN) IONUMB(I) = LUN 100 CONTINUE .....CC Open user's own data file OPEN(UNIT=IONUMB(1), FILE='C:\REACTOR\FCC\INPUT.DAT', 1 STATUS='OLD', ERR=5000)CC Read data from user's own data file .....CCC----------------------------------------------------------------C -C - Get feed stream data from PRO/IIC - DO 300 I= 1, NFEDIN CALL URXINF('FEED', I, CID, CNAME, IERR)C Check error flag IERR CALL URXSTR(CID, STREAM, 1, IERR)C Check error flag IERRCC Set up the component properties XPROPY for this feed streamC This is required only if CDATA=VARY is applied ISETUP = 1 CALL USTHER(CID, ISETUP, JMETHD, IERR)CC Get molecular wt CALL USTPRP(CID, 'TOTAL', 'MW', STMW, IERR)C Check error flag IERRC Get spgr CALL USTPRP(CID, 'TOTAL', 'SDEN', STDENS, IERR)C Check error flag IERRC Get sulfur wt% CALL USTRIP(CID, 'SULF', 0, STSULF, IERR)C Check error flag IERRC Get nitrogen wt% CALL USTRIP(CID, 'NITR', 0, STNITR, IERR)C Check error flag IERRC Get naphthene carbon fraction from SPROP(NSNAPH) CALL USTRIP(CID, '', NSNAPH, STNAPH, IERR)C Check error flag IERRC Get aromatics carbon fraction from SPROP(NSAROM) CALL USTRIP(CID, '', NSAROM, STAROM, IERR)C Check error flag IERR


.....CC Get distillation curve dataC TBP curve from 0.1% to 99.9% ITYPE = 2 ICONV = 2 IBASIS = 0 WVIP = 0.1 WVEP = 99.9 CALL UDIST(STREAM, XMW, BP, DENS, ITYPE, 1 ICONV, IBASIS, WVIP, WVEP, NUMCOP, 2 TDIST, IERR)C Check error flag IERRC C Assign feed data to interface variables which can be accessedC by the reactor simulation programC Assume:C FDDATA(*,1)= total flowrateC FDDATA(*,2)= stream densityC FDDATA(*,3)= stream sulfur contentC FDDATA(*,4)= stream nitrogen contentC FDDATA(*,5)= stream naphthene carbon contentC FDDATA(*,6)= stream aromatics carbon contentC FDDATA(*,7)= stream CRC contentC FDDATA(*,8)= stream refractive indexC .....C FDDATA(*,11-17)= distillation data at IP,10%,30%,50%,70%,C 90%,EP (7 points)C FDDATA(*,21)= H2 flowrateC FDDATA(*,22)= C1 flowrateC FDDATA(I,1) = STREAM(1) * STMW FDDATA(I,2) = STDENS FDDATA(I,3) = STSULF FDDATA(I,4) = STNITR FDDATA(I,5) = STNAPH FDDATA(I,6) = STAROM FDDATA(I,7) = CRC(I) FDDATA(I,8) = REFRAC(I) .....C Distillation curve data at IP,10%,30%,50%,70%,90%,EP points FDDATA(I,11) = TDIST(1) FDDATA(I,12) = TDIST(3) FDDATA(I,13) = TDIST(7) FDDATA(I,14) = TDIST(11) FDDATA(I,15) = TDIST(15) FDDATA(I,16) = TDIST(19) FDDATA(I,17) = TDIST(21) .....C H2, C1 and other light component flowrates FDDATA(I,21) = STREAM(10+IDCOMP(1)) FDDATA(I,22) = STREAM(10+IDCOMP(2)) .....


C Any required error checks for feed stream properties ..... 300 CONTINUE .....CCC----------------------------------------------------------------C -C - Assign all other desired data to the interface variablesC - The data can be reactor operating condition, catalystC - activity, etc.C - IXIN(1) = IH2IN .....C RXIN(1) = TIN RXIN(2) = PIN RXIN(3) = CATWT RXIN(4) = CATACT RXIN(5) = TCUT1 RXIN(6) = TCUT2 RXIN(7) = TCUT3 .....CC----------------------------------------------------------------C -C - Execute user's reactor simulationC -C ===================================================== CALL USER_REACTOR(IXIN, RXIN, RXOUT, FDDATA, PDDATA, 1 PDCURV, IERR)C =====================================================C Check error flag IERRCC----------------------------------------------------------------C -C - Store reactor effluent data to PRO/II product streamC - CALL URXINF('PROD', 1, CID, CNAME, IERR)C Check error flag IERR CALL URXSTR(CID, STREAM, 1, IERR)C Check error flag IERRCC Set up the component properties XPROPY for the product streamC This is required only if CDATA=VARY is applied in the .inp file ISETUP = 1 CALL USTHER(CID, ISETUP, JMETHD, IERR)C Check error flag IERRCC Get reactor pseudocomponent dataC Assume:C PDCURV(*,1)= (reserved)C PDCURV(*,2)= mid boiling point of the pseudocomponent


C PDCURV(*,3)= wt% of the pseudocomponentC PDCURV(*,4)= MW of the pseudocomponentC PDCURV(*,5)= SPGR of the pseudocomponentC PDCURV(*,6)= sulfur wt% of the pseudocomponentC PDCURV(*,7)= nitrogen wt% of the pseudocomponentC PDCURV(*,8)= naphthene carbon fraction of the pseudoC componentC PDCURV(*,9)= aromatics carbon fraction of the pseudoC componentC PDCURV(*,10) = initial boiling point of the data pointC PDCURV(*,11) = end boiling point of the data pointC .....CC Get number of reactor pseudocomponents NCPSEU = INT(RXOUT(1))C DO 320 J= 1, NCPSEU CTMID(J) = PDCURV(J,2) CWTPCT(J) = PDCURV(J,3) CMWT(J) = PDCURV(J,4) CSPGR(J) = PDCURV(J,5) CSULF(J) = PDCURV(J,6) CNITR(J) = PDCURV(J,7) CNAPH(J) = PDCURV(J,8) CAROM(J) = PDCURV(J,9) CTMIN(J) = PDCURV(J,10) CTMAX(J) = PDCURV(J,11) ..... 320 CONTINUECC Get reactor data such as reactor temperature, pressure, ... TOUT = RXOUT(2) POUT = RXOUT(3) FWOUT = RXOUT(4) ..... ICUMUL = 1 IMETHD = 4CC Match the weight flowrate of pseudocomponent CALL URATE(TMAX, CWTPCT, NCPSEU, ICUMUL, 1 FWOUT, IBEGIN, IEND, BPTIP, 2 BPTEP, IMETHD, IMAPED, FRATE, 3 IERR)C Check error flag IERRCC Match the component properties based on curve dataCC Use the molecular weight curve determined by the reactorC simulation to determine the molecular weight of all assayC pseudocomponents that were selected to store the reactorC product data. ATEXT = 'MW' ISPROP = 0


TMINI = CTMIN(1) TMAXI = CTMAX(NCPSEU) YLOW = 2.0 YHIGH = 1000.0 IFILL = 2 ITREND = 0 IMETHD = 3 IUPDAT = 0 SSCALE = 1.0 CALL UCURVE(ATEXT, ISPROP, CTMID, CMW, NCPSEU, 1 BP, FRATE, IBEGIN, IEND, TMINI, 2 TMAXI, YLOW, YHIGH, IFILL, ITREND, 3 IMETHD, IUPDAT, SSCALE, IMAPED, RXMW, 4 SUMMW, IERR)C Check error flag IERRCC Use the specific gravity curve determined from the reactorC simulation to determine the specific gravity of all assayC pseudocomponents that were selected to store the reactorC product data. ATEXT = 'SPGR' ISPROP = 0 TMINI = CTMIN(1) TMAXI = CTMAX(NCPSEU) YLOW = 0.5 YHIGH = 1.5 IFILL = 2 ITREND = 0 IMETHD = 3 IUPDAT = 0 SSCALE = 1.0 CALL UCURVE(ATEXT, ISPROP, CTMID, CSPGR, NCPSEU, 1 BP, FRATE, IBEGIN, IEND, TMINI, 2 TMAXI, YLOW, YHIGH, IFILL, ITREND, 3 IMETHD, IUPDAT, SSCALE, IMAPED, RXSPGR, 4 SUMSPG, IERR)CC Update all required secondary component properties, such as Tc,C Pc, and Zc, based on the NBP, MW, and SPGR PPTEXT(1) = 'NBP' PPTEXT(2) = 'MW' PPTEXT(3) = 'SPGR' NPTEXT = 3 CALL UPETMD(PPTEXT, NPTEXT, IERR)CC Use the sulfur wt% curve determined from the reactorC simulation to determine the sulfur wt% of all assayC pseudocomponents that were selected to store the reactorC product data. ATEXT = 'SULF' ISPROP = 0 TMINI = CTMIN(1) TMAXI = CTMAX(NCPSEU)


YLOW = 0.0 YHIGH = 100.0 IFILL = 2 ITREND = 0 IMETHD = 3 IUPDAT = 0 SSCALE = 1.0 CALL UCURVE(ATEXT, ISPROP, CTMID, CSULF, NCPSEU, 1 BP, FRATE, IBEGIN, IEND, TMINI, 2 TMAXI, YLOW, YHIGH, IFILL, ITREND, 3 IMETHD, IUPDAT, SSCALE, IMAPED, RXSULF, 4 SUMSUL, IERR)CC Similarly for NITROGEN mapping here ...

C Use the naphthene fraction curve determined from the reactorC simulation to determine the naphthene fraction of all assayC pseudocomponents that were selected to store the reactorC product data.C Assuming that the reactor predicts this property for onlyC four points and they are located at index 2 to 5 of NCPSEU:

ATEXT = '' ISPROP = NSNAPH TMINI = CTMIN(2) TMAXI = CTMAX(5) YLOW = 0.0 YHIGH = 100.0 IFILL = 2 ITREND = 0 IMETHD = 0 IUPDAT = 0 SSCALE = 1.0 CALL UCURVE(ATEXT, ISPROP, CTMID, CNAPH, NCPSEU, 1 BP, FRATE, IBEGIN, IEND, TMINI, 2 TMAXI, YLOW, YHIGH, IFILL, ITREND, 3 IMETHD, IUPDAT, SSCALE, IMAPED, RXNAPH, 4 SUMNAP, IERR)CC Similarly for AROMATICS mapping hereCC Map the component product rateC DO 330 J= 1, MAXCN STREAM(10+J) = ZERO 330 CONTINUECC Match flowrate of defined componentC Assume PDDATA(30-31) store the weight flowrates of H2 and C1 STREAM(10+IDCOMP(1)) = PDDATA(30) STREAM(10+IDCOMP(2)) = PDDATA(31) .....


CC Match the weight flowrate of pseudocomponent DO 340 J= IBEGIN, IEND STREAM(10+J) = FRATE(J) 340 CONTINUECC CONVERT WT TO MOLAR FLOWRATE DO 340 J= IBEGIN, IEND STREAM(10+J) = STREAM(10+J) / XMW(J) 340 CONTINUECC SUM up stream molar rate FTOTAL = ZERO DO 380 J= 1, MAXCN FTOTAL = FTOTAL + STREAM(10+J) 380 CONTINUECC Assign product stream rate, temperature and pressure STREAM(1) = FTOTAL STREAM(2) = TOUT STREAM(3) = POUTC CALL UFLSH(STREAM, VAPOUT, XL1OUT, XL2OUT, XKVALU, 1, IERR)C ERROR CHECK:C STTH = VAPOUT(4) + XL1OUT(4) + XL2OUT(4) STREAM(4) = STTHCC Save the product stream data CALL URXSTR(CID, STREAM, 2, IERR)CC Match the bulk stream property for a defined boiling range ofC the reactor effluent stream.CC RON NUMBERC ATEXT = 'RON' ISPROP = 0 BRON = RXOUT(11) TMINI = RXOUT(12) TMAXI = RXOUT(13) IFILL = 4 SSCALE = 1.0 CALL UBULK(CID, ATEXT, ISPROP, BRON, 1 BP, IBEGIN, IEND, TMINI, 2 TMAXI, IFILL, SSCALE, IMAPED, 3 RXRON, IERR)CC Similarly for other bulk properties .....C----------------------------------------------------------------C -C - Determine the solution flag value


C - 9000 CONTINUEC CLOSE USER'S I/O FILES CLOSE(IONUMB(1)) CLOSE(IONUMB(2)) .....C IF (IERR .EQ. 0) THEN ISOLV = 10 ISTOP = 0 GO TO 9999 ELSEIF ..... ..... ISTOP = 1 ENDIFC 9999 RETURN END C


C *** Example of User’s Reactor Main Subroutine ***CC The main interface routine on the user's side for the reactorC interface with PRO/IIC SUBROUTINE USER_REACTOR(IXIN, RXIN, RXOUT, FDDATA, PDDATA, 1 PDCURV, IERR)C -C - Block of INCLUDE and DIMENSIONC - PARAMETER (LIXIN=100, LRXIN=100, LRXOUT=100, 1 LFDDAI=10, LFDDAJ=100, LPDDA=100, 2 ZERO=0.0, TCUT0=32.0, MAXPSU=100, MAXPRP=20)CC Interface variables DIMENSION IXIN(LIXIN), RXIN(LRXIN), RXOUT(LRXOUT), 1 FDDATA(LFDDAI,LFDDAJ), PDDATA(LPDDA), 2 PDCURV(MAXPSU,MAXPRP)CC Reactor module variables DIMENSION COPRXN(100,20)C -C - Create reaction pseudocomponentsC -C The reaction pseudocomponents are created based on TBPC data, and bulk properties such as gravity, molecular wt,C sulfur content, nitrogen content, and refractive index.C These data are available in the FDDATA().C COPRXN(I,J) stores the pseudocomponent data created from these data,C where I= pseudocomponent index;C J=1 for molar flowrate;C J=2 for initial boiling point;C J=3 for end boiling point;C J=4 for molecular wt;C J=5 for SPGR;C J=6 for paraffin carbon fraction;C J=7 for naphthene carbon fraction;C J=8 for aromatics carbon fraction;C J=9 for sulfur wt%;C J=10 for nitrogen wt%C CALL USER_PSEUDOCOMPONENT( FDDATA, NCPSEU, COPRXN) CC NCPSEU IS DECIDED BY THE REACTION MECHANISM RXOUT(1) = NCPSEUC -C - Calculate the reaction resultC -C Calculate the reaction result based on the given reactor inletC temperature and pressure, catalyst amount and activity, and theC pseudocomponent data. In this example the reaction mechanismC and kinetic data are all defined in the USER_RXN subroutine.


C The result of reactor effluent is also stored at COPRXN(). C TIN = RXIN(1) PIN = RXIN(2) CATWT = RXIN(3) CATACT = RXIN(4) ..... CALL USER_RXNCALCULATION(NCPSEU, COPRXN, TIN, PIN, CATWT, 1 CATACT, TOUT, POUT, RATE ...)C -C - Write reaction results to the interface variables RXOUT,C - PDDATA, and PDCURVC - RXOUT(2) = TOUT RXOUT(3) = POUT RXOUT(4) = RATE .....C DO 100 J= 1, NUMCOP PDCURV(J,1) = COPRXN(J,1) PDCURV(J,2) = (COPRXN(J,2)+COPRXN(J,3))/2 PDCURV(J,3) = COPRXN(J,1) * COPRXN(J,4) PDCURV(J,4) = COPRXN(J,4) PDCURV(J,5) = COPRXN(J,5) PDCURV(J,6) = COPRXN(J,9) PDCURV(J,7) = COPRXN(J,10) PDCURV(J,8) = COPRXN(J,7) PDCURV(J,9) = COPRXN(J,8) PDCURV(J,10) = COPRXN(J,2) PDCURV(J,11) = COPRXN(J,3) ..... 100 CONTINUEC -C - Determine the bulk refinery inspection propertiesC -C Generate bulk propertiesC TCUT1 = RXIN(5) TCUT2 = RXIN(6) TCUT3 = RXIN(7)C CALL USER_BULKPROPERTY(NUMCOP, COPRXN, TOUT, POUT, TCUT1, 1 TCUT2, TCUT3, STBRON, ...)C RXOUT(11) = STBRON RXOUT(12) = TCUT0 RXOUT(13) = TCUT1CC Write similar code for other bulk properties ..... RETURN END


Chapter 21UAS Solid Components

OverviewThe subroutines and other interfaces described in this chapter are designed explicitly to handle components and streams that form solid phases in PRO/II simulations. Table 21-1 summarizes the interfaces discussed in this chapter. Most of them were not available prior to PRO/II version 8.3

Table 21-1: Solids Handling Interfaces in PRO/II Version 8.3

Solids Handling See ...

GETNCOMP Retrieves various component counts (for solids problems).

21-2

USOLSTR Retrieves and stores streams containing solids.

21-3

UFLSHSOL Performs vapor/liquid flash for streams with solids. May be used in place of UFLSH and U3FLSH.

21-5

USOLDENS Calculates the solid stream density 21-8

UHSSOLID Calculates solid molar heat capacity, molar enthalpy, and molar entropy

21-9

USOLCDAT Retrieves pure solid component heat of fusion, normal melting point temperature, triple point temperature, or triple point pressure.

21-10

GETPSDC Retrieves the number of Particle Size Distribution (PSD) cuts for any single component.

21-11

USOLPSD Retrieves or stores the Particle Size Distribution data

21-11

UPDSCPY Copies all Particle Size Distribution data 21-12


User InformationIn the past, most user-added interfaces in PRO/II supported only vapor and liquid phases in streams. This section describes the cur-rent user-added interfaces that support solids phases. They are intended for use inside user-written subroutines, such as unit opera-tions. Refer to the example routine USER57.FOR for some code demonstrations that use these solids-handling routines. This typi-cally is installed in \SIMSCI\PROII82\USER\UAS\EXAMPLES\EXAM7. Most of the material in this chapter is of interest to developers of user-added subroutines. Users running a simulation in PRO/II have no direct access to these interfaces through keywords or ProVision.

Developer Information

GETNCOMPSubroutine GETNCOMP retrieves component counts in simulations that include solid-phase components. Often the first interface used when dealing with solids components, it allows developers to iden-tify solids components in the PRO/II component lists.

Calling sequence:

CALL GETNCOMP( NOCR, NOCMOLR, NOCTOTR,& NOCSR, NOCIR, MICSR,& MACSR, MICIR, MACIR )

Where the following scalar integers are returned:

NOCR The number of Vapor-Liquid (VL) components

NOCMOLR The number of molecular weight-based components

NOCTOTR The total number of components, including non-molecular weight solids

NOCSR The number of molecular weight solids components

NOCIR The number of non-molecular weight solids components

MICSR The index to the first molecular weight solid

MACSR The index to the last molecular weight solid

MICIR The index to the first non-molecular weight solid

MACIR The index to the last non-molecular weight solid

21-2 UAS Solid Components February 2009

USOLSTRThis routine is an extension of URXSTR. Use it to store or retrieve data for streams that contain solids. All floating-point arguments are double precision, and data transfer uses the dimensional units of measure used for problem input data. Set argument IOTYPE = 1 to retrieve data from a PRO/II stream and set IOTYPE = 2 to store data from a PRO/II stream.Calling sequence:

CALL USOLSTR( CSID, DStVec,& DMRate, DCoMRate, SMWENTH,& SNMWRATE, SNMWCRATE, SNMWENTH,& IOTYPE, IERR )

Where:

CSID Input character string that identifies a PRO/II stream to which data is stored or from which data is retrieved. It may be a quoted literal string or a character variable containing a maximum of 12 characters.

DStVec A standard (user) stream array1 that transfers data between the user subroutine and PRO/II. When IOTYPE = 1, it retrieves values in elements STREAM(1) through (7), as well as the component mole rates beginning in DStVec(11). When IOTYPE = 2, data in the same elements are stored in the PRO/II stream identified by CSID. Dimension DStVec as follows:

REAL(8) :: DStVec( NOCTOTR2 + 10 )

DMRate Output double precision scalar that returns the total mole rate of the molecular weight solids in stream CSID. This value is not used when storing data (i.e., when IOTYPE = 2).

DCoMRate Double precision array of mole rates for molecular weight solids components. Units are mole rate, for example, kg-mole / hr. Used to store and retrieve data. Dimension this array as:

REAL(8) :: SMWRATE( NOCTOTR2 )

SMWENTH Double precision scalar value for total enthalpy rate of molecular weight solids in the stream. Uses the same units of measure as STREAM(4). Used for both storage and retrieval.

Notes:1 See routine URXSTR for a description of a standard stream array.2 Retrieve NOCTOTR by using routine GETNCOMP.


Total stream mole rate must be supplied in STREAM(1). This rate includes all molecular weight solids that are included in SMWRATE. STREAM(1) does not include any non-molecular weight solids.

For any molecular weight component i, the mole rate in STREAM (10+i) includes solid and non-solid rates. The non-solid rate of com-ponent i is found by STREAM (10+i) - SMWCRATE(i).

Total stream enthalpy in STREAM(4) includes enthalpy for both molec-ular weight solids (SMWENTH) and non-molecular weight solids (SNMWENTH).

SNMWRATE Output double precision scalar that returns the total weight rate of the non-molecular weight solids in stream CSID (for example, lb / hr). This value is not used when storing data (i.e., when IOTYPE = 2).

SNMWCRATE Double precision array of weight rates for non-molecular weight solids components. Units are weight rate, for example, lb / hr. Used to store and retrieve data. Dimension this array as:

REAL(8) :: SMWCRATE( NOCTOTR2 )

SNMWENTH Double precision scalar value for total enthalpy rate of non-molecular weight solids in the stream. Uses the same units of measure as STREAM(4). Used for both storage and retrieval.

IOTYPE Integer input option flag that controls data transfer1 = Retrieve data2 = Store data

IERR Integer output status flag0 = Success, no errors1 = Failure, IOTYPE is invalid (not 1 or 2)2 = Failure, stream not found (CSID is invalid).3 = Failure, CSID is not a product of this user unit

when storing data (IOTYPE=2).4 = Failure storing data (IOTYPE = 2) due to one of:

(A) Stream rate (STREAM(1)) less than zero.(B) Stream temperature invalid (STREAM(2))(C) Stream pressure invalid (STREAM(3))(D) At least one negative stream component

mole rate encountered (in STREAM).5 = Failure retrieving data (IOTYPE = 1). Stream

CSID may not yet be properly set or saved.Notes:

1 See routine URXSTR for a description of a standard stream array.2 Retrieve NOCTOTR by using routine GETNCOMP.


UFLSHSOLSubroutine UFLSHSOL is an extension of DU2FLSH and DU3FLSH. As with DU2FLSH, it performs a vapor/liquid flash. It then keeps track of solid component rates and enthalpy. It supports the same flash types as DU2FLSH.

All floating point variables and arrays in the argument list are dou-ble precision. The dimensional units used to transfer all data are the units declared and used for input data in the simulation. For isen-tropic flashes only, this routine requires passing in total stream entropy through variable SISENV that is explicitly declared single precision in common CSPEC.CMN.

When using this routine, the total stream to flash is loaded into STREAMIN, a standard double precision stream vector (See “User Stream Vector” on page 15-10 in chapter 15). Before calling UFLSH-SOL, load the molar solids rates into the SMWCRATE vector and the non-molar solids rates into the SNMWCRATE vector. Components are ordered in PRO/II internal order (See “Internal Component Order vs. Print Order” on page 15-40 in chapter 15). Load the enthalpy rate of the non-molar solids into argument variable SNM-WENTH. Refer to the documentation of routines URXSTR and USOL-STR for further discussion.

The vapor and liquid return in standard double precision stream vectors VAPOUT, XL1OUT, and XL2OUT, the same as from DU2FLSH. Molar solids return in SOLIDOUT, and the non-molar solids enthalpy rate returns in OUTNMWENTH. All arguments use input dimensional units of measure.

Calling sequence:

CALL UFLSHSOL( STREAMIN, SMWCRATE, SNMWCRATE,& SNMWENTH,& VAPOUT, XL1OUT, XL2OUT,& SOLIDOUT, OUTNMWENTH,& XK1VAL, XK2VAL,& ITYPE, IFVLLE, IERR )


Where:

STREAMIN Input double precision standard stream array2 dimensioned:REAL(8) :: STREAM( NOCTOTR1 + 10 )

SMWCRATE Input double precision array of molecular weight solids component mole rates in input units of measure for mole rates (e.g., kg-mol/hr). dimension: REAL(8) :: SMWCRATE( NOCTOTR1 ).

SNMWCRATE Input double precision array of NON-MW solids component weight rates in input units of measure for weight rates (e.g., kg/hr). dimension: REAL(8) :: SMWCRATE( NOCTOTR1 ).

SNMWENTH Input double precision scalar enthalpy rate of the NON-MW solids at the inlet of the flash. Uses the same dimensional units as STREAM(4).

VAPOUT Output double precision standard stream array2 that returns the vapor product. Dimensioned:REAL(8) :: VAPOUT( NOCTOTR1 + 10 ).

XL1OUT Output double precision standard stream array2 that returns the primary (light, L1 sub-phase) liquid product. Dimensioned:REAL(8) :: XL1OUT( NOCTOTR1 + 10 )

XL2OUT Output double precision standard stream array2 that returns the second liquid product. When water is a separate system, this array contains the decanted water. Dimensioned:REAL(8) :: XL2OUT( NOCTOTR1 + 10 )

SOLIDOUT Output double precision standard stream array2 that returns the molar solids. SOLIDOUT(4) is the total enthalpy rate of all the solids, including that of both MW and NON-MW solids. Dimensioned:REAL(8) :: SOLIDOUT( NOCTOTR1 + 10 )

OUTNMWENTH Output double precision scalar that returns the Enthalpy rate of the NON-MW solids at the outlet of the flash. It has the same units of measure as STREAMIN(4).

Notes:1 Retrieve NOCTOTR by using routine GETNCOMP.2 See routine URXSTR for a description of a standard stream array.


XK1VAL Output double precision array that returns the component equilibrium K-values for the L1 (first) liquid phase. Dimensioned:REAL(8) :: XK1VAL( NOCTOTR1 )

XK2VAL Output double precision array that returns the component equilibrium K-values for the L2 (second) liquid phase. Dimensioned:REAL(8) :: XK2VAL( NOCTOTR1 )

ITYPE Input integer flag for the type of flash requested: 1 or 101 Isothermal flash (temp and press

specified) 2 or 102 Adiabatic flash (temperature specified) 3 or 103 Adiabatic flash (pressure specified) 4 or 104 Dew point (temperature specified) 5 or 105 Dew point (pressure specified) 6 or 106 Bubble point (temperature specified) 7 or 107 Bubble point (pressure specified) 8 or 108 Isentropic (temperature specified) 9 or 109 Isentropic (pressure specified)10 or 110 Aqueous dew point (temp. specified)11 or 111 Aqueous dew point (pressure specified)

IFVLLE Returned Integer. This returns a value of 1 if the thermodynamics method is a VLLE method and the flash predicted two liquid phases. XK2VAL is meaningful only when IFVLLE = 1.

IERR Returned Integer flash calculations status flag 0 = Success, no errors 1 = Failure, flash did not converge 2 = Failure, ITYPE requested an invalid flash 3 = Failure, Flow rates of STREAMIN, SMWCRATE, and SNMWCRATE are all zero. 4 = Failure, the flow rate of MW solids exceeds total stream rate declared in STREAMIN(1).



USOLDENSSubroutine USOLDENS calculates the solid stream density at a spec-ified temperature. It returns the Molecular Weight Solids mole and weight densities, the NON-MW solids weight density, and the weight density of the total solids. All arguments use input dimen-sional units of measure.

Calling sequence:

CALL USOLDENS( TEMPIN, SMWCRATE, SNMWCRATE, & DENSMOLE, DENSWT, DENSNMW, & DENSTOT, IERR )

Where:

TEMPIN Input temperature in input units of measure. This is a double precision scalar value.

SMWCRATE Input double precision array of molecular weight solids component mole rates ( e.g., kg-mol/hr ). Dimension: REAL(8) :: SMWCRATE(NOCTOTR1)

SNMWCRATE Input double precision vector of NON-MW solids component weight rates (e.g., kg-mol/hr).Dimension: REAL(8) :: SNMWCRATE(NOCTOTR1)

DENSMOLE Output double precision scalar returns molar density of the molecular weight solids in moles / volume units (e.g., kg-mol/m3).

DENSWT Output double precision scalar returns weight density of the molecular weight solids in weight / volume units (e.g., kg/m3).

DENSNMW Output double precision scalar returns weight density of the NON-MW solids in weight / volume units (e.g., kg/m3).

DENSTOT Output double precision scalar returns weight density of the total solids in weight/volume units (e.g., kg/m3).

IERR Output integer scalar returns the error status flag: 0 Success, no errors 1 Failure. Flow rates of SMWCRATE and SNMWCRATE are all zero. 2 Failure. TEMPIN is outside the system limits. 3 Failure. Density calculation failed.



UHSSOLIDThe solid molar heat capacity, molar enthalpy or molar entropy for a specified molar solid composition may be determined with this subroutine. The composition is loaded into a vector of mole rates sized to NOCTOTR elements (see subroutine GETNCOMP). Supply all input values using problem input dimensional units.

Calling sequence:

CALL UHSSOLID( ITYPE, TEMPIN, PRESIN,& SMWCRATE, SMOLARCP,& SMOLENTH, SMOLENTRO, IERR )

Where:

ITYPE Property requested:1 Enthalpy and/or heat capacity2 Entropy3 Compressibility factor on a dry basis

calculated from the density method(s) declared on the METHODS statement.

TEMPIN Input temperature in input units of measure; a double precision scalar value.

PRESIN Input pressure in input units of measure; a double precision scalar value.

SMWCRATE Input double precision array of molecular weight solids component mole rates (e.g., kg-mol/hr). Dimension:

REAL(8) :: SMWCRATE(NOCTOTR1)

SMOLARCP Input solid molar heat capacity (when ITYPE = 1). Specific heat is reported in energy units per mole per temperature unit. This is a double precision scalar value.

SMOLENTH Input solid molar enthalpy (in input enthalpy units. For example, kcal / kg-mole.) This is a double precision scalar value.

SMOLENTRO Input solid molar entropy (in input entropy units. For example, kcal / kg-mol K). This is a double precision scalar value.

IERR Error flag:0 Success, no errors.1 Failure, ITYPE not in range 1-22 Failure in Cp or enthalpy calculations3 Failure in entropy calculations


USOLCDATSubroutine USOLCDAT is used to retrieve these pure solid compo-nent fixed properties:

Heat of fusion, Normal melting point temperature, Triple point temperature, and Triple point pressure.

All property values return using appropriate units of measure used for problem input.

Calling sequence:

CALL USOLCDAT( ICNO, IPROP, VALUE, IERR )

Where :

ICNO Input integer component (internal order) sequence number. (See routines COINUM and COPNUM.)

IPROP Input integer flag indicating the requested property.1 Heat of fusion, energy / weight2 Temperature at Normal Melting point3 Triple point temperature4 Triple point pressure

VALUE Output property value; a double precision scalar.

IERR Output integer status flag that returns:0 Success, no errors1 Failure, requested property not found.

4 Failure due to one of the following: Zero or negative stream flow rate, Temperature or pressure out of bounds, A negative value in SMWCRATE. No Solid component specified.


GETPSDCThis subroutine may be used to retrieve the number of Particle Size Distribution cuts (NCUTS) for a single specified component. NCUTS is required by the Particle Size Distribution retrieval/stor-age subroutine (see USOLPSD).

Calling sequence:

CALL GETPSDC( ICNO, NCUTS )

where:

ICNO Input integer that specifies the internal order number1 of the component of interest.

NCUTS Output integer returns the number of cuts for component ICNO in the Particle Size Distribution data tables.

Note 1: See routine COINUM to access component internal order numbers.

USOLPSDThis subroutine retrieves or stores the Particle Size Distribution attributes for a solid component in a given stream.

Calling sequence:

CALL USOLPSD( CSID, ICNO, LENPSD, PSD,& IOTYPE, IERR )

Where

CSID Input character string that identifies a PRO/II stream to which data is stored or from which data is retrieved. It may be a quoted literal string or a character variable containing a maximum of 12 characters.

ICNO Input integer that specifies the internal order number1 of the component of interest.

LENPSD Input integer that declares the size of argument array PSD. LENPSD must equal the number of PSD cuts for the component (NCUTS - 1). Obtain NCUTS by using interface routine GETPSDC.

PSD Double precision array of PSD values for component ICNO (in stream CSID). Used to store or retrieve data. Usually, this as an ALLOCATABLE array.


Example:Assume we wish to retrieve PSD data for component 3, and the stream of interest already is declared in variable CSID. SIMSCI recommends declaring data transfer array PSD as a local ALLO-CATABLE array.

REAL(8), ALLOCATABLE :: PSD( : ) INTEGER(4) :: LENPSD, ICNO, NCUTS, ifOK INTEGER(4) :: IOTYPE, IERR CHARACTER(LEN=12) :: CSID . . . ICNO = 3 CALL GETPDSC( ICNO, NCUTS ) LENPSD = NCUTS - 1 ALLOCATE( PSD( LENPSD ), STAT=ifOK ) . . . IOTYPE = 1 ! option to retrieve data

CALL USOLPSD( CSID, ICNO, LENPSD, PSD,& IOTYPE, IERR ) . . . ! use date, then free array PSD IF( ALLOCATED( PDS ) ) DEALLOCATE( PSD )

UPSDCPYThis subroutine copies all particle size distribution data from one PRO/II stream to another. No data values pass through the argument list.

Calling sequence:CALL UPSDCPY( FromSID, ToSID, IERR )

Where:

FromSID Input 12 character stream ID from which data is copied.

ToSID Input 12 character stream ID into which data is copied.

IERR Integer return status flag.0 = Success, no errors1 = Failed for unspecified reasons.

IOTYPE Integer input option flag that controls data transfer.1 = Retrieve data2 = Store data

IERR Integer output status flag.0 = Success, no errors1 = Failure, unspecified errors encountered


Chapter 22Pressure Drop Subroutines

The User-Added Pressure Drop subroutines described in this chap-ter allow users and other independent developers to supplement the PRO/II-supplied pressure drop methods. Only the PIPE and PLUG Flow reactor models in PRO/II support user-added pressure drop subroutines.

The PIPE unit can use only one of the PIPUSn pressure drop routines. When the PLUG model runs in OPENPIPE mode, it also uses only the PIPUSn routines. However, a PLUG model with the PACKING option uses only the PACUSn routines. The two types of pressure drop rou-tine have different data requirements. To accommodate these differ-ences, separate pressure drop interfaces are provided for the PIPE and the PLUG Flow Reactor models. Both the keyword input facili-ties and the ProVision Graphical User Interface fully support these subroutines.

PIPE Pressure Drop SubroutinesUser Information

The PIPE unit operation in PRO/II supports up to two user-added subroutines to compute the pressure drop through a pipe. Each PIPE unit in a simulation can access one or the other of these two routines by specifying either DP1 or DP2 as the argument of the DPCORR key-word on the LINE statement. PRO/II already includes sample calcu-lation routines, so these two options may be exercised in the version as delivered.


Pipe Pressure Drop Method Selection Using ProVisionThe ProVision GUI makes it simple to access user-added pressure drop methods in PIPE units. Figure 22-1 illustrate how selection is accomplished with just a few mouse clicks.

Figure 22-1: Pipe Pressure Drop Methods in ProVision

22-2 Pressure Drop Subroutines February 2009

Pipe Pressure Drop Method Selection Using KeywordsPIPE UID=<unit ID>, {NAME=<name>}

LINE DPCORR= DP1 or DP2 ...

Users must explicitly select either DP1 or DP2 to use a user-added pressure drop routine. See Table 22-1. If the selection is omitted, the pipe unit uses internal correlation to compute pressure drop.

where:

Table 22-1: Selecting A User-Added Pressure Drop In A PIPE Unit

DPCORR = Selects the pressure drop correlation. Arguments DP1 and DP2 select a user-added subroutine written and built in the User-Added Library.

DP1 PIPUS1.FOR computes pressure drop of a PIPEDP2 PIPUS2.FOR computes pressure drop of a PIPE

Input Data RequirementsThere are no input data values for the user to supply. The PIPE model in PRO/II uses internal calculation values to satisfy all the data requirements of the user-added subroutine.

Output ReportingPRO/II does not provide any reporting from user-added pressure drop subroutines.

Developer InformationOf course, the intended purpose is to allow you to implement and use your own pressure drop correlation(s) instead of using those provided by SIMSCI. To create your own pressure drop correlation routine, you must replace a subroutine supplied by SIMSCI with one that contains your own code. Sample routines PIPUS1.FOR and PIPUS2.FOR are made available when the user-added add-on is installed during PRO/II installation. Replace the code in these rou-tines with your own code.

Guidelines for CodingDevelopers should acquire a reasonably thorough understanding of using user-added subroutines before beginning code development.


All the previous information for users is relevant. This section high-lights areas of concern that developers may encounter.

Here are a couple of tips about general coding practices.

1. Check the input data for completeness and consistency, and perform any necessary error processing. If desired, call UAERR to register a warning in the PRO/II error system. Do this before starting the calculations.

2. Perform the calculations, returning the results in the seven out-put variables of the subroutine argument list. Normally utilities such as pressure drop calculations should generate fatal errors. Always try to return reasonable values, even after encountering problems. For example, when calculations are impossible, return dP as zero and issue a warning. Let the calling unit oper-ation decide if it needs to fail.

3. Intermediate results may be printed as desired. Use variable IDG as a diagnostic print flag. It is passed in for this purpose.

Subroutine Naming ConventionsPRO/II associates input keywords with specific user-added subrou-tines. These associations are implemented through a pre-defined set of the subroutine naming conventions. Developers must use the subroutine names shown in Table 22-1 on page 22-3 to achieve a successful implementation for PIPE units.

Calculation Routines -- Fortran Coding ConventionsInformation is communicated to the user subroutine through the subroutine’s argument list and the common blocks listed in Table 15-2, “Interface Common Blocks,” on page 15-6.

Calling sequence:

CALL PIPUSn(& HLNS, AINCL, DIAM, AREA, RUFF,& RNUMB, FRICT, FROUDE, NOACCL, PRES,& RLVELN, VELSL, VELSG, QLI, QGI,& RLDENS, VISL, RLSTEN, RVDENS, VISV,& HL, IREG, FRGR, ELGR, ACCGR,& DPINCR, NFOUT, IDG, NUIDD, IDUM1,& IDUM2 )

where:


n in PIPUSn is a digit, either 1 or 2. It is part of the subroutine name, as shown above in Table 22-1.

All data available to the pressure drop routine is passed through the argument variables in the call list by each PIPE unit that uses the pressure drop subroutine. The data are specific to the PRO/II pipe model, so the pressure drop routine is suitable for use only with PRO/II PIPE unit operations.

Table 22-2 describes the 31 arguments in the call list.

Table 22-2: PIPUSn Argument ListName Type Brief Description UOM

Input VariablesHLNS DP1 No slip holdup

≤ 0.0 = Single-phase vapor0.0<HLNS<1.0 = Mixed phase


AINCL DP Pipe inclination angle radians

DIAM DP Pipe inside diameter feet

AREA DP Pipe inside area square feet2

RUFF DP Pipe roughness/diameter ratio

RNUMB DP Reynolds number


NOACCL Integer3 NOACCELERATION option flag

0 = acceleration APPLIED 1 = acceleration OMITTED

PRES DP Input. Absolute pressure psiaRLVELN DP Pipe liquid VELOCITY number

VELSL DP Pipe liquid SUPERFICIAL VELOCITY

ft/sec

VELSG DP Pipe vapor SUPERFICIAL VELOCITY

ft/sec

QLI DP Pipe liquid FLOWRATE cu.ft/secQGI DP Pipe vapor FLOWRATE cu.ft/sec1) DP indicates the argument is a double precision floating point value.2) Chr*(*) indicates the argument is an inherited-length character string. 3) INT indicates variables are type INTEGER(4)


RLDENS DP Pipe liquid (oil+water) DENSITY

lb/cu.ft

VISL DP Pipe liquid (oil+water) VISCOSITY

cP

RLSTEN DP Pipe liquid (oil+water) SURFACE TENSION

dyne/cm

RVDENS DP Pipe vapor DENSITY lb/cu.ftVISV DP Pipe vapor VISCOSITY cPNFOUT Integer Fortran File Unit for printing

diagnostic messages

IDG Integer Diagnostic printout flag (DUMP value)

0 = Suppress diagnostics1 = Generate diagnostics

NUIDD Chr*(*)2 Character string containing ID of (calling) unit op

IDUM1 Integer Not used here

IDUM2 Integer Not used here

OUTPUT VariablesFRICT DP Pipe friction factor (Calculated

and returned even when no input value is supplied)

HL DP Pipe slip holdup

IREG Integer dP method flow regime flag1 = Liquid 2 = Vapor 3 = Distributed 4 = Intermittent 5 = Segregated6 = Transition

FRGR DP Friction gradient psi/ftELGR DP Elevation gradient psi/ftACCGR DP Acceleration gradient psi/ftDPINCR DP Total gradient FRGR + ELGR +

ACCGRpsi/ft

Table 22-2: PIPUSn Argument ListName Type Brief Description UOM

1) DP indicates the argument is a double precision floating point value.2) Chr*(*) indicates the argument is an inherited-length character string. 3) INT indicates variables are type INTEGER(4)


Note: Be sure to declare all floating-point argument variables as double precision REAL(8), or include the SIMSCI-pro-vided INCLUDE file PRECIS.CMN as the first line of active code after the SUBROUTINE statement.

Availability of DataThe PIPE unit delivers current values of its ongoing calculations to the subroutine through variables in the call argument list. The argu-ment list variables essentially constitute the entire universe of PIPE data available to the subroutine. Other simulation data not specific to the PIPE unit, such as component data, may be accessed using any of the interfaces listed in chapter 15, ”Interfacing Software”, Table 15-1 and Table 15-2. In most cases, stream data is of little use in pressure drop calculations; so use of stream interfaces probably should be avoided.

Returning Results to PRO/IIReturn all calculated results through the seven output variables in the subroutine’s argument list. Refer to Table 22-2 on page 22-5.

Output SubroutinesPRO/II does not provide any support for output from user-added pressure drop subroutines.

Sample Code ListingsPRO/II Keyword Input File

TITLE PROJ=PipeDp, PROB=Ex8-1, USER=SimSci, DATE=Mar-2008 $ $ Sample Pipe using User-added Pressure drop routine $ PRINT INPUT=ALL DIMENSION ENGLISH, PRES=PSIG, LIQVOL=GAL, TIME=MINCOMPONENT DATA LIBID 1, WATERTHERMO DATA METHODS SYSTEM=LIBRARY, TRANSPORT=PURE, & DENSITY(L)=LIBRARYSTREAM DATA $ 40 gpm of condensate water at 50 psig PROP STRM=F40P2, PHASE=L, PRES=50, COMP=1, RATE(V)=40 PROP STRM=F40DP1, PHASE=L, PRES=50, COMP=1, RATE(V)=40UNIT DATA PIPE UID=PipeProII, NAME=300 FT LINE FEED F40P2


PROD M=ProdProII $ Internal dP LINE DIAM=3.26, LENGTH=300, DPCORR=BBM PIPE UID=PipeUser1, NAME=300 FT LINE FEED F40DP1 PROD M=ProdUser1 $ dP from PIPUS1 LINE DIAM=3.26, LENGTH=300, DPCORR=DP1

This example runs two pipe units that are identical except for one difference: the first uses an internal PRO/II correlation, while the second uses a user-added subroutine to calculate pressure drop.

Fortran Source ListingSee file PIPUS1.FOR for a listing of the code used in this example. The file is located in the ..\USER\Uas\examples\ directory tree of the PRO/II installation.

Partial Output Listing The partial output listing that follows demonstrates the differences in the results.

This first unit uses a PRO/II internal pressure drop correlation.

UNIT 1, 'PIPEPROII', '300 FT LINE'

OPERATING CONDITIONS DUTY, MM BTU/MIN 0.00000 PRESSURE DROP SUMMARY LINE FRICTION, PSI 0.50257 ELEVATION, PSI 0.00000 ACCELERATION, PSI 3.12162E-05 TOTAL, PSI 0.50260 CALC TOTAL PRESSURE DROP, PSI 0.50260 CALC MAX LINE FLUID VELOCITY, FT/SEC 2.05859 UNIT 2, 'PIPEUSER1', '300 FT LINE'

The second pipe used user-added subroutine PIPUS1.FOR to per-form the pressure drop calculations.

OPERATING CONDITIONS DUTY, MM BTU/MIN 0.00000 PRESSURE DROP SUMMARY LINE FRICTION, PSI 0.52551 ELEVATION, PSI 0.00000 ACCELERATION, PSI 3.83041E-05 TOTAL, PSI 0.52555 CALC TOTAL PRESSURE DROP, PSI 0.52555 CALC MAX LINE FLUID VELOCITY, FT/SEC 2.07656


Plug Flow Reactor Pressure Drop SubroutinesUser Information

The PLUG Flow Reactor unit operation (PFR) in PRO/II supports two sets of user-added subroutines to compute the pressure drop through the reactor; the PIPUSn routines and the PACUSn routines. In OPENPIPE mode, the PLUG reactor uses the PIPUSn user-added pres-sure drop subroutines described earlier in this chapter. They are not discussed further here.

PLUG units model packed-bed reactors when they include the PACKING and CATALYST statements in keyword input. In ProVision, setting the Pressure Specification to Packed-Bed Pressure Drop results in the same packed-bed configuration. In this mode, only the PACUSn subroutines are available. This section only describes the PACUSn subroutines.

Each PLUG unit in a simulation can access only one of the pressure drop routines. PRO/II already includes a sample calculation routine, PACUS1.FOR. That means the DPCORR=DP1 option for a packed-bed PLUG reactor may be exercised in the version as delivered.

Open Pipe Pressure Drop Methods Using KeywordsPLUG UID=<unit ID>, {NAME=<name>}

OPENPIPE DPCORR= DP1 or DP2 ...

Table 22-3 relates the input options to pressure drop routines that perform the calculations in a PLUG reactor running in OPENPIPE mode.

Table 22-3: UAS Pressure Drop Options In Open Pipe Plug Reactors

OPENPIPE DPCORR =

Selects a packed-bed pressure drop correlation. Arguments DP1 and DP2 select a user-added subroutine written and built in the User-Added Library.

DP1 PIPUS1.FOR computes reactor pressure drop

DP2 PIPUS2.FOR computes reactor pressure drop


Packed-Bed Pressure Drop Methods Using KeywordsPLUG UID=<unit ID>, {NAME=<name>}

PACKING DPCORR= DP1 or DP2

Table 22-4 relates the input options to calculation routines that per-form the calculations in a PLUG reactor running in PACKING mode:

Table 22-4: UAS Pressure Drop Options In A Packed-Bed PLUG Unit

PACKING DPCORR =

Selects a packed-bed pressure drop correlation. Arguments DP1 and DP2 select a user-added subroutine written and built in the User-Added Library.

DP1 PACUS1.FOR computes packed-bed pressure drop

DP2 PACUS2.FOR computes packed-bed pressure drop

Users must explicitly select either DP1 or DP2 to use a user-added pressure drop routine. If the selection is omitted, the pipe unit uses internal correlation to compute pressure drop.

PFR Pressure Drop Method Selection Using ProVisionAccessing user-added pressure drop methods for PLUG reactors using ProVision is simple. The procedure is almost identical for an open pipe or a packed-bed reactor.

Right-click a PLUG flow reactor icon in the Flowsheet window and select Data Entry ... from the pop-up action menu.

In the Plug Flow Reactor window, click the Pressure button on the plug-flow icon on the right-hand side of the window.

In the Plug Flow Reactor-Pressure window that opens, choose the pressure drop option for the desired reactor configuration.

For an OPENPIPE reactor, click the Pressure Drop Method radio button. Or,

For a packed-bed reactor, click the Packed-bed Pressure Drop radio button.

With the radio button active, click Enter Data just to the right. This opens the PFR Pressure Drop Method DEW.

Select User-1 or User-2 to specify a user-added pressure drop method.


Click OK to confirm the selection and return to the parent Data Entry Window.

Figure 22-2 illustrates the selection process.

Figure 22-2: User-Added PFR Pressure Drop Methods in ProVision


Input Data RequirementsThere are no input data values for the user to supply to the pressure drop routine. The PLUG model in PRO/II uses internal calculation values to satisfy all the data requirements of the user-added subroutine.

Output ReportingPRO/II does not provide any reporting from user-added pressure drop subroutines.

Developer InformationThis section discusses implementing user-added pressure drop cor-relation(s) as alternatives to those within PRO/II. To implement a pressure drop correlation routine, you must replace a subroutine supplied by SIMSCI with one that contains your own code.

Subroutine Naming ConventionsPRO/II associates input keywords with specific user-added subrou-tines. These associations are implemented through a pre-defined set of subroutine naming conventions. Developers must conform to the subroutine names shown in Table 22-4 on page 22-10 to achieve a successful implementation of pressure drop routines for PLUG reac-tors.

GuidelinesRefer to the general “Guidelines for Coding” on page 3 of this chapter. They also apply when coding Plug flow pressure drop routines.

Calculation Routines -- Fortran Coding ConventionsReactor data is passed in, and results are returned to PRO/II, through the subroutine’s argument list.

Calling sequence:

CALL PACUS1( & HLNS, DIAM, AREA, RNUMB, FROUDE, & PRES, VELSL, VELSG, QLI, QGI, & RLDENS, VISL, RLSTEN, RVDENS, VISV, & HL, IREG, DPINCR, NFOUT, IDG, & NUIDD, IDUM1, IDUM2, CDIAM, CVOID, & CSPER, ISTOP )


where:

n in PACUSn is a digit, either 1 or 2. It is part of the subroutine name, as shown in Table 22-4 on page 22-10 of this chapter.

The 27 arguments in the call list are defined in Table 22-5.

Table 22-5: PACUSn Argument ListName Type Brief Description UOM

Input VariablesHLNS DP1 No slip holdup

≤ 0.0 = Single-phase vapor0.0<HLNS<1.0 = Mixed phase


DIAM DP Packed plug inside diameter feet

AREA DP Packed plug inside area feet2

RNUMB DP Reynolds number of flowing fluid (using superficial velocity)


PRES DP Absolute pressure psiaVELSL DP Packed plug liquid SUPERFICIAL

VELOCITYft/sec

VELSG DP Packed plug vapor SUPERFICIAL VELOCITY

ft/sec

QLI DP Packed plug liquid FLOWRATE cu.ft/secQGI DP Packed plug vapor FLOWRATE cu.ft/secRLDENS DP Packed plug liquid (oil+water)

DENSITYlb/cu.ft

VISL DP Packed plug liquid (oil+water) VISCOSITY

cP

RLSTEN DP Packed plug liquid (oil+water) SURFACE TENSION

dyne/cm

RVDENS DP Packed plug vapor DENSITY lb/cu.ftVISV DP Packed plug vapor VISCOSITY cPNFOUT INT Input Fortran File Unit for printing

diagnostic messages

1) DP indicates the argument is a double precision floating point value.2) CHR* indicates the argument is an automatic-length character string.3) INT indicates variables are type INTEGER(4)


Availability of DataEach PLUG reactor that uses the pressure drop subroutine delivers current values from its ongoing calculations through the subroutine argument list. Thus, the argument list variables essentially consti-

IDG INT Diagnostic printout flag (DUMP value)

0 = Suppress diagnostics1 = Generate diagnostic

NUIDD Chr*2 Character string containing ID of (calling) unit op

IDUM1 INT Not used here

IDUM2 INT Not used here

CDIAM DP Particle diameter

CVOID DP Void fraction of the bed

CSPER DP Sphericity

Output VariablesHL DP Packed plug slip holdup

IREG INT dP method flow regime flag1 = Liquid 2 = Vapor 3 = Distributed 4 = Intermittent 5 = Segregated6 = Transition

DPINCR DP Total gradient FRGR + ELGR + ACCGR

psi/ft

ISTOP INT Returned error status flag0 = Success, no errors1 = Failure, results may be invalid.

Note: Be sure to declare all floating-point argument variables as double precision REAL(8), or include the SIMSCI-pro-vided INCLUDE file PRECIS.CMN as the first line of active code after the SUBROUTINE statement.

Table 22-5: PACUSn Argument ListName Type Brief Description UOM

1) DP indicates the argument is a double precision floating point value.2) CHR* indicates the argument is an automatic-length character string.3) INT indicates variables are type INTEGER(4)


tute the entire universe of PLUG reactor data available to the subrou-tine. Other simulation data not specific to the PLUG unit, such as component data, may be accessed using any of the interfaces listed in chapter 15, ”Interfacing Software”, Tables 15-1 and 15-2. In most cases, stream data is of little use in pressure drop calculations; so use of stream interfaces probably should be avoided.

Returning ResultsAll calculated results return to PRO/II through the output variables in the argument list of the subroutine. The 4 required results include: HL, IREG, DPINCR, and ISTOP. Refer to Output Variables in Table 22-5 on page 22-13.

Output SubroutinesPRO/II does not provide any support for output from user-added pressure drop subroutines.

Sample Code ListingsThis example runs two PLUG reactors with these differences: The first is an OPENPIPE plug reactor. The OPENPIPE DPCORR=DPI state-ment specifies user-added subroutine PIPUS1.FOR to calculate the pressure drop.

The second is a packed-bed reactor. The PACKING DPCORR=DP1 statement specifies user-added subroutine PACUS1.FOR to calculate pressure drop.

PRO/II Keyword Input FileTITLE PROB=USERADD, PROJ=dPPlug, USER=SIMSCI, DATE=Mar2006 $ This file tests user-added Pressure Drop $ subroutines in Plug-Flow reactors $ US1Open uses PIPUS1 in an OPENPIPE reactor $ US2Pack uses PACUS1 in an PACKED reactor PRINT INPUT=ALL, STREAM=PART DBASE DATA=PC1 COMP DATA LIBI 1,H2O/ 2,HCL/ 3,CL2/ 4,PROPYLEN/ & 5,ALLYLCL/ 6,12DCLPRP/ 7,13DCLPRETHERMO DATA METH KVAL=SRK, ENTH=SRK, ENTR=SRK, TRANS=LIBR, & DENS(V)=IDEAL, DENS(L)=IDEALSTREAM DATA PROP STRM=X100, TEMP=852.4933, PRES=1500.0, &


COMP=0.0000/0.1/172.5399/1010.4196/1.75 PROP STRM=X200, TEMP=852.4933, PRES=1500.0, & COMP=0.0000/0.1/172.5399/1010.4196/1.75 PROP STRM=X300, TEMP=852.4933, PRES=1500.0, & COMP=0.0000/0.1/172.5399/1010.4196/1.75RXDATA RXSET ID=SET01 REACTION ID=REAC01 STOI 4,-1/3,-1/5,1/2,1 KINETICS PEXP=2.1E11, ACTI=27.0096 KPHASE DEFAULT=V REACTION ID=REAC02 STOI 4,-1/ 3,-1/ 6,1 KINETICS PEXP=1.19E7, ACTI=6.81198 KPHASE DEFAULT=V REACTION ID=REAC03 STOI 5,-1/ 3,-1/ 7,1/ 2,1 KINETICS PEXP=4.69E14, ACTI=4.23E1 KPHASE DEFAULT=VUNIT OPERATIONS PLUGFLOW UID=US1Open FEED X100 PROD L=USOpen RXCALC KINETICS(SUBROUTINE)=U1, NSTEPS=100 OPER LENG=5.0,DIAM=10.0,PHASE=V,TEMP=850

OPENPIPE DPCORR=DP1 $ User-added PACUS1 RXSTOIC RXSET=SET01 REACTION REAC01 BASE COMPONENT=3 REACTION REAC02 BASE COMPONENT=3 REACTION REAC03 BASE COMPONENT=3 SUPPLE 199,1234.0

PLUGFLOW UID=Us2Pack FEED X200 PROD L=USPack RXCALC KINETIC(SUBROUTINE)=U1, NSTEPS=100 OPER LENG=5.0,DIAM=10.0,PHASE=V,TEMP=850

PACKING DPCORR=DP1 $ User-added PACUS1 CATALYST POROSITY=0.99, PDIAM=0.5 RXSTOIC RXSET=SET01 REACTION REAC01 BASE COMPONENT=3 REACTION REAC02


BASE COMPONENT=3 REACTION REAC03 BASE COMPONENT=3 SUPPLE 199,1234.0END

Fortran Source ListingSee files PIPUS1.FOR and PACUS1.FOR for listings of the pressure drop code used in this example. The files located in the ..\USER\Uas\examples\ directory tree of the PRO/II installation.

Partial Output file The partial output listing that follows demonstrates the differences in the pressure drop results.

The first unit is an open pipe reactor that uses the PIPUS1 pressure drop routine.

UNIT 1, 'US1OPEN'

OPEN PIPE REACTOR DETAILS

REACTING SIDE Inlet Outlet ----------- ----------- Feed X100 VAPOR Product USOPEN Temperature, F 852.49 850.00 Pressure, PSIA 1500.0000 1499.9985

The second unit is a packed-bed reactor that uses the PACIS1 pres-sure drop routine.

UNIT 2, 'US2PACK'

PACKED BED REACTOR DETAILS

REACTING SIDE Inlet Outlet ----------- ----------- Feed X200 VAPOR Product USPACK Temperature, F 852.49 850.00 Pressure, PSIA 1500.0000 1103.2132


Appendix A Special Property Key Words

Named Special PropertiesThis appendix lists the named special properties supported by the User-added Subsystem in PRO/II. Some interface routines that use these key words include: UCoPrp on page 15-44.

Table A-1 lists the key words that identify named Special Properties supported by PRO/II user-added interface routines. These key words are used only inside user-added subroutines. They may be different from the key words used in PRO/II keyword input files.

Table A-1: Keywords for Named Special Properties

Keyword PropertyKVIS Kinematic ViscosityCLOU Cloud PointPOUR Pour PointFLPC Flash Point (Closed Cup)SULF Sulfur ContentCETN Cetane NumberSMOK Smoke PointARO1 Mono AromaticsARO2 Di-AromaticsARO3 Tri-AromaticsARO4 Tetra-AromaticsARO5 Penta-AromaticsARO7 Hepta-Aromatics

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

AROT Total AromaticsNAPH NaphthenePARN Normal ParaffinPARI Iso-ParaffinPARA Alkyl-ParaffinPARP Poly-ParaffinPART Total ParaffinOLE1 Mono OlefinOLEB Branched OlefinOLEC Cyclic OlefinH2 HydrogenCARB CarbonVANA VanadiumNICK NickelSODI SodiumOXGY OxygenN2TO Total NitrogenN2BA Basic NitrogenN2NB Nonbasic NitrogenASC5 Asphaltene C5ASC7 Asphaltene C7V50 V50 ValueVIND Viscosity IndexPEN Penetration IndexFRZP Freeze Point (temperature)CCR Conradson Carbon ResidueRCR RAM Carbon ResidueCHRA Carbon-Hydrogen Weight RatioTAN Total Acid NumberWAX Wax ContentASH Ash Content

Keyword Property

A-2 Special Property Key Words February 2009

RON Research Octane NumberMON Motor Octane NumberREFI Refractive IndexRIND Ring IndexARIN Aromatic IndexGIND Grade IndexSIND Structure IndexLUMI Luminometer NumberNOAC Noack VolatilityJT Joule-Thompson, K/kPaEXPN Expansivity, 1/KVSOU Velocity of Sound, m/sBULK Bulk Modulus, kPaCVOL CVOLCETA Cetane IndexIBP Initial Boiling Point (temperature)FBP Final BP (temperature)MERC MercaptanNPHL NaphthaleneANIL Anilne PointBROM Bromine NumberANEU Neutralize NumberCFPP CFPPICI Icing IndexSTUI Startup IndexWUI Warm-up IndexSOFT Softening PointPHEN Phenol ContentMON3 MON at 3 ml TELRON3 RON at 3 ml TELASUL Aliphatic Sulfur

Keyword Property


RI70 Refractive Index at 70CAROG Aromatic RingsIRON Iron ContentWTAR Weight AromaticsWTPA Weight ParaffinsWTNA Weight NaphthenesFLPO Flash Point (Open Cup)CVLU Car Vapor Lock (USA)CVLE Car Vapor Lock (Europe)MEAB Mean Average Boiling Point (temp)CABP Cubic Average Boiling Point (temp)MOAB Molal Average Boiling Point (temp)NHV Net Heating ValueIDLT IDL TypePEPT Peptising PowerPVAL P ValueFRMX FR MaximumFLOC Flocculation RatioCPWX Congealing Point of WaxPWAX Paraffinic Wax ContentCPPW Congealing Point of Paraffinic WaxARI1 Initial Point Mono-AromaticsARI2 Initial Point Di-AromaticsARI3 Initial Point Tri-AromaticsARIP Initial Point Total AromaticsMERS Mercaptan SulfurTRS Total Reactive SulfurFLPW Flash Point (Wong Closed Cup)

Keyword Property


Numbered Special PropertiesSeveral interface routines that may be called from user-added sub-routines require a key word argument to identify a component prop-erty or a named special property. However, some special properties are defined by the user, and so do not have a name assigned to them that PRO/II can recognize universally. Typically, such numbered (user-defined) properties are designated in PRO/II keyword input files using keyword SPROP(nn), where “nn” represents the prop-erty number.

To allow accessing these properties from user-added subroutines, these properties are identified by supplying an ID number. Here are the general usage conventions.

Whenever the character string argument (cProp) for a named property is non-blank, PRO/II attempts to process that property.

When the string is not resolvable into a recognized property ID, an error results.

When the character string argument (cProp) for a property is blank or zero length, PRO/II tests an additional integer argu-ment (iProp) in an attempt to identify a numbered user-defined special property.

If the property identified by the iProp argument is found to be available, PRO/II processes that numbered property.

When iProp is not resolvable into a recognized property ID, or the property cannot be found, an error results.


PROII User-Added Subroutines User Guide

Documents

Transcript of PROII User-Added Subroutines User Guide