Descripción: This book tell to you know about how to use reference in abaqus version 6.11.
Descripción: Manual de uso de simulador de procesos PRO II
Hadnling Assays in PROIIDescripción completa
PROII Advanced TrainingFull description
Smart Plant User GuideDescription complète
User Guide to the optimization code OptistructFull description
pipesimDescripción completa
rwetrkjhgFull description
VodiaFull description
Wastewater Network Analysis and Design Software Product. SewerGEMS is a fully dynamic, multi-platform, sanitary and combined sewer modeling solution. Engineers can analyze sanitary or combi…Description complète
Descripción completa
C:\AVEVA\Plant\PDMS12.0.SP6\Manuals\Docs
This is the official instruction manual for the Motorola-brand Model GM 338 Professional Mobile Radio for Conventional System. This version of the manual was published in 2010, and was scanned f...Full description
SaludosFull description
For inspiration to conduct investigationsFull description
Descrição: rwetrkjhg
Fibersim 15 userguide
EclipseDeskripsi lengkap
User guide for installing Liaison Dsc System.Full description
PRO/II 8.3 User-Added Subroutine User Guide
PRO/II Version 8.3
The software described in this guide is furnished under a written agreement and may be used only in accordance with the terms and conditions of the license agreement under which you obtained it.
Thermodynamic Data Keyword Manual Copyright Notice
PRO/II and Invensys SIMSCI-ESSCOR are trademarks of Invensys plc, its subsidiaries and affiliates. AMSIM is a trademark of DBR Schlumberger Canada Limited. RATEFRAC®, BATCHFRAC®, and KOCH-GLITSCH are registered trademarks of Koch-Glitsch, LP. Visual Fortran is a trademark of Intel Corporation. Windows Vista, Windows 98, Windows ME, Windows NT, Windows 2000, Windows XP, Windows 2003, and MS-DOS are trademarks of Microsoft Corporation. Adobe, Acrobat, Exchange, and Reader are trademarks of Adobe Systems, Inc. All other trademarks noted herein are owned by their respective companies. U.S. GOVERNMENT RESTRICTED RIGHTS LEGEND The Software and accompanying written materials are provided with restricted rights. Use, duplication, or disclosure by the Government 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.
Chapter 1 Modular UAS Introduction Beginning in PRO/II® version 7, new interfaces for user-added subroutines 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 versions of PRO/II still function in exactly the same manner as they always have. SIMSCI® has no plans to abandon them, and continues development activities to extend their capabilities. Note: Refer to Chapter 14, Classic UAS Introduction for informa-
tion about new enhancements to the older interfaces.
General Information This section presents general introductory information about the technologies and methodologies used in the modular user-added interfaces. The next section in this chapter presents information for end users who wish to use modular user-added subroutines when running simulations in PRO/II. Instructions for developers implementing modular user-added subroutines appears in separate chapters.
Nomenclature PRO/II categorizes modular user-added subroutines by function. Below is a brief summary of some terms used in this manual. UAS
A generic term for any User-Added Subroutine entity. It includes UAUOP and UAUTIL subroutines written by users. It does not refer to INTERFACEs supplied by PRO/II.
UAUOP
A User-Added Unit OPeration written by a userdeveloper. Registered as a [UAUOP] in the P2UasReg.Ini file. Called only from PRO/II.
PRO/II User-Added Subroutine User Guide
1-1
UAUTIL
A User-Added UTILity subroutine written by a userdeveloper. 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 subroutines. Older interfaces are available in UASLB.LIB. The modular interfaces are available in USERLB6.LIB and in a number of Fortran modules. Interfaces are intended to be used within user-added subroutines.
Procedural Interfaces The older user-added interfaces in PRO/II treat individual data items as separate entities. Refer to Chapter 14, Classic UAS Introduction. They typically include long lists of arguments in subroutine calls. Enhancing them typically requires changing the number and type of arguments in the call lists. To maintain backward compatibility, all versions of each interface must be supported. This results in many variations of subroutines that basically perform the same function, which can be confusing. Procedural interfaces require changes to user-added routines before they can use the newer versions of the interfaces. Code must be rewritten and re-linked with PRO/II; then it must be tested and debugged. From a maintenance perspective, this is inefficient and undesirable. The newer user-added interfaces in PRO/II do not use this paradigm.
Modular Interfaces This is a short overview of object-oriented programming (OOP) using Fortran 90. It defines the terminology used throughout the rest of this manual to describe the modular interfaces in PRO/II. It is not a tutorial of object-oriented practices, which is beyond the scope of this manual. Object-oriented programming treats data in sets. First, a storage object is created and all related data entities are mapped into it. The storage object may contain a mixture of scalar and array data of different intrinsic types, such as integer, real, character, and logical data. Each data entity is a data member of the storage object. Data members that are arrays typically have a dynamic size. They can be adjusted to accommodate different amounts of data. In Fortran 90, a data object having these characteristics is called a defined type.
1-2 Modular UAS Introduction
February 2009
Second, member methods are added to operate on the data in the storage object. This ensures that basic functions for operating on the data are always available with the data. Adding these methods transforms the defined type into an Abstract Data Type, or ADT for short. Third, the ADT is transformed into a class by adding constructor and destructor methods. These methods allow allocating and freeing 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 useradded subroutines. PRO/II interfaces provide a separate module for each class. However, the executable code for all modules resides in a single DLL. Together, all the modules and the DLL constitute the new PRO/II modular interface.
Modular User-Added Subroutines Modular user-added subroutines interact with PRO/II through the modular interfaces. They include user-added unit operations and user-added utilities. Later chapters present interfacing details. To use modular UAS’s in PRO/II simulations, end-users must first install and register them with PRO/II. Specific installation instructions must be obtained from the UAS developer, not from SIMSCI. The registration process consists of editing the PRO/II registration file to include essential access information, so PRO/II can call and use the UAS. The registration file is divided into sections based on the functionality of the UAS. Each UAS must be registered in the proper section of the registration file. For example, a user-added unit operation must be registered in the [UAUOP] section, while an interfacial area utility must be registered in the [IFAREA] section.
PRO/II User-Added Subroutine User Guide
1-3
Modular User-Added Unit Operations UAUOP behavior is similar to that of native unit operations contained
in PRO/II. However, users first create and install them in their own dynamic link libraries (DLL’s); then register them, so that PRO/II can locate them. PRO/II accepts input data for UAUOP’s through key words and PROVISION™. In the course of solving a flowsheet, PRO/II calls out to these routines to perform their own data cross-checks, perform calculations, and to write reports of their results. UAUOP’s have substantially different capabilities from user-added utilities. For example, a UAUOP conceivably could call a UAUTIL, but a UAUTIL should never call a UAUOP. Similarly, one UAUOP cannot call another UAUOP. Generally, user-written subroutines cannot call a UAUOP. A UAUOP can use any of the interfaces described in this
manual.
Modular User-Added Utilities Certain PRO/II unit operations allow user-written subroutines to perform specific calculations. This manual refers to those user-written 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 existing 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 support 3 new modular utilities. Only RATEFRAC supports them. They are: Interfacial Area methods. RATEFRAC allows a different subroutine or method on each tray or in each packed section. Binary Mass Transfer Coefficient methods. RATEFRAC allows a different subroutine or method on each tray or in each packed section. Heat Transfer Coefficient methods. RATEFRAC allows a different subroutine or method on each tray or in each packed section. These types are discussed in detail in separate chapters later in this manual. Additional chapters describe UAUOP’s.
1-4 Modular UAS Introduction
February 2009
Modular Interface Call-backs Modular interface call-backs provide mechanisms for exchanging data and calculation control between PRO/II and user-added subroutines. 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 subroutine by calling either a UAUOP or a UAUTIL. The UAS performs its own calculations, which may or may not involve calling PRO/II calculation call-backs. For example, a UAUOP might call function flash_Fluid to perform a flash calculation on a fluid object. Function flash_Fluid returns it’s results to the UAS. Data call-backs return data and other information from PRO/II when they are called from a UAS. For example, function GetFactor_DmUom returns factors for converting numerical values between user-defined and internal PRO/II units of measure.
Compatibility with Procedural Interfaces Generally, modular subroutines are not compatible with the older procedural interfaces. In most other cases, mixing the two interfaces is discouraged. The problems arise mostly from the different dimensional 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 callbacks that pass class objects in their argument lists. However, procedural subroutines may safely use the file-handling, error register, and line printing routines from the modular interface. Other uses are strongly discouraged.
PRO/II User-Added Subroutine User Guide
1-5
User Information This section presents an overview of information that users need to set up and use modular user-added subroutines with PRO/II. More complete details are available in Chapter 2, Modular UAS Build Procedures. Information for developers who author user-added subroutines appears in later chapters, not here.
Registering a Modular UAS with PRO/II PRO/II maintains a “registry” file that includes a separate category for each supported type of user-added utility. It also supports a separate category for registering unit operations. PRO/II cannot find a UAS or its DLL unless it is properly registered. The procedure for registering a UAUOP is different from the procedure for registering a UAUTIL. Both procedures are simple, and fully described in Chapter 2.
Locating User-Added DLL’s Modular User-added dynamic link libraries (DLL’s) built for PRO/II may be located anywhere on a network so long as PRO/II can find and access them. This means the user-added DLL’s do not need to be located in the same directory tree where PRO/II is installed. These DLL’s could be located on a different disk drive, or even a different computer. The operating system of the computer that stores the DLL’s could be any operating system (such and Unix or Linix) so long as it supports a Windows-compatible protocol for calling DLL’s. The full path to the DLL (from PRO/II) must not exceed 255 characters. This is different from the requirements for procedural DLL’s discussed in Building with the Intel Visual Fortran Compiler in Chapter 14.
Program Limits Every new UAS must be registered with PRO/II before it can be used. Some benefits of this approach are: An almost unlimited number of UAUTIL’s and UAUOP’s may be implemented in PRO/II. No pre-defined subroutine names. Any subroutine name up to 31 characters is allowed.
1-6 Modular UAS Introduction
February 2009
Implementation is through Dynamic Link Libraries that may be located anywhere on a computer network (so long as PRO/II can navigate to them). There are almost no restrictions on the names of modular DLL’s (or the subroutines within them). This is possible because users must “register” each user-added subroutine in a simple text file. PRO/II dynamically finds and executes the required subroutines in each DLL as needed, by looking them up in the “registry” file. Any number of UAS’s may be included in a single DLL, and any number of DLL’s may be used. DLL’s all may reside in a single directory or in separate directories, as the end user chooses. The only restriction is that the fully justified path to the DLL should require no more than 255 characters. There are no limitations on number of components allowed in new user-added subroutines. In fact, PRO/II passes the number of components in each simulation to each interface routine in a user-added DLL. If the DLL requires storage for component data, it should dynamically allocate that storage based on the number of components passed to it by PRO/II.
Software Requirements for PRO/II UAS The hardware and software requirements of modular subroutines generally are the same as for procedural routines. See Chapter 2, Modular UAS Build Procedures, and Software Requirements for PRO/II UAS in Chapter 14.
Compilers and Linkers Developers integrate user-added subroutines written in Fortran into PRO/II by creating a custom version of the dynamic link library UASLB.DLL. To compile and link user-added subroutines into the current PC version of PRO/II, use the following compiler: Intel Visual Fortran version 10.1 or newer (standard or professional editions). This compiler is compatible with Net 2003 and Net 2005 architectures. Important: The Compaq Visual Fortran compiler no longer is com-
patible. Starting with version 8.2, PRO/II is built on the Net 2003 architecture. This change was required to continue delivering new product versions on the current and future operating systems from Microsoft Corporation. PRO/II User-Added Subroutine User Guide
1-7
Other legacy compilers, such as Lahey Fortran and MicroSoft PowerStation Fortran, also are no longer compatible with current versions 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.
Program Limits Although PRO/II internally has no fixed limits on the number of components, the classic user-added interface for PRO/II imposes certain hard restrictions. The limitations shown in Table 1-1 apply. Table 1-1: PRO/II UAS Limitations Calculation/Model Component/Variable Maximum Classic User-Added Calculations1
2500 Components in Flowsheet
Classic User-Added Unit Operations
IPARM RPARM HEAT SUPPLE
User-Added Kinetic Models
50 Components in Flowsheet IPARM (10) RPARM (70) SUPPLE (200)
Modular User-Added Calculations
Dynamic allocation, no fixed limits.
(250) (500) (10) (10000)
1) Except user-added kinetics
Note: For flow sheets containing more than 2500 components,
contact your SIMSCI representative to obtain a version of PRO/II User-Added Subroutines with an increased component maximum. (This is not required for modular useradded applications.) Note: For user-added thermodynamic and transport properties, the TDATA array (and corresponding UDATA statement) is
limited to 2600 entries. Note: These limits do not apply to the new modular user-added
subroutines described in the first chapters of this Guide.
PRO/II User-Added Subroutine User Guide
1-9
Upgrading Legacy User-Added Subroutines Starting with version 8.2, PRO/II is based upon the Net 2003 architecture and no longer is compatible with any earlier versions. All user-added projects created using PRO/II 8.1 and any earlier version must be recompiled and re-built. This must be done using the new Intel Fortran compiler, version 10.1 or newer, or another compiler compatible with the Net 2003 architecture. Follow the directions in Chapter 2, Modular UAS Build Procedures to perform the rebuild.
Use of Common Blocks Note: All newer modular user-added applications use Fortran mod-
ules that provide dynamic data objects to pass all data. No common blocks are used in these implementations. If your previous installation of UAS was built on a version earlier than PRO/II 5.5, please contact your SIMSCI support representative for information about upgrading your user-added subroutines. Previous to PRO/II version 5.5, common block definitions were specified directly in the source code. For example: COMMON /FACTOR/ TCONVT, TFAC, . . .
Now you need to only specify the name of the INCLUDE file (with its proper path) that contains the common block of interest. For the common block /FACTOR/, it suffices to specify: INCLUDE ‘FACTOR.CMN’
In order to maintain compatibility with the supplied INCLUDE files, you should ensure that the original common variable names contained in these common blocks have not been modified. These INCLUDE files are supplied as part of the UAS/PDTS product in the C:\SIMSCI\PROII82\USER\CMNS directory. These changes facilitate the creation of DLL versions of user-added subroutines. These source code modifications are required only when using a MicroSoft Windows version of PRO/II. User-added subroutines on other platforms do not require modification.
1-10 Modular UAS Introduction
February 2009
Replacement Source Code Important: New Intel Visual Fortran solutions and projects replace the older (now obsolete) workspaces and projects used formerly by Compaq Visual Fortran. Table 1-2 shows the new solutions and projects on the left with the corresponding workspaces and projects they replace on the right.
Table 1-2: Replacement UAS Solutions and Projects New Code for PROII 8.2
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) :: INTEGER(4) :: . . . CALL PAOPEN( NAME, " 1001 FORMAT( A ) WRITE( NFOUT, 1001 )
NAME NFOUT ", NFOUT, IRCODE ) “This Write FAILS”
PDTS example modified for Intel Fortran inter-operation with Compaq Fortran: CHARACTER(LEN=16) :: INTEGER(4) :: CHARACTER(LEN=78) :: . . . 1001 FORMAT( A ) . . . CALL PAOPEN (NAME, "
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 subroutine. This approach eliminates the need for any code changes to the READ or WRITE statements. The reason is that the OPEN, READ, and WRITE calls are executed under the same architecture, so the discontinuities discussed above do not apply.
1-14 Modular UAS Introduction
February 2009
Chapter 2 Modular UAS Build Procedures Overview When PRO/II is installed by a user, the Setup Wizard provides an option to install the sample user-added subroutines. When selected, this option copies all the necessary source code and sample projects to the hard drive of the computer. However, the sample modular subroutines must be built and registered (by the user) before they can be used by PRO/II. A developer writes user-added subroutine code, builds executable dynamic link libraries (DLL’s), and delivers them to users. Once again, users are the ones who must install and register the subroutines 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 subroutines so PRO/II can use them.
Building A UAS DLL Using Visual Studio .NET 2003 Building a dynamic link library involves two major phases: 1.
Compiling. The source code of all routines in the library is processed to create relocatable binary object files.
2.
Linking. The object files are passed into a linker that creates the executable DLL.
Both of these functions are performed by using the Build command in Microsoft Visual Studio for NET 2003. The PRO/II Installation Disk includes a sample UAUTIL project that includes subroutines for computing interfacial area, binary mass transfer coefficients, and heat transfer. This discussion uses that project to demonstrate the build process. Note: These instructions assume the sample project was installed
in the default directory structure. For PRO/II version 8.3, this directory is: C:\SIMSCI\PROII82\USER\UAS\UASF90\IVF
The source code is located in: C:\SIMSCI\PROII82\USER\UAS\UASF90\
Modify the paths for this example if the sample code was installed in a different directory. To build other projects, modify the file names as needed. Start Intel Visual Fortran version 10.1 (or later version) by opening Visual Studio .NET 2003. Select File/Open Solution from the menu bar. Select the file: \SIMCI\PROII82\USER\UAS\UASF90\IVF\EXUASF90.SLN,
then click OK. Be sure the Solution Explorer pane is open. If not, select View/ Solution Explorer from the menu bar. Expand the Source Files directory under the ExUasF90 project in the Solution Explorer pane. All the member files for the project are listed in the Source Files directory, as shown in Figure 2-1.
2-2 Modular UAS Build Procedures
February 2009
Figure 2-1: Visual Studio Solution Explorer
To add files to the project, right-click the Source Files folder icon to display a pop-up action menu; then select Add from the action menu for more options. To view source code, simply double-click any of the .f90 files in the list of source files. Ensure the “active configuration” is Release on the standard tool bar. See Figure 2-2, “Setting the Project Configuration to Release.” Figure 2-2: Setting the Project Configuration to Release.
PRO/II User-Added Subroutine User Guide
2-3
Compile and link the entire project. In the Solution Explorer, right-click the ExUasF90 project. From the action menu that opens, highlight Project Only; then click Rebuild Only Project, as shown in Figure 2-3. Figure 2-3: Building A Project
When the “active configuration” is Release, the executable DLL is created in: \SIMSCI\PROII82\USER\UAS\UASF90\IVF\RELEASE\
When the “active configuration” is Debug, the executable DLL is created in: \SIMSCI\PROII82\USER\UAS\UASF90\IVF\DEBUG\ Note: PRO/II does not provide any debug libraries, so any debug-
ging activity is limited to the User-Added project.
2-4 Modular UAS Build Procedures
February 2009
Registering a UAS with PRO/II Before PRO/II can use a modular user-added subroutine, it must be registered so that PRO/II can access it. Registering subroutines enables PRO/II to dynamically locate and call them on demand. Only the newer modular user-added subroutines can be registered. Because the older procedural subroutines are installed in predefined locations, there is no need to register them. Subroutine registration is a simple procedure that involves modifying one plain-text file.
Editing the Registration File The registration file named P2UasReg.ini is located in the SYSTEM sub-directory where PRO/II is installed. For a default installation of PRO/II, the full path to this file is: C:\SIMSCI\PROII82\SYSTEM\P2UASREG.INI
This may be different on machines that installed PRO/II using some of the custom installation options. Syntax in P2UasReg Note: When modifying the registration file to include a new user-
added subroutine, use only a plain-text editor, such as Notepad or the Visual Studio editor. Do not use a word processor which inserts hidden codes that invalidate the entire registration file. The P2UasReg.ini file is divided into sections based upon the functional 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 quotation marks. PRO/II User-Added Subroutine User Guide
2-5
Character entries are not case-sensitive. For example, “EX1UOP” and “Ex1uop” are equivalent. Do not use “tabs” to space entries. Instead, use one or more space characters to separate entries. Each of the following sub-sections discusses one section of the registration file. Edited examples of parts of the P2UasReg.ini file illustrate correct usage. The actual file shipped with PRO/II includes wider fields and additional comments not shown here.
Registering User-Added Utilities PRO/II currently supports three types of user-added utility subroutines: Interfacial Area, Mass Transfer, and Heat Transfer. When the PRO/II setup program installs user-added subroutines, it includes one example of each type of UAUTIL they are registered in different sections of the P2UasReg.ini file. Table 2-1 shows the relationships of the utility types to sections in the P2UasReg.ini file. Table 2-1: Utility Type Sections in the Registration File Utility type
Register In Section
Interfacial Area
[UAIFAREA]
Mass Transfer
[UAMASSTR]
Heat Transfer
[UAHEATTR]
As shown below, the registration file contains a separate section for each supported type of UAUTIL subroutine. It is important to register utility subroutines in the correct section so that PRO/II can locate and call them. ;[UAIAREA] UAS identifier ; -------------"IFAREAUas1" ; [UAMASSTR] ; UAS identifier ; -------------"MassTranUas1" ; [UAHEATTR] ; UAS identifier ; -------------"HeatTranUas1"
UOM PathNo DLL name UAS routine System ------ -------------- ----------- -----4 "ExUasF90.dll" "AreaMain" Proii UOM PathNo DLL name UAS routine System ------ -------------- ----------- -----4 "ExUasF90.dll" "MassMain" Proii UOM PathNo DLL name UAS routine System ------ -------------- ----------- -----4 "ExUasF90.dll" “HeatMain" Proii
where:
2-6 Modular UAS Build Procedures
February 2009
UAS Identifier Enter a text string that uniquely identifies the utility
subroutine. The identifier is a required entry, and must not duplicate any other identifier in the same section. It may contain up to 31 characters. The first character must be a letter, A through Z. The sample above assigns “IFAREAUas1” as the identifier of an interfacial area utility. The UAS Identifier is used by keyword input and PROVISION to select this utility. See “Using a User-Added Modular Utility in PRO/II” on page 2-14 for examples of keyword usage. PathNo This specifies the path to the directory where the DLL that
contains the subroutine is installed. Enter a path ID number from the [UASPATH] section of the registration file. See “Registering a Path to a User-Added DLL” on page 2-9 of this chapter to learn about adding path entries. DLL name The exact name of the dynamic link library that contains
the user-added utility subroutine. The access functions of the operating system are case sensitive, so it is important that the name of the DLL and this ID always exactly agree. The recommended convention is to enter the DLL name and the ID in all upper case characters. Each ID may contain up to 31 characters. UAS routineThe exact name of the interface subroutine that PRO/II
calls to access this utility. The interface routine must be in the DLL specified by the DLL NAME entry. Each ID may contain up to 31 characters. UOM systemEnter one of the key words from Table 2-2 to specify
the system of dimensional units used for data transfer. PRO/II delivers all input data in the specified dimensional units system. It also expects all results to return using the same system of dimensional units. No mixing of systems of units is allowed. Table 2-2: Systems of Dimensional Units for Data Transfer Keyword
System of Units
PROII
PRO/II internal units
ENGLISH
English units
METRIC
Metric system units
SI
System International
PRO/II User-Added Subroutine User Guide
2-7
Refer to Table 4-1 of the PRO/II Keyword Manual for a list of dimensional units used in each of these systems. Example: This example registers a Mass Transfer utility routine using the identifier MyMassTr1. Assume the name of the callable interface routine is MYMASS1, the DLL named MYUAS1.DLL is located in directory E:\MYDRIVE\MYCODE\, and that this path already is registered as path 5 in the [UASPATH] section of the registration file. Data transfer uses the SI system of units. [UASPATH] ; PathNo
The procedure for registering other utility subroutines is analogous to this example. Simply substitute the appropriate section of the registration file for the type of utility. Register an Interfacial Area utility in the [UAIFAREA] section instead of the [UAMASSTR] section. Register a heat transfer utility in the [UAHEATTR] section.
2-8 Modular UAS Build Procedures
February 2009
Registering a Path to a User-Added DLL A path allows PRO/II to access a user-added DLL anywhere on the computer network. The [UASPATH] section declares the location of all the directories that PRO/II uses to find user-added dynamic link libraries. PRO/II pre-defines several paths that developers may use to store their DLL’s, as shown. [UASPATH] ; PathNo Fully justified path (255 char max) ; ------ -----------------------------------1 "%p2Install%\USER\UAS\EXAMPLES\" 2 "%p2Install%\USER\" 3 "%p2InstallPath%\SYSTEM\" 4 "%p2Install%\USER\UAS\F90\VF6\Debug\"
where: PathNo A unique integer number that identifies the path. The PathNo
entries in other sections refer to this to register user-added utility routines. Numbering should be sequential, beginning with the first available (unused) path number. This is a required entry. Path text The fully justified path to a directory used to store DLL’s.
Always enclose the path text in quotation marks to allow embedded blanks. The path may contain as many as 255 characters, including embedded blanks. Note: The path does not include the name of the DLL file. It ter-
minates with the name of the directory that contains the DLL. Paths already registered during PRO/II installation should not be deleted or altered in any manner. “%p2Install%” is a parameter that expands to be the root directory
where PRO/II is installed. It is defined in the [P2Config] section 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 filename of the PRO/II configuration file is: C:\SIMSCI\PROII82\USER\PROII.INI
In this file, the parameter is defined as: P2Install=D:\SIMSCI\PROII82\
Changing the value of the P2Install parameter in the PROII.INI file dynamically changes the path of the%p2Install% expansion macro. PRO/II User-Added Subroutine User Guide
2-9
Use of this macro is optional. It could be replaced by the actual text of the installed path. The PathNo entries in other sections of the registration file refer to entries in the [UASPATH] section. The PathNo entries for user-added utilities (described earlier) refer to the paths in the [UASPATH] section. To locate DLL’s elsewhere, a new path must be added to the [UASPATH] section.
Note: Unit operations do not refer to the [UASPATH] section. Each of them has its own configuration (INI) file that includes the
path declaration. Example: A developer wishes to add directory path “E:\MyDrive\MyCode” to the registration file. Assuming the first four paths (shown above) already exist in the registration file, the new path is installed as path 5. [UASPATH] ; PathNo Fully justified path (255 char max) ; ------ -----------------------------------1 "%p2Install%\USER\UAS\EXAMPLES\" 2 "%p2Install%\USER\" 3 "%p2InstallPath%\SYSTEM\" 4 "%p2Install%\USER\UAS\F90\VF6\Debug\" 5 “E:\MYDRIVE\MYCODE\”
2-10 Modular UAS Build Procedures
February 2009
Registering [UAUOP] User-Added Unit Operations Register all modular user-added unit operations in the [UAUOP] section 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 duplicate 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 simulation: UAUOP( Ex1Uop )
UID= U1
This identifier (i.e., “Ex1Uop”) also appears in the list of available user-added unit operations in PROVISION‰. INI File Name This is the name of the initialization file that defines
the access and data content of the unit operation. Refer to the Chapter 5, Modular Unit Operations, for information about the INI file. While this entry is optional, omitting it eliminates many powerful features, including the ability to define the data structure, and the ability to relocate the DLL. Help File Name Optional, and not fully supported by PRO/II. For
now, always enter a tilde (~) for this entry.
PRO/II User-Added Subroutine User Guide
2-11
Help Content Declares the “home” help topic in the user-added help
file. This is not supported in PRO/II version. For now, always enter a tilde (~) for this entry. Example: When first installed, the [UAUOP] section contains only the Ex1Uop entry, as shown above. Assume a developer wishes to register a new user-added unit operation with an ID number of 123 and a UATYPE of ABC. Also assume it has an “INI” file named “ABC.INI”. After registering this unit operation, the [UAUOP] section would include the following information. ; ============================================================== ; Enter User-Added Unit Operations in the [UAUOP] section [UAUOP] ; IdNo UATYPE INI File Name Help File Name Help Context ; ------ ---------- ------------- -------------- -----------1 “Ex1Uop” Ex1Uop.ini ~ ~ 123 “ABC” ABC.INI ~ ~
Reserved Sections - [P2UOP] The [P2UOP] section is reserved for use by SIMSCI“. It typically includes the following entries, but is not discussed further. ====================================================== ; Invensys/SIMSCI User-Added Unit Ops. 3rd party ; developers should never alter the [P2UOP] section. [P2UOP] ; IdNo UATYPE INI File Help File Help Topic ;------ --------- ----------- --------- ---------10001 "FURNACE" FURNACE.INI ~ ~ 10002 "ACE" ACE.INI ~ ~ 10003 "PPUOP" PPUOP.INI ~ ~
Note: Users and third-party developers should never modify the
entries in this section.
2-12 Modular UAS Build Procedures
February 2009
Troubleshooting Registration Errors PRO/II fails when attempting to call a user-added utility subroutine not properly registered in the P2UasReg.ini file. In such cases, PRO/II generates an error message that reports the failure. The message reports the faulty path in the [UASPath] section. To fix the problem, the user could correct the faulty entries in the P2UasReg.ini file. The problem may be due to a faulty DLL path, DLL name, or subroutine name. Alternatively, the user could move the DLL or the subroutine name to match the P2UasReg.ini file. Always ensure the UAS is registered in the correction section of the registration file. For example, assume the sample UAS project (shipped with PRO/II) installs the DLL named EXUASF90.DLL in the path: C:\SIMSCI\PROII71\USER\UAS\UASF90\IVF\RELEASE\
Assume the path and DLL name in the P2UasReg.ini file are erroneous, 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 usersupplied UAS DLL from path C:\SIMSCI\PROII82\USER\UASF90\VF6\ RELEASE\EXUBASF90.DLL. Please ensure the entry is correct in the UAS registry (P2UasReg.ini).
The user should determine the actual location of the installed DLL on the hard drive. Comparing the actual location and name with the error message reveals the two errors (highlighted for emphasis). It is then a simple matter to correct the P2UasReg.ini file.
PRO/II User-Added Subroutine User Guide
2-13
Using a User-Added Modular Utility in PRO/II This discussion assumes a user-added DLL is built and the callable subroutines are properly registered in the PRO/II UAS registration file, P2UasReg.ini. Refer to topics earlier in this chapter. A detailed presentation of using the interfacial area utility is presented here. Discussion of the mass transfer and heat transfer utilities is minimal, since their usage is analogous to that of the interfacial area utility.
Using An Interfacial Area Utility – End Users This utility was first available in PRO/II version 7.1. It is used only by the RATEFRAC algorithm of the COLUMN model in PRO/II. Because PRO/II includes built-in correlations for computing interfacial area, 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. 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 compatibility with PRO/II. End users must install the user-added subroutine according to the directions supplied by the developer or supplier. SIMSCI cannot offer further guidance concerning subroutine 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 subroutine registered in the [UAIFAREA] section of the P2UasReg.ini file is available as the argument for the IASUB keyword.
Using the Sample Interfacial Area Utility As delivered, PRO/II includes a working sample of an interfacial area utility that demonstrates a working interfacial area utility. The 2-14 Modular UAS Build Procedures
February 2009
correlations included in the sample utility are not adequate for all column configurations supported by RATEFRAC. Note: The sample code shipped with PRO/II is part of sample
projects that must be built before executing. Refer to “Building A UAS DLL Using Visual Studio .NET 2003” in this chapter to learn how to build and use sample projects. A Fortran compiler and linker are required. The following input listing includes an RFTRANSFER statement that uses the sample code for computing interfacial area, binary mass transfer coefficients, and heat transfer. It is a complete input file, and should solve successfully.
TITLE PROJ=IFAreaUAS, PROB=SampleIFA1 DESC Demonstrate An Interfacial Area UAS Using RateFrac DIMENSION ENGLISH COMPONENT DATA LIBID 1,METHANOL / 2,WATER / 3,ETHANOL / & 4,PROPANOL / 5,BUTANOL / 6,NITROGEN THERMODYNAMIC DATA METHOD SYSTEM=WILSON, TRANSPORT=PURE STREAM DATA PROP STRM=FEED, PHASE=L, PRES=15, RATE(WT)=1000 & COMP(M)= 1,0.4/ 2,0.2/ 3,0.2/ 4,0.1/ 5,0.10/ 6,0.0 PROP STRM=GAS, TEMP=200, PRES=20, RATE(WT)=1000 & COMP(M) = 6,1.0 UNIT OPERATIONS COLUMN UID=T1, NAME=10 TRAY ABS PARAM TRAY=10, RATEFRAC=15 FEED FEED,1 / GAS,10 TRATE SECTION(1)=1,4, CAP, DIAMETER(FT)=4, WEIR=2 TRATE SECTION(2)=5,7, CAP, DIAMETER(FT)=4, WEIR=2 TRATE SECTION(3)=8,10, CAP, DIAMETER(FT)=4, WEIR=2 PRODUCT OVHD(WT)=OVHD, 1000, BTMS(WT)=BTMS, 1000 TEMP 1, 175 / 10,200 PRES 1, 15.0 / 10,16.0 $ Comment the next 3 lines to use internal correlations RFTRANSFER
Notice in the input listing that the column includes three TRATE sections. The RFTRANSFER statement applies the user-added subroutines only to TRATE section 2. Additional RFTRANSFER statements may be added for each section in the column. PRO/II User-Added Subroutine User Guide
2-15
Also in the input listing above, the sample interfacial area subroutine supplied by SIMSCI has the identifier IFAREAUas1. This can be changed to any other desired identifier that is registered (“Registering User-Added Utilities” on page 2-6. Edit the ID entry in P2UasReg.ini (only the ID entry). Change the RFTRANSFER IASUB=iaSubID entry in the input file so that iaSubID matches the new identifier. As long as the DLL path, DLL name, and subroutine entries remain unchanged, the sample will run successfully. The problem could be modified to use the built-in correlations in PRO/II by deleting or commenting the three lines of code for the RFTRANSFER statement. Comparing the results of the problem with and without using the user-added subroutines should demonstrate the two solutions agree to three or four significant digits.
Using A Mass Transfer Utility Use of this utility is analogous to the usage of the interfacial area utility. Because PRO/II includes built-in correlations for computing the binary mass transfer coefficients, use of this user-added feature is always optional. Refer to Chapter 12.10 of the PRO/II Keyword Input Manual for information about the RATEFRAC algorithm and the RFTRANSFER statement.
Using A Heat Transfer Utility Use of this utility is analogous to the usage of the interfacial area utility. Because PRO/II includes built-in correlations for computing the heat transfer, use of this user-added feature always is optional. Refer to Chapter 12.10 of the PRO/II Keyword Input Manual for information about the RATEFRAC algorithm and the RFTRANSFER statement.
2-16 Modular UAS Build Procedures
February 2009
Developer Information This section presents useful information to developers writing their own modular user-added subroutines. The requirements and available resources for a utility calculation routine are different from those of a unit operation. Separate outlines are presented for each of them.
Contexts in PRO/II PRO/II performs a variety of operations to successfully complete a simulation. Related types of operations are grouped together in contexts. When PRO/II calls a user-added subroutine, it expects each UAUTIL or UAUOP to perform actions appropriate to the current context, as illustrated in Table 2-3. Yes indicates that PRO/II makes a call to a UAUTIL or UAUOP. No indicates that PRO/II does not attempt to call the UAUTIL or UAUOP in that context. Table 2-3: Contexts in PRO/II Context
UAUTIL
Description
Need
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
INPUT
No
UAUOP
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 characters only. Note that Fortran 90 uses a percent sign ( % ) as the “member selection” operator. PRO/II User-Added Subroutine User Guide
2-17
As shown in Table 2-3, PRO/II calls a UAUTIL only during the CALCULATE context. In other words, the user-added utility code must perform calculations on request. In contrast, PRO/II expects a useradded unit operation to support all contexts except INPUT. Note that the only code requirement is to return a valid ISOLVE flag to PRO/II, even for the CALCULATE context. For example, returning ISOLVE = 0 informs PRO/II that the UAS did not perform any actions. In such cases, PRO/II executes alternative code, or issues error messages, as appropriate.
ISOLVE Return Values Whenever PRO/II calls a UAUTIL or UAUOP, it requires the called routine to perform specific actions and to return specific data. This is true regardless of the context in which PRO/II makes the call. PRO/II does not always require return values from a utility routine in every context. However, it always requires a valid return value for ISOLVE. For example, a utility routine normally returns all results in the array DataObj%RESULTS. However, these may be omitted if the utility returns ISOLVE=0 or 3. Table 2-4 explains the valid return values 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. Typically, a return value of DATAOBJ%ISOLVE = 2 indicates a convergence problem. The UAS completes calculations and returns results, but the results may not be converged within tolerance. For example, 2-18 Modular UAS Build Procedures
February 2009
this frequently occurs in early iterations of recycle problems that require several cycles to build up flow rates to meet the overall convergence 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 continue 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.
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, MassMain.f90, or HeatMain.f90) as a template for the interface routine. Use class_ UASOBJ as the only argument in the call list.
3.
Code the calculation algorithm in Fortran 90. Access available PRO/II data from the class_UASOBJ storage object. Perform calculations. Store the required results in the RESULTS array of the class_UASOBJ storage object. Set the ISOLVE flag in the class_UASOBJ storage object.
4.
Compile and Link the DLL.
PRO/II User-Added Subroutine User Guide
2-19
5.
Register the subroutine and DLL in the PRO/II P2UasReg.ini file. Remember that each type of UAUTIL must be registered in the appropriate section of the registry file.
The UAS now should be ready for use by PRO/II.
Resources for Modular Utility Calculation Routines Each type of user-added utility may require the use of a different set of PRO/II interfaces. Any departures from the requirements listed here are presented in later chapters that discuss specific types of user-added utility routines. Generally, the various calculation utilities 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 subroutine (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 “Output Report” subroutine, a GUI routine for input processing,
2-20 Modular UAS Build Procedures
February 2009
a “Cross Check” routine for input data verification, and an “Output Review” GUI window. 4.
Compile and Link the DLL.
5.
Add the DLL and subroutine access data to the “[Access Data]” section of the “.INI” file.
6.
Register the “.INI” in the “[UAUOP]” section of the PRO/II registry file.
The UAUOP now should be ready for use by PRO/II.
Resources for Modular User-Added Unit Operations class_UaUop.mod This Fortran 90 module contains the explicit interface for the unit operation data storage object. The majority of available PRO/II data is passed to the unit operation 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 represent the user-added unit operation. The developer of a useradded 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 developer of a user-added unit operation also creates this file.
PRO/II User-Added Subroutine User Guide
2-21
Resources for All Modular User-Added Subroutines class_Fluid.mod A Fortran 90 module that contains the explicit
interface for the user-accessible analog of a PRO/II stream. This is used by class_UASOBJ.mod to store data for a single stream. Access to data in this module normally is through members of class_UASOBJ. Class_FluidPhase.mod A Fortran 90 module that contains the
explicit interface for a single phase of a stream. This is used by class_Fluid.mod. Access to data in this module normally is through members of class_UASOBJ. The modules listed above are required by the compiler when the user compiles the source code for the UAS. These are provided to you by PRO/II. The path to them must be included in the UAS project. UserLb6.LIB This is the “export library” for UserLb6.DLL, the
Dynamic Link Library (DLL) containing code for the modules 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 available in the .\User\LIBS\ directory.
2-22 Modular UAS Build Procedures
February 2009
Compiler and Linker Project Settings Projects that build user-added subroutines use resources installed with PRO/II. The necessary Fortran modules and libraries must be installed using the PRO/II installation (or Setup) program on the PRO/II installation disk. Selecting the User-Added Subroutines option will copy all the necessary files to directories in the PRO/II directory tree. The settings for the compiler and linker must include paths to the directories that include these SIMSCI resource files. All the necessary 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 discusses those settings.
Setting the Module Path for the Fortran Compiler Fortran modules are templates that define the data structures and interface routines available to modular user-added subroutines. The include option specifies a directory to add to the path that is searched for module files referenced in USE statements, in addition to files referenced using INCLUDE statements. For all USE statements, the directories searched are as follows, in this order: 1.
The directory containing the first source file (assuming default settings).
2.
The current default directory where the compilation is taking place.
3.
If specified, the directories listed in the INCLUDE option. The order of searching multiple directories occurs within the specified list from left to right.
4.
Directories indicated by the INCLUDE environment variable.
Follow these steps to set the module path in MicroSoft Visual Studio. Refer to Figure 2-4 In the Solution Explorer, right click the project and select Properties from the action menu; then open the Fortran tab.
PRO/II User-Added Subroutine User Guide
2-23
Figure 2-4: Setting the Fortran USE Module Path
Click the down arrow of the Category: list box and highlight PreProcessor in the list. Enter the following text in the Additional Include Directories text box: C:\SIMSCI\PROII82\USER\CMNS
This is the absolute path from the project directory where the modules are installed. Click OK to confirm the setting. When the project is in the default PRO/II install directory path, a relative path may be used. Refer to Figure 2-4, “Setting the Fortran USE Module Path”, on page 2-24.
Setting the Import Library Path for the Linker 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
USERLB6.LIB
In the Solution Explorer, right click the project and select Properties from the action menu; then open the Linker tab. In the General tab, enter the following text in the Additional Library Directories text box: 2-24 Modular UAS Build Procedures
February 2009
C:\SIMSCI\PROII82\USER\LIBS\ This is the absolute path from the project directory where the modules are installed... When the project is in the default PRO/II install directory path, a relative path may be used. Refer to Figure 2-5, “Setting the Linker Libraries Path”, on page 2-25.
Click OK to confirm the setting Figure 2-5: Setting the Linker Libraries Path
Refer to the On-Line Help in Visual Studio and the Intel Visual Fortran compiler for more information about using the build tools effectively.
PRO/II User-Added Subroutine User Guide
2-25
2-26 Modular UAS Build Procedures
February 2009
Chapter 3 Modular Interface Software Overview This chapter discusses the interfaces available for communicating between PRO/II and modular user-added subroutines. Table 3-1 shows how the data is organized in this manual. Table 3-1: Interface Modules and Routines in UserLb6.lib Name
Description
See page...
Output and Reporting Routines HEAD
Heads and numbers an output page
15-7
UAOUT
Write a single line of text to the Report file, 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.
class_FluidPhase Data transfer and member functions to manipulate data in each phase of a fluid.
6-25 6-34
Dimensional Units Module class_DMUOM
PRO/II
Class containing member functions that access dimensional units conversion factors.
User-Added Subroutine User Guide
Chapter 7
3-1
PRO/II communicates with user-added subroutines through: Data classes defined in Fortran modules. Call-back routines provided in the PRO/II program. Subroutine argument lists, including modular storage objects.
Modular Interface Data Classes PRO/II organizes the data that it passes to user-added subroutines into groups called classes. A separate Fortran module implements each class. The classes often have a hierarchical structure, where one class may include one or more other classes. For example, a UAUOP includes the Fluid class. The available base classes are described in chapters 4 through 7.
Modular Call-back Routines Modular call-back routines allow modular user-added subroutines to call PRO/II to retrieve and store data, or to perform calculations on demand. Several call-back functions and subroutines are general purpose and not members of the data classes. These routines are described in this chapter. Other call-back routines are “member functions” of the data classes. Table 3-1, ”Interface Modules and Routines in UserLb6.lib”, provides cross-references to the chapters that describe the data classes and all their member functions.
Subroutine Argument Lists When PRO/II calls a UAUOP or a UAUTIL, it passes data and execution control to them. Arguments in the call list include a data object and execution control flags. The data object is specific to the type of modular UAS being called. Control variables include a CONTEXT flag and a solution flag, ISOLVE. The CONTEXT flag tells the UAS what PRO/II expects. ISOLVE informs PRO/II whether or not the UAS succeeded.
3-2 Modular Interface Software
February 2009
Contexts in PRO/II During any simulation, PRO/II performs a variety of operations to orchestrate the successful execution of the flowsheet. During these operations, PRO/II may or may not call a UAUTIL or UAUOP to perform its own processing. PRO/II defines several execution contexts, 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
CROSSCHECK
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 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; i.e., IF( DataObj%Context(1:10) .EQ. “CROSSCHECK” ) THEN
When performing tests on text strings, always use upper case characters only. Note that Fortran 90 uses a percent sign ( % ) as the member access operator.
PRO/II
User-Added Subroutine User Guide
3-3
ISOLVE Return Values Whenever PRO/II calls a UAUTIL or UAUOP, it expects the called routine to perform specific actions based on the call context. PRO/II does not require calculation results to return from a user-added subroutine 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. Typically, 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 convergence 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 continue the (iterative) calculations. If the ISOLVE = 2 error occurs on the last pass through the UAS, it causes PRO/II to report, “Solution not reached.” The ISOLVE = 3 error always is fatal. UAS developers should return this code when the UAS encounters a problem that prevents it from 3-4 Modular Interface Software
February 2009
performing its calculations. Typically, these situations occur when data is missing or invalid. When PRO/II receives this return code, it immediately terminates all flowsheet calculations, and results in “solution not reached”. Later chapters that discuss each specific utility or unit operation may expand these definitions.
Call-back Routines In addition to the data modules used to communicate with useradded subroutines, PRO/II provides additional subroutines and functions that may be useful to developers. Call-back routines are used inside user-added subroutines to request data or calculations from PRO/II. This section describes those routines.
Output and Reporting UAOUT Purpose: Write a single line of text to selected PRO/II output files. Calling sequence: SUBROUTINE UAOUT( cFile, cAct, cText )
where: cFile
This option flag selects the files that receive the output data. It is a character string that may have one of the following values. Normal Displays the output on the user display terminal, and writes the data in the PRO/II history file. Terminal Displays data on the user display terminal only. History
Writes the output to the PRO/II history file only.
Report
Writes the output in the PRO/II output report file.
The value of cFile may be truncated to only the first character of the values listed above (N, T, H, or R). cAct
An option flag that controls line spacing when writing the output. The character string may have one of the following values. Single Single space; simply write the line of output. Double Double space; write a blank line, then write the output. Page
Start a new page, then write the output.
This option is active only when writing to the Report file. The value of cAct may be truncated to only the first character of the values listed above (S, D, or P). PRO/II
User-Added Subroutine User Guide
3-5
cText
A character string or variable containing the actual text to output.
The cFile option should be set to “Report” only when the useradded Context also is “Report”. Note that the output report file normally constrains each line of output to no more than 78 characters. 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, “General 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 disregard the cAct flag. They also discard all lines of output that are completely blank. At the end of execution, PRO/II merges the history file into the report file to save the calculation history. Any data written to a display terminal is lost after being displayed. UAOUT does not write output to any other files. The following sample code illustrates the proper use of UAOUT. CHARACTER :: cLine*78 605 FORMAT( " ", A, 1P, 3E13.4 ) . . . WRITE(cLine, * ) & " _________ Test Results from UAS MassReport _________" CALL UAOUT( "REPORT", "DOUBLE", cLine ) WRITE(cLine, * ) & " ___________________ Column Data ___________________" CALL UAOUT( "REPORT", "DOUBLE", cLine ) WRITE(cLine,605) " Cross-sectional area = ", MTobj%DS1( 1 ) CALL UAOUT( "REPORT", "SINGLE", cLine ) WRITE(cLine,605) " Weir Height = ", MTobj%DS1( 2 ) CALL UAOUT( "REPORT", "SINGLE", cLine ) WRITE(cLine,605) " Downcomer area = ", MTobj%DS1( 3 ) CALL UAOUT( "REPORT", "SINGLE", cLine )
The ExUasF90 and ExUOP sample projects that ship with PRO/II include output report subroutines that make extensive use of UAOUT. Refer to the source code for subroutines in files HEATREPO.f90, MASSREPO.f90 and AREAREPO.f90 of that project.
3-6 Modular Interface Software
February 2009
UAWRITE This routine writes a single record of pre-formatted text to any Logical 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 variable, populating it with text and numerical values, obtaining a file unit in variable LFU using FIGETU, and calling UAWRITE. INTEGER(4) :: LFU, Ival REAL(8) :: Rval CHARACTER(LEN=133) :: cLine . . . CALL FIGETU( 1, LFU ) Rval = 23.4 Ival = 3 cLIne = “The value of RVAL( ) is:” WRITE( cline(19,21), “( I3 )” ) Ival WRITE( cLine(29:39), “(F9.4)” ) Rval CALL UAWRITE( LFU, TRIM(cLine) )
The single line of output would be: The value of RVAL(
3) is :
23.4000
Note: Modular unit operations (UAUOP) include variable LFUout for writing to the standard PRO/II output file. Assuming the UaUop data object is named UopObj in the user-written unit operation, the following example writes cLine to the PRO/II standard output file: CALL UAWRITE( UopObj%LFUout, TRIM( cLine ) )
PRO/II
User-Added Subroutine User Guide
3-7
UAERROR Purpose: Register an error, warning, or message in the PRO/II error subsystem. Also write a user-defined message to a standard output file. Calling sequence: UAERROR( cELevel, IUNO, MESSAGE )
Where: cELevel
Required input single character that acts as an option for the error level to record. Allowed values include: “E”
Severe error, calculations failed. The message may describe the error.
“W” Warning, calculations hampered, results may be suspect. The message describes the situation. “M” Message, no error, calculations succeeded. This is merely information for the user. IUNO
Required scalar input. The internal order number of a unit operation. This may be a UAUOP that calls UAERROR; or a unit operations that calls a user-added utility that calls UAERROR. A value of zero omits IUNO from the message.
MESSAGE
Required character input. This is the text of the error message to display or print. It may contain up to 200 characters of text.
The error level specified by cELevel indicates the severity of the reported problem. In most cases, a user-added subroutine is either a unit operation or a utility called from a unit operation. In either case, the error behaves as if it were generated by a unit operation. An Error terminates flowsheet calculations when registered outside a flowsheet recycle loop. When registered inside a recycle loop, an Error fails the current loop iteration but may allow additional iterations of the loop. A Warning does not halt calculations, but informs users that a problem 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 calculations in PRO/II. For example, assume a user-added subroutine 3-8 Modular Interface Software
February 2009
allows the user to enter a calculation option but the user neglects to supply it. A Message may be appropriate to inform users that a “default” method is being used. If no default is allowed, then a Warning or an Error may be more appropriate. Since messages are processed by the error processing subsystem, normal progress messages 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 useradded 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 literal 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 argument (IUNO). The text of the message is wrapped when it is too long to fit on a single line. Also, whenever two or more contiguous blanks appear in the text, they are compressed to a single space.
PRO/II
User-Added Subroutine User Guide
3-9
class_UASOBJ.mod This is the base class used to create modular Utility subroutines. It contains a data structure and accessor functions to access the data. The data structure is populated and passed from PRO/II in the argument list in each call to a modular user-added utility. See Chapter 4, Modular Utility Subroutines for detailed information about using this module and its members.
class_UAUOP.mod This is the base class used to create modular Unit Operations. It contains a data structure and accessor functions to access the data. The data structure is populated and passed from PRO/II in the argument list in each call to a modular user-added unit operation. See Chapter 5, Modular Unit Operations for extensive information about using this module and its members.
class_Fluid.mod This module makes Fluid data objects available to within modular user-added subroutines. Modular Utilities such as IFAREA include fluids within their data structures. Modular unit operations only identify their feed and product streams and do not provide pre-built fluids. Member methods of class_Fluid.mod, such as load_fluid, provide developers the necessary tool to instantiate, manipulate, and destroy fluid object at will. See Chapter 6, UAS Modular Fluids for comprehensive information about using this module and its members.
class_DMUOM.mod This module defines a class that provides dimensional units to modular user-added subroutines. Currently it provides a single user-callable function, GetFactor_DmUom, that returns factors to convert between user-units and PRO/II internal units. Chapter 7, User-Added Units of Measure, defines the module, its member functions, and data structure. See Chapter 6, UAS Modular Fluids for information and examples that use this module and its members.
3-10 Modular Interface Software
February 2009
Chapter 4 Modular Utility Subroutines Overview User-added utilities perform specific calculations and return specific, pre-defined results when called from PRO/II. They serve as alternatives to existing PRO/II methods. The first section in this chapter present user information that describes using modular utilities in PRO/II simulations. The remainder of the chapter presents developer information that includes coding requirements, a full description of class_UASOBJ, and an extensive example of an implementation.
User Information The RATEFRAC column model in PRO/II is the only unit operation that supports modular utilities. The following are the only supported modular utilities. Interfacial Area methods. RATEFRAC allows a different subroutine or method on each tray or in each packed section. Binary Mass Transfer Coefficient methods. RATEFRAC allows a different subroutine or method on each tray or in each packed section. Heat Transfer Coefficient methods. RATEFRAC allows a different subroutine or method on each tray or in each packed section.
Keyword Summary RFTRANSFERSECTION = idno, MTCORR = DEFAULT, or MTSUBROUTINE = user-added subroutine-name, HTCORR = CHILTON, or HTSUBROUTINE = user-added subroutine-name, IACORR=DEFAULT or ONDA or BRAVO or SCHEFFE, or IASUBROUTINE = user-added subroutine-name
Use the MTSUB, HTSUB, and IASUB entries to use user-added utility routines. Refer to Chapter 12.10 of the PRO/II Keyword Manual for more information. PRO/II User-Added Subroutine User Guide
4-1
Utility Input Data Requirements Utility routines currently do not accept input data values.
Utility Output Reports PRO/II does not call user-added utility routines to report results. Because utility calculations are an intrinsic part of unit operations, the effects of the utility calculations are implicit in the solved results of the unit operations. However, developers may add code to write intermediate results when their utilities are called. Interface routine UAOUT may be used by them for this purpose.
Utility Installation and Registration It is the user’s responsibility to install and register the user-added utilities before attempting to use them from PRO/II. Users must obtain specific installation instructions from the developer of each utility subroutine; not from SIMSCI. See “Registering User-Added Utilities” on page 2-6 of Chapter 2 in this manual to learn about registering modular utilities. See “Using a User-Added Modular Utility in PRO/II” on page 2-14 of Chapter 2 for an example of using these utilities in PRO/II simulations.
Developer Information The remainder of this chapter is intended for developers of useradded utilities. Users who merely use pre-built modular utilities in PRO/II simulations may find some of the material interesting.
Data Exchange Between PRO/II and Utility Routines Each sub-class of user-added utility routine performs a specific type of calculation. For each utility type, PRO/II passes in a limited, predefined 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 subroutines; Chapter 12, ”Binary Mass Transfer Utility” for mass transfer subroutines, and Chapter 13, ”Heat Transfer Utility” for heat transfer subroutines.
Coding Guidelines Each user-added calculation utility requires an interface routine written in Fortran 90. This is because PRO/II passes a reference to a data class in the argument list when it calls the user-added subroutine. 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 support 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 coding” 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 computations. 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 simplest and most intuitive approach probably would be to code a separate 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 functionality. The sample code in Figure 4-1 illustrates the basics of this approach.
PRO/II User-Added Subroutine User Guide
4-3
Contexts in Utility Subroutines PRO/II uses several execution contexts that perform a variety of operations to solve a simulation. "Contexts in PRO/II" on page 3-3 defines them. As shown in Table 4-1, PRO/II calls a UAUTIL only in the CALCULATE context. Table 4-1: Contexts in PRO/II Context
UAUTIL
Description
INPUT
No
Input simulation data
CROSS
No
Validate input data
CALC
Yes
Perform calculations
OPCALC
No
Post-flowsheet calculations
REPORT
No
Write final results
PRO/II expects the user-added utility to perform calculations on request. Support for all other contexts is not currently implemented for user-added utilities.
ISOLVE Return Values PRO/II requires each user-added utility to return the ISOLVE flag each time it is called. See "ISOLVE Return Values" on page 3-4. The “expected” return code is DATAOBJ%ISOLVE = 1. Values of 2 or 3 always indicate an error condition. When a UAS does not support a context, it should return DATAOBJ%ISOLVE = 0 to indicate “no action taken”.
Results Return Values PRO/II expects each user-added utility routine to return a complete set of valid results when the subroutine returns control to PRO/II. The Results member of the UASOBJ data structure is the mechanism that performs this function. Different types of user-added utilities return completely different sets of results. For example, an interfacial area utility returns a single value representing the (specific) interfacial area of a stage. For a packed stage, this is dimensionless (actually, interfacial area per unit area of packing). For a stage with trays, the dimensional units are inverse length (actually, interfacial area per unit of tray volume). In both cases, 4-4 Modular Utility Subroutines
February 2009
this single value returns in the first element of the results array, Results(1,1). In contrast, a mass transfer coefficient utility returns a set of binary mass transfer coefficients that includes a value for each binary pair of components in a simulation. This requires a two dimensional array. For NOC components, the number of results is NOC*NOC, and the results array has two dimensions, each of NOC elements. The declaration for the size is Results(NOC,NOC). Each value has units of mole-rate (wt-moles/time). For a simulation containing five components, the mass transfer coefficient routine has a results array dimensioned Results(5,5), and PRO/II expects the subroutine to return all 25 values.
Dimensional Units Each user-added utility subroutine exchanges data with PRO/II in a consistent set of dimensional units. The subroutine developer chooses one of several sets provided by PRO/II. The developer must inform the end-user of the correct set of units. The end-user must declare the developer’s set of units when registering the subroutine 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 system of units for a utility routine.
PRO/II User-Added Subroutine User Guide
4-5
Coding A Utility Interface Routine Each user-added utility requires a standard interface routine so PRO/II can call it. The interface routine must conform exactly to the requirements presented here. Using a separate interface routine removes the PRO/II constraints from the calculation routine. Figure 4-1 illustrates the essentials of a basic interface subroutine. Figure 4-1: Sample Interface Routine Called by PRO/II 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
SUBROUTINE UASMAIN( DataObj ) !DEC$ ATTRIBUTES DLLEXPORT:: UASMAIN ! Export UASMain !___________________________________________________________ ! | ! Variables in Argument list | ! Name Type I/O Brief Description | ! -------- ------ --- ------------------------------------- | ! DataObj UasObj I/O UAS Data object (all input/output data| !___________________________________________________________| ! USE class_UASOBJ ! Interface DataObj as a UASOBJ class ! IMPLICIT NONE ! Require explicit variable declarations ! TYPE(UASOBJ), INTENT(INOUT) :: DataObj ! Instantiate Obj ! CHARACTER :: context*12 ! local character variable ! ! --------------------- Code Begins here -------------------! context = TRIM( UASOBJ%Context ) Evaluate Context flag ! IF( context(1:4) .EQ. "CALC" ) THEN CALL UasCalc( DataObj ) ! Perform calculations ELSE IF( context(1:6) .EQ. "REPORT" ) THEN CALL UasReport( DataObj ) ! Generate report ELSE ! Handle unsupported contexts UasObj%ISOLVE = 0 ! Set ISOLVE to “Never Solved” ENDIF END SUBROUTINE UASMAIN
Notes about Figure 4-1: Line 1 illustrates the interface that PRO/II calls. It includes a single argument in the dummy argument list – DataObj. Line 2 is the Compaq Visual Fortran compiler directive that exports UASMAIN from the DLL and exposes it to PRO/II, or other external applications that may call it. The routine that PRO/II calls always 4-6 Modular Utility Subroutines
February 2009
must be exported from the DLL; otherwise, PRO/II cannot find it. It is not necessary to export routines (such as the calculation routine) that are not called from outside the DLL. Lines 3 through 10, and 18 through 20, are simply documentation comments (a good coding practice). Line 11 is the Fortran 90 command that invokes the explicit interface 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 members in DataObj. Lines 23 through 29 constitute an IF-THEN-ELSE construct that handles all functionality that the UAS supports. Different subroutines are called depending upon the value of variable context. Line 23 compares the first four characters of variable context to the literal string “CALC”, a pre-defined context string set up by PRO/II. If this test evaluates to TRUE, the subroutine containing the calculation algorithm is called at line 24. If it evaluates to FALSE, control passes to line 25. Line 25 tests the first six characters of variable context against literal string “REPORT” (always all upper-case). A test that evaluates to TRUE calls routine UasReport at line 26. This illustrates the modular separation of functionality, wherein the calculation algorithm is coded in one subroutine, while the code to generate a report is coded in different subroutine. If the test at line 25 evaluates FALSE, control passes to lines 27 and 28. PRO/II User-Added Subroutine User Guide
4-7
Line 27 is the default clause of the “IF” construct. If none of the preceding clauses evaluate TRUE, control passes to here. In this example, this handles all other contexts not supported by the UAS. Line 28 sets the ISOLVE flag directly in the DataObj data structure. Since this value needs to be returned through DataObj, there is no advantage to creating a local variable for it. Finally, line 30 ends the subroutine. When control reaches this line, the subroutine exits and returns to PRO/II. Note the omission of a Fortran 77 RETURN statement. It is not required by Fortran 90. This basic subroutine is suitable for use in any UAS that requires a single call-list argument of TYPE(UASOBJ). The sample code of Figure 4-1 supports only two contexts: CALCULATE and REPORT. All others return ISOLVE = 0, indicating “no action taken”. Developers should expand the IF-THEN-ELSE construct to handle other PRO/II contexts that the UAS supports.
4-8 Modular Utility Subroutines
February 2009
Coding A Utility Calculation Routine Typically, the calculation code should appear in a routine separate from the utility interface routine. In this approach, PRO/II only calls the interface routine, and the interface routine is the only routine that calls the calculation routine. This provides the most flexibility for writing the code and modularizing the functionality. There are two approaches for coding the call from the interface to the calculation 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 structure. This simplifies the call between the interface and calculation routines. It also allows the calculation routine to work directly with the input data and results in a straightforward manner. However, this requires the calculation routine to depend upon the availability of the class_ UASOBJ class. Using this approach, the calculation routine could be used only when called by PRO/II, and would not be portable for use in other applications. Either approach is equally valid; the choice of implementation is left to the developer. Refer to the topic “Accessing Data of class_UASOBJ” later in this chapter to learn how to implement and use class_UASOBJ in a user-added subroutine.
PRO/II User-Added Subroutine User Guide
4-9
Definition of class_ UASOBJ.mod This module makes class_ UASOBJ available to user-added subroutines. The class includes a data structure and member methods. For user-added utility subroutines, a UASOBJ instance is the only argument in the call list of the subroutine. PRO/II does not support using UASOBJ with user-added unit operations. This section describes the proper usage of class_UASOBJ mod. It also describes all the data in the UASOBJ base class. Remember that only a sub-set of the data described here is available to any specific type of user-added subroutine.
Usage of class_ UASOBJ PRO/II passes the data object of this class to each user-added utility subroutine that it calls. To use the data structure, the user-added subroutine code must perform several operations. Include the UASOBJ instance as the only item in the subroutine argument list. This allows data in the data object to pass between PRO/II and the user-added subroutine. USE the class_UASOBJ module. This brings in the definition of the data structure, and makes the accessor functions of the class available to the subroutine.
Declare the UASOBJ argument variable as a UASOBJ instance. This makes the local instance of UASOBJ accessible by within the subroutine. The following code sample illustrates these three operations. SUBROUTINE MASSMAIN( MTobj ) USE class_UASOBJ TYPE(UASOBJ), INTENT(INOUT) :: MtObj
Notes: 1. 2.
MTobj is the mass transfer class. It is a sub-type of the UASOBJ
class.
The statement USE class_UASOBJ brings the module class_UASOBJ into the user-added subroutine. This defines the class used in the following TYPE statement. This allows access to member methods in the module.
3.
The TYPE statement applies the definition of the UASOBJ class to MtObj. This allows access to the data and methods in MtObj.
4-10 Modular Utility Subroutines
February 2009
All data items in the UASOBJ data structure are “members” of that data structure. There are two methods available to access the members: Direct member addressing Indirect accessor routines The following sections discuss both data access methods.
Direct Member Addressing in class_UASOBJ Direct member addressing accesses data by direct reference to the data member. Fortran 90 defines the percent symbol % as the access operator. Consider the following data structure as an analog of UASOBJ: TYPE CHARGE INTEGER :: PARTS(40) REAL(8) :: LABOR REAL(8) :: MILEAGE END TYPE CHARGE
Now assume a subroutine includes the following declaration: TYPE(CHARGE) MONTH
This declares MONTH as a CHARGE structure. Some valid array references for this type follows: MONTH%PARTS(I) MONTH%PARTS(I:K) MONTH%LABOR
! An integer array element ! An integer array section ! 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 components 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
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 members that might be available in the UASOBJ data structure. The first column, labeled “Member”, is the name of the data member to use for direct member addressing.
Indirect Accessor Routines in class_UASOBJ This is a more traditional access method, quite similar to Fortran 77. In addition to defining the UASOBJ data structure, class_UASOBJ.mod also provides accessor functions to retrieve data from UASOBJ. No functions to store data in UASOBJ are provided. Note: The accessor routines discussed in this section are available only when using class_UASOBJ.mod in a subroutine.
Many (but not all) data members of UASOBJ have keywords assigned to them to enable indirect access. Table 4-2 lists these keywords in the last column, labeled “Keyword”. The accessor functions are described below.
4-12 Modular Utility Subroutines
February 2009
GETUASVAL This function retrieves data from the UASOBJ storage object. It is an alternative to using direct accessing of data members. It supports several different types of argument variables, depending upon the type of data being retrieved. Named Integer Scalar Data Calling sequence: FUNCTION GETUASVAL( kwIn, ObjIn, Ivalue ) RESULT(iErr)
&
This form of the function retrieves a scalar integer member of array IS1. kwIn
A keyword for an element of the IS1 array. These 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 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 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 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), access keyword PARRANGE.
Tray type stored in IS1(6) with access keyword TTYPE. With this information, the following code is valid: PRO/II User-Added Subroutine User Guide
4-13
SUBROUTINE ABC( IfObj ) USE class_UASOBJ TYPE( UASOBJ ) :: IfObj INTEGER(4) :: ierr, StageType INTEGER(4) :: PackType, PackArr INTEGER(4) :: TrayType ! ierr = GETUASVAL("COLTYPE", IfObj, StageType) ! ! For a stage with packing IF( StageType .EQ. 1 ) THEN ierr = GETUASVAL("PTYPE", IfObj, PackType) ierr = GETUASVAL("PARRANGE", IfObj, PackArr ) ! For a stage with trays ELSE IF( StageType .EQ. 2 ) THEN ierr = GETUASVAL("TTYPE", IfObj, TrayType ) ENDIF
The values mapped to these flags for an interfacial area object are listed in Table 11-1 on page 11-2. For example, Table 11-1 explains that StageType represents the value of IfObj%IS1(1), a flag for the column type, where StageType = 1 indicates a packed stage and StageType = 2 indicates the stage has trays. The error code returns in variable ierr. A negative value indicates an error. Integer Array Elements Calling sequence: FUNCTION GETUASVAL(kwIn, Obj, IValue, ix1, ix2) & RESULT(iErr)
This form of the function retrieves a scalar value from any integer array available in the UASOBJ data object. The only integer array currently supported is IS1. Use of this form is discouraged for data retrieval from array IS1. kwIn
A keyword for an integer array. Currently, this is always “IS1”.
ObjIn
The name of the data object declared as TYPE(UASOBJ). The data to retrieve must be a member of this data structure.
Ivalue
The returned scalar integer value.
ix1
The first dimension element (column) of the item in the array referenced by kwIn.
ix2
The second dimension element (row) of the item in the array referenced by kwIn. Currently, this always is 1.
4-14 Modular Utility Subroutines
February 2009
Ierr
An error code returned as the value of the function. A value of 0 indicates successful retrieval (no errors). Any negative value indicates an error.
Example: In an interfacial area calculation subroutine, determine whether the current stage has packing or trays. If packed, retrieve the packing type and packing arrangement. If the stage has trays, retrieve the tray type. This is the same example as above, but now uses this alternative form of the GETUASVAL accessor routine. Use Table 11-1 (for an interfacial area subroutine) to find: Stage Type stored in IS1(1) with access keyword COLTYPE. Packing type stored in IS1(2) with access keyword PTYPE. Packing arrangement stored in IS1(3), using access keyword PARRANGE.
Tray type stored in IS1(6) with access keyword TTYPE. Array IS1 is a single-dimension array, so the second dimension, ix2 (the row) must always be 1. With this information, the following code is valid: SUBROUTINE ABC( IfObj ) USE class_UASOBJ TYPE( UASOBJ ) :: IfObj INTEGER(4) :: ierr, StageType, ix1, ix2 INTEGER(4) :: TrayType, PackType, PackArr ! ix2 = 1 ! always = 1 to access array IS1 ix1 = 1 ! offset to "COLTYPE" ierr = GETUASVAL("IS1", IfObj, StageType, & ix1, ix2 ) ! For a stage with packing IF( StageType .EQ. 1 ) THEN ix1 = 2 ! offset to packing type ierr = GETUASVAL("IS1", IfObj, PackType, & ix1, ix2 ) ix1 = 3 ierr = GETUASVAL("IS1", IfObj, PackArr,& ix1, ix2 ) ! For a stage with trays ELSE IF( StageType .EQ. 2 ) THEN Ix1 = 6 ! offset to tray type ierr = GETUASVAL("IS1", IfObj, TrayType, & ix1, ix 2) ENDIF
PRO/II User-Added Subroutine User Guide
4-15
Double Precision Named Array Element Calling sequence: FUNCTION GETUASVAL( kwIn, ObjIn, DValue ) & RESULT( iErr )
This form of the function retrieves one double precision value from array DS1. kwIn
A keyword for an element of the DS1 array. These keywords are not listed in Table 4-2, because the data in DS1 may be different for each type of user-added utility data object. Refer to the data tables in the chapters that describe individual types of user-added subroutine. For example, see Table 12-1 for keywords of data available in a mass transfer coefficient utility subroutine.
ObjIn
The name of the data object declared as TYPE(UASOBJ). The data to retrieve must be a member of this data structure.
Dvalue
The returned scalar double precision value.
iErr
An error code returned as the value of the function. A value of 0 indicates successful retrieval (no errors). Any negative value indicates an error.
Example: In an interfacial area calculation subroutine, retrieve the stage weir height. Table 11-1 (for an interfacial area subroutine) lists the weir height in DS1( 2 ). It also shows that the keyword for this member is HTWIER. With this information, the following code is valid: SUBROUTINE ABC( IfObj ) USE class_UASOBJ TYPE( UASOBJ ) :: IfObj INTEGER(4) :: ierr REAL(8) :: WeirHeight ierr = GETUASVAL( "HTWIER", IfObj, WeirHeight )
The value for the height of the weir returns in variable WeirHeight. The error code returns in variable ierr.
4-16 Modular Utility Subroutines
February 2009
Double Precision Unnamed Array Element FUNCTION GETUASVAL( kwIn, Obj, DValue, ix1, ix2 & RESULT(iErr)
This form of the function retrieves a scalar value from any double 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 individual types of user-added subroutine. For example, Table 13-1 on page 13-2 defines the double precision arrays DS1, DA2, and DA3 that are available in a heat transfer coefficient utility subroutine.
ObjIn
The name of the data object declared as TYPE(UASOBJ). The data must be a member of this data structure.
Dvalue
The returned scalar double precision value.
ix1
The first dimension element (column) of the item in the array referenced by kwIn.
ix2
The second dimension element (row) of the item in the array referenced by kwIn.
iErr
An error code returned as the value of the function. A value of 0 indicates successful retrieval (no errors). Any negative value indicates an error.
Example: In a heat transfer coefficient utility subroutine, retrieve the mass transfer coefficient and the diffusion coefficient of the binary pair for components 3 and 6. For an HTC subroutine, use Table 13-1 to find the diffusion coefficient array is DS2 with the keyword DIFFCO. In addition, notice the mass transfer coefficient array is DS3, with the keyword MASSCO. With this information, the following code is valid: SUBROUTINE BCD( HtObj ) USE class_UASOBJ TYPE( UASOBJ ) :: HtObj INTEGER(4) :: ierr, REAL(8) :: Diff36, ix1 = 3 ix2 = 6
The value for the diffusion coefficient returns in variable Diff36. The value for the mass transfer coefficient returns in variable Mass36. The error code returns in variable ierr. Named Character Data Calling sequence: FUNCTION UasGetChar( kwIn ) RESULT( cValue )
This function retrieves a limited number of character data. This routine is most useful to developers rather than end users of user-added subroutines. The only character data currently supported are the module type and version of class_UASOBJ.mod. Developers may wish to access that data during the debugging stage of development to verify that the object passed from PRO/II is the correct one. kwIn
A keyword for a character member in Table 4-2.
cValue
The returned data string of up to 40 characters.
Example: Retrieve the module type and module version of UASOBJ. CHARACTER(LEN=40) :: mType, mVersion mType = UasGetChar( "MODT" ) mVersion = UasGetChar( "MODV" )
4-18 Modular Utility Subroutines
February 2009
Data Structure of class_UASOBJ Table 4-2 describes the data structure of the UASOBJ data structure in the base class. It is presented for the convenience of engineers who develop user-added subroutines. The complete base class never is passed to a user-added subroutine. However, describing it here provides a single source of information about data that is passed to two or more types of user-added subroutine. Table 6-11 on page 635 lists the data structure of “fluid phase” members of UASOBJ.
Table 4-2: class_UASOBJ Data Member Module Data Member
Type
Description
UasType
C 12
Identifies the type of utility subroutine being called
UasPath
C 256
Path to DLL directory from P2UasReg.ini
UasName
C 32
Actual name of subroutine called, from P2UasReg.ini
UasID
C 32
PRO/II ID of the called UAS, from P2UasReg.ini
UasVersion
C 12
Version of the UAS set by the developer of the UAS. General Data
Member
Type
Description
ThermoFl
I4
Thermodynamic method set flag, not yet supported.
DiagnosticFl
I4
Diagnostic flag, for use only by the UAS developer.
UomSystem
I4
UOM system flag 1 = PRO/II internal 2 = English 3 = Metric 4 = SI
Context
C 12
Context flag 1 INPUT 3 CALCULATION 5 REPORT
iContext
I4
Integer version of Context flag 1 INPUT 3 CALCULATION 5 REPORT
PRO/II User-Added Subroutine User Guide
2 CROSSCHECK 4 OPCALC
2 CROSSCHECK 4 OPCALC
4-19
Table 4-2: class_UASOBJ Data Member UASOBJ Data Members Member Phase
Type I4
Description Fluid Phase of interest (for calculations) 0 = Phase does not apply 1 = Vapor 2 = Liquid
CallerID
C 12
ID of calling Unit Operation
Exist
L4
Logical. True if UASOBJ contains valid data. Component Data
Member
Type
Description
NOC
I4
Total number of components in problem
CompIndex(i)
I4
Internal component numbers, in input order. I = 1, NOC Fluid Data
Member
Type
Description
FlVapor
Fluid
Vapor phase fluid data object
FlLiquid
Fluid
Liquid phase fluid data object
FlIface
Fluid
Interface phase fluid data object
FlFeed
Fluid
Liquid phase fluid data object
FlProd
Fluid
Interface phase fluid data object
The following members are validation flags for the fluid data members immediately above. They take the following values: 1 = Array is allocated and populated with valid data. 0 = allocated but empty. -1 = missing. ValidFlVapor
I4
Validation flag for fluid FlVapor
ValidFlLiquid
I4
Validation flag for fluid FlLiquid
ValidFlIface
I4
Validation flag for fluid FlIface
ValidFlIFeed
I4
Validation flag for fluid FlFeed
ValidFlProd
I4
Validation flag for fluid FlProd Subroutine-specific Data
Member IS1
4-20 Modular Utility Subroutines
Type I4
Description An array containing scalar integer data. Contents may change for each type of utility subroutine.
February 2009
Table 4-2: class_UASOBJ Data Member IA2
DP
An array for integer array data. Contents may change.
IA3
DP
Another array for integer array data. Contents may change.
DS1
DP
An array of double precision floating-point data. Contents may change for each type of utility subroutine.
DA2
DP
An array for floating point array data. Often contains binary diffusion coefficients. Contents may change.
DA3
DP
An array for floating point array data. Often contains binary mass transfer coefficients. Contents may change.
DA4
DP
An array for floating point array data. Contents may change.
DA5
DP
An array for floating point array data. Contents may change.
The following validation flags take the following values: 1 = Array is allocated and populated with valid data. 0 = allocated but empty. -1 = missing. ValidIS1
I4
Validation flag for array IS1
ValidIA2
I4
Validation flag for array IA2
ValidIA3
I4
Validation flag for array IA3
ValidDS1
I4
Validation flag for array DS1
ValidDA2
I4
Validation flag for array DA2
ValidDA3
I4
Validation flag for array DA3
ValidDA4
I4
Validation flag for array DA4
ValidDA5
I4
Validation flag for array DA5 Output Data to Return
Member
Type
Results
DP
PRO/II User-Added Subroutine User Guide
Description Calculated Results returned to PRO/II. Number of elements and dimensional units are different for each type of user-added subroutine.
4-21
Table 4-2: class_UASOBJ Data Member ISOLVE
I4
Solution flag to return UAS 0 = no processing took place 1 = solved successfully (expected value) 2 = errors encountered, but results returned 3 = failed, stop calculations
SizeR1
I4
First extent of Results vector (1), not a return value
SizeR2
I4
Second extent of Results vector (1), not a return value
ValidResults
I4
Validation flag for Results array. 1 = Results array passed in containing valid data. 0 = Results array passed in empty, but allocated. -1 = Results array is absent. User-defined Data
Member
Type
Description
LenINT
I4
Size of INTdata array
LenPAR
I4
Size of PARdata array
LenDBL
I4
Size of DBLdata array
INTdata
I4
User-supplied integer data
PARdata
I4
User-supplied PARAMETER data
DBLdata
I4
User-supplied supplementary data
Member
Type
LfuInput
I4
A logical file unit to be used for data input
LfuData
I4
A logical file unit to be used for intermediate data storage
LfuOutput
I4
A logical file unit to be used for writing results
Logical File Units Description
The MEMBER column lists the exact name of each member. These names are used for direct access to the data from within the data object; e.g. IAObj%NOC
4-22 Modular Utility Subroutines
February 2009
Table 4-2: class_UASOBJ Data Member The Type column indicates the data type declared for each entry C nnn
Character string containing up to nnn characters
I4
Integer(4) integer scalar value (one 4 byte word)
L4
Logical(4) logical scalar variable (one 4 byte word) The only possible values are TRUE or FALSE.
DP
A REAL(8) double precision floating point scalar value
Module Identification Data The data in this section is available to verify the identity of a useradded 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 discussion of the registration process. The UasPath depends upon where the end-user installs the useradded direct link library. Normally, this may be anywhere on a computer or a network that PRO/II is able to access. (Subroutine developers may place constraints on the installed location.) The UasID must be unique among all the ID’s in the specific section of the P2UasReg.ini file (where the subroutine is registered). The end user may choose any desired identifier, subject to any constraints imposed by the subroutine developer. The UasVersion typically is of little interest to an end user, but may be quite important to a subroutine developer.
UasType
Identifies the type of utility subroutine being called, including: UAIFAREA
Interfacial Area subroutine.
UAMASSTR Mass transfer coefficient subroutine. UAHEATTR Heat transfer Coefficient subroutine. These types correspond to the sections in the P2UasReg.ini file for the types of user-added subroutines supported by PRO/II. SIMSCI defines these types.
PRO/II User-Added Subroutine User Guide
4-23
UasPath
Registered path to the directory that contains the DLL containing the UAUTIL currently being called. Not used by any UAUOP. PRO/II looks up this member and extracts it from the [UASPATH] section of the P2UasReg.ini file.
UasName
Actual name of the interface subroutine that PRO/II calls. It is the entry in the column labeled UAS routine name in the section identified by the UasType member (above) in the P2UasReg.ini file.
UasID
Registered ID of the called UAS. It is an entry in the UAS identifier column in the section identified by the UasType member (above) in the P2UasReg.ini file.
UasVersion
Version of the UAS set by the developer of the UAS.
General Data Data in this section is important, because it includes various flags that inform the subroutine what PRO/II expects it to do.
ThermoFl
Thermodynamic method set flag. This is the ID number of the Thermodynamic Method Set that PRO/II used to compute component and fluid properties. Currently, no user-added subroutines need to compute these properties, since all available data passes in from PRO/II. Consequently, this member is not needed.
DiagnosticFl Diagnostic flag, for use only by the UAS developer.
PRO/II does not allow the user to enter a value for this member, so it cannot be used. However, during subroutine implementation, the developer could set this value in the code of the user-added subroutine. This could be useful for writing diagnostic messages from the routine under development. The Developer has the responsibility of defining values for this flag. UomSystem
UOM system flag 1 = PRO/II internal 2 = English 3 = Metric 4 = SI This member is read from the P2UasReg.ini file. The user needs to enter this when registering the subroutine.
4-24 Modular Utility Subroutines
February 2009
Context
Context flag (a character string) INPUT CROSSCHECK CALCULATION OPCALC post convergence REPORT
iContext
Integer version of the Context flag. 1 2 3 4 5
INPUT CROSSCHECK CALCULATION OPCALC REPORT
The context flag is essential, because it informs the useradded 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 useradded code is not necessary. It may be useful to developers during code development.
Component Data The component data members in Table 4-2 are generic, since the same data set is passed to all types of utility routine supported by PRO/II. NOC
Total number of components in problem
PRO/II User-Added Subroutine User Guide
4-25
CompIndex(i)
Internal component numbers, in input order. i = 1, NOC.
Components and component data delivered to a utility subroutine are always sorted in their order of appearance in the input data of the simulation. In keyword input, the COMPONENT DATA section of input declares all components and assigns them ordinal numbers. However, PRO/II internally reorders the components to gain calculation efficiency. The CompIndex(i) array contains the internal component number for each component. For example, assume the input file contains three components: COMPONENT DATA LIBID 1,EBENZENE / 3, H2 POLY 2,PS
The following table shows the relationship of CompIndex elements to input order and internal order. Input Order 1 2 3
Component EBENZENE PS H2
Internal CompIndex Order (1) = 2 (2) = 3 (3) = 1
Fluid Data A fluid is the user-added analog of a PRO/II material flow stream. See “Data Structure of class_Fluid” on page 6-27 for a list of all available data in each fluid. Each type of user-added utility subroutine defines its own set of fluids. For example, the interfacial area subroutine includes three separate 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
4-26 Modular Utility Subroutines
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 February 2009
vapor, the data for the total fluid and the vapor phase are identical. FlLiquid
A fluid object that contains the data for the stage bulk liquid phase. It supports data for the total fluid and for the bulk liquid phase. Since the fluid is all liquid, the data for the total fluid and bulk liquid phase are identical. It does not include any data for possible liquid sub-phases.
FlIface
A fluid object that contains data for the Total fluid, bulk vapor phase, and bulk liquid phase. It does not include data for any possible liquid sub-phases.
FlFeed
A fluid object that contains data for the combined feed stream of a simulation object. Currently, none of the utility subroutines allow a feed stream. An FlFeed fluid contains phase members for total fluid, bulk vapor phase, and bulk liquid phase. It does not include data for any possible liquid subphases, solids, or electrolyte phases.
FlProd
A fluid object that contains data for the combined product stream of a simulation object. Currently, none of the utility subroutines allow an FlProd stream. An FlProd fluid contains phase members for total fluid, bulk vapor phase, and bulk liquid phase. It does not include data for any possible liquid sub-phases, solids, or electrolyte phases.
The variables listed below are validation flags that correspond to the fluids listed above. They allow user-added subroutine code to determine which fluids are present and contain data from PRO/II.
ValidFlVapor
Validation flag for fluid FlVapor
ValidFlLiqui d ValidFlIface
Validation flag for fluid FlLiquid
ValidFlIFeed
Validation flag for fluid FlIFeed
ValidFlProd
Validation flag for fluid FlProd
Validation flag for fluid FlIface
Each flag may have any of the following values. Values of Validation Flags
PRO/II User-Added Subroutine User Guide
4-27
Value
Description
1
Array is allocated and populated with valid data
0
Array is allocated but empty. Do not use data from the array
-1
Array is not allocated. Do not attempt to use the array
Developers should test the appropriate validation flag before using the data from a particular fluid. Do not use data from a fluid when the validation flag is less than one.
Subroutine-specific Data Each type of utility subroutine has its own unique data requirements. 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 listings of available data. IS1
A one-dimension array containing scalar integer data. Contents defined by each UAS.
IA2
A two-dimension array for integer array data. Contents defined by each UAS.
IA3
Another two-dimension array for integer array data. Contents defined by each UAS.
DS1
A one-dimension array of double precision floating-point data. Contents defined by each UAS.
DA2
A two-dimension array for floating point array data. Often contains binary diffusion coefficients. Contents defined by each UAS.
DA3
A two-dimension array for floating point array data. Often contains binary mass transfer coefficients. Contents defined by each UAS.
DA4
A two-dimension array for floating point array data. Contents defined by each UAS.
DA5
A two-dimension array for floating point array data. Contents defined by each UAS.
The size and data content for each array are different for each type of subroutine. Developers should refer to the data listings in the chapter that describes the particular type of subroutine under development. For example, refer to See “Interfacial Area Data Members” on page 11-2, when developing an Interfacial Area utility subroutine. 4-28 Modular Utility Subroutines
February 2009
The variables listed below are validation flags that allow user-added subroutines to determine which arrays were populated by PRO/II. ValidIS1
Validation flag for array IS1
ValidIA2
Validation flag for array IA2
ValidIA3
Validation flag for array IA3
ValidDS1
Validation flag for array DS1
ValidDA2
Validation flag for array DA2
ValidDA3
Validation flag for array DA3
ValidDA4
Validation flag for array DA4
ValidDA5
Validation flag for array DA5
Each flag may have any of the following values. Values of Validation Flags Value
Description
1
Array is allocated and populated with valid data.
0
Array is allocated but empty. Do not retrieve data from the array.
-1
Array is not allocated. Do not attempt to use the array.
Developers should test the appropriate validation flag before using the data from a particular array. A value of “1” indicates the data in an array is available for use. Do not use data from an array when the validation flag is less than one.
Returned Results (required) The interfacial area calculation subroutine must return two values to PRO/II: ISOLVE
Required integer scalar returned solution flag. Use a value for ISOLVE from Table 2-4 on page 2-18. Always return ISOLVE= 1 when returning reasonable values in the Results array. See “ISOLVE Return Values” on page 2-18 for more information.
Results(1,1)
Returned calculated values. Different types of utility subroutines return different values. This is a twodimension array, even when returning a single value. See “Results Return Values” on page 4-4. Also, refer to the chapters that describe each utility type for the specific return values that PRO/II requires.
PRO/II User-Added Subroutine User Guide
4-29
The following two data members are not return values, but are included here to complete the documentation. SizeR1
First dimension of the Results array. The value always is 1.
SizeR2
Second dimension of the Results array. The value always is 1. The class_UASOBJ constructor sizes the Results array as Results(SizeR1,SizeR2).
Logical File Units Developers of utility subroutines may wish to read or write data to files outside the control of PRO/II. The file units described here are provided to ensure that the external file units used by a subroutine do not conflict with file units used by PRO/II. No utility subroutines currently supported by PRO/II have access to this feature. LfuInput
A logical file unit to be used for data input. Not available.
LfuData
A logical file unit to be used for intermediate data storage. Not available.
LfuOutput A logical file unit to be used for writing results outside the PRO/II output report. Not available.
class_Fluid.mod and class_FluidPhase.mod These modules make fluid and phase data objects available to useradded subroutines. The number of fluids in the UASOBJ object of a utility subroutine may be different in each type of user-added subroutine. Each fluid object may contain one or more PHASE objects, depending upon the phase state that the fluid represents. See Chapter 6, UAS Modular Fluids for thorough information about class_Fluid and class_FluidPhase.
4-30 Modular Utility Subroutines
February 2009
Chapter 5 Modular Unit Operations Overview Modular user-added unit operations (UAUOP) allow users and other independent developers to extend PRO/II with their own unit operations. 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 reasonable size. Developers may assign names and units of measure in the data definition. PRO/II does not call user-added subroutines during input processing, 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 interface available for the older procedural user-added unit operations. In the course of a simulation, PRO/II calls modular user-added unit operations to perform the following functions. Validate input data during CROSSCHECK execution. Perform calculations during the CALCUATION phase, as part of the flowsheet solution. Perform post-convergence calculations in the OPASS phase (after the simulation flowsheet has converged). Write final results during the REPORT phase of a simulation. The first section of this chapter present useful information to users running simulations that include user-added unit operations. Later sections are intended for developers who create and implement the user-added unit operation models. PRO/II User-Added Subroutine User Guide
5-1
Keyword Summary Unit Identification (required) UAUOP( ), UID= {, NAME=, PRINT= 1, & BYPASS= 1, PLOT, DIAGNOSTIC= 1}, & CALOPTION( CALC or OUT )= 1
User Information Keyword Input Data for modular unit operations is entered in the UNIT OPERATION 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 variations from the normal input conventions are presented here.
Unit Identification (required) UAUOP( ), UID= {, NAME=, 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( ) The qualifier specifies the type
of user-added unit operation. It is the identifier registered in the [UAUOP] section of the UASREG.INI file.
UID= A standard entry required by PRO/II. is a charac-
ter string of up to 12 characters that uniquely identifies a specific instance of the UAUOP in the flowsheet.
NAME= A standard optional PRO/II entry. is descrip-
tive text up to 40 characters.
BYPASS Specifies the calculation contexts in which PRO/II calls
the unit. Table 5-1 defines the available values.
Table 5-1: Bypass Options Bypass Value
Description
1
CALCULATE context during flowsheet convergence only. This is the default.
2
OPASS context after flowsheet convergence only
3
Both CALC and OPASS contexts during and after flow sheet convergence.
When the BYPASS keyword or it’s argument is missing, PRO/II assumes BYPASS=1. The bypass flag does not affect other contexts. The unit operation always is called for CROSSCHECK 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 purpose of the keyword. The actual significance is defined by the developer of the model. These options may or may not be supported PRO/II User-Added Subroutine User Guide
5-3
in any specific user-added unit operation. The limitations that are listed are imposed by PRO/II. Any specific UAUOP may impose more stringent constraints. Users must obtain the input requirements 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 missing, PrintFL = 0. When the keyword is present without an argument value, PrintFL=1. PLOT
An optional logical flag that does not accept an argument. 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 calculations. 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 specify the number of zones in heat exchanger zones analysis calculations. However, the significance may be redefined 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 operations require at least one side, typically side number 1. To be included in flowsheet calculations, each unit operation must have at least one feed stream. If it has no feeds, it will be skipped. This is a requirement of the PRO/II calculation sequencer. No feeds 5-4 Modular Unit Operations
February 2009
are required for units that perform calculations only in the OPASS context (i.e., when BYPASS=2). PRO/II allows each side to have between zero and 10 feeds. Products are always optional. PRO/II allows each side to have between zero and 10 products. SIDE( sideid or sideno ) FEED=sid {, sid, ... }, & PROD=sid {, sid, ..., ), METHOD=setid
sideid
An identifier of up to 32 characters, assigned by the developer, that uniquely identifies the side. The first character of the sideid must be a letter (A -Z). Since each side implicitly has an integer sequence number, the side number (sideno) may be used instead of the sideid.
FEED
Specifies the feed streams to the side. When this keyword is present, it requires at least one stream identifier. Up to 10 feeds are allowed by PRO/II.
Note: At least one side must have at least one FEED. If this requirement is not satisfied, the unit will be skipped during flowsheet convergence calculations. PROD
When this keyword is present, it requires at least one stream identifier.Products always are optional. Omit this keyword on sides that do not have products.
METHOD This declares the thermodynamic METHOD set used by
the side. Each side in the unit operation may have a different 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 number (seqno) assigned to it by the developer. Optionally, it also may have an assigned name (name). The keyword input statements described here allow users to identify data items using either the (seqno) or the (name).
Integer Data INT( name or seqno )
PRO/II User-Added Subroutine User Guide
intval1 {, intval2, .... }
5-5
Parameter Data PAR( name or seqno ) parval1 {, parval2, .... }
Double Data DBL( name or seqno ) parval1 {, parval2, .... }
Any number of INT, PAR, and DBL statements may appear in an input file. Data for more than one variable may appear in each statement. All data for an array should appear in order on a single statement. Numeric Data Example: Consider the following (partial) data storage definition. Table 5-2: Sample Numeric Data Definition Type
seqno
PAR
1
PAR
2
PAR
ID Name
Size
Value
First
1
1.0
Second
3
2.1
3
2.2
4
2.3
5
Third
2
6 7
3.1 3.2
Fourth
1
4.0
All the data in Table 5-2 may be entered on a single PAR statement: PAR( First ) 1.1, 2.1, 2.2, 2.3, 3.1. 3.2, 4.0 Alternatively, several PAR statements could be used: PAR( PAR( PAR( PAR(
First ) Second ) Third ) Fourth )
1.1 2.1, 2.2, 2.3 3.1, 3.2 4.0
Statements may use sequence numbers instead of ID names. PAR( PAR( PAR( PAR(
1 2 5 7
) ) ) )
1.1 2.1, 2.2, 2.3 3.1, 3.2 4.0
Enter all values of an array in order on a single statement. Values for single elements of arrays should not be entered. For example, it is invalid to input only element 2 of PAR( 2 ) : PAR( Second ) , 2.2 ! This is invalid. However, the following is valid 5-6 Modular Unit Operations
February 2009
PAR( 3 ) 2.2 array Second.)
(Where 3 is the sequence number of element 2 of
All the strategies demonstrated in the preceding examples also apply to INT, DBL, and TEXT data.
Text Data TEXT( name or idno {, elno})
txtval1 {, txtval2, .... } TEXT statements behave differently than the INT, PAR, and DBL statements. Text statements use an ID number or name in conjunction with an element number to identify the first data entry on the statement. name or idno
The name of the TEXT variable or array. 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
TEXT
1
TEXT
2
TEXT
Size
elno
Value
First
1
1
A1
Tarray
3
1
B2.1
-
2
B2.2
-
3
B2.3
1
C3
3
ID Name
Third
2
All the data in Table 5-3 may be entered on a single TEXT statement: TEXT( First ) “A1”, “B2.1”,”B2.2”,“B2.3”, “C3” Alternatively, several PAR statements could be used: TEXT( First ) “A1” TEXT( Tarray ) “B2.1”, ”B2.2”, “B2.3” TEXT( Third ) “C3”
Statements may use ID numbers instead of ID names. TEXT( 1 ) 1.1
PRO/II User-Added Subroutine User Guide
5-7
TEXT( 2 ) 2.1, 2.2, 2.3 TEXT( 3 ) 3.1, 3.2
Values for single elements of arrays also may be entered using element numbers. For example, enter data for Tarray (3) as: TEXT( Tarray, 3 ) “B2.3”
or TEXT( Tarray, 1 ) “B2.1”, “B2.2”
Where 1 is the element of Tarray used to store the first value. The second value “B2.2” is stored in Tarray(2). Each text variable has a limit (imposed by the developer) on the number of characters it may contain. The limit applies to each element in a TEXT array. Text strings that contain embedded blanks or commas must be enclosed in quotation marks.
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. Identifies the item that receives the value in the import-
ing unit operation. When the importing unit is another UAUOP, must have the form: PAR(seqno).
This element specifies the type of user-added unit
operation that will supply the data. It is the identifier registered in the [UAUOP] section of the UASREG.INI file.
A standard entry required by PRO/II. Keyword UID is required. is a character string of up to 12 characters 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; however, it may be an element of a PAR array. Using the name of the PAR is not supported. It must be accessed
or DEFINE PAR( seqno ) AS STREAM=, & {, , } 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 Manual”. 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.
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.
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 subsystem. Refer to Chapter 10.3, Flowsheet Parameters, in the “PRO/ II Keyword Manual” for more information.
PRO/II User-Added Subroutine User Guide
5-9
PROVISION Input Figure 5-1: UAUOP Icon on PFD Palette
.When user-added unit operations are registered in the P2UasReg.ini file, PROVISION automatically adds icons to the PFD palette so users can select them. This is shown in Figure 5-1. The new icon is separate from the “User-added Unit” icon (that allows selection of the procedural unit operations described in Chapter 18, “Classic Unit Operations”). To add a UAUOP to a simulation, simply click the icon to select it. Move the mouse cursor to the main “Flowsheet” window and left-click the mouse. A UAUOP icon appears at the position of the cursor. This is exactly the same procedure used to add any other unit operation to the simulation. To enter or edit input data, right-click the UAUOP icon in the main “Flowsheet” window. This opens the pop-up “action menu”. Click the “Data Entry...” menu item shown in Figure 5-2. Figure 5-2: Opening a UAUOP Date Entry Window
PROVISION includes generic Data Entry Windows that allow users to enter data for a UAUOP. The generic DEW supports input for all data declared in the INI file associated with the UAUOP. However, the layout is extremely simple. By using the optional AutoGui in PRO/II, the developer of the UAUOP can create a much more sophisticated DEW that organizes
5-10 Modular Unit Operations
February 2009
user input in a more user-friendly format. Figure 5-3 shows part of a fairly simple example of a custom AutoGui DEW. Figure 5-3: Sample Custom AutoGui DEW
Clicking the tabs near the top of the window display additional data input dialog boxes. Notice the data have been grouped and have labels. It is even possible to change the units of measure. Chapter 8, “UAUOP AutoGUI” explains how to create and use AutoGui windows. PRO/II User-Added Subroutine User Guide
5-11
UAUOP User Options Calculation Options PRO/II provides a CALOPTION flag on the UAUOP statement of keyword input that allows simulation users to control optional calculations in a UAUOP. Developers may or may not choose to implement this in their models.
Final Reports PRO/II calls each UAUOP during the REPORT context to allow it to generate a report of its results. Interface routine UAOUT may be used for this purpose. When the UAUOP does not include reportwriting code, PRO/II can write a default report for it. The UAUOP developer controls whether or not PRO/II writes a default report by returning an appropriate code in the ISOLVE variable.
Optional Reports The UAUOP keyword statement provides several flags that developers may implement to control optional output. Developers should inform users of any options they implement for the following flags. DIAGNOSTIC=ival This flag is intended to allow simulation users
to control the generation of trace back and debugging information. The ival argument accepts any integer value. The default is ival=0.
PRINT=ival A flag intended to control optional or additional
reports. Typical uses include controlling intermediate output during calculations, or extended output in the final report. The ival argument accepts any integer value. The default is ival=0.
PLOT
PRO/II provides a PLOT flag on the UAUOP statement of keyword input that allows simulation users to control the generation of plotted results. Developers may or may not choose to implement this in their models.
UAUOP Installation and Registration It is the user’s responsibility to install and register user-added unit operations before attempting to use them from PRO/II. Users must obtain specific installation instructions from the developer of each UAUOP; not from SIMSCI. See “Registering [UAUOP] UserAdded Unit Operations” on page 2-11 of Chapter 2 in this manual to learn about the registration procedure.
5-12 Modular Unit Operations
February 2009
Developer Information The remainder of this chapter is intended for developers of useradded unit operations. This material is not essential for users who only use pre-built modular utilities in PRO/II simulations; but they may find some of the material informative.
Data Exchange between PRO/II and UAUOP Routines Almost all unit operation data is encapsulated in a UAUOP data object that is an argument in the subroutine call list. The syntax of the call to a UAUOP always has the following form: CALL myUaUop( CONTEXT, UopObj, ISOLVE )
Where: myUaUop The name of the interface subroutine called by PRO/II. The developer replaces myUaUop with an actual subroutine 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 Values” on page 2-18 of Chapter 2, “Modular UAS Build Procedures”.
Other types of data are accessed through interface classes, such as class_Fluid (Chapter 6) and class_DMUOM (Chapter 7).
Contexts Involving a UAUOP PRO/II defines several contexts that perform different types of operations during a simulation. Table 5-4 lists the contexts in which PRO/II makes calls to user-added unit operations. Table 5-4: Contexts for a UAUOP in PRO/II Context
UAUOP
PRO/II User-Added Subroutine User Guide
AutoGui
Description
5-13
Table 5-4: Contexts for a UAUOP in PRO/II INPUT
Not called
Called
Read and Store input data
CROSSCHECK
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
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 implemented, PRO/II calls it only during the INPUT context.
ISOLVE Return Values from a UAUOP Whenever PRO/II calls a UAUOP, it expects the UAS to perform specific actions. PRO/II requires the UAUOP to return a valid value for ISOLVE after each call. Table 5-5 lists the valid return values that PRO/II accepts from a user-added unit operation.. Table 5-5: ISOLVE Values returned from a Utility ISOLVE 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. 5-14 Modular Unit Operations
February 2009
It is not used by PRO/II; however, it is a safe practice to set ISOLVE both in the call argument variable and in the UAUOP object.
Example Setting ISOLVE: The following code sample illustrates setting both instances of ISOLVE in the interface subroutine. SUBROUTINE myUOP( CONTEXT, UOPOBJ, ISOLVE ) CHARACTER(10) :: CONTEXT TYPE(UAUOP) :: UOPOBJ INTEGER(4) :: ISOLVE, iErr IF( CONTEXT(1:4) .EQ. “CALC” ) THEN ISOLVE = 2 ! assume failure CALL myCalcs( UAUOP, iErr ) IF( iErr .EQ. 0 ) ISOLVE = 1 ! success ELSE ISOLVE = 0 ! all other contexts END IF UOPOBJ%ISOLVE = ISOLVE ! sets the copy The branching logic is based on the CONTEXT flag passed in from PRO/II. For the CALCULATION context only, subroutine myCalcs is called. If no error occurred, myCalcs returns iErr = 0, and ISOLVE is set to 1; otherwise it returns an error value of
2. In all other contexts, ISOLVE returns zero indicating “no action performed”. See “ISOLVE Return Values” on page 2-18 of Chapter 2 for more general information.
Results Return Values Other than the ISOLVE argument variable, PRO/II does not require any specific results to be returned from a UAUOP. There are two mechanisms that allow a UAUOP to return results to PRO/II. Calculated UAUOP results return in the IntValue, ParValue, DblValue, and TxtValue members of the UAUOP data object. PRO/II always stores these arrays upon return from the useradded 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 associate with the UAUOP. Any values stored by the UAUOP are available in all subsequent calls to the UAUOP from PRO/II. Values stored in available for the first 100 elements of the PARVALUE array are subsystem. use throughout the flowsheet by using the DEFINE
PRO/II User-Added Subroutine User Guide
5-15
Dimensional Units Each user-added unit operation exchanges data with PRO/II in a consistent set of dimensional units. The UOM’s are defined by the developer in the INI file that defines the data storage of the UAUOP. The developer chooses one of several UOM sets provided by PRO/II. Additionally, specific units of measure may be assigned to each dimensional class in the set of dimensional units. These definitions 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 available set of units.
Coding Guidelines Each user-added unit operation should have its own interface routine 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 simplify 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 eliminates the need for long argument lists in subroutine call. A user-added unit operation must “instantiate” the data class so data can be retrieved and stored. Earlier versions for Fortran, such as Fortran 77 or Fortran 66, do not provide this capability. All PRO/II modular interfaces conform to the Fortran 90 standard as much as possible. However, dynamic calls to external DLL’s are outside the strict domain of the Fortran standards. PRO/II uses 5-16 Modular Unit Operations
February 2009
extensions to the Fortran 90 language to accomplish this. In the examples in this manual, the extensions are illustrated using Compaq Visual Fortran version 6.6b. They will be different if other compilers are used.
Coding A UAUOP Interface Routine Each user-added unit operation requires a standard interface routine so PRO/II can call it. The interface routine must conform exactly to the requirements presented here. Using a separate interface routine removes the PRO/II constraints from the calculation routine. Figure 5-4 illustrates the essentials of a basic interface subroutine. Figure 5-4: Sample Interface Routine Called by PRO/II 1 SUBROUTINE UOP1MAIN( CONTEXT, UopObj, iSolve ) 2 !DEC$ ATTRIBUTES DLLEXPORT:: UOP1MAIN ! Export UOP1Main 3 !___________________________________________________________ 4 ! | 5 ! Variables in Argument list | 6 ! Name Type I/O Brief Description | 7 ! -------- ------ --- ------------------------------------- | 8 ! CONTEXT C*10 I Type of Action requested by PRO/II ! 9 ! "CROSSCHECK" - Verify input data ! 10 ! "CALCULATE" - calculate a solution ! 11 ! "OPASS" - Post flowsheet calcs ! 12 ! "REPORT" - Write final report ! 13 ! UopObj UaUop I/O UaUOp Data object instance ! 14 ! ISOLVE INT O Required return status flag ! 15 !___________________________________________________________| 16 ! 17 USE class_UAUOP ! Interface module for a UAUOP 18 ! 19 IMPLICIT NONE 20 CHARACTER(LEN=*), INTENT(IN) :: CONTEXT 21 TYPE(UAUOP), INTENT(INOUT) :: UopObj ! define dataobj ! 22 INTEGER(4), INTENT(OUT) :: iSolve 23 ! 24 IF( CONTEXT(1:9) .EQ. "CALCULATE" ) THEN 25 CALL Uop1Calc( UopObj, iSolve ) 26 ELSE IF( CONTEXT(1:10) .EQ. "CROSSCHECK" ) THEN 27 CALL Uop1Cros( UopObj, iSolve ) 28 ELSE IF( CONTEXT(1:5) .EQ. "OPASS" ) THEN 29 iSolve = 0 ! not supported in this example 30 ELSE IF( CONTEXT(1:6) .EQ. "REPORT" ) THEN 31 CALL Uop1Repo( UopObj, iSolve ) 32 ELSE 33 iSolve = 0 34 ENDIF 35 ! 36 UopObj%ISOLVE = ISOLVE 37 END SUBROUTINE UASMAIN
PRO/II User-Added Subroutine User Guide
5-17
Notes about Figure 5-4: Line 1 illustrates the exact argument list that PRO/II requires. Argument 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 available 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, subroutine 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 calculation algorithm is coded in one subroutine, while the crosscheck code is in a different subroutine. If the test at line 26 evaluates FALSE, control passes to lines 28. Line 28 tests for the OPASS context, branching in the same manner as the previous IF clauses. This example does not support OPASS calculations, and sets ISOLVE = 0 to indicate this. Line 30 follows the same pattern, branching on the REPORT context. Lines 32 and 33 are the default clause of the “IF” construct. If none of the preceding clauses evaluate TRUE, control passes to line 33. In this case, the subroutine does nothing except set the ISOLVE return variable to 0 to indicate the subroutine did nothing. Line 36 sets the ISOLVE member of UopObj data structure to match the ISOLVE variable. This is not required, but is a safe practice. 5-18 Modular Unit Operations
February 2009
Finally, line 37 ends the subroutine. When control reaches this line, the subroutine exits and returns to PRO/II. Note the omission of a Fortran 77 RETURN statement. It is not required by Fortran 90. With simple modifications, the sample code of Figure 5-4 is suitable for use by any UAUOP. For example, to support OPASS calculations, simply replace line 29 with a call to an appropriate subroutine. To disable one of the supported contexts, replace the subroutine call with ISOLVE = 0 at line 25, 27, or 31, as appropriate.
Coding A Unit Operation Calculation Routine Typically, the calculation code should appear in a routine separate from the interface routine. In this approach, PRO/II only calls the interface routine, and the interface is the only routine that calls the calculation routine. This provides the most flexibility for writing the code and modularizing the functionality. There are two primary approaches for coding the call from the interface to the calculation routine. 1.
The interface routine performs all access to class_ UAUOP. It extracts all necessary input data from UopObj into local variables 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 calculation 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 demonstrated in the sample code of Figure 5-4. The calculation routine 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 calculation routine to work directly with the input data and store results in a straightforward manner. However, this creates a dependency of the calculation routine on class_ UAUOP. Using this approach, the calculation routine could be used only when called by PRO/II, and would not be readily available for use in other applications.
Either approach is equally valid; the choice is left to the developer. Refer to the topic “Direct Member Addressing in class_UAUOP” on page 5-20 to learn more about using class_UAUOP.
PRO/II User-Added Subroutine User Guide
5-19
Definition of class_ UAUOP.mod This module makes class_ UAUOP available in modular user-added unit operations. The class includes a data structure that is passed as an argument in the subroutine call list. This section describes all the data in the UAUOP data structure. It also describes the proper usage of the class. PRO/II does not support using class_ UAUOP in useradded utility (UAUTIL) subroutines.
Usage of class_ UAUOP PRO/II passes an instance of the UAUOP data object to each useradded unit operation that it calls. Before using the data structure, the user-added subroutine code must make several declarations. Calling Sequence: SUBROUTINE myUop( CONTEXT, UopObj, ISOLVE ) !DEC$ ATTRIBUTES DLLEXPORT :: myUop USE class_UAUOP TYPE(UAUOP) UopObj INTEGER(4), INTENT(IN) :: CONTEXT INTEGER(4), INTENT(OUT) :: ISOLVE
The second argument in the subroutine call list is the variable to declare as a UAUOP instance. This allows data in the data object to pass between PRO/II and the user-added subroutine. See “Coding A UAUOP Interface Routine” on page 5-17. Be sure to export the subroutine from the DLL. Use either the !DEC$ ATTRIBRUTES statement shown above, or an external “.DEF” export file. USE class_UAUOP Include this statement to bring in the definition of the UAUOP data structure. TYPE(UAUOP) UopObj This statement declares the UopObj argument variable as a UAUOP instance. This makes the local instance of UAUOP accessible by within the subroutine.
Two common methods of accessing the data in a module are: Direct member addressing is fully supported in class_UAUOP. Indirect accessor routines (using member accessor routines) is not supported by class_UAUOP. The following sections discuss both data access methods.
Direct Member Addressing in class_UAUOP Direct member addressing accesses data by direct reference to the data member. Fortran 90 defines the percent symbol % as the mem-
5-20 Modular Unit Operations
February 2009
ber selection operator. Consider the following data structure as an analog of a UAUOP data structure. TYPE ONESIDE INTEGER(4) :: FeedCount INTEGER(4) :: FeedNo( 20 ) CHARACTER(LEN=lszIdChar) :: FeedID( 20 ) END TYPE ONESIDE TYPE UAUOP INTEGER(4) :: NOC REAL(8), DIMENSION(30) :: ParValue INTEGER(4) :: SideCount CHARACTER(LEN=32) :: SideName( 3 ) TYPE( OneSide ), DIMENSION(3) :: Side END TYPE UAUOP TYPE ONESIDE defines one side of a UAUOP, while TYPE UAUOP defines a UAUOP data structure that allows up to 3 sides.
Each user-added unit operation subroutine contains the following statements: SUBROUTINE myUop( CONTEXT, UopObj, ISOLVE ) USE class_UAUOP TYPE(UAUOP) UopObj
The TYPE(UAUOP) statement declares variable UopObj as a UAUOP structure that includes the 3 sides. Some valid references in the user-added unit operation subroutine might be: numComps = UopObj%NOC ! Number of components numSides = UopObj%SideCount ! Actual number of sides
The above statements retrieve scalar data from the UopObj storage object. Array data is accessed in the same manner. cNameSide= UopObj%SideName( 2 ) ! Name of Side 2 UserPar3 = UopObj%ParValue( 3 ) ! Element 3 of PAR
The “parent % member” paradigm is extensible to any level in the data structure. For example, nFeed3 = UopObj%Side(3)%FeedCount cFeed = UopObj%Side(3)%FeedID( nFeed3 )
Local variable nFeed3 retrieves the actual number of feeds to side 3. Character variable cFeed retrieves the name of the last feed to side 3. It is possible to access any data member in any sub-structure of UAUOP in this manner. Table 5-6 lists all data members available in the UAUOP data structure. The first column, labeled “Member”, is the exact name of the data member to use for direct member addressing.
PRO/II User-Added Subroutine User Guide
5-21
Indirect Access in class_UAUOP The module class_UAUOP does not provide any accessor functions at this time. All data is accessed using direct member addressing, as described in the previous topic.
Data Structure of class_UAUOP Table 5-6 defines the data structure in class_UAUOP. Table 5-6 lists the data structure of one SIDE member of UAUOP. The member DMUOM is itself another class object that is defined in Chapter 7. Table 5-6: class_UAUOP Data Members
Member
Type
Description Module Data
ModType
C 12
Identifies the class_UAUOP module as “UAUOP“. Set only by PRO/II.
ModVersion
C 12
Version of class_UAUOP, typically “8.0". Set only by PRO/II. (setting is not reliable.)
ProgID
C 64
Program ID of a COM object. Not applicable in a UAUOP. Set in the INI file.
UAUOP Identification and Access Data UasType
C 32
Identifies the type of this UAUOP subroutine. Set in the INI file.
UasVersion
C 12
Version of the UAUOP. May be set by the developer by the UAUOP subroutine code.
UasRoutine
C 64
Name of the interface routine called by PRO/ II to access this particular UAUOP model. Set in the INI file.
UasFile
C 40
File name of the DLL that contains this UAUOP. Set in the INI file.
UasPath
C 256
Path to directory where the DLL file resides. Set in the INI file.
UasID
C 12
PRO/II UID of this instance of the UAUOP in each simulation. User input.
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.
UasIdNo
5-22 Modular Unit Operations
February 2009
Table 5-6: class_UAUOP Data Members
Member
Type
Description General Data
Context
C 12
iContext
I4
BypassFl
I4
CalOpContext
I4
CalOpValue
I4
DiagnosticFl
I4
LFUout
I4
PlotFl
I4
PrintFl
I4
Exist
L4
PRO/II Context flag “INPUT” “CROSSCHECK” “CALCULATION” “OPASS” “REPORT” Integer version of Context flag 1 INPUT 2 CROSSCHECK 3 CALCULATION 4 OPASS 5 REPORT Calculation bypass flag, user input. Refer to the UAUOP statement of Keyword Input earlier in this chapter. Calculation context option flag. See the UAUOP statement of Keyword Input. Calculation Option argument value. Defined by the developer. Diagnostic flag, user input. Refer to the UAUOP statement of Keyword Input earlier in this chapter. Logical File unit for standard PRO/II output Plot option flag, user input. Refer to the UAUOP statement of Keyword Input. Print option flag, user input. Refer to the UAUOP statement of Keyword Input. Logical TRUE if UAUOP contains valid data
Component Data NOC
I4
NOCMW
I4 I4
CompIndex( n)
Total number of components in the simulation Number of molecular weight components Internal component numbers, in input order. n = 1, NOC
Dimensional Units of Measure Factors
DMUOM Data object containing UOM data and conversion factors. See Chapter 7.
Side Data SideCount
I4
Number of sides in the UAUOP. User input.
Side( ns )
Side
Array of side-data objects. ns = 1, SideCount See Table 5-8.
PRO/II User-Added Subroutine User Guide
5-23
Table 5-6: class_UAUOP Data Members
Member
Type
Description
INT Input and Results Data IntExtent IntCount IntValue( n )
I4 I4 I4
IntSize( i )
I4
IntMapNo( i )
I4
IntLower( i )
I4
IntUpper( i )
I4
IntName( i )
C 32
IntMinName( i )
I4
Total INT storage available (32 bit words) Number of defined INT variables Values of every element of every INT variable n = 1, IntExtent Number of elements in each INT i = 1, IntCount Offset to first element of each INT variable. i = 1, IntCountt. Lower bound limit of each INT variable. i = 1, IntCountt Upper bound limit of each INT variable. i = 1, IntCountt. Name of every INT variable. i = 1, IntCountt. Number of characters in each INT name that makes the name unique. i = 1, IntCountt
PAR Input and Results Data ParExtent
I4
ParCount
I4
ParValue(i)
I4
ParSize( i )
I4
ParMapNo( i )
I4
ParUomClass( i )
I4
ParLower( i )
I4
ParUpper( i )
I4
ParName( i )
C 32
ParMinName( i )
5-24 Modular Unit Operations
I4
Total PAR storage available. (64 bit words), from INI file. Number of defined PAR variables, from INI file. Values of every element of every PAR variable. i = 1, ParExtent. Number of elements in each PAR array, from INI file. i = 1, ParCount. Offset to first element of each PAR variable. i = 1, ParCount. Unit of measure class (temp, pres, etc.) of each PAR variable, from INI file. i = 1, ParCount. Lower bound limit of each PAR variable, from INI file. i = 1, ParCount Upper bound limit of each PAR variable, from INI file. i = 1, ParCount. Name of every PAR variable, from INI file. i = 1, ParCount. Number of characters in each PAR name that makes the name unique. i = 1, ParCount.
February 2009
Table 5-6: class_UAUOP Data Members
Member
Type
Description
DBL Input and Results Data DblExtent
I4
Total DBL storage available. (64 bit words), from INI file.
DblCount
I4
Number of defined DBL variables, from INI file.
DblValue( i )
I4
Values of every element of every DBL variable. i = 1, DblExtent
DblSize( i )
I4
Number of elements in each DBL array i, from INI file. i = 1, DblCount
DblMapNo( i )
I4
Offset to first element of each DBL variable. i = 1, DblCount.
DblUomClass( i )
I4
Unit of measure class (temp, pres, etc.) of each DBL variable i, from INI file. i = 1, DblCount
DblLower( i )
I4
Lower bound limit of each DBL variable, from INI file. i = 1, DblCount
DblUpper( i )
I4
Upper bound limit of each DBL variable, from INI file. i = 1, DblCount.
DblName( i )
C 32
DblMinName( i )
I4
Name of every DBL variable, from INI file. i = 1, DblCount Number of characters in each DBL name that makes the name unique. i = 1, DblCount
TEXT Input and Results Data TxtExtent
I4
Total TXT storage available. (Char*4 words) from INI file.
TxtCount
I4
Number of defined TXT variables from INI file.
TxtMaxChr
I4
Maximum characters allowed in any element of any TXT variable. Computed from TEXT definitions in the INI file.
TxtValue( i )
I4
Values of every element of every TXT variable i = 1, TxtExtent
TxtMapNo( i )
I4
Offset to first element of each TXT variable. i = 1, TxtCount.
TxtSize( i )
I4
Number of elements in each TXT array, from INI file. i = 1, TxtCount
PRO/II User-Added Subroutine User Guide
5-25
Table 5-6: class_UAUOP Data Members
Member
Type
Description
TxtWidth( i )
I4
Maximum characters allowed in each element of each TXT variable, from INI file. i = 1, TxtCount
TxtName( i )
C 32
Name of every TXT variable, from INI file. i = 1, TxtCount.
TxtMinName( i )
I4
Number of characters in each TXT name that makes the name unique. i = 1, TxtCount.
Output Data I4
ISOLVE
Solution flag to return UAS. 0 = no processing took place 1 = solved successfully (expected value) 2 = errors encountered, but results returned 3 = failed, stop calculations
The MEMBER column lists the exact name of each member. These names are used for direct access to the data from within the data object; e.g. UopObj%NOC The Type column indicates the data type declared for each entry C nnn I4 L4
Character string containing up to nnn characters Integer scalar value (one 4 byte word) Logical scalar variable (one 4 byte word) The possible values are .TRUE. and .FALSE. A Real(8) double precision floating point scalar value
DP
Module Data The data in this section allows developers to determine the version of the UAUOP module being used. ModType Always identifies the module as “UAUOP’. ModVersion The version of the module that changes whenever
changes are made to the module itself. This may include adding or modifying the data structure or any accessor functions. The current version is “8.0”.
ProgID
This is used only by COM objects in PRO/II and is not generally meaningful for a UAUOP. The ProgID is used to register a COM object in the Windows® operating system.
UAUOP Identification and Access Data The variables in this section allow developers to add their own identification information and make it available inside the user-added 5-26 Modular Unit Operations
February 2009
subroutine. It includes information registered in the P2UasReg.ini file by the user and used by PRO/II to access the UAUOP during a simulation run. UasType
This is the text string that uniquely identifies the UAUOP to PRO/II. Developers define it using the UATYPE=UasType entry in the [Access] section of the INI file. Users register it as the UATYPE entry in the [UAUOP] section of the P2UasReg.ini file. In keyword input, users declare the exact same string on each UAUOP statement of UNIT OP input. For example, UAUOP( Ex1Uop ) UID=U1, where Ex1Uop is the registered UasType.
UasVersion
Version of the UAS set by the developer of the UAS. The code to set this must be implemented in a routine written by the UAUOP developer. PRO/II simply saves the data in the storage of the UAUOP in each simulation.
UasRoutine
The exact name of the interface routine called by PRO/ II for this UAUOP. The developer defines this name as the ROUTINE=UasName entry in the [Access] section of the INI file.
UasFile
The complete name of the library file that contains the user-written code of the UAUOP. This name includes the DLL suffix. It does not contain any directory or path information. The developer defines this name as the DLL=Uasfile.DLL entry in the [Access] section of the INI file.
UasPath
The complete path to the directory that contains the UasFile DLL. It should end with a back-slashes (\), and does not include the UasFile name. The developer defines this using the PATH=UasPath entry in the [Access] section of the INI file.
UasID
This is the 12 character identifier of one specific instance of the UAUOP in a simulation. In keyword input, the user declares a different UasID on each UAUOP statement of UNIT OP input. For example, UAUOP( Ex1Uop ) UID=U1, where U1 is the UasID. of that specific unit operation.
UasIdNo
Integer unit sequence number of the UAUOP in a simulation. Every unit operation in a PRO/II simulation is assigned a sequence number (seqno) during input data processing. UasIdNo is the seqno currently assigned to the current UAUOP.
PRO/II User-Added Subroutine User Guide
5-27
UasName
An optional 40 character descriptive name for a specific instance of the UAUOP in a simulation. It may be any text and does not need to be unique. In keyword input, users may declare this using the NAME keyword on the UAUOP statement; e.g, UAUOP(Ex1Uop) UID=U1, NAME=MyName, where MyName is the UasName.
CallerID
12 character ID of the PRO/II routine that called the unit operation. Typically this is routine UAUOP_CA in all contexts. Intended as a debugging aid, this variable probably is not too useful.
General Data Data in this section includes various flags that inform the subroutine what actions PRO/II expects it to perform. Context
Context flag (See “Contexts Involving a UAUOP” on page 5-13 of this chapter.) “ INPUT” “CALCULATION” “REPORT”
iContext
Integer version of the Context flag. (See“Contexts Involving a UAUOP” on page 5-13 of this chapter.) 1 = INPUT 3 = CALCULATION 5 = REPORT
BypassFL
“ CROSSCHECK” “OPASS”
2 = CROSSCHECK 4 = OPASS
The calculation bypass flag on the UAUOP statement of keyword input. Refer to Table 5-1, ”Bypass Options,” on page 3 of this chapter.
CalOpContext An integer flag for the context qualifier of the CalOption entry on the UAUOP statement of keyword input. For example, UAUOP(Ex1Uop) UID-U2, CALOP(Context)=ival when Context = CALC, CalOpContext = 1 Context = OUT, CalOpContext = 2 CalOpValue
5-28 Modular Unit Operations
An integer flag for the value of the ival argument to the CalOption entry on the UAUOP statement of keyword input. For example, UAUOP(Ex1Uop) UID-U2, CALOP(Context)=ival where ival is the value of CalOpValue. Developers define the significance of CalOpValue (if any).
February 2009
DiagnosticFl
A flag that lets developers request diagnostic reports during a simulation through keyword input. An example of keyword usage is: UAUOP( EX1UOP), UID=U2, DIAGNOSTIC=2 This sample input sets DiagnosticFL = 2. Developers define values for this flag.
LFUout
This is the Logical File Unit used by PRO/II to generate primary output reporting. The file may change depending on the execution context. See “Output and Reporting” on page 5 of Chapter 3.
PrintFl
The integer value of the Print option on the UAUOP statement. An example of keyword usage is: UAUOP( EX1UOP), UID=U2, PRINT=2 This sample input sets PrintFL = 2. Developers define values they support for this flag.
PlotFL
The integer value of the PLOT flag option on the UAUOP statement. The PLOT option does not accept an argument value. An example of keyword usage is: UAUOP( EX1UOP), UID=U2, PLOT The example sets PlotFL = 1. PlotFL values have the following meaning. 0 = No PLOT entry (on the UAUOP statement). 1 = PLOT entry specified by user input.
Exist
Logical TRUE when the UAUOP object contains valid data. If for some reason the UAUOP data structure has not been initialized, this flag is FALSE. Normally, testing this member in the user-added code is not necessary. It may be useful to developers during code development.
Component Data NOC
Total number of components in a simulation
NOCMW
Number of molecular weight components in a simulation. NMWSolids are excluded. When no NMWSolids are in the simulation, NOCMW = NOC.
CompIndex(i)
Internal component numbers, in input order. i = 1, NOC.
Components and component data delivered to a UAUOP are always sorted in their order of appearance in the input data of the simulation. In keyword input, the COMPONENT DATA section of input declares all components and assigns them ordinal numbers. This define the component Input Order. However, PRO/II reorders the PRO/II User-Added Subroutine User Guide
5-29
components into Internal Order to gain calculation efficiency. See “Internal Component Order vs. Print Order” on page 40 of Chapter 15. All component data exchanged between a UAUOP and PRO/II are in Input Order. The CompIndex array contains the internal component 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
Table 5-7 shows the relationship of CompIndex elements to input order and internal order. Table 5-7: Input versus PRO/II Internal Component Ordering Input Order
Component
CompIndex
Internal Order
1
EBENZENE
(1)
2
2
PS
(2)
3
3
H2
(3)
1
Dimensional Units of Measure Data Dimensional units handling is handled in class_DMUOM. Refer to Chapter 7 for an extensive discussion of units of measure in any modular user-added subroutine, including UAUOP.. Factors
This is a DMUOM object that contains conversion factors and UOM accessor functions for converting data between USER and P2Internal units of measure in a UAUOP. Refer to Chapter 7.
Side Data Every UAUOP always contains at least one SIDE. See “Data Structure of One Side” on page 5-38. The SIDE concept allows logical partitioning of the functionality and data storage in a unit operation model. Some information, such as the number of sides, applies to all the sides as an aggregate. The data members listed here are members of the UAUOP itself. 5-30 Modular Unit Operations
February 2009
SideCount The number of sides that the UAUOP contains. This is defined using the MAXSides entry in the [Sides] section of the associated INI file. Note: some sides may not require
input data in every simulation.
Sides( ns ) An array of SIDE objects, with one member for SIDE in the UAUOP. Index ns ranges from 1 to SideCount.
each
Integer User Data and Calculated Results All integer data values for a UAUOP are stored in a single array. Additional arrays provide auxiliary information useful to developers. IntExtent A scalar integer that allocates the total storage available for integer data. It is set using the TOTINT entry in the [Data Definition] section of the INI file of the UAUOP.
Storage is counted using 32-bit integer words.
IntCount The number of INT variables and arrays allowed to be defined on INT statements in the [Data Definition] section of the INI file. IntCount is defined using the MAXINT entry in the [Data Definition] section of the INI file of the UAUOP. Each array and each scalar is a single count. IntValue(n) Array of integer values, including all user input and all calculated results. Individual INT variables and arrays are mapped into this array using the IntMapNo array described below. Index n varies from 1 to IntExtent. In keyword input, users use INT statements to provide
actual data values. The size of this array is declared by: INTEGER(4) IntValue( IntExtent )
IntSize(i) The number of 32-bit integer words used to store each INT member. The sizes are defined on INT statements in the [Data Definition] section of the INI file of the UAUOP. Index i varies from 1 to IntCount. IntMapNo(i) Each element i contains the starting storage address of an INT variable or array in the IntValue array. Index i varies from 1 to IntCount. The value of element i is n, the position of the data value in IntValue(n). This is generated from data in the [Data Definition] section of the INI
file.
IntLower(i) The lower limit value of any element of INT scalar or array i. Limits are defined on INT statements in the INI
file. PRO/II uses this to validate user input data. It
PRO/II User-Added Subroutine User Guide
5-31
applies to each element of an array. Index i varies from 1 to IntCount. IntUpper(i) The lower limit value of any element of INT scalar or array i. Limits are defined on INT statements in the INI
file. PRO/II uses this to validate user input data. It applies to each element of an array. Index i varies from 1 to IntCount.
IntName(i) A character string name of up to 32 characters for each integer scalar or array i. It is defined on INT statements in the [Data Definition] section of the INI file of the UAUOP. Index i varies from 1 to IntCount. IntMinName(n) The minimum number of characters that makes IntName(i) unique among all names of INT variables and arrays. It is defined on INT statements in the [Data Definition] section of the INI file Index i varies from 1 to IntCount.
Example: Using Integer Data The following code fragment demonstrates accessing Integer data from UAUOP storage. Assume the UAUOP data object is named UopObj; INT(3) is a scalar and INT(4) is a 4 element array. iLoc3 = UopObj%IntMapNo(3)! locate INT(3) value iVal3 = UopObj%IntValue( iLoc3 ) ! get INT(3) value cNam3 = UopObj%IntName( 3 ) ! get name of INT(3) LimLo = UopObj%IntLower(3 ) ! get lower bound LimHi = UopObj%IntUpper(3 ) ! get upper bound IF( iVal3 .LT. LimLo ) THEN UopObj%IntValue( iLoc3 ) = LimLo ! Set IVAL(3) ELSE IF( iVal3 .GT. LimHi ) THEN UopObj%IntValue( iLoc3 ) = LimHi ! Set IVAL(3) END IF ! Work with element 2 of array INT(4) iLoc4 = UopObj%IntMapNo(4 ) ! first INT(4) location iSize = UopObj%IntSize( 4 ) ! get size of INT(4) IF( iSize .GE. 2 ) THEN ! test size of INT(4) iVal4el2 = IntValue( iLoc4 + 1) ! get element 2 ! ! Test value of element 2 of INT(4) against the upper limit ! and reset it to upper limit if out of range ! IF( iVal4El2 .GT. UopObj%IntUpper(4) THEN IntValue( iLoc4 + 1) = UopObj%IntUpper(4) END IF cNam4 = UopObj%IntName( 4 ) ! get name of INT(4)
5-32 Modular Unit Operations
February 2009
PARAMETER User Data and Calculated Results Parameter data are double precision values. In keyword input, the PAR statements provide user-supplied values. Calculated results also may be stored here, although the DBL data arrays are preferred for this purpose. PAR data are the only UAUOP data available to the PRO/II SPEC/ VARY/DEFINE subsystems. See “Exporting Scalar Parameters” on
page 5-8 and “Importing Scalar Parameters” on page 5-9 earlier in this chapter. The SPEC/VARY/DEFINE subsystems support only scalar values stored in the first 100 elements of the ParValue array. ParExtent A scalar integer that allocates the total storage available for double precision PAR data. It is set by developers using the TOTPAR entry in the [Data Definition] section of the INI file of the UAUOP. Storage is counted using
64-bit words.
ParCount A scalar integer value defined using the MAXPAR entry in the [Data Definition] section of the INI file of the UAUOP. ParCount is the number of PAR variables and arrays allowed on PAR statements in the INI file. Each
array and each scalar is a single count.
ParValue(n) Array of all PAR data values, including all user input and all calculated results. Individual PAR variables and arrays are mapped into this array by the ParMapNo array described below. Index n varies from 1 to ParExtent. In keyword input, users use PAR statements to provide
actual data values. The size of this array is declared by: Real(8) ParValue( ParExtent )
ParUomClass(i) An integer value that identifies the units of measure class of a PAR member. The class applies to all elements of a PAR array. The actual dimensional unit is the user unit declared for the UOM class in the [UOM] section 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 statements in the [Data Definition] section of the INI file of the UAUOP. Index i varies from 1 to ParCount. ParMapNo(i) Each element i contains the starting storage address of a PAR variable or array in the ParValue array. This is generated from data in the [Data Definition] section of the INI file. Index i varies from 1 to ParCount.
PRO/II User-Added Subroutine User Guide
5-33
ParLower(i) The lower limit value of a PAR scalar or any element
of PAR array i. Limits are defined on PAR statements in the INI file. PRO/II uses this to validate user input data. Index i varies from 1 to ParCount.
ParUpper(i) The upper limit value of a PAR scalar or any element of PAR array i. Limits are defined on PAR statements in the INI file. PRO/II uses this to validate user input data. Index i varies from 1 to ParCount. ParName(i) A character string name of up to 32 characters for each PAR scalar or array i. It is defined on PAR statements in the [Data Definition] section of the INI file of the UAUOP. Index i varies from 1 to ParCount. ParMinName(n) The minimum number of characters that makes ParName(i) unique among all names of PAR variables and arrays. It is defined on PAR statements in the [Data Definition] section of the INI file. Index i varies from 1 to ParCount.
Example: Using PAR Data The following code fragment demonstrates accessing PAR data from UAUOP storage. The accessing strategy is analogous to accessing INT data (demonstrated above). Assume the UAUOP data object is named UopObj; PAR(3) is a scalar and PAR(4) is a 4 element array. iLoc3 = UopObj%ParMapNo(3) ! locate PAR(3) value Val3 = UopObj%ParValue( iLoc3 ) ! get PAR(3) value cNam3 = UopObj%ParName( 3 ) ! get name of PAR(3) boundLo = UopObj%ParLower(3 ) ! get lower bound boundHi = UopObj%ParUpper(3 ) ! get upper bound IF( Val3 .LT. BoundLo ) THEN UopObj%ParValue( iLoc3 ) = BoundLo ! Set PAR(3) ELSE IF( Val3 .GT. BoundHi ) THEN UopObj%ParValue( iLoc3 ) = BoundHi ! Set PAR(3) END IF ! Work with last element of array Par(4) iSize = UopObj%ParSize( 4 ) ! get size of PAR(4) IF( iSize .GE. 1 ) THEN ! test size of PAR(4) ! ! get value from last element of PAR(4) ! iLoc4 = UopObj%ParMapNo(4) ! first PAR(4) location Val4n = ParValue( iLoc4 + iSize - 1 ) ! ! Test value of last element of PAR(4) against the upper limit ! and reset it to upper limit if out of range ! IF( Val4n .GT. UopObj%ParUpper( 4 ) THEN
5-34 Modular Unit Operations
February 2009
ParValue( iLoc4 + 1) = UopObj%IntUpper(4) END IF ! ! Get name of array PAR(4) ! cNam4 = UopObj%IntName( 4 ) ! get name of PAR(4)
Double Precision User Data and Calculated Results DBL data are double precision values. In keyword input, the DBL statements allow user-supplied DBL data. Calculated results are stored here, usually after user input values. DBL data are not available to the PRO/II SPEC/VARY/DEFINE subsystems. 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 TOTDBL 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 measure class of a DBL member. The class applies to all elements of a DBL array. The actual dimensional unit is the user unit declared for the UOM class in the [UOM] section 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 statements in the [Data Definition] section of the INI file of the UAUOP. Index i varies from 1 to DblCount. DblMapNo(i) Each element i contains the starting storage address of a DBL variable or array in the DblValue array. This is
PRO/II User-Added Subroutine User Guide
5-35
generated from data in the [Data Definition] section of the INI file. Index i varies from 1 to DblCount. DblLower(i) The lower limit value of a DBL scalar or any element of DBL array i. Limits are defined on DBL statements in the INI file. PRO/II uses this to validate user input data. Index i varies from 1 to DblCount. DblUpper(i) The upper limit value of a DBL scalar or any element of DBL array i. Limits are defined on DBL statements in the INI file. PRO/II uses this to validate user input data. Index i varies from 1 to DblCount. DblName(i) A character string name of up to 32 characters for each DBL scalar or array i. It is defined on DBL statements in the [Data Definition] section of the INI file of the UAUOP. Index i varies from 1 to DblCount. DblMinName(n) The minimum number of characters that makes DblName(i) unique among all names of DBL variables and arrays. Index i varies from 1 to DblCount.
accessing DBL data is completely analogous to accessing PAR data. Refer to the sample (above) for using PAR data.
Text User Data and Calculated Results Text data are strings containing a maximum number of characters as defined in the INI file. In keyword input, TEXT statements allow user-supplied text data. Calculated results may be stored here, typically 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 characters allowed in any TEXT scalar or any element of a TEXT array. It is computed as the largest width defined
5-36 Modular Unit Operations
February 2009
on any TEXT statement in the INI file. For example, local variable cText dimensioned CHARACTER(LEN=Uopobj%TxtMaxChr) :: cText
will be sized adequately to contain one TEXT scalar or one element of any TEXT array defined in the INI file. TxtValue(n) Array of all TEXT data values, including all user input and all calculated results. Individual TEXT variables and arrays are mapped into this array by the TxtMapNo array described below. Index n varies from 1 to TxtExtent. In keyword input, users use DBL statements to provide
actual data values. The size of this array is declared by: Real(8) DblValue( DblExtent )
TxtSize(i) The number of 64-bit floating-point words used to store each DBL member. The sizes are defined on DBL statements 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] section of the INI file. Index i varies from 1 to TxtCount. TxtLower(i) The lower limit value of a DBL scalar or any element of DBL array i. Limits are defined on DBL statements in the INI file. PRO/II uses this to validate user input data. Index i varies from 1 to DblCount. TxtUpper(i) The upper limit value of a DBL scalar or any element of DBL array i. Limits are defined on DBL statements in the INI file. PRO/II uses this to validate user input data. Index i varies from 1 to DblCount. TxtName(i) A character string name of up to 32 characters for each DBL scalar or array i. It is defined on DBL statements in the [Data Definition] section of the INI file of the UAUOP. Index i varies from 1 to DblCount. TxtMinName(n) The minimum number of characters that makes DblName(i) unique among all names of DBL variables and arrays. Index i varies from 1 to DblCount.
PRO/II User-Added Subroutine User Guide
5-37
Example: Using TEXT data The following code fragment illustrates using text data. Assume the UAUOP data object is named UopObj.
Data Structure of One Side Each user-added unit operation includes an array of SIDE data structures. The number of SIDEs in a UAUOP is defined by the developer in the [SIDES] section of the INI file of the user-added unit operation. Data specific to each individual SIDE is stored its own data structure (which is one of the members of the SIDE array). Table 5-8 defines the data in each SIDE. Table 5-8: Side Data Members
Member
Type
Description Identification
Name
C 32
Exist
L4
Descriptive name of the Side Logical side validity flag. TRUE= valid data
Feed Data MaxFeed
I4
Maximum feeds allowed to this side
FeedCount
I4
Number of feed streams to this side
FeedNo(n)
I4
Array of feed stream sequence numbers
FeedID(n)
C 16
Array of feed stream identifiers
Product Data MaxProd
I4
Maximum products allowed from this side
ProdCount
I4
Number of product streams from this side
ProdNo(n)
I4
Array of product stream sequence numbers
ProdID(n)
C 16
Array of product stream identifiers
Thermodynamic METHOD Set TherSetID
C 16
TherSetNo
I4
Thermodynamic METHOD Set identifier 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 contains valid data. When Exist = TRUE, the data in the SIDE object is valid. Do not attempt to use other data
5-38 Modular Unit Operations
February 2009
from this SIDE when Exist = FALSE. This flag should be tested before accessing data from a SIDE that is optional. MaxFeed The maximum number of feeds allowed by this SIDE. MaxFeed is set by developers on each SIDE statement in the [Sides] section of the INI file that configures the UAUOP. FeedCount The total number of feed streams to this side in a simu-
lation. This is the number of stream ID’s appearing as arguments of the FEED keyword on the SIDE card of a UAUOP in keyword input. In PROVISION, FeedCount is the number of streams connected as feed streams to this SIDE of the UAUOP icon in the PFD window. The FeedCount cannot exceed MaxFeed.
FeedNo(n) This array contains the stream numbers of all the feeds to the SIDE. Index n is an integer that may vary from 1 to FeedCount. FeedID(n) An array of stream identifiers for the FEED streams to this SIDE. Index n is an integer that may vary from 1 to FeedCount. MaxProd The maximum number of products allowed by this SIDE. MaxProd is set by developers on each SIDE statement 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 ProdCount cannot exceed MaxProd.
ProdNo(n) This array contains the stream numbers of all the products of the SIDE. Index n is an integer that may vary from 1 to ProdCount. FeedID(n) An array of stream identifiers for the PROD streams to this SIDE. Index n is an integer that may vary from 1 to ProdCount. TherSetID The identifier of the Thermodynamic METHOD set assigned to the SIDE. It is the setid argument of the METHOD=setid on the SIDE statement of keyword
input.
PRO/II User-Added Subroutine User Guide
5-39
TherSetNo The set number of the Thermodynamic METHOD set assigned to the SIDE. It refers to the same METHOD set as TherSetID.
5-40 Modular Unit Operations
February 2009
Chapter 6 UAS Modular Fluids Interface Software This section discusses the facilities available for manipulating fluids in user-added subroutines. All interfacing functions listed in Table 6-1 are available in class_Fluid.mod. This module is part of dynamic link library USERLB6.DLL. Table 6-1: Interface Software for Fluids
class_Fluid.mod Function flash_Fluid
Calculation Routines Calculates the thermodynamic state of a fluid
Kcalc_Fluid Computes K-values, dK/dT, fugacity coefficients, liquid activities, and compressibility.
See . . . 6-3 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.mod Function
Phase Manipulation Functions
zero_FluidPhase Sets all data in one phase to zero
See . . . 6-20
Data Storage Structures TYPE FluidPhase
Secondary fluid data storage. Each phase in a fluid is stored in a separate FluidPhase
PRO/II User-Added Subroutine User Guide
6-34
6-1
Note: The create_Fluid function returns an instance of a fluid as its
returned value. All the other functions include at least one fluid object in their argument lists.
Overview Fluids are modular analogs of PRO/II material streams. They are an enhanced successor of the older user-added streams. Being objectoriented constructs, they are compatible with modular utilities and modular unit operations. They are not generally compatible with the older procedural user-added subroutines.
User Information Users do not directly interact with modular fluids when they run simulations using PRO/II. They still manipulate PRO/II streams as they always have. Users who merely use pre-built modular utilities in PRO/II simulations may find some of the material interesting. However, developers of new modular user-added subroutines use fluids extensively.
Fluid Input Data Requirements There is no direct user interaction with modular fluids when running simulations. PRO/II dynamically populates the fluids passed to user-added subroutines with data extracted from flowsheet streams.
Fluid Output Reports PRO/II does not directly provide any output reports of fluids. Useradded subroutines may extract data from streams, manipulate the fluids, and store fluid data back into streams. In this indirect manner, the standard PRO/II stream report generators provide all available fluid reports.
Developer Information The remainder of this chapter is intended for developers of useradded utilities. The first section that follow describe the interface routines that use fluids to communicate with PRO/II. This is followed by some guidelines that should be helpful in creating fully functional modular utilities and unit operations. Next is an extensive
6-2 UAS Modular Fluids
February 2009
description of the storage objects that store stream and phase data. The chapter ends with a short example.
Calculation Subroutines flash_Fluid The flash_Fluid function computes essential thermodynamic properties that determine the equilibrium state of a fluid. All flash conditions are entered in the fluid object (passed in the argument list) before calling the function. Results return in the same fluid object. Calling sequence: iRet = flash_Fluid( cTypeIn, cSrIdIn, FLObj, iErr)
where: cTypeIn
Required input character string indicating the type of flash calculation requested. Table 6-3 lists the available flash types.
Table 6-3: Flash types Supported By Function flash_Fluid Flash Type and Description cTypeIn “ISO”
Temperature and Pressure specified
“TADIA”
Adiabatic flash at specified temperature
“PADIA”
Adiabatic flash at specified pressure
“TDEW”
Dew point flash at specified temperature
“PDEW”
Dew point flash at specified pressure
“TBUB”
Bubble point flash at specified temperature
“PBUB”
Bubble point flash at specified pressure
“TISEN”
Isentropic flash at specified temperature and entropy. See examples below.
“PISEN”
Isentropic flash at specified pressure and entropy. See examples below.
“TWDEW”
Water dew point flash at specified temperature
“PWDEW”
Water dew point flash at specified pressure
“THCDEW”
Hydrocarbon dew point flash at specified temperature (as opposed to water dew point).
“PHCDEW”
Hydrocarbon dew point flash at specified pressure (as opposed to water dew point).
“TDUTY”
Duty (i.e., enthalpy change) flash at specified temperature and enthalpy change.
PRO/II User-Added Subroutine User Guide
6-3
Table 6-3: Flash types Supported By Function flash_Fluid “PDUTY” Duty (i.e., enthalpy change) flash at specified pressure and enthalpy change. cSrIdIn
Optional input. This is the identifier of a PRO/II stream to be updated when performing the flash. In a user-added unit operation, it is typically the identifier of one of the product streams from the UAUOP. User-added utility subroutines typically use only their member fluids and have no access to PRO/II streams; so set cSrIdIn to a blank. When this argument is blank, no PRO/II streams are updated with results from the flash. To enter a blank, use the blank quoted literal string “ ” as the argument value. See examples below.
FLObj
Required input. This is a Fluid data object of the fluid to flash. Refer to See “Data Structure of class_Fluid” on page 6-27 of this chapter. Before calling flash_Fluid, the calling routine must set all required flash information in this object. Refer to the discussion and examples that follow.
iRet, iErr Output status flags, both integers. iRet is the primary return flag. iErr often returns additional information when
iRet indicates an error, as shown in Table 6-4. Table 6-4: Return Codes from flash_Fluid
6-4 UAS Modular Fluids
iRet
iErr
Description
+3
n/a
Success, VLE + Decant flash performed
+2
n/a
Success, rigorous VLLE flash performed
+1
n/a
Success, VLE (no DECANT) flash performed
0
+1
Success, VLE flash data not stored in stream
0
+2
Success, VLLE flash data not stored in stream
0
+3
Success, DECANT data not stored in stream
0
+4
Success, returned values based on fluid flowrate of 1 kg-mole per second.
-1
-1
Failure, Stream specified in cSrIdIn not found
-1
-7
Failure, invalid flash type in cTypeIn
-1
-8
Failure during attempt to use dummy stream
-1
-9
Failure, corrupt data, data conversion failed
February 2009
Table 6-4: Return Codes from flash_Fluid iRet
iErr
Description
-2
n/a
Failure, internal invalid phase requests
-3
n/a
Failure, unidentified internal error
-4
n/a
Failure, invalid number of components in fluid
-5
n/a
Failure, invalid UOM system in fluid
-6
-1
Failed converting fluid data to PRO/II UOM’s
-6
-2
Failed converting results to USER UOM’s
-7
iType
-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)
Flash calculations failed to converge
Usage Notes The flash_Fluid function requires a fully populated Fluid data object as an input argument. See function "load_Fluid" on page 6-16 to learn about initializing a fluid from a PRO/II stream. Equilibrium Models The thermodynamic METHOD set of the fluid determines the equilibrium 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 indicates the equilibrium model used in the calculations. Refer to iRet in Table 6-4. Flash Types In PRO/II, a flash calculation has NOC + 3 state variables, where NOC is the number of components in the simulation. The component compositions in the Total phase always are used for NOC of these state variables. Specifying two additional state variables essentially reduces the problem to one degree of freedom with one unknown and one equation. Set these variables directly in the fluid data object
PRO/II User-Added Subroutine User Guide
6-5
before calling flash_Fluid. In the following discussion of flash types, assume the fluid object is named FLOBJ. ISO Flash An “ISO” flash specifies both temperature and pressure. Set both temperature and pressure before calling flash_Fluid. For example: FLOBJ%TEMP = 100.0 FLOBJ%PRES = 15.5 iRet = flash_Fluid( “ISO”, “ “, FLOBJ, iERR )
All other flash types specify either temperature or pressure, plus one other variable. TADIA, PADIA Flashes These are adiabatic flashes where the total fluid enthalpy is held constant at its existing value. Either temperature or pressure is specified and the other is calculated. For example: FLOBJ%TEMP = 100.0 iRet = flash_Fluid( “TADIA”, “ “, FLOBJ, iERR)
Temperature is held at the specified value, total enthalpy is held constant, and the calculated pressure returns in FLOBJ%PRES. or FLOBJ%PRES = 15.0 iRet = flash_Fluid(“PADIA”, “ “, FLOBJ, iERR)
Pressure is held at the specified value, total enthalpy is held constant, and FLOBJ%TEMP returns the calculated temperature. Total fluid molar enthalpy may be specified along with temperature or pressure. This is not recommended, but here is an example. FLOBJ%TOTAL%SpEnthM = 12321.0 FLOBJ%PRES = 15.0 iRet = flash_Fluid(“PADIA”, “ “, FLOBJ, iERR)
Total enthalpy and pressure are held at the specified values. Calculated temperature is returned in FLOBJ%TEMP. Instead of setting the enthalpy in the manner, use a DUTY flash to incrementally change the enthalpy (see next). TDUTY, PDUTY Flashes These flashes apply a change to the total enthalpy of the fluid. A special variable in the fluid data object, DUTY, allows the calling routine to set the amount of enthalpy change on a total-stream basis. As 6-6 UAS Modular Fluids
February 2009
usual, also set either the temperature or pressure to complete the specification for these flashes. For example:
The DUTY is applied to the total enthalpy of the fluid and the specified temperature or pressure is held constant. Note: Setting FLOBJ%DUTY = 0.0 in a DUTY flash is equivalent to performing an adiabatic (TADIA or PADIA) flash.
TBUB, PBUB Flashes Specify only temperature or pressure for these flashes. The second state variable is inherent in the flash type. The resulting fluid is all liquid at the temperature and pressure at which the first vapor molecules condense. For example: FLOBJ%TEMP = 100.0 iRet = flash_Fluid(“TBUB”, “ “, FLOBJ, iERR)
The calculated bubble point pressure returns in FLOBJ%PRES. or FLOBJ%PRES = 15.0 iRet = flash_Fluid(“PBUB”, “ “, FLOBJ, iERR)
Data member FLOBJ%TEMP returns the calculated bubble point temperature. TDEW, PDEW Flashes Specify only temperature or pressure for these flashes. The second state variable is implied by the flash type. The resulting fluid is all vapor at the temperature and pressure at which the first vapor molecules begin to condense to a liquid. For example: FLOBJ%PRES = 15.0 iRet = flash_Fluid(“PDEW”, “ ”, FLOBJ, iERR)
The calculated dew point temperature returns in FLOBJ%TEMP. or FLOBJ%TEMP = 100.0 iRet = flash_Fluid(“TDEW”, “ ”, FLOBJ, iERR)
PRO/II User-Added Subroutine User Guide
6-7
The calculated dew point pressure returns in FLOBJ%PRES. TWDEW, PWDET These flashes compute the conditions at which the first water molecules begin to condense to liquid. In non-rigorous VLE with DECANT, this is where the DECANT liquid phase first begins to condense. In rigorous VLLE systems, this is where the L2 (heavy) liquid sub-phase first begins to condense. The L2 liquid sub-phase has a flowrate of zero. The resulting fluid may be all vapor, or vapor with some L1 (hydrocarbon) liquid. Specify only temperature or pressure for these flashes. The second state variable is implied by the flash type. For example: FLOBJ%PRES = 15.0 iRet = flash_Fluid(“PWDEW”,“ ”, FLOBJ, iERR)
The calculated temperature returns in FLOBJ%TEMP. or FLOBJ%TEMP = 100.0 iRet = flash_Fluid(“TWDEW”,“ ”, FLOBJ, iERR)
The calculated pressure returns in FLOBJ%PRES. THCDEW, PHCDEW These flashes compute the conditions at which the first hydrocarbon molecules begin to condense to liquid. In non-rigorous VLE with DECANT, this is where the non-DECANT liquid phase first begins to condense. In rigorous VLLE systems, this is where the L1 (light) liquid sub-phase first begins to condense. The L1 liquid sub-phase has a flowrate of zero. The resulting fluid may be all vapor, or vapor with some L2 (water, DECANT) liquid. Specify only temperature or pressure for these flashes. The second state variable is implied by the flash type. For example: FLOBJ%PRES = 15.0 iRet = flash_Fluid(“PHCDEW”, “ ”,FLOBJ,iERR)
The calculated temperature returns in FLOBJ%TEMP. or FLOBJ%TEMP = 100.0 iRet = flash_Fluid(“THCDEW”, “ ”,FLOBJ, iERR)
The calculated pressure returns in FLOBJ%PRES. TISEN, PISEN Flashes These types perform isentropic flashes on a fluid. They are entropy analogs of the TADIA and PADIA flash types described earlier. The calling routine first sets the total fluid entropy, then calls one of 6-8 UAS Modular Fluids
February 2009
these flashes. A special variable in the fluid data object, Entropy, allows the calling routine to set the entropy on a total-fluid basis. Also, set either the temperature or pressure to complete the specification for these flashes. For example: FLOBJ%ENTROPY = 97531.0 FLOBJ%PRES = 15.0 iRet = flash_Fluid(“PISEN”, “ ”,FLOBJ, iERR)
The calculated temperature is available in FLOBJ%TEMP. or FLOBJ%ENTROPY = 97531.0 FLOBJ%TEMP = 15.0 iRet = flash_Fluid(“TISEN”, “ ”,FLOBJ, iERR)
The calculated pressure is available in FLOBJ%PRES. Using Temperature and Pressure Estimates Flash calculations can be computationally expensive, especially if they are repeatedly executed in large iterative loops. Routine flash_Fluid allows the calling UAS to provide temperature and pressure estimates to start calculations near the solution values. The dimensional units of the estimates are the same user units used throughout the UAS. Available estimates are: EstTemp Specifies the temperature used to start flash calculations. EstPres
Specifies the pressure used to start flash calculations.
Estimates are declared in the fluid object (FLOBJ in this discussion) before calling flash_Fluid. They are cleared after each flash, so they must be initialized before each call to flash_Fluid. Example: A fluid initially is ISO-flashed at specified temperature and pressure. Duty is added that is expected to raise the temperature by 10 degrees. The pressure is incremented by 1.2 pressure units. The new fluid state is determined by a subsequent DUTY flash. A temperature estimate is applied before starting the DUTY flash. FLOBJ%TEMP = 100.0D+0 FLOBJ%PRES = 15.0D+0 iRet = flash_Fluid( “ISO”, “ “, FLOBJ, iErr ) . . . FLOBJ%DUTY = 1234.5D+0 FLOBJ%EstTEMP = FLOBJ&TEMP + 10.0D+0 FLOBJ%PRES = FLOBJ%PRES + 1.2D+0 iRet = flash_Fluid( “DUTY”, “ “, FLOBJ, iErr )
PRO/II User-Added Subroutine User Guide
6-9
Retrieving Flash Results After successfully completing its calculations, function flash_Fluid returns all fluid results in the fluid data object passed through the argument list of the call. All data for each phase and sub-phase are stored in the fluid Phase objects that are members of the fluid. Returned data is complete, including transport properties, K-values, vapor fugacities, and either liquid fugacities or liquid activity coefficients, 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 specifies a METHOD set declared in the simulation, which in turn determines the equilibrium model. Table 6-5 lists the phase objects populated by flash_Fluid for each equilibrium model. Table 6-5: Fluid Phases Returned from flash_Fluid Equilibrium Model iRet = 1 Phase Name
VLE
iRet = 2
iRet = 3
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
Molec wt solids
Molec wt solids
Molec wt solids
No
No
No
Solid NMWSolid
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 x3Tot x3Tot x3Tot
Kcalc_Fluid In some situations, it may be desirable to obtain K-values, dK/dT’s, vapor fugacities, liquid fugacities, or liquid activity coefficients without performing a flash. Function kcalc_Fluid provides this capability. Purpose: Compute K values, dK/dT, Fugacities or Liquid Activity coefficients, and compressibility (Z). Call PRO/II to perform the calculations. All data in and results out are in the Fluid Object. Calling sequence: iRet = Kcalc_Fluid( cPhase, cDeriv, cComp, & FLObj, ieStat )
Where: cPhase
Phases of interest. This is a keyword entry input as a quoted literal string. Available options are: “BULK” or “LIQU” requests bulk liquid properties and
vapor phase fugacities. “SUBL” or “LSUB” requests liquid sub-phase (L1 and L2)
properties and vapor fugacities. cDeriv
Input option to compute K-value derivatives with respect to time. Available keywords are: “NONE” Omit K-value derivatives. This is the default
when this argument is blank. “DKDT” Compute and return K-value derivatives. cComp
Composition dependency flag. Input as a quoted literal keyword. Available options are: “COMP” Use the mole fraction compositions supplied in the FLOBJ phase objects. This is the default when the
entry is blank. Mole fractions must be pre-loaded in the following phase arrays: FLOBJ%VAPOR%XFracM() Always required. FLOBJ%LIQUID%XFracM() Required for cPhase = “BULK” FLOBJ%L1%XFracM() Required for cPhase = “SUBL” FLOBJ%L2%XFracM() Required for cPhase = “SUBL” “NOCOMP” Compute properties from special code with-
out using composition data. Valid only when using SRK. PRO/II User-Added Subroutine User Guide
6-11
FlObj
This is a fluid object that contains the composition data required by the cPhase and cComp arguments. It returns all the calculated results.
ieStat
An output integer that returns information about calculation 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 conjunction with argument iErr when errors occur. Table 6-6 defines the returned values. Table 6-6: Return Codes from Kcalc_Fluid iRet
iErr
Description
+2
n/a
Success, returned vapor, L1, L2 phase results
+1
n/a
Success, returned vapor, and bulk liquid results
0
n/a
Success (this value is never returned)
0, 1, 2
-1
Invalid cPhase, returned bulk liquid values
0, 1, 2
-2
Invalid cPhase, returned L1, L2 values
0, 1, 2
-3
Missing XFracM data - dK/dT values omitted
-1
n/a
Invalid temperature
-2
n/a
Invalid pressure
-3
-1
Invalid vapor fraction
-3
-2
Invalid (bulk) liquid fraction
-3
-3
Invalid L1 fraction
-3
-4
Invalid L2 fraction
-4
-1
Vapor fugacity calculations failed
-4
-2
Bulk liquid calculations failed
-4
-3
L1 calculations failed
-4
-4
L2 calculations failed
Retrieving Results After successfully completing its calculations, function Kcalc_Fluid returns all results in the fluid data object passed through the argument list of the call. Returned data includes K-values, dK/dT values, vapor fugacities, and either liquid fugacities or liquid activity coefficients, as appro6-12 UAS Modular Fluids
February 2009
priate, depending upon equilibrium model. See “Equilibrium Models” on page 6-5 of this chapter for more information. The phases that Kcalc_Fluid populates depends on the cPhase input argument. Table 6-7 illustrates the data that may be returned in each phase. Table 6-7: Results Returned by Kcalc_Fluid Summary of Data Returned from Kcalc_Flash Phases that Return Data for Various Equilibria Property
Rigorous VLLE EOS
LACT
VLE + DECANT
VLE EOS
LACT
EOS
LACT
KVal( NOC )
L1, L2 L1, L2
L
L
L
L
dKdT ( NOC )
L1, L2 L1, L2
L
L
L
L
V
V
V
V
L
L
L
L
V
V
V
V
ZKval
XFug( NOC )
V
V
L1, L2 L1, L2 V
V
L1, L2
XLact( NOC )
L L1, L2
L L
L
L = Bulk liquid, L1 = Non-decant (light) liquid sub-phase, NOC = number of L2 = DECANT (heavy) liquid sub-phase components EOS = Equation of State, LACT = Liquid Activity method
Example: The following illustrates calling Kcalc_Fluid to compute and retrieve some of the calculated properties. Assume the fluid is the fluid data object. The blank arguments use the default setting “NONE” for argument cDeriv and “COMP” for argument cComp. 1 2 3 4 5 6 7
Line 4 retrieves the calculated compressibility of the vapor Line 5 retrieves the vapor phase fugacity of component 3. Lines 6 and 7 retrieve the K value and its derivative for component 3 in the bulk liquid phase. All the retrieved properties were computed by Kcalc_Fluid.
PRO/II User-Added Subroutine User Guide
6-13
Fluid Manipulation Functions The functions described in this section allow user-added subroutines to manipulate fluid objects in user-added subroutines. All are members of class_Fluid or class_FluidPhase. To access the fluid functions, the class_Fluid module must be declared with a USE statement in each user-added subroutine that uses fluids. See “Subroutine Coding Requirements” on page 6-21.
create_Fluid This function allows user-added subroutines to erect instances of fluids. It dynamically allocates all arrays and computer resources needed by a fluid. Call this function before attempting to use the fluid in any other way. It is intended for use in unit operation subroutines. 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 function. 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 characters. The first character should be an upper or lowercase letter (A-Z). The ID should be unique among all fluid instances in the subroutine.
NOC
The total number of components in the current simulation. It is a required integer input argument. This should be retrieved from the NOC member of a UAUOP or UASOBJ data structure.
6-14 UAS Modular Fluids
February 2009
FacObj
A fully populated dimensional units object created by class_DMUOM. It is a required input argument. The most convenient way to obtain this object is to use the Factors member from a UAUOP data structure.
ieStat
A scalar integer output variable that returns the status code of the calculations. Negative values indicate errors that cause the calculations to fail. Returned values are: +1 = success, created fluid 0 = success (should never return) -1 = Failed, missing newID -2 = Failed, missing NOC
Example of Using create_Fluid: The following sample demonstrates proper usage of the function to dynamically create a fluid in a unit operation subroutine. Only code related to using create_Fluid is shown. 1 2 3 4 5 6 7 8 9 10 11 12 13 14
Line 4 makes class_Fluid available in the subroutine, so function 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 dimensional units data structure that is a member of the UAUOP object.
PRO/II User-Added Subroutine User Guide
6-15
load_Fluid This function populates a fluid with data from a PRO/II stream. The fluid already must exist. It may be a pre-defined fluid from a UASOBJ object or one that was locally created. Use "create_Fluid" on page 6-14 to create a fluid locally in a subroutine. Calling sequence: iRet = load_Fluid( cSrIdIn, FLObj )
Where: cSrIdIn
The identifier of the PRO/II stream from which data is extracted. This is the same ID used to identify the stream in PRO/II keyword input and in the flowsheet (PFD) window of PROVISION.
FLObj
The fluid object that receives data from the stream.
iRet
A local integer scalar variable that receives the status flag returned as the function value. Returned values are: +1 Success, the fluid is loaded with stream data. 0 Success (never returned). -1 Failure, could not load data into the fluid.
When called, load_Fluid fully populates the fluid with as much data as possible. This includes generated properties that it derives from the data in the PRO/II stream. However, when the stream data is not complete, the resulting fluid data also will be incomplete. Any preexisting data in the fluid is overwritten during loading. During the loading process, load_Fluid associates the fluid with the PRO/II stream. The ID of the associated stream is stored in data member P2StreamID of the fluid. For example, for a fluid named FLObj, access the associated stream ID using FLObj%P2StreamID. The most common method of finding a PRO/II stream is to use one of the feeds to a user-added unit operation. File UOP1CALC.f90 in sample project ExUOP.DSW demonstrates this approach.
6-16 UAS Modular Fluids
February 2009
copy_Fluid Data from one fluid are copied to a second fluid by this function. Fluid identification information is not copied. All other data in the source fluid and its phases are copied to the target fluid. If the source fluid has an associated PRO/II stream, the target fluid also becomes associated with that stream. Calling sequence: iRet = copy_Fluid( FLin, FLout, ieStat )
Where: iRet
Returned status flag, a local scalar integer variable. Possible returned values are: +1 Success, all phases copied, ieStat does not apply. 0 Success, some phases not copied, See ieStat. -1 Failure, source fluid FLin is invalid (FLin%Exist=.FALSE.). -2 Failure, target fluid FLout invalid (FLout%Exist=.FALSE.).
FLin
The source FLUID object containing the data to copy.
FLout
The target FLUID object that receives the copied data.
ieStat
Returned scalar integer status flag indicating the status of copying individual phases. Set only when iRet = 0 (conditional success). It contains packed digits, with each digit being a flag for a specific phase. The number of digits indicates the number of phases not copied. The value of each digit indicates a phase that did not copy: Value Phase that did not copy 0
Complete success, all phases copied.
1
Total phase did not copy.
2
Vapor phase did not copy.
3
Bulk Liquid phase did not copy.
4
L1 liquid sub-phase did not copy.
5
L2 liquid sub-phase did not copy.
6
Solid phase did not copy.
7
NMWSolid phase did not copy.
PRO/II User-Added Subroutine User Guide
6-17
store_Fluid Use this function to store FLUID data in a PRO/II stream. Because fluids are virtual objects, they cannot persist their data themselves. PRO/II user-added unit operations usually compute the state of their product streams. This function allows user-added subroutines to use fluids for all calculations; then store the fluids in the product streams. Data stored in a stream is available throughout the simulation 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) window of PROVISION.
FLObj
The fluid object from which data is copied.
iRet
Returned status flag, a local scalar integer variable. Possible returned values are: +1 Success, all data stored successfully. 0 Success (never returned). -1 Failure, cSrIdIn is invalid. -2 Failure, some fluid phase objects are invalid. -3 Failure, unspecified reasons. -4 Failure, invalid number of components (in FLObj). -5 Failure, invalid conversion factors in FLObj%Factors. -6 Failure, could not convert data from User to P2 UOM’s.
Note: Many fluid properties are derived values that streams do
not store. For example, fluid data includes many properties on both a mole and weight basis. PRO/II streams usually store only molar properties and molecular weight. The weight-based properties are easily computed from the molar properties. The safest strategy for generating complete fluid properties is to flash the fluid before storing it in a PRO/II stream.
6-18 UAS Modular Fluids
February 2009
free_Fluid This function destroys an instance of a fluid by de-allocating and releasing all the dynamic computer resources used by the fluid. This function should be used only for fluids instantiated by using create_fluid in a user-added subroutine. It never should be applied to a pre-defined fluid that is a member of a UASOBJ passed from PRO/II through the subroutine call list. Calling sequence: iRet = free_FLUID( FLObj )
Where: FLObj
The instance of a fluid to be freed.
iRet
Returned status flag, a local scalar integer variable. Possible returned values are: +1 Success, all resources successfully released. 0 Success, all resources successfully released. -1 Failure, unspecified resources were not released.
The static members of the fluid remain available after calling free_fluid. These are listed in Table 6-8 on page 27. For example, all the member phase objects are destroyed, but the phase validation flags remain available. There is no real need to test the iRet status variable. There are no further actions the user-added subroutine can perform to release the fluid. Developers may wish to test iRet and issue a message or warning (see "UAERROR" on page 3-8) during development for debugging purposes. This is a non-fatal condition that does not need to be reported in a release version. Normal exit from the subroutine usually releases unneeded resources through the close-out procedures that automatically are performed when running Fortran applications.
PRO/II User-Added Subroutine User Guide
6-19
zero_FluidPhase Purpose: Reset all data members of a fluid phase object to values of zero or missing. Only floating point data is processed. Calling sequence: iRet = zero_FluidPhase( NOC, PhObj )
Where: NOC
The total number of components in the simulation.
PhObj
The fluid phase object to be reset.
iRet
Returned status flag, a local scalar integer variable. Possible returned values are: +1 Success, all phase data set to a value of zero or missing. 0 Never returned. -1 Never returned. -2 Failure, PhObj is not allocated (PhObj%Exist = FALSE). -3 Failure, NOC is invalid (less than 1 or greater than 10000).
Fluid phases are members of fluids, and the fluid manipulation functions initialize phase data when appropriate. Usually, there is little need to call this function. However, here is an example that uses zero_phase to reset phase Vapor in a fluid named myFluid: iRet = zero_FluidPhase(myFluid%NOC,myFluid%Vapor)
This function operates on the floating-point phase properties listed in Table 6-8 on page 27 of this chapter. It does not alter any integer or character data. The following data members are set to zero. RateM
RateV
FracM
FMDecant ZKval
RateWt
RateVstd
FracWt
FWDecant XFracM
All other floating-point properties in Table 6-8 are set to “missing”. Module class_DMUOM defines this value as parameter DUAMISS. It is a large negative value (-1.5D35). Another parameter available in class_DMUOM is DUATEST with a value of -1.0D-35. To determine when a value is set to missing, use the following: IF( myFluid%myPhase%property .LT. DUATEST ) THEN
the value is missing. Refer to Chapter 7 for more information.
6-20 UAS Modular Fluids
February 2009
Fluid Guidelines Project Requirements Any user-added project that uses fluid objects must be configured to satisfy the following two requirements: The project compiler settings must include the path to file class_Fluid.mod. See “Setting the Module Path for the Fortran Compiler” on page 2-23 of Chapter 2, ”Modular UAS Build Procedures”. The project linker settings must include the path to file UserLb6.lib. See “Setting the Import Library Path for the Linker” on page 2-24 of Chapter 2, ”Modular UAS Build Procedures”.
Subroutine Coding Requirements User-added subroutines that use fluids must be declared module class_Fluid in a USE statement. The two scenarios of most interest are discussed here.
Declaring Fluids in Utility Subroutines (UAUTIL) PRO/II passes an instance of class_UASOBJ to each utility subroutine through the argument list. This class already includes fluid objects as members, so using class_UASOBJ automatically provides access to class_Fluid. This eliminates the need for a specific USE statement for class_Fluid. Similarly, every fluid contains fluidPhase objects, so using class_Fluid automatically provides access to class_FluidPhase. The following code fragment illustrates this. SUBROUTINE MYUAUTIL( UAUTIL ) USE class_UASOBJ TYPE(UASOBJ) :: UAUTIL REAL(8) :: TempV, DensityL ! ! Retrieve temperature of fluid FlVapor, a member of UAUTIL ! TempV = UAUTIL%FlVapor%TEMP ! ! Retrieve the density of the bulk liquid sub-phase of this fluid ! DensityL = UAUTIL%FlLiquid%Liquid%Density
PRO/II User-Added Subroutine User Guide
6-21
Declaring Fluids in Unit Operations (UAUOP) User-added unit operations are based on class_UAUOP, which does not provide automatic access to the class_Fluid module. Therefore, an explicit USE statement is needed. Also, explicit TYPE statements are required to declare variables as fluid objects. Since all fluids include fluidPhase objects, no additional USE statement is required to access class_FluidPhase. The following annotated code extract demonstrates the construction of two fluids. SUBROUTINE MYUAUOP( UOPOBJ ) USE class_UAUOP USE class_Fluid ! required to use fluids ! TYPE(UAUOP) :: UOPOBJ INTEGER(4) :: iRet, NOC ! ! Declare 2 local variables as fluid objects TYPE( FLUID ) :: Fluid1, Fluid2 ! NOC = UOPOBJ%NOC ! number of components ! ! Allocate resources for the two fluid objects iRet = create_Fluid(“F1”, NOC, Fluid1, iRet) iRet = create_Fluid(“F1”, NOC, Fluid1, iRet)
Usage of class_Fluid After the basic fluid declarations described above are complete, the fluids are available for use. The basic steps for working with fluids are: 1.
Create Instances of Fluids. Fluids were designed to be created within UAUOP subroutines. Use function "create_Fluid" on page 6-14 to allocate the computer resources needed by these virtual constructs. This step is not required when developing a UAUTIL subroutine that uses only the fluids that are members of UASOBJ data structures passed as arguments in the call list.
2.
Populate Fluid Instances with Data. The subroutine may initially populate each fluid in a number of ways: Use the direct-access method of coding to store data in the data members. Typically, PRO/II requires the temperature and pressure in the encompassing fluid object. It also requires the Total phase molar flowrate in Total%RateM and molar compositions in array Total%XFracM.
6-22 UAS Modular Fluids
February 2009
Use function "load_Fluid" on page 6-16 to fully populate a fluid with data from a PRO/II stream. 3.
Use Fluids to Perform Tasks. Make copies of fluids (see function "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 module class_Fluid.mod. It is required for class_UASOBJ to build properly. Using the sample user-added projects installed with PRO/II satisfies this requirement. Pre-defined FLUID structures are available only as members of a UASOBJ instance that is passed to a UAUTIL subroutine. The UAUOP object passed to user-added unit operations does not contain pre-defined fluids. A user-added utility subroutine does not need to “USE” class_Fluid. Class_UASOBJ automatically makes the module available. Unit operation subroutines must “USE” class_Fluid. Pre-defined fluids in UASOBJ have specific names assigned by PRO/II. Refer to the chapters that describe individual utility subroutines to determine exactly which fluids the subroutine supports. All references to data in pre-defined fluids must be in the form of calls to data members of UASOBJ. This includes access to any data in the fluid phases. Fluids instantiated using the create_Fluid function are referenced as independent entities (i.e., not as members of UASOBJ). Only direct member addressing is available for accessing fluid data. The class_Fluid module does not implement accessor functions, so indirect addressing is not available.
PRO/II User-Added Subroutine User Guide
6-23
Dimensional Units Fluids use the dimensional units of measure in effect in the unit operation or utility subroutine. The end-user must declare the developer’s set of units when registering the subroutine with PRO/II. See “Registering a UAS with PRO/II” on page 2-5 of Chapter 2 for a description of the registration process. The registered set of dimensional units applies to all data exchanged between PRO/II and a user-added subroutine. This is independent of the units used for input data in a simulation. Refer to Chapter 7, ”User-Added Units of Measure”, for lists of the available sets of units, including all dimensional classes.
Support for Solids-Forming Components Module class_Fluid supports molecular weight solids in the Solid phase. This includes all the member functions as well as the data storage object. Note: Non-Molecular weight solids are not supported in class_Fluid. Member phase NMWSolid provides storage, and the manipulation functions (create_fluid, load_Fluid, copy_Fluid, store_fluid, and free_Fluid) handle the data properly. However, calculation function flash_Fluid will return invalid results when
NMWSolid components are present in the fluid.
6-24 UAS Modular Fluids
February 2009
class_Fluid.mod This module makes fluid data objects available to the UASOBJ data structure in user-added utility subroutines. It provides the create_Fluid and free_Fluid functions that allow user-added unit operations to instantiate instances of fluids. Additional manipulation functions and calculation functions facilitate using fluids. Each FLUID contains one or more FluidPhase objects. Each FluidPhase 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 predefined fluids are available as members of UASOBJ only in UAUTIL subroutines. UAUOP subroutines must instantiate and manage fluids using the manipulation functions described earlier in this chapter.
Direct Member Access in class_Fluid Direct member addressing accesses data by direct reference to the data member. Fortran 90 defines the percent symbol % as the access operator. Direct member addressing takes the form: “parent % member”. The “parent % member” construct is extensible to any level in the data structure. Consider the following contrived example (line numbers added for clarity): 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
RmoleV = FluidObj%Vapor%RateM Ratec6 = RmoleV * c6MFVap FluidObj%Vapor%XFracM( 6 ) = 0.0D+0 RmoleV = RmoleV - Ratec6 FluidObj%Vapor%RateM = RmoleV FluidObj%Vapor%FracM = & RmoleV / RmoleTot FluidObj%Total%RateM = & RmoleTot - Ratec6 END IF 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 contains 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 validity flags for each phase. (Members Status, VapStatus, and L1Status are the validity flags for the Total, Vapor, and L1 phases, respectively.) 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 FluidPhase 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 component 6 from the Vapor phase. Line 20 computes the mole rate of component 6 in the vapor phase. Line 21 zeroes the mole fraction of component 6. 6-26 UAS Modular Fluids
February 2009
Line 22 adjust the vapor rate to remove component 6. Lines 23 and 24 adjust the fraction of vapor in the fluid. Lines 25 and 26 subtracts the vapor rate of component 6 from the total phase rate, removing component 6 from the fluid. This demonstrates the power of the direct access method to access data in any fluid. Developers should test for the existence of a fluid before attempting to access data from it (refer to lines 12, 16, and 17).
Indirect Member Addressing in class_Fluid The class_Fluid module does not implement accessor functions. For this reason, indirect member addressing is not supported for data in fluids.
Data Structure of class_Fluid Table 6-8 lists all the member data in a fluid. Several fluid phases are members of the fluid. All the phases are always created when the fluid is allocated using function create_Fluid. Pre-defined fluids that are members of the UASOBJ class do not include all the phases. In pre-defined fluids, the Total phase always is present. Other phases may be missing, depending upon the phase state of the fluid. For example, the pre-defined FLVapor fluid does not include a Liquid, L1, or L2 phase. Before attempting to access data in fluid phase members, developers should test the phase validation flags to ensure the phase is valid. Table 6-8: class_Fluid Data Members Member
Type
Description Fluid Identification
ID IdNo
C12 Identifies the fluid, typically “Vapor”, “Liquid”, or “Iface”. I4
An ID number assigned to the Fluid. Typically, 1 = Vapor – an all vapor stream 2 = Liquid – an all liquid stream 3 = L1 liquid sub phase (not available) 4 = L2 liquid sub-phase (not available) 5 = Total phase (always present)
Name
C40 A name for the Fluid, typically “Vapor Fluid”, “Liquid Fluid”, or “Interface Fluid”.
P2StreamID
C20 Identifier of associated PRO/II stream General Data
PRO/II User-Added Subroutine User Guide
6-27
Table 6-8: class_Fluid Data Members DiagnosticFl
I4
Diagnostic print flag for code debugging
Dimensional Units Conversion Factors UomSystem Factors
I4
Identification number of dimensional units system
DMUOM data object. See Chapter 7. Thermodynamic Method Identification
TherSetNo TherSetID
I4
Thermodynamic METHOD set number
C16 Thermodynamic METHOD set identifier Component Data
NOC
I4
Total number of components in problem.
NOCMW
I4
Number of Molecular weight components in a simulation (excludes NMW Solids components).
CompIndex(i)
I4
Internal component numbers, in input order. i = 1, NOC Fluid Properties
TEMP
DP Temperature of the fluid
PRES
DP Pressure of the fluid
FMDecant
DP Mole fraction DECANT component in total stream
FWDecant
DP Weight fraction DECANT component in total stream Flash Control Flags and Estimates
EstTemp
DP Temperature estimate
EstPres
DP Pressure Estimate
DUTY
DP Enthalpy change applied by a DUTY flash
Entropy
DP Total stream entropy for a PISEN or TISEN flash
EstKValues
I4
Flag for flash to reuse previous K values Phase Members
Total
FluidPhase
Total Fluid phase object (always present)
Vapor
FluidPhase
Vapor phase
Liquid
FluidPhase
Bulk Liquid phase
L1
FluidPhase
Light (non-decant) liquid sub-phase
L2
FluidPhase
Heavy (Decant) liquid sub-phase
6-28 UAS Modular Fluids
February 2009
Table 6-8: class_Fluid Data Members Solid
FluidPhase
Molecular-weight Solids phase
NMWSolid
FluidPhase
Non-Molecular-weight Solids phase
Validation Flags (always present) Exist
L4
Fluid existence flag. Always.TRUE. if fluid exists.
Status
L4
Status flag. .TRUE. if Total phase exists.
VapStatus
L4
Status flag. .TRUE. if Vapor phase exists.
LiqStatus
L4
Status flag. .TRUE. if Bulk Liquid phase exists.
L1Status
L4
Status flag. .TRUE. if L1 sub-phase exists.
L2Status
L4
Status flag. .TRUE. if L2 sub-phase exists.
SolidStatus
L4
Status flag. .TRUE. if Solid phase exists.
NMWStatus
L4
Status flag. .TRUE. if NMWSolid phase exists.
Fluid Identification The data in this section identifies the fluid. PRO/II automatically generates this information when it creates a UASOBJ. Users cannot modify or access this information. Developers may find it useful during the debugging stages of subroutine implementation.
Component Data Each fluid includes basic information about the components in a simulation. Since fluids typically are members of a UASOBJ data structure, the component data of a fluid duplicates the component data of the parent UASOBJ. Developers usually retrieve component data from UASOBJ, in which case retrieving component data from a fluid is not necessary. NOC
Total number of components in the simulation, including NMWSolids.
NOCMW
Number of molecular weight components, including molecular weight Solids. NMWSolids are excluded.
CompIndex(i) Internal component numbers, in input order. i=1, NOC
PRO/II User-Added Subroutine User Guide
6-29
Fluid Properties A few properties are so useful that they have storage members directly in the main fluid structure. Most properties are stored in the fluid phase members. Temp
Temperature of the fluid.
Pres
Pressure of the fluid.
FMDecant
Mole fraction of DECANT phase in the total fluid.
FWDecant
Weight fraction of DECANT phase in the total fluid.
The following code extract illustrates retrieval of properties from the pre-defined fluid named Liquid that is a member of a UASOBJ structure named UaUtil. SUBROUTINE EFG( UaUtil ) USE class_UASOBJ TYPE(UASOBJ), INTENT(INOUT) :: UaUtil REAL(8):: TempI, PresI, RateI, FvapI, FliqI . . . TempI = UaUtil%Liquid%TEMP PresI = UaUtil%Liquid%PRES RateI = UaUtil%Liquid%FMDecant FvapI = UaUtil%Liquid%FWDecant
Thermodynamic Method Set Identification PRO/II simulations may contain several METHOD sets. The entries in this section identify the thermodynamic METHOD set assigned to a fluid and all its phases. The integer number of the METHOD set assigned to the fluid. This value is used in PRO/II call-back routines to perform calculations.
TherSetNo
TherSetID
The character identifier of the METHOD set assigned to the fluid. It contains up to 16 characters. TherSetID is not used by PRO/II call-back routines; TherSetNo is used instead. TherSetID may be useful when writing reports from user-added subroutines. It has no effect on any calculations.
The following fluid functions propagate TherSetNO and TherSetID in the following ways: create_Fluid assigned the DEFAULT METHOD when it instanti-
ates a fluid.
6-30 UAS Modular Fluids
February 2009
load_Fluid assigns the PRO/II stream METHOD to the fluid dur-
ing the data loading process. store_Fluid assigns the fluid METHOD to the PRO/II stream
that stores the fluid data. copy_Fluid assigns the source fluid METHOD to the target fluid
during the copy operations. flash_fluid uses the fluid METHOD to perform the flash calcula-
tions. If a PRO/II stream is specified for the flash, the fluid METHOD is assigned to the specified stream.
Phase Members Fluids store most of their data in member data structures that represent different fluid phases. The Total phase stores most of the properties of the fluid as a whole. Other phase members, Vapor and Liquid in particular, store properties of each phase present in the fluid. Fluids created in a user-added subroutine using the create_Fluid function always include all the phases listed in Table 6-9. This includes all fluids created in user-added unit operation subroutines. Table 6-10 does not apply to these fluids. . Table 6-9: Phases Available in a Fluid Total
Properties of the overall fluid; i.e., the Total phase. This phase always is present in a fluid.
Vapor
Properties of the Vapor phase of a fluid. This phase may or may not be present.
Liquid
Properties of the bulk Liquid phase in a fluid. This phase may or may not be present.
L1
Properties of the L1 liquid sub-phase. This phase may or may not be present.
L2
Properties of the L2 liquid sub-phase. This phase may or may not be present.
Solid
Properties of the molecular-weight solids phase. This phase may or may not be present.
NMWSolid Properties of the non-molecular-weight solids phase. This phase is not yet fully supported by PRO/II.
PRO/II User-Added Subroutine User Guide
6-31
Table 6-10 lists the phases that may be present in each pre-defined fluid member of a UASOBJ data structure. Currently, none of the pre-defined fluids support the L1 or L2 phase. Table 6-10: Phases in Pre-defined Fluids of a UASOBJ Data Structure Phases Present in a Fluid Fluid Name
Total
Vapor
Liquid
L1
L2
Vapor
Yes
Yes
-
-
-
Liquid
Yes
-
Yes
-
-
Iface
Yes
Yes
Yes
-
-
Validation Flags Fluid validation flags allow developers to test for the existence and availability of data in a fluid object and its phase members. The flags should be tested before attempting to access data from fluid objects. Exist
Fluid existence flag, a logical variable. Always TRUE if fluid exists. Do not attempt to use data from the fluid if this flag is FALSE. Test this variable first, before attempting to access any other data in the fluid.
For all the phase flags listed below, a value of +1 indicates data has been loaded in the phase member of the fluid. Do not attempt to use data when the value is 0 or -1. Status
Status flag for the entire fluid. When the value = 1, the overall fluid and the Total fluid phase are present and valid. This includes data for Fluid Identification, the Validation Flags, Component Data, and the Fluid Properties. The phase members must be tested individually using the flags listed below.
VapStatus
Vapor phase status flag. When this flag has a value =1, data in the Vapor phase is available for use.
LiqStatus
Liquid phase status flag. When this flag has a value =1, data in the Liquid phase is available for use.
L1Status
Status flag for L1 liquid sub-phase. When this flag has a value =1, data in the L1 sub-phase is available for use.
L2Status
Status flag for L2 liquid sub-phase. When this flag has a value =1, data in the L2 sub-phase is available for use.
SolidStatus
Status flag for the (molecular-weight) solids phase. When this flag has a value =1, data in the Solid phase is available for use.
6-32 UAS Modular Fluids
February 2009
NMWSolid
Status flag for the Non-Molecular-Weight solids phase. When this flag has a value =1, data in the NMWSolid phase is available for use.
The following sample code illustrates one of many possible ways to use the fluid validation flags. The only intent is to illustrate the logic branching in Fortran code. The example is not intended to execute successfully without further development. SUBROUTINE EFG( Obj ) USE class_UASOBJ TYPE(UASOBJ), INTENT(INOUT) :: Obj INTEGER(4) :: IfErrFl, IfErrT, IfErrV, IfErrL ! Test for existence of Interface Fluid IF( Obj%Iface%Exist ) THEN IfErrFl = 0 ! Fluid Exists. ! ! Test validity of Total phase. IF( Obj%Iface%Status .EQ. 1 ) THEN IfErrT = 0 ! Total fluid data is valid ELSE IfErrT = 1 ! Error – invalid total fluid. ENDIF ! ! Test validity of vapor phase. IF(Obj%Iface%VapStatus .EQ. 1 ) THEN IfErrT = 0 ! Vapor phase is valid. ELSE IfErrT = 1 ! Error – invalid vapor phase. ENDIF ! ! Test validity of Liquid phase. IF(Obj%Iface%LiqStatus .EQ. 1 ) THEN IfErrT = 0 ! Liquid phase is valid. ELSE IfErrT = 1 ! Error – invalid liquid phase. ENDIF ! !
Error – fluid dies not exist. ELSE IfErrFl = 1 ! Error – invalid fluid ENDIF
PRO/II User-Added Subroutine User Guide
6-33
class_FluidPhase.mod This module makes FluidPhase data objects available to fluids in user-added subroutines. Pre-defined fluids in a UASOBJ data structure do not include all the defined phases. However, fluids instantiated 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 typically do not directly instantiate phase objects.
Usage of class_FluidPhase FluidPhase data structures are available only as members of
fluids. Developers should adhere to the following guidelines when writing code to access data from a FluidPhase object. User-added subroutines do not need a USE statement for class_FluidPhase, since Class_Fluid automatically does this. All fluidPhase objects in a fluid have pre-defined names. Tables 6-9 and 6-10 includes the names of all possible phases that a fluid might contain. All references to FluidPhase data should access the phase as a member of a fluid (e.g., Fluid%Phase%prop). Only direct member addressing is available for accessing phase data. The class_FluidPhase module does not implement accessor functions, so indirect addressing is not available. Sample code that demonstrates accessing phase data appears in the section "Fluid Phase Example" on page 6-36.
Direct Member Addressing in class_FluidPhase Direct member addressing of phase data is an inherent part of accessing fluid data. This is described by "Direct Member Access in class_Fluid" on page 6-25.
Indirect Member Addressing in class_FluidPhase The class_FluidPhase module does not implement accessor functions. For this reason, indirect member addressing is not supported for data in phases.
6-34 UAS Modular Fluids
February 2009
Data Structure of class_FluidPhase Table 6-11 lists all the data members in a FluidPhase storage ture.
struc-
Table 6-11: class_FluidPhase Data Members Phase Identification (always present) ID IdNo
C12 I4
Identifies the phase, typically “Total”, “Vapor”, or “Liquid”. An ID number assigned to the phase. Typically, 1 = Vapor phase 2 = Bulk Liquid phase 3 = L1 liquid sub-phase (not available) 4 = L2 liquid sub-phase (not available) 5 = Total phase (always present)
Name
C40
A name for the phase, typically “Total Fluid”, “Vapor Phase”, or “Liquid Phase”. Validation Flag (always present)
Exist
L4
.TRUE. when phase has been instantiated. Phase Properties (always present)
RateM
DP
Mole rate, wt*moles / time
RateWt
DP
Weight rate, wt / time
RateV
DP
Volumetric rate, vol / time
RateVstd
DP
Standard volumetric rate, vol / time
MolecWt
DP
Average molecular weight of phase
Density
DP
Density, wt / vol
DensStd
DP
Standard density, wt / vol
Acentric
DP
Acentric factor
SpVolM
DP
Specific mole volume, vol / wt*mole
SpVolMSt d
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
Component weight fractions, wt(i) / total phase wt
XConcM(i)
DP
Component concentrations, weight*mole/volume
XLact(i)
DP
Component liquid activities, i = 1, NOC
XFug(i)
DP
Component Fugacities, i = 1, NOC
KVal(i)
DP
Component K-values, i = 1, NOC
dKdT(i)
DP
Component K-value derivatives with respect to temperature, i = 1, NOC
Fluid Phase Example As an example of accessing phase data, consider the following. An Iface fluid contains three phase members: Total, Vapor, and Liquid. 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
The sample code (above) retrieves the total fluid mole rate from the Total phase of the fluid.
PRO/II User-Added Subroutine User Guide
6-37
6-38 UAS Modular Fluids
February 2009
Chapter 7 User-Added Units of Measure Overview of User Dimensional Units All data exchanged between PRO/II and any user-added subroutine are passed using the dimensional units requested by the developer. This is regardless of the units used for data input or output reporting in a simulation. The dimensional units may be different for each type of user-added subroutine, but every instance of a particular type of UAS uses the same set of dimensional units. This chapter refers to these UOM’s as User Dimensions. Each UAUTIL declares its system of user dimensions in the P2UasReg.ini file. In contrast, each UAUOP declares its UOM’s in its associated INI file. User-added unit operations allow more flexibility 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 useradded unit operations. The module is not available in user-added utility routines.
Base Systems of Units of Measure PRO/II provides four systems of dimensional units that are available for use in all modular user-added subroutines. Table 7-1 Lists the keywords that identify these systems. Table 7-1: Base Systems of Dimensional Units System Keyword Description ENGLISH
Common system used in the United States
METRIC
Traditional KMS Metric system
SI
International System of Measurements
PROII
PRO/II Internal System of Measurement
PRO/II User-Added Subroutine User Guide
7-1
Dimensional Classes in the Base System of Units The registered set of dimensional units applies to all data exchanged between PRO/II and a user-added subroutine. Table 7-2 lists the keywords for the units of all dimensional classes in each of the dimensional units systems. It includes the exact unit of measure used by each class for each dimensional class.
Table 7-2: Base Sets of Dimensional Units of Measure UOM Keywords Class
Description
English
Metric
SI
PRO/II
F
C
K
K
Pressure
PSIA
KG/CM
KPA
KPA
PDIF
Pressure change
PSI
KG/CM
KPA
KPA
WT
Weight
LB
KG
KG
KG
TIME
Time
HR
HR
HR
SEC
LENG
Length
FT
Meter
Meter
Meter
FLEN
Fine Length
INch
MM
MM
Meter
AREA
Area
FT2
M2
M2
M2
FAREA
Fine Area
IN2
MM2
MM2
M2
VELO
Velocity, LENG/TIME
FT/S
M/S
M/S
M/S
LIQV
Liquid Volume
FT3
M3
M3
M3
VAPV
Vapor Volume
FT3
M3
M3
M3
EQVO
Equivalent Volume, LIQV/ LENG
FT3/F
M3/M
M3/M
M3/M
LDEN
Liq. Density, WT/LIQV
LB/FT
KG/M
KG/M
KG/M
VDEN
Vap. Dens., WT/VAPV
LB/FT
KG/M
KG/M
KG/M
XDEN
Petro Density, WT/LIQV
LB/FT
KG/M
KG/M
KG/M
SPVO
Specific Volume, LIQV/WT- FT3/LB mole
M3/KG
M3/KG
M3/KG
ENER
Energy
BTU
KCAL
KJ
KJ
WORK
Work, ENER/TIME
HP
KW
KW
KJ/S
DUTY
Duty, ENER/TIME * 1.0e6
BTU/HR
KC/HR
KJ/HR
KJ/S
ENTH
Enthalpy, ENER/WT
BTU/LB
KC/KG
KJ/KG
KJ/KG
TEMP
Temperature
TDIF
Temperature change
PRES
CAKE
7-2 User-Added Units of Measure
February 2009
Table 7-2: Base Sets of Dimensional Units of Measure UOM Keywords Class
Description
English
Metric
SI
PRO/II
ENTR
Entropy, ENER/ (WT*TEMP)
BTU/LB
KC/KG
KJ/KG
KJ/KG
CP
Heat Capacity, ENER/ (WT*TEMP)
BTU/LB
KC/KG
KJ/KG
KJ/KG
MRAT
Mole Rate, (WT*mole) / TIME
LBM/HR
KGM/HR
KGM/HR
KGM/S
WTRA
Weight Rate, WT/TIME
KG/HR
KG/HR
KG/S
LVRA
LB/HR Liquid Volume Rate, LIQV/ FT3/HR TIME
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/MK
VISC
Viscosity
CP
CP
PAS
PAS
KINE
Kinematic Viscosity
CST
CST
CST
CST
SURF
Surface Tension
D/CM
D/CM
N/M
N/M
HTCO
Heat Transfer, ENER/ (TIME*AREA*TEMP)
BTU/HR
KC/HR
KW/MK
KW/MK
FOUL
Fouling Coefficient
HFF/B
HMC/K
MK/KW
MK/KW
UA
U*A value, ENER/ (TIME*TEMP)
BTU/HF
KC/HC
KW/K
KW/K
SPHT
Specific Heat, ENER/ (WT*TEMP)
BTU/LB
KC/KG
KJ/KG
KJ/KG
FRAC
Fraction
FRAC
FRAC
FRAC
FRAC
PCT
Percentage
PCT
PCT
PCT
PCT
PPM
Parts per million
PPM
PPM
PPM
PPM
ANGL
Angle
RAD
RAD
RAD
RAD
DIPO
Dipole Moment
DEB
DEB
DEB
DEB
HVAL
Heating Value, ENER/ VAPV
BTU/FT3
KC/M3
KJ/M3
KJ/M3
RUA
Radial U*A coefficient
PRO/II User-Added Subroutine User Guide
7-3
UAUTIL User Dimensions PRO/II calls each UAUTIL subroutine with a single argument in the call list. The argument is a data object of TYPE(UASOBJ). All data in the UASOBJ structure are passed in already converted to user dimensions. Refer to Chapter 4, “Modular Utility Subroutines” for a general 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 routine. A UAUTIL does not allow changing the units of individual classes in the chosen system. The developer must inform the endusers of the correct set of units. The end-user must declare the set of units when registering the utility subroutine in PRO/II’s P2UasReg.INI file. See “Chapter 2, “Registering 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 subroutine “IFENGL”, which expects data in the UASOBJ of the argument list to be in English units (column 3 of Table 7-2). The "myIFMET" utility on the last line uses the METRIC UOM system. While the structure and data content in the UASOBJ’s are identical for both IFAREA utilities, the numeric values are in different units. For instance, pressure values in English units are psia, but pressure in metric units are kg/cm2. Developers and users can be confident that these conventions apply to every instance of each of these two utility routines. Similarly, a UASOBJ passed to instances of mass transfer utility “muMassE” contains different data than a UASOBJ passed to either interfacial area utility. However, both objects use the same set of user dimensions (English). Thus, for example, any pressure data in either UASOBJ is passed using units of psia.
7-4 User-Added Units of Measure
February 2009
Note: For information specific to each type of utility routine refer
to Chapter 11, “Interfacial Area Utility”, Chapter 12, “Binary Mass Transfer Utility”, and Chapter 13, “Heat Transfer Utility”.
UAUOP User Dimensions User-added unit operations do not register their units of measure in the P2UasReg.ini file. Instead, they allow specifying dimensional units for individual classes in their “ini” files. A developer first declares a pre-defined system of units using a BASE statement and a UOM system keyword from column 1 of Table 7-1. Subsequent statements may “override” the base units used by individual classes in the system. The selected base system, together with all the individual class overrides collectively are known as a system of “user dimensions”. User-added unit operations (UAUOP) include a member named %Factors that is an instance of class_DMUOM. User-added utilities cannot access this class.
Usage of class_DMUOM in a UAUOP Each UAUOP data object includes a member named %Factors which is an instance of class_DMUOM. All units of measure data are initialized and available in the %Factors member. Never attempt to alter the data in the DMUOM data structure. The data in the DMUOM structure allow converting data values between user units and PRO/II internal units of measure. Two sets of factors are available: one to convert from user units to PRO/II and the other to convert back from PRO/II to user units. The format for using both sets of conversion is the same: Value to = Value from * Factor
Because temperature and pressure allow relative values (e.g., F, C, psi, barg), conversion of these classes additionally requires use of a translation factor. For example, to convert temperature or pressure, use: Value to = Value from * Factor + Offset
Use accessor function GetFactor_DmUom( ), described below, to obtain the desired conversion Factor and (when required) Offset.
PRO/II User-Added Subroutine User Guide
7-5
Definition of class_DMUOM.mod This section describes the proper usage of class_DMUOM mod in a modular user-added unit operation. The class includes a data structure and member methods for accessing and using dimensional units data and conversion factors. The module is available only in modular user-added unit operations. Modular utility routines do not permit access to this module, since the data in class_DMUOM are not initialized when PRO/II calls a UAUTIL.
Data Structure of class_DMUOM The data structure included in class_DMUOM is a derived-type of object assigned the type name DMUOM. It contains the conversion factor data necessary to convert between defined USER dimensional 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 integer 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 translation factor to perform a dimensional units conversion. This accessor function is a member of class_DMUOM. The input arguments specify which factor to retrieve. Calling sequence: iStat = GetFactor_DmUom( cSysIn, cClassIn, & UomObj, FacOut, OffOut, cIdOut )
Where: cSysIn
Input character keyword that specifies the system of units from which to convert. Valid entries are:
“USER” Requests a factor to convert from a user unit to a PRO/II internal unit. May be abbreviated as “U”.
7-6 User-Added Units of Measure
February 2009
“P2” Requests a factor to convert from a PRO/II internal unit to a user unit. May be abbreviated as “P”. cClassIn Input character keyword that identifies the class of the
requested conversion factor. This keyword may be any entry listed in the left-most column of Table 7-2.
UomObj An instance of a DMUOM data object. Currently, this should be the %Factors member of the UAUOP structure
passed through the argument list in calls to a user-added unit operation. This is an input argument.
FacOut
Returned scalar double precision conversion factor.
OffOut
Returned scalar double precision translation factor associated 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 keywords 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: Success, no error, returns class ID number. Failure, cClassIn is invalid. -3 Failure, cSysIn is invalid. Any other negative value - Failure, unspecified reasons. >=1
0
cGetID_DMUOM( ) This function returns the keyword identifier for the units of measure of a specified dimensional class and system. It is a member function of class_DMUOM. It supports only PRO/II internal units and user units. Calling sequence: cIDout = cGetID_DMUOM( cSysIn, cClassIn, UomObj )
&
Where: cSysIn
Input character keyword that specifies the system of units from which to convert. Valid entries are:
PRO/II User-Added Subroutine User Guide
7-7
“USER” Requests an identifier from the user system of units May be abbreviated as “U”. “P2” Requests an identifier from the PRO/II internal system of units. My be abbreviated as “P”. When cSystem specifies an unrecognized system of units, cGetID_DMUOM returns the identifier of the user unit. cClassIn Input character keyword that identifies the dimensional
class of the requested identifier. This keyword may be any entry listed in the left-most column of Table 7-2.
UomObj An instance of a DMUOM data object. Currently, this should be the %Factors member of the UAUOP structure
passed through the argument list in calls to a user-added unit operation. This is an input argument.
cIDout
A local character variable that accepts the identifier returned from cGetID_DMUOM. If argument cClassIn is invalid, cIDout returns the string “INVALID”. If the call failed due to an internal error, cIDout returns a blank string.
Examples The following illustrates the proper usage for class_DMUOM using the recommended accessor functions. The sample code represents a subroutine within a user-added unit operation model where a UAUOP object is passed in through the argument list.
:: PresUA, TempUA, WorkUA, & PresP2, TempP2, WorkP2, & FacUA, OffUA, FacP2, OffP2 INTEGER(4) :: iStat CHARACTER(LEN=16) :: cIdUomUA, cIdUomP2 ! ISOLVE = 1 ! ! Convert a temperature, a pressure, and work ! from user units to PRO/II internal units ! PresUA = 14.6959D+0 ! assume psia ! iStat = GetFactor_DmUom( “USER”, “PRES”, &
7-8 User-Added Units of Measure
February 2009
myUop%Factors, FacUA, OffUA, cIdUomUA ) ! IF( iStat .GE. 1 ) THEN ! PresP2 = PresUA * FacUA + OffUA ! Eqn 1 ! cIdUomP2 = cGetID_DMUOM( “P2”, “PRES”, & myUop%Factors ) END IF End Subroutine MyCode
Notes: The statement “TYPE(UAUOP): MyUop“ declares the UAUOP data object which includes “myUop%Factors“, an instance of class_DMUOM. Local variable PresUA is set to any value (here, 14.6959). All calculations 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 conversion factor returns in variable FacUA with the associated translation 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, resulting in variable PresP2 having the pressure value in internal PRO/II units. Finally, the call to “cIdUomP2 = cGetID_DMUOM( “P2”, “PRES”,” returns the identifier for the PRO/II internal pressure units.
PRO/II User-Added Subroutine User Guide
7-9
7-10 User-Added Units of Measure
February 2009
Chapter 8 UAUOP AutoGUI Overview Each modular user-added unit operation allows developers to create a custom data entry window (DEW). Simulation users use the window 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 creates and positions the data in the tabbed dialog box. Simple interactions can be specified in the XML file, with no GUI programming required. This chapter provides details about using the AutoGUI to create tabbed data entry dialog boxes for PRO/II UAUOP units. It specifies the syntax of the XML used for creating the dialog boxes, and shows some sample screens using AutoGUI.
Notation Used in this Chapter To clarify the explanations, the following conventions are used in this chapter. Many XML tokens are enclosed in chevrons, e.g., . The chevrons are part of the token. In use, they usually have separate start and end forms that encloses member elements; for example, members . Bold font is for emphasis only. XML tokens are case sensitive. For example, and represent different XML elements. XML elements in monospaced font are exact tokens or names that should be used exactly as they appear. For example, Name=”AutoGUI” is the exact element that should be used as shown, including the quotation marks. Italicized text indicates generic placeholders that should be replaced with appropriate data. For example, HelpFile=”filename.hlp”
PRO/II User-Added Subroutine User Guide
8-1
indicates that the developer should replace filename with an actual file name. All quotation marks shown in the XML samples are required.
Basic XML File Structure Table 8-1 shows the basic structure of an AutoGUI XML file Table 8-1: Basic Structure of an AutoGui XML file
The AutoGUI XML file has a single XML element that contains everything else in the file Inside the element are one or more elements. Each element defines the contents of one tab in the dialog box. Inside each element are additional elements that identify the specific UAUOP attributes to be displayed in that tab. The sections below present specific information and examples of displaying different types of attributes.
8-2 UAUOP AutoGUI
February 2009
Associating an XML file with a UAUOP Unit Operation The files listed in Table 8-2 are required for a UAUOP unit operation to implement AutoGui windows in PRO/II. Table 8-2: AutoGui Files Associated with a UAUOP File name
Location
Description
myUaUop.dll
%P2Install%\Bin
myUaUop.ini
%P2Install%\System Data Definition file
DLL containing runtime code for UAUOP unit operation XXX
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 installation path. Before using an AutoGUI.XML file with a UAUOP unit operation, it must be associated with the UAUOP. This linkage is accomplished by modifying the myUaUopIcon.dat file: GROUP 420001 "AutoGUI Test" "UAUOP" 1 "AutoGUIUOP" ICON "AutoGUI Test" 60 0 20.0 "AG%d" 1 0 FORM P2GenericUnit.dll myUaUop.xml
Specifically, the FORM line must specify P2GenericUnit.dll as the first argument and the name of your XML file as the second argument.
PRO/II User-Added Subroutine User Guide
8-3
XML Schema Reference The list of XML elements and attributes for the XML-based tabbed dialog box is specified in Table 8-3. Detailed explanation of key elements are provided after the table. Specific examples appear later in this chapter. In Table 8-3, “AutoGUI XML Schema in PRO/II,” on page 4: (R) refers to an XML element or attribute which is required.
A number in parenthesis specifies the number of elements required or allowed. In column 4, “Text Value”, the terms used are: none – The attribute/element does not accept a text value. String – The attribute/element accepts any unquoted string
value. “string” – The attribute/element accepts any character string enclosed in quotation marks. "xxx" – A text value in quotes means that the text value must be specified exactly as shown, where xxx is the exact text and the quotation marks are required. Integer – The text value must be a numeric integer value. monospaced font – An exact entry to use as shown. Table 8-3: AutoGUI XML Schema in PRO/II
Attribute of Text Value XML Child Elements of of Element XML Element XML Element or Attribute Element
None Name= (R)
“String” (1 or more)
None None
Name= (R)
“String”
Type= (R)
“Normal”
(0 or more) None
8-4 UAUOP AutoGUI
(0 or more)
None
(0 or more)
None
February 2009
Table 8-3: AutoGUI XML Schema in PRO/II
Attribute of Text Value Child Elements of of Element XML XML Element XML Element or Attribute Element (0 or more)
None None
Name= (R)
“String”
Type= (R)
“Normal”, “Weak”, “Strong”
(0 or 1)
Integer
(0 or 1)
String
String or (0 or 1) false (0 or 1)
true or false
(0 or more) None
PRO/II User-Added Subroutine User Guide
(0 or more)
None
(0 or more)
None
(0 or more)
None
8-5
Table 8-3: AutoGUI XML Schema in PRO/II
Attribute of Text Value Child Elements of of Element XML XML Element XML Element or Attribute Element
Attribute of Text Value Child Elements of of Element XML XML Element XML Element or Attribute Element
(0 or 1)
I or L
String or false (0 or 1) (0 or 1)
String None
Name= (R)
“String”
Type=
“Real”, “Integer”, “String”
(0 or 1)
String
“Name” of (0 or more) Group element
None (exactly 1)
String
True or (0 or 1) false
None Name= (R)
String (exactly 1)
String
(0 or 1)
True or false
(0 or 1)
Integer
(0 or 1)
Integer
Miscellaneous Elements that are Children of Other Elements
Integer
True or false
String
True or false
I or L
True or false
PRO/II User-Added Subroutine User Guide
8-7
Table 8-3: AutoGUI XML Schema in PRO/II
Attribute of Text Value Child Elements of of Element XML XML Element XML Element or Attribute Element
Req or opt or none
String or false
String
String
None Name= (R)
“String” (1 or more)
None
Notes Client The element is a child element of . Refer to the topic "Image" on page 8-10 for details.
Constraint The element is used to display static text on the tab. The child element specifies the text to display.
Count The element is a child of or . When used as a child element of a vector variable or vector parameter, it defines the number of rows to display. When used as a child element of a scalar variable or scalar parameter, it defines the width (approximate number of characters) to display.
CreateSideBySide The child element is used to modify the default positioning of a control. Normally, controls are stacked vertically 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 and elements can be used to place the edit control next to the controlling check box. 8-8 UAUOP AutoGUI
February 2009
Desc The element specifies the actual text to display in the tabbed dialog box of the parent XML element.
DependentGroup The element is a child of the element and is used to specify interactions between controls. See the element for a detailed description.
FileName The element is a child element of . Refer to the topic "Image" on page 8-10 for details.
Group The element is used to group one or more items for purposes 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 element supports the following attributes. Name=
This attribute specifies the text identifier for the group. This text identifier is used in the 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 specified as child elements of this element. The text of the child element is dis-
played as group box title. “Strong” Creates the child controls in a grid. The child
controls must be one of the following types: Scalar Variables: The grid is row-based; each variable is displayed in its own row. Scalar Parameters: The grid is row-based; each parameter is displayed in its own row. PRO/II User-Added Subroutine User Guide
8-9
Note: Scalar variables and scalar parameters can be combined in
one strong group. Vector Variables: The grid is column-based; each vector variable is displayed in a separate 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 separate 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 element is a child element of . See “Image” (below) for details.
Image The element is used to display image files in the tabbed dialog box. The image formats supported are BMP, JPEG, and GIF. The child element specifies file name of the image file. The child element specifies whether the file is located in the client side; for PRO/II, this element. If 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 and child elements. If not specified, the image will be displayed in its actual size.
MilanoAttribute The element is a child of the element. The text value of this element can be: I
8-10 UAUOP AutoGUI
(Capital I) If the 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. February 2009
If the text value is L (“level”, or calculated value), then the calculated value of the variable is displayed.
L
NoLabel The 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 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 element, so the group name can be specified as the dependent group of the check box.
2.
In the edit field, include the elements and with values of true to display the edit field next to the controlling check box.
Parameter The element is used to create a check box, radio button, 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 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 element. There can be only one dependent group which will be enabled if the check box is checked and disabled if unchecked.
PRO/II User-Added Subroutine User Guide
8-11
If no 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 database value using a 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 child element. “String” or “Real” or “Integer”
Each of these creates and edit field. The PRO/II database attribute may be an integer value (INT), a double value (DBL), or a text value (TEXT). The child elements , , , and may be used to specify additional characteristics.
ReadOnly The element can be used to display information while preventing the user from modifying it. Set the text value of this element to true to create a read-only control.
Required The element sets the required/optional state of the control. The valid values are req
Indicates that an input user value is required. If the user does not supply a value, the border will be red.
opt
Indicates that an input user value is optional. If the user does not supply a value, the border will be green.
none
Indicates that no border color will be used.
ShowTitleHeader The element specifies text to be displayed in cell (0,0) of a grid when displaying an array parameter or an array variable.
8-12 UAUOP AutoGUI
February 2009
Spec Each element in the XML document denotes a single tab in the tabbed dialog box. Note: For PRO/II, each element must include the Type=”Normal” attribute. Type=“Normal” The Type= attribute of the node must have the value “Normal”. Normal tabs are displayed when
the user double-clicks on the unit operation icon in the flowsheet. Desc=
This attribute (if specified) or the Name= attribute will be displayed as the tab name.
SpecList The element is the top-level element in the XML file. There is only one element in an AutoGUI XML file. This element will contain one or more elements.
ToolTip The element specifies the text to be displayed as a tooltip when the mouse hovers over the control. Tooltips are not supported in a grid.
Value One or more elements may be specified as a child element of a element if its Type= attribute is “Choice”, “Option”, or “Selection”. The purposes of the element are: 1.
Associate a database attribute value to a human-readable description. The Name= attribute of the element identifies the database value for which the information in the element will apply. The 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 element identifies the database value for which the information in the element will apply. The child element identifies the name of the element containing the controls that are enabled (or shown) when the database value matches the Type= attribute.
PRO/II User-Added Subroutine User Guide
8-13
ValueDomain The 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 element whose Type= attribute is “Selection”. The text value of this element must be THERMOSETS. See Example 5 below for an example of defining a drop-down list box to choose a thermodynamic METHOD set.
Variable The 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 , , , and may be used to specify additional characteristics.
Variable and Parameter Names AutoGUI XML files use PRO/II database attributes. For a modular User-Added Unit Operation (UAUOP), the attribute names are defined in a configuration (INI) file. For demonstration purposes, Figure 8-1 shows part of the data definition in a UAUOP INI file. Figure 8-1: Sample UAUOP INI File Data Definition INT 1
Table 8-4 shows the proper Name= syntax for referring to the UAUOP data attributes declared in Figure 8-1.
8-14 UAUOP AutoGUI
February 2009
Table 8-4: AutoGUI XML Access to PRO/II UAUOP Attributes Name=
Description of UAUOP data
Name=“MyScalarINT”
Name for a scalar INT value (INT 1, a scalar integer)
Name=“MyVectorINT[0]”
Name for one element (the first) of an integer array (INT 2)
Name=“MyVectorINT”
Name for an entire INT array 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)
(INT
Note: Use square brackets to declare subscripts, e.g.,”MyVectorDBL[9]”
Width The element is a child element of . Refer to the topic "Image" on page 8-10 for details.
PRO/II User-Added Subroutine User Guide
8-15
AutoGUI Examples This section contains various AutoGUI examples. Each example shows the relevant portion of a UAUOP data definition *.INI file, the source XML file, and the resulting GUI image.
Example 1: Display Scalar Edit Fields This demonstrates the basic setup required to display scalar values in float, integer, and text edit fields. .ini file [Data Definition] MAXINT = 1 TOTINT = 1 MAXPAR = 1 TOTPAR = 1 MAXDBL = 1 TOTDBL = 1 MAXTEX = 1 TOTTEX = 2 INT 1 “ScalarINT” 1 None -2111111111 -2111111111 -2111111111 PAR 1 “ScalarPAR” 1 TEMP -1.5E35 -1.5E35 -1.5E35 DBL 1 “ScalarDBL” 1 None -1.5E35 -1.5E35 -1.5E35 TEX 1 “ScalarTXT” 1 8 9
The element is used to display the PAR attribute Scrapper (PAR 1 in the INI file listing). The 3 elements are used to display INT, DBL, and TEXT attributes. If the unit-of-measure 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 element is used to specify the border color convention for missing data. Result The resulting AutoGUI display is shown in Figure 8-2. Figure 8-2: Example 1 AutoGUI Display
PRO/II User-Added Subroutine User Guide
8-17
Example 2: Display Vector Edit Fields This demonstrates the basic setup required to display vector values in grids. .ini file [Data Definition] MAXINT = 1 TOTINT = 10 MAXPAR = 1 TOTPAR = 10 MAXDBL = 0 TOTDBL = 0 MAXTEX = 0 TOTTEX = 0 INT 1 “ArrayINT” 10 None -2111111111 -2111111111 -2111111111 PAR 1 “ArrayPAR” 10 TEMP -1.5E35 -1.5E35 -1.5E35
.xml file Array Integer:Array Parameter:Both Arrays in same GridIndex11Array Integer:Array Parameter:
8-18 UAUOP AutoGUI
February 2009
Result The first tab displays the two arrays in separate grids, as shown in Figure 8-3. Figure 8-3: First AutoGUI Tab of Example 2
Fields bordered in red indicate required but missing data that the user must supply.
PRO/II User-Added Subroutine User Guide
8-19
The second tab uses the element to combine the two vectors 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 Index element specifies the text “Index” displayed in the upper left corner cell of the grid. The 11 element defines the approximate number of rows to display.
8-20 UAUOP AutoGUI
February 2009
Example 3: Display Check box, Radio Button, List Box Controls This demonstrates the basic setup required to display integer values using check box, radio button, and drop-down list box controls. .ini file [Data Definition] MAXINT = 3 TOTINT = 3 MAXPAR = 0 TOTPAR = 0 MAXDBL = 0 TOTDBL = 0 MAXTEX = 0 TOTTEX = 0 INT 1 “CheckINT” 1 None -2111111111 -2111111111 -2111111111 INT 2 “RadioINT” 1 None -2111111111 -2111111111 -2111111111 INT 3 “LBoxINT” 1 None -2111111111 -2111111111 -2111111111
The element is used for the radio button and the drop-down
list box to associate a database value with a readable string. Result Figure 8-5: AutoGUI Tab of Example 3
Example 4: Implementing automated interactions This demonstrates the setup required to implement interactions for check box, radio button, and drop-down list box controls. .ini file [Data Definition] MAXINT = 4 TOTINT = 4 MAXPAR = 4 TOTPAR = 8 MAXDBL = 0 TOTDBL = 0 MAXTEX = 0 TOTTEX = 0 INT INT INT INT PAR PAR PAR PAR
Option 4LBoxGroup4 Dependent CheckboxDependent Scalar PARDependent Vector PAR
The 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 element in the controlling widget has a child element which identifies the specific 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 and are used for the elements in the “CheckINTGroup” and “RadioINTGroup” groups so that these edit fields are displayed adjacent to the controlling widget.
Result The first tab demonstrates interaction with a check box. If the check box is checked, then the dependent edit field is enabled.
8-24 UAUOP AutoGUI
February 2009
Figure 8-6: First AutoGUI Tab of Example 4
The second tab demonstrates interaction with radio buttons. The selected radio button will enable the dependent edit field. Figure 8-7: Second AutoGUI Tab of Example 4
The third tab demonstrates interactions with a drop-down list box. The selected entry in the list box shows the dependent controls. The controls associated with the other options in the list box are hidden. Figure 8-8: Third AutoGui Tab of Example 4.
PRO/II User-Added Subroutine User Guide
8-25
Example 5: Assigning Thermodynamic METHOD Sets to Sides This demonstrates the setup required to allow the user to select a Thermodynamic Set for one or more “sides” in the unit operation. The example defines a unit containing two sides. .ini file [Sides] MAXSides = 2 SIDE 1 Side_1 SIDE 2 Side_2
.xml file Thermodynamic Set Side 1THERMOSETSThermodynamic Set Side 2THERMOSETS
The 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 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 contains the thermodynamic set names assigned for each side in the unit operation.)
8-26 UAUOP AutoGUI
February 2009
Result Figure 8-9: AutoGUI Tab of Example 5
PRO/II User-Added Subroutine User Guide
8-27
8-28 UAUOP AutoGUI
February 2009
Chapter 9 UAUOP Icons Each modular user-added unit operation allows developers to create a custom image for display on the PRO/II icon palette and flowsheet. The image specification contains information on the appearance and the stream connections.
Icon Data File Structure The structure of an Icon data file is shown in Table 9-1. Table 9-1: Basic Structure of an Icon Data File GROUP 420001 "MyUAUOPName" "UaUOP" 1 "MYUAUOP" ICON "MyUAUOPName" 60 0 20.0 "UOP%d" 1 0 FORM P2GenericUnit.dll myUaUop.xml shape ... DATA ... PORT ... DATA ... PLIN ... DATA ... ID -1 -1 -1 -1 -1 -1 DATA ...
The icon file contains the following statements: The first statement is the GROUP statement which defines the display name of the UAUOP and associates it with the data definition (*.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 statements (such as LINE or CIRCLE) that define the visual appearance of the icon. The DATA statement provides additional information for the shape. There may be zero or more PORT statements which define “point” connections for streams. The DATA statement provides additional information for the PORT.
PRO/II User-Added Subroutine User Guide
9-1
There may be zero or more PLIN statements which define “line” connections for streams. The DATA statement provides additional information for the port line. The shape, PORT, PLIN, and ID statements may appear in any order. There must be one ID statement (usually at the end) that specifies the location of the unit identifier. The DATA statement provides additional information for the identifier.
Associating an Icon Data File with a UAUOP Unit Operation The files listed in Table 9-2 are required for a UAUOP unit operation to fully implement icons and tabbed dialog boxes in PRO/II. Table 9-2: AutoGUI Files Associated with a UAUOP File name
Location
Description
myUaUop.dll
%P2Install%\Bin
DLL containing runtime code for UAUOP unit operation myUaUop
myUaUop.ini
%P2Install%\System Data Definition file
myUaUopIcon.dat %P2Install%\System Definition file for the icon to display on the PFD icon palette and in the PFD flowsheet. myUaUop.xml
%P2Install%\System AutoGUI XML definition file.
Note: (%P2Install% refers to the installation directory, such as C:\simsci\proii82. See “Registering a Path to A User-Added DLL”
on page 11-7 for information about specifying the PRO/II installation path. The association of the UAUOP icon with the data definition file (*.ini) and the AutoGUI XML file (*.xml) is accomplished in the icon data file (myUaUopIcon.dat): GROUP 420001 “MyUAUOPName” "UaUOP" 1 "MYUAUOP" ICON "MyUAUOPName" 60 0 20.0 "UOP%d" 1 0 FORM P2GenericUnit.dll myUaUop.xml
Specifically, The last value on the GROUP line must be a text string that matches one of the entries in the PRO/II UAS registry file P2UasReg.ini. The FORM line must specify P2GenericUnit.dll as the first argument and the name of the XML file as the second argument. 9-2 UAUOP Icons
February 2009
Icon File Reference The complete structure of an icon data file is shown in Table 9-3: Table 9-3: Complete Structure of an Icon Data File // Comment line GROUP (exactly 1) ICON (1 or more for the GROUP) FORM (1 for each ICON) shape (0 or more) DATA (additional data for shape) BEGOUTLINE (zero or more BEGO/ENDO sections) shape or PLIN DATA (additional data for shape or PLIN)
END
ENDOUTLINE PORT DATA PLIN DATA ID DATA
(0 or more) (additional data for PORT) (0 or more) (additional data for PLIN) (exactly 1) (additional data for ID) (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 statement. For example the statement DATA 1 2 3 on one line followed by DATA 4 5 6 on the next line is equivalent to DATA 1 2 3 4 5 6 all on one line.
A line beginning with // is a comment line. PRO/II User-Added Subroutine User Guide
9-3
Statements GROUP Statement The GROUP statement defines the description of the icon and identifies which UAUOP in the p2uasreg.ini file is associated with this icon. The format of this statement is: GROUP 420001 "UAUOP"
Where: 420001
This code number is required to identify the icon as being a UAUOP icon.
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.
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.
Text string identifying the type of UAUOP unit. This
text string must match the text string used in the p2uasreg.ini file.
ICON Statement Each ICON section starts with an ICON statement and ends with another ICON statement, an END statement, or an end-of-file. The format of the ICON statement (with all values on one line) is: ICON
60
Where:
9-4 UAUOP Icons
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.
Allowed flip/rotation settings during lay down, 0 = allow flip and rotate, 1 = allow flip only, 2 = do not allow flip or rotate. February 2009
The 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.
Scale factor, a floating point number. A larger factor means a proportionately larger icon relative to the other icons.
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 consecutively, starting at the value defined below. An example is “UOP%03d”, which results in default unit identifiers of UOP001, UOP002, and so on.
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 value.
Specify a value of 1 if input data is required. This sets the initial color of the label to red.
FORM Statement This statement defines the XML file to be used for data entry. The format is: FORM
where: The name of the DLL used to process the XML file. For UAUOP units, this should be P2GenericUnit.dll The name of the XML file used to define the tabbed dialog box for the UAUOP unit operation.
PRO/II User-Added Subroutine User Guide
9-5
Shape Statements Shape is a generic term for any of several statements, each of which describes a graphic primitive such as a line, circle, or rectangle. Several shape statements may be used to create a complex icon. The format of a shape statement (all data on one line) is: shape
