Aspen plus 8.0 GUIDE

7/26/2019 Aspen plus 8.0 GUIDE

1/215

Summary File Toolkit

Aspen Plus


2/215

Version Number: V8.0December 2012

Copyright (c) 1981-2012 by Aspen Technology, Inc. All rights reserved.

Aspen Plus, aspenONE, the aspen leaf logo and Plantelligence and Enterprise Optimization are trademarks orregistered trademarks of Aspen Technology, Inc., Burlington, MA.

All other brand and product names are trademarks or registered trademarks of their respective companies.

This document is intended as a guide to using AspenTech's software. This documentation contains AspenTechproprietary and confidential information and may not be disclosed, used, or copied without the prior consent ofAspenTech or as set forth in the applicable license agreement. Users are solely responsible for the proper use ofthe software and the application of the results obtained.

Although AspenTech has tested the software and reviewed the documentation, the sole warranty for the software

may be found in the applicable license agreement between AspenTech and the user. ASPENTECH MAKES NOWARRANTY OR REPRESENTATION, EITHER EXPRESSED OR IMPLIED, WITH RESPECT TO THIS DOCUMENTATION,ITS QUALITY, PERFORMANCE, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.

Aspen Technology, Inc.200 Wheeler RoadBurlington, MA 01803-5501USA

Phone: (1) (781) 221-6400Toll Free: (1) (888) 996-7100URL: http://www.aspentech.com


3/215

Contents iii

ContentsWho Should Read this Guide ...................................................................................1

Introducing Summary File Toolkit ...........................................................................3

Related Documentation .....................................................................................3Technical Support ............................................................................................4

1 Getting Started....................................................................................................5

The Summary File and Toolkit............................................................................6

Initializing the Toolkit .......................................................................................6

Accessing the Required Files....................................................................7Getting the Summary File Name ........................................................................7

Getting Property and Units File Names ......................................................7Defining Units of Measurement ................................................................8

Specifying a Value for Missing Results.......................................................8Determining the Data Dimensions ......................................................................8

Retrieving Data for an Object.............................................................................9Using the Toolkit With a Hierarchical Aspen Plus Run .......................................... 11

Linking Toolkit Subroutines into Your Module ..................................................... 11

Creating a Toolkit Application for Windows ........................................................ 11About the Windows Version ................................................................... 12

Linker Directive Commands for Windows ........................................................... 12Calling Summary File Toolkit Routines .............................................................. 13

Opening and Closing Files Using the Summary File Toolkit......................... 13Using Fortran to Call Routines................................................................ 14

Changes in the Toolkit .................................................................................... 14

2 General Subroutines..........................................................................................15

Initializing the Summary File Toolkit ................................................................. 16

Closing the Summary File Toolkit ..................................................................... 17Opening and Closing Files................................................................................ 18Retrieving Run Information ............................................................................. 19

Standard Run Information ..................................................................... 19

Run Titles............................................................................................ 20Accounting Information......................................................................... 21

Retrieving Flowsheet Balance Results................................................................ 21Units Conversion ............................................................................................ 22

Changing Units Sets ............................................................................. 22Converting Units for Real Numbers ......................................................... 23

Determining Units Labels ...................................................................... 23

Component Information Retrieval..................................................................... 24Number of Components ........................................................................ 24Component IDs.................................................................................... 25

Component Alias Names ....................................................................... 25


4/215

iv Contents

Component CAS Numbers ..................................................................... 26Component Properties .......................................................................... 26

Sensitivity Block Results ................................................................................. 26

Identifying Sensitivity Blocks ................................................................. 27Determining Sensitivity Dimensions ........................................................ 27Retrieving Sensitivity Results................................................................. 28

3 Block Result Subroutines...................................................................................29

Block Identification .........................................................................................30Block IDs ............................................................................................ 30Next Block........................................................................................... 30

Block Connectivity Information ........................................................................ 31

Number of Inlet and Outlet Streams ....................................................... 31Stream Names and Types ..................................................................... 31

Additional Port Information.................................................................... 32Standard Block Results ................................................................................... 34

Dimensions of Standard Scalar Results ................................................... 34Standard Scalar Block Results................................................................ 35

Compressor Results ........................................................................................ 36Dimensions of Performance Results ........................................................ 36Stage-by-Stage Performance Results ...................................................... 37

Dimensions of Wheel-by-Wheel Performance Results ................................ 38Wheel-by-Wheel Performance Results ..................................................... 38

Compressor Profile Results .............................................................................. 39Dimensions of MCompr Profile Results .................................................... 39

MCompr Profile Results ......................................................................... 39

MCompr Cooler Profile Results ............................................................... 40Heat Exchanger Results .................................................................................. 40

Number of Detailed Results ................................................................... 41

Detailed Results ................................................................................... 41

Velocity and Pressure Results ................................................................ 42

Heat Exchanger Results Dimensions ....................................................... 42Heat Exchanger Zone Results ................................................................ 43

Heat Exchanger Shell Results................................................................. 43Heat Exchanger Tube Results................................................................. 44Heat Exchanger Baffle Results ............................................................... 45

Heat Exchanger Nozzle Results .............................................................. 45

Heat Exchanger Profiles .................................................................................. 46Heat Exchanger Profile Size ................................................................... 46

Heat Exchanger Profile Properties ........................................................... 47

Heat Exchanger Profile Results............................................................... 47Column Results .............................................................................................. 48

Number of Columns.............................................................................. 48

Column Profile Dimensions .................................................................... 49Column Profile Properties ...................................................................... 49Non-Component-Dependent Column Profiles............................................ 50Component-Dependent Column Profiles .................................................. 50

RadFrac Thermosiphon Reboiler Results .................................................. 51Interconnecting Stream and Pumparound Results..................................... 52

Additional Data for PetroFrac Models................................................................. 54

Dimensions of Additional Data ............................................................... 54

Additional Scalar Results Data ............................................................... 55


5/215

Contents v

Additional PetroFrac Profile Properties ..................................................... 56Additional Property Profiles.................................................................... 56

Furnace Data for PETROFRAC ................................................................ 57

Component-Dependent Properties for the PetroFrac Furnace ..................... 58Pumparound Results for PetroFrac Columns............................................. 58Connectivity Data for PetroFrac Strippers ................................................ 59

Additional Data for RateFrac Models ....................................................... 60Dimensions of Additional Scalar Data ...................................................... 60Additional Scalar Results Data ............................................................... 60Dimensions of Component Split Fractions ................................................ 61

Component Split Fractions..................................................................... 61Number of Liquid Phases ....................................................................... 62

Tray Reports.................................................................................................. 62

Tray Report Dimensions ........................................................................ 62Sequential Tray Report Properties .......................................................... 63Specific Tray Report Properties .............................................................. 64

Tray/Packing Sizing and Rating ........................................................................ 64

Number of Columns.............................................................................. 65Number of Column Sections .................................................................. 65

Column Section Types and Numbers ....................................................... 65Size of a Column Section....................................................................... 66Scalar Results for a Column Section ....................................................... 67Column Section Profile Properties ........................................................... 67Column Section Profiles......................................................................... 68

Reactor Results .............................................................................................. 69Number of Reactor Substreams.............................................................. 69Reactor Profile Dimensions .................................................................... 69

Reactor Profile Properties ...................................................................... 70

Non-Component-Dependent Reactor Profiles............................................ 70Component-Dependent Reactor Profiles .................................................. 71Number of Components with Component Attribute Results ........................ 72

Number of Attributes for a Component.................................................... 72Details of a Component Attribute ........................................................... 72Component Attribute Results ................................................................. 73

Number of Continuous Feed Streams ...................................................... 73

Continuous Feed Stream Results ............................................................ 74RBATCH Vent Accumulator Results ......................................................... 74RBatch Vent Profile Results.................................................................... 77

Reaction Data ...................................................................................... 79Reactor Property Reports ................................................................................ 82

Number of Reports for a Reactor Block.................................................... 82

Size of a Reactor Property Report ........................................................... 82

Sequential Reactor Report Properties ...................................................... 83Specific Reactor Report Properties .......................................................... 84

Pipeline Results.............................................................................................. 84Pipeline Results Dimensions................................................................... 85

Non-Component-Dependent Pipeline Inlet and Outlet Conditions................ 85Component-Dependent Pipeline Inlet and Outlet Property Names............... 86

Component-Dependent Pipeline Inlet and Outlet Conditions....................... 87

Segment Data Property Names .............................................................. 87Pipeline Segment Data.......................................................................... 88Pipeline Node Property Names ............................................................... 88

Pipeline Node Results............................................................................ 89


6/215

vi Contents

Pipeline Profile Property Names.............................................................. 89Pipeline Profile Results .......................................................................... 90

Pipe Results................................................................................................... 90

Pipe Standard Profile Dimensions ........................................................... 91Pipe Standard Profile Property Names ..................................................... 91Pipe Standard Profile Properties ............................................................. 91

Pipe Property Reports ........................................................................... 92Block VLE Results ........................................................................................... 94Heating/Cooling Curves................................................................................... 94

Number of Heating/Cooling Curves for a Block ......................................... 95

Heating/Cooling Curves for a Block......................................................... 95Size of a Heating/Cooling Curve ............................................................. 96Standard Heating/Cooling Curve Results ................................................. 97

Sequential Heating/Cooling Curve Properties ........................................... 97Specific Heating/Cooling Curve Properties ............................................... 98Interconnecting Stream IDs................................................................... 99

4 Stream Result Subroutines ..............................................................................101

Stream Identification .................................................................................... 101Listing Stream IDs.............................................................................. 101Determining the Next Stream .............................................................. 102

Material Stream Results ................................................................................ 102Retrieving Basic Stream Information..................................................... 102

Listing Substream IDs......................................................................... 103Retrieving Stream Results ................................................................... 103

Retrieving a Single Stream Property ..................................................... 104

Heat and Work Stream Results ...................................................................... 104Component Attribute Results ......................................................................... 105

Determining the Number of Components with Attributes ......................... 105

Determining Number of Attributes for a Component ............................... 106

Determining Component Attribute Size ................................................. 106

Retrieving Component Attribute Values ................................................. 107Substream Attribute Results .......................................................................... 107

Determining the Number of Substream Attributes .................................. 107Determining Substream Attribute Size .................................................. 108Retrieving Substream Attribute Values.................................................. 108

Stream Property Set Results.......................................................................... 109

Determining Dimensions of Stream Property Values ............................... 109Retrieving Stream Property Results ...................................................... 109

5 Physical Property Table Results Subroutines...................................................111

Property Table Identification .......................................................................... 112

Property and Flashcurve Table Results ............................................................ 112

Determining Property Table Dimensions................................................ 112Retrieving Sequential Properties in a Table ............................................ 113Retrieving Specific Properties from a Table ............................................ 113

Pressure-Temperature Envelope Results.......................................................... 114Determining Dimensions for Properties in the Envelope........................... 114

Determining Envelope Dimensions........................................................ 115

Retrieving Temperature and Pressure for Envelope Branch ...................... 115Retrieving Sequential Envelope Properties ............................................. 116

Retrieving Specific Envelope Properties ................................................. 117


7/215

Contents vii

6 Costing Results Subroutines ............................................................................119

Equipment Item Identification........................................................................ 120Determining Number of Equipment Items.............................................. 120

Listing Equipment Items ..................................................................... 120Determining Next Equipment Item ....................................................... 120

Equipment Item Results ................................................................................ 121

Retrieving Equipment Item Costing Results ........................................... 121Determining Equipment Item Sizing Results .......................................... 121

Retrieving Equipment Item Sizing Results ............................................. 122

7 Pressure Relief Subroutines ............................................................................123

Pressure Relief Block Identification ................................................................. 124Determining the Number of Pressure Relief Blocks.................................. 124Listing Pressure Relief Blocks............................................................... 124

Determining the Next Pressure Relief Block ........................................... 125Pressure Relief Results.................................................................................. 125

Determining the Number of Substreams................................................ 126

Determining Dimensions of Pressure Relief Arrays.................................. 126

Listing Profile Properties ...................................................................... 127Retrieving Dynamic Scalar Results........................................................ 128Retrieving Steady-State Scalar Results ................................................. 129

Retrieving Non-Component-Dependent Dynamic Profiles......................... 129

Retrieving Dynamic Component-Dependent Profiles................................ 130Retrieving Steady-State Profiles ........................................................... 131

Determining Vent Accumulator Profile Dimensions.................................. 131

Listing Vent Accumulator Profile Properties ............................................ 132Retrieving Non-Component-Dependent Vent Accumulator Profiles ............ 132Retrieving Component-Dependent Vent Accumulator Profiles ................... 133

Determining Pressure Relief Vent Profile Dimensions .............................. 133

Listing Vent Profile Properties .............................................................. 134

Retrieving Position-Dependent Vent Profiles........................................... 134Retrieving Component-Dependent Vent Profiles ..................................... 135

8 Examples .........................................................................................................137

Example 1: Stream Heat and Material Balance Table Generation ........................ 137Declaring Variables and Dimensioning................................................... 137Initializing the Toolkit ......................................................................... 138

Finding Number of Streams ................................................................. 139Finding Component Molecular Weight ................................................... 139

Writing Stream Table .................................................................................... 140Example 2: Interactive Heating/Cooling Curve Table Generation ........................ 143

Declaring Variables............................................................................. 143

Initializing the Toolkit ......................................................................... 143Finding Number of Blocks .................................................................... 143

Finding Blocks with Heating/Cooling Curves........................................... 144Prompting for Block Name ................................................................... 145Finding Heating/Cooling Curves for Selected Block ................................. 145Finding Dimensions of Heating/Cooling Curve ........................................ 146

Retrieving Standard Heating/Cooling Curve Results ................................ 146Retrieving Property Sets ..................................................................... 147

Example 3: Column Profile Results Written to Plot File ...................................... 150


8/215

viii Contents

Opening Files and Initializing Toolkit ..................................................... 150Finding List of Blocks .......................................................................... 151

Finding List of Properties ..................................................................... 151

Retrieving Selected Property Profile ...................................................... 152Closing the Application........................................................................ 152

Example 4: Distillation Column Diagram Generation ......................................... 154

Initializing the Toolkit ......................................................................... 154Retrieving Basic Block Results.............................................................. 154Retrieving Inlet and Outlet Stream Flows .............................................. 155Finding Inlet and Outlet Stream IDs ..................................................... 156

9 XML Summary File ...........................................................................................159

A Units ...............................................................................................................161

Table A.1 - Units Options .............................................................................. 163

B Property Names ..............................................................................................173

Table B.1 - Standard Property Names ............................................................. 174

Table B.2 - Mixture Thermodynamic Properties ................................................ 186Volume ............................................................................................. 186Flow Rates, Fractions .......................................................................... 186Enthalpy, Entropy, Gibbs Energy, Heat Capacity..................................... 186

Other properties................................................................................. 187

Table B.3 - Thermodynamic Properties of Components in Mixtures ..................... 188Table B.4 - Pure Component Thermodynamic Property Sets............................... 189

Table B.5 - Electrolyte Property Sets .............................................................. 190Table B.6 - Transport Properties..................................................................... 191

Mixture ............................................................................................. 191Component in a Mixture ...................................................................... 191

Pure Components............................................................................... 191

Table B.7 - Petroleum-Related Properties for Mixtures ...................................... 191Distillation Curves .............................................................................. 192

Distillation Temperature ...................................................................... 192Distillation Volume and Weight Percent ................................................. 193

Bulk Petroleum Property Values from Assay Curves ................................ 193Petroleum Cuts .................................................................................. 194

Petroleum Property Curves .................................................................. 195

Table B.8 - Elemental Analysis of Mixtures ...................................................... 196Table B.9 - Nonconventional Component Properties .......................................... 197

Table B.10 - Property Names for Costing Results.............................................. 197Equipment Type: HEATX ..................................................................... 197

Equipment Type: AIRCOOL.................................................................. 197Equipment Type: FIRED-HEATER.......................................................... 198

Equipment Type: PUMP ....................................................................... 198Equipment Type: COMPR..................................................................... 199

Equipment Type: BLOWER................................................................... 199

Equipment Type: TRAY-TOWER ............................................................ 200Equipment Type: TRAY-TOWER Section Results ..................................... 200

Equipment Type: USER ....................................................................... 200Equipment Type: V-VESSEL................................................................. 201

Equipment Type: H-VESSEL................................................................. 201Equipment Type: TANK ....................................................................... 202


9/215

Contents ix

Index ..................................................................................................................203


10/215

x Contents


11/215

Who Should Read this Guide 1

Who Should Read this Guide

The intended audience for this toolkit is application developers who need toget information from Aspen Plus simulations into their applications, and prefera file based data transfer to data transfer through OLE Automation.


12/215

2 Who Should Read this Guide


13/215

Introducing Summary File Toolkit 3

Introducing Summary FileToolkit

An Aspen Plus summary file is an ASCII file produced by Aspen Plus for everysimulation run, containing all the results for that run. The Summary File

Toolkit is a set of Fortran subroutines that you can use to build a program toextract results from an Aspen Plus summary file.

This reference manual describes the Summary File Toolkit and how to build

programs using the toolkit.

The manual assumes that you are familiar with Fortran, Aspen Plus, and theresults of an Aspen Plus simulation.

There is also an XML Results file available from Aspen Plus which can be

processed by standard XML tools. See Chapter 9 for some information aboutthis file.

Related DocumentationTitle Content

Aspen Plus Getting Started Building andRunning a Process Model

Tutorials covering basic use ofAspen Plus. A prerequisite for theother Getting Started guides

Aspen Plus Getting Started ModelingProcesses with Solids

Tutorials covering the Aspen plusfeatures designed to handle solids

Aspen Plus Getting Started ModelingProcesses with Electrolytes

Tutorials covering the Aspen plusfeatures designed to handleelectrolytes

Aspen Plus Getting Started Using

Equation-Oriented Modeling

Tutorials covering the use of

equation-oriented models inAspen Plus

Aspen Plus Getting Started CustomizingUnit Operation Models

Tutorials covering thedevelopment of custom unitoperation models in Aspen Plus

Aspen Plus Getting Started ModelingPetroleum Processes

Tutorials covering the Aspen Plusfeatures designed to handlepetroleum

Aspen Plus User Guide Procedures for using Aspen Plus


14/215

4 Introducing Summary File Toolkit

Title Content

Aspen Plus Reference Manual Series Detailed information about AspenPlus

Aspen Plus Application Examples A suite of examples illustratingcapabilities of Aspen Plus

Aspen Engineering Suite InstallationManual

Instructions for installing AspenPlus and other Aspen EngineeringSuite products

Technical SupportAspenTech customers with a valid license and software maintenance

agreement can register to access the online AspenTech Support Center at:

http://support.aspentech.com

This Web support site allows you to:

Access current product documentation

Search for tech tips, solutions and frequently asked questions (FAQs)

Search for and download application examples

Search for and download service packs and product updates

Submit and track technical issues

Send suggestions

Report product defects

Review lists of known deficiencies and defects

Registered users can also subscribe to our Technical Support e-Bulletins.

These e-Bulletins are used to alert users to important technical support

information such as: Technical advisories

Product updates and releases

Customer support is also available by phone, fax, and email. The most up-to-

date contact information is available at the AspenTech Support Center at

http://support.aspentech.com.
http://support.aspentech.com/http://support.aspentech.com/http://support.aspentech.com/http://support.aspentech.com/


15/215

1 Getting Started 5

1 Getting Started

This chapter describes how to build an application program using the AspenPlus Summary File Toolkit. It contains information on:

The summary file and toolkit.

Initializing the toolkit.

Determining data dimensions.

Retrieving data for an object.

Using the toolkit with a hierarchical Aspen Plus run.

Linking toolkit subroutines into your module.

Creating a toolkit application for Windows.

Transferring the toolkit to another computer.


16/215

6 1 Getting Started

The Summary File and ToolkitThe summary file is an ASCII file produced by Aspen Plus for every simulation

run. This file contains the summary of simulation results, such as blockresults, stream values, tray profiles, heating/cooling curves, and property

tables. The information in a summary file is also contained within the AspenPlus backup file. Summary files are named according to the form runid.SUM.

Backup files are named according to the form runid.BKP.

The summary file toolkit is a set of Fortran subroutines that retrieve results

information from the Aspen Plus summary file and backup file. (Use the

backup file with results, in place of the summary file, in proceduresthroughout this manual.)

The subroutines are organized around the logical structure of the data. You

can retrieve selected results. Or you can retrieve all the results of asimulation or simulation object (such as unit operation blocks or streams).

The Fortran source code for the subroutines is provided so that you can buildapplications on any computer.

The Fortran source code is delivered in a self-extracting zip archive namedtoolkit.exe in the Engine\Utl directory of the Aspen Physical Property System

installation (typically C:\Program Files\APrSystem\Engine\Utl\toolkit.exe).

The DLL is stored in the Engine\xeq directory of the Aspen Physical Property

System installation (typically C:\Program Files\APrSystem

\Engine\xeq\zetoolkit.dll).

To use the summary file toolkit, an application program must perform three

steps:

1 Initialize the toolkit for a summary file.

2 Get the dimensions of the data to be retrieved.

3 Retrieve the data.

These three steps are described in the following sections.

Initializing the ToolkitYou must initialize the toolkit for a summary file before you can retrieve data.

The initialization process consists of:

1 Accessing the required files and setting up directories for fast data access.

2 Defining the units of measurement for all values retrieved from the toolkit.

3 Specifying a value to substitute for missing results.


17/215

1 Getting Started 7

Accessing the Required FilesYou need to include file definitions for the following files during theinitialization process. The unit numbers for these files must match those

specified in the call to toolkit initialization routine TKINIT or TKINI2.

File Description

Summary file The summary file

Properties file A file defining the names of results within the summary file

Units file A file containing units conversion information

Scratch file A temporary direct access file for fast access to summary file results

Defining the Summary File

To define the summary file, use the subroutine TKOPEN. See Chapter 2 formore information.

Getting the Summary File NameBecause the summary file may be different each time the toolkit application is

executed, some input to the program is required to determine the summaryfile name. If the application program has an existing method of passing

information into the program, use this method to pass the summary file nameto the program.

Otherwise, the three principal ways the program can get the file name are by:

1 Prompting the user at the terminal.

2 Reading the file name from the command line.3 Reading the file name from a file.

Prompting the user is the easiest method for most operating systems. FortranREAD and WRITE statements are used to get the file name.

Getting Property and Units File NamesThe properties file, RCPROPNU.DAT, and the units file, RCUNITS.DAT, are

installed in the toolkit subdirectory of the Aspen Plus Simulation Engineinstallation. The Engine directory should be set as the value of the %asptop%

environment variable.


18/215

8 1 Getting Started

Example of Environment Variable for Windows

When running in an Aspen simulation engine window, the environmentvariable ASPTOP points to the top level supplementary directory for AspenPlus. The TOOLKIT directory is a subdirectory of this directory. You can use

the following code to expand the file specification:CALL GETENV('ASPTOP', ASPTOP)D O 5 0 I = 8 0 , 1 , - 1

IF (ASPTOP(I:I) .NE. ' ') GO TO 5550 CONTINUE55 CONTINUE

RCPROP = ASPTOP(1:I) // '\TOOLKIT\RCPROPNU.DAT'RCUNIT = ASPTOP(1:I) // '\TOOLKIT\RCUNITS.DAT'

Scratch File Units Number

The direct access file is used to provide fast access to data in the summary

file after initialization. The units number you specify for this file should not be

used by the application program.

Defining Units of Measurement

As part of the toolkit initialization process, you must specify a base units setin which the results will be returned. The base units set defines the units of

measurement for each physical quantity (units type).

The base units sets available are SI, ENG, MET, and OUT. To customize aunits set to change the output units of measurement for one or more physical

quantities, or convert a result to another unit of measurement, use the

subroutines described in Chapter 2. See Appendix A for other conversion

options.

Specifying a Value for Missing ResultsIf you make calls to the toolkit to retrieve results, and a requested result is

missing, the toolkit returns a special value in place of the result. As part ofthe toolkit initialization process, you specify this value by assigning it to theargument RMISS in the call to routine TKINIT or TKINI2. Choose a value thatwill not be mistaken for a real result. A very large value (greater than 1E20)

is recommended.

Determining the DataDimensionsThe toolkit data retrieval routines require you to know the data dimensions

before a retrieval is done. With these dimensions in mind, you must allocatespace inside your application program for the data before retrieving it.

Determining data dimensions includes:


19/215

1 Getting Started 9

1 Querying the summary file for the existence of simulation objects anddata within an object.

2 Defining the size of the data for a simulation object.

The subroutine TKINFO returns the number of blocks, streams, propertytables, and sensitivity tables in the summary file.

Each type of simulation object has a subroutine to find the next object insequence. These subroutines are:

Object Type Subroutine to Find Next Object

Blocks TKNBLK

Streams TKNSTR

Property tables TKNPPT

Sensitivity tables TKNEXT

Equipment item TKNEQP

Pressure relief TKNXPR

Each of these subroutines has a sequence number as an argument. The

sequence number identifies the position of the object within the summary file.For example, a sequence number of five for TKNBLK indicates the fifth unit

operation block in the summary file. Except for sensitivity objects and

pressure relief, the subroutine also returns information about the type ofobject: the unit operation model type for a block, the type of stream(MATERIAL, HEAT, or WORK), or the type of property table.

The data available for an object are organized by the type of data. Forexample, block data is organized into a standard results set, connectivityinformation, heating/cooling curve data, profile data, and property set profile

data. Each type of data has a routine that returns the dimensions of the data.

Chapters 2 through 7 describe the toolkit routines for determining thedimensions of data and retrieving it. If a type of data is not available for an

object, dimension values of zero are returned.

Retrieving Data for an ObjectOnce the dimensions for data are known, you can retrieve the data by callingthe appropriate routine. Each result returned is identified by a property name.

Appendix B contains a list of property names and their descriptions.

In addition to property names, some results have qualifiers to further identify

the data. For example, for an FSPLIT block, the split fractions for each outlet

stream are returned. The stream ID of the outlet stream is returned as aqualifier for the result.

You can use single subroutine calls to retrieve standard results for blocks,

streams, heating/cooling curves, and pressure-temperature envelopes.Standard tray or reactor profiles are retrieved one profile at a time. You canidentify property set results by the property set qualifiers:

Qualifier Description

PNAME Property name. See Appendix B for a description.

SUBSID Substream ID


20/215

10 1 Getting Started

Qualifier Description

PHASE Phase (VAPOR, LIQUID, LIQUID1, LIQUID2, TOTAL, SOLID)

COMPID Component ID

WETDRY Wet/dry basis (WET or DRY)

BASIS Unit basis for properties with multiple units

Can be left unspecified. Valid values for the basis are MOLE, MASS and FLOW. MOLE and MASS apply todensity (specifying mole density and mass density), entropy (specifying mole entropyand mass entropy), and heat capacity (specifying mole heat capacity and mass heatcapacity). MOLE and FLOW apply to volume (specifying mole volume and volumeflow). MOLE, MASS and FLOW apply to enthalpy (specifying mole enthalpy, massenthalpy, and enthalpy flow).

Before calling a subroutine, make sure that all the qualifiers are set to the

desired values or unset. If you do not unset a qualifier from a previous value,

unexpected results may be returned.

All values with physical dimensions are returned in the units you specifyduring the initialization process. The units label and the units type are usually

returned with the value. When the physical dimensions of a property arealways known, the units information may not be returned. You can call theutility routine TKLABL to return the units label for a value not returned. In

addition, you can use the utility routine TKCNVT to convert a value fromdefault units to user-specified units.

Sometimes the retrieved data values are two-dimensional. For example, the

column profile routine TKPRO2 returns values for every stage and component

combination in a column. The dimension for the results then appears as twodimensions multiplied together. This figure yields the total number of results

returned. It also shows the sequence of the results data in the array.

The results array is ordered so that the first dimension can scroll before the

second dimension. In the TKPRO2 example, the results are returned inRVALS, which is dimensioned as NCP*NSTAGE (the number of components*

the number of stages). The values returned in the RVALS array are orderedso that the results for every component on the first stage are given first,

followed by all the results for every component on the second stage, and so

on.


21/215

1 Getting Started 11

Using the Toolkit With aHierarchical Aspen Plus RunMost Aspen Plus objects, including hierarchies, can exist within hierarchies. In

such cases it is not sufficient to reference an object by type and eightcharacter ID. The objects ID must contain the full hierarchical path to theobject, with each hierarchy name separated by a period (.). For example, if a

run contains hierarchy H1, which contains hierarchy H2, which contains blockB1, refer to the block as H1.H2.B1.

All toolkit subroutines that accept or return an object ID declare the argument

as CHARACTER *(*). When passing such an argument, set up the dimensionlarge enough to hold the hierarchical ID. If referencing a non-hierarchicalproblem, declaring the ID arguments as CHARACTER*8 is sufficient.

Note: The length must be larger for hierarchical problems. A declaration ofCHARACTER*128 is always sufficient.

The toolkit always returns IDs with full path name. For example, TKNBLK,which lists the blocks in a run, cycles through all blocks in all hierarchy levels,

returning IDs with full path name.

Block, stream, pressure relief, property table, and sensitivity IDs arehierarchical. Property name, substream, phase, and component IDs are not.

Note: It is not possible to cycle through all blocks in a single hierarchy level.

Linking Toolkit Subroutines intoYour ModuleAfter you write or modify your application program to call the appropriate

toolkit subroutines to retrieve the data, you must build an executable module,including the toolkit routines. The object code for the toolkit subroutines isstored in a dynamic link library for Windows, which is delivered with Aspen

Plus.

To link to this library, include %asptop%\toolkit\zetoolkit.lib in the linkerdirective, where %asptop% represents the Engine installation directory.

Creating a Toolkit Applicationfor WindowsThe source code, in the form of a self-extracting executable, and dynamic link

library (DLL) for the summary file toolkit are located in the toolkit directory ofthe Aspen Plus Simulation Engine installation.


22/215


About the Windows VersionThe Windows version of the summary file toolkit consists of two files:

File Name Description

zetoolkit.dll The summary file toolkit dynamic-link library. This file is stored in the

Engine\xeq subfolder of the APrSystem installation, typically C:\ProgramFiles\APrSystem \Engine\xeq\zetoolkit.dll

zetoolkit.lib Import library. This file contains the external references to the summaryfile toolkit routines in zetoolkit.dll. This file is stored in the Engine\toolkitsubfolder of the Aspen Plus installation, along with the Fortran sourcefiles.

The DLL and LIB are compiled and linked with Intel Fortran 9.1.

If you are using the summary file toolkit as part of a full installation of AspenPlus, you can compile and link toolkit applications with the Fortran compiler

for your Operating System. Make sure you are set up for running Aspen Plus.Aspen Plus provides procedures to help use the Aspen Plus Fortran utilities.The following table summarizes these procedures:

To do this Enter these commands

Compile a Fortran routine ASPCOMP appname

Link an application executable link @appname.opt

Run a previously linked executable appname.exe

Where:

appname = The file name of the main Fortran application. Do notinclude the file extension when specifying the filename. ASPCOMP will accept Fortran files with the

extension .for.

appname.opt = Text file containing the linker directive commands. For

more information, see the following section, LinkerDirective Commands for Windows.

Linker Directive Commands forWindowsThe linker directive file contains a set of commands that control thegeneration of the linked executable. Any object files or libraries you want to

be included in the linked executable must be listed in the linker directive file.

The standard set of commands required to link a toolkit application are shownfor a toolkit application named tkexampl.

Example of Linker Directive File-entry:mainCRTStartupmsvcrt.lib-nodefaultlib:libc.liblibifcoremd.lib-nodefaultlib:libifcore.lib


23/215

1 Getting Started 13

libifportmd.lib-nodefaultlib:libifport.liblibmmd.lib-nodefaultlib:libm.lib-nodefaultlib:libifcoremt.lib-nodefaultlib:libmmt.libc:\Engine\toolkit\zetoolkit.libtkexample.obj-out:tkexample.exe

Substitute c:\Engine with the appropriate drive and directory location wherethe Aspen Plus Simulation Engine is installed. Replace tkexample with thename of your application. Add any additional object files and libraries you

need to this directive file.

After creating the linker directive file for your application, you can use the linkand run commands to generate and run your application's executable

program.

Calling Summary File ToolkitRoutinesThe files are compiled so that the summary file toolkit routines use thedefault calling and naming conventions for the Fortran compiler. These are

similar to the stdcall convention, except:

All routine names are in uppercase.

All arguments are passed by reference.

There is a hidden string length argument when character strings are

passed.

Applications calling the DLL should use this convention. Please see yourcompiler documentation about calling Fortran routines and hidden string

length arguments.

Fortran applications can call the routines in the Summary File Toolkit withoutany code modifications. If you want to call the Summary File Toolkit from

another language, you will have to modify the code to work with the Fortranconventions adopted, but this is not recommended. Instead, export an XMLsummary file and use standard XML tools to process it.

Opening and Closing Files Using the

Summary File ToolkitYou must be careful with file input and output when using the Summary File

Toolkit. You must observe the following practices:

Open and close the summary file with TKOPEN and TKCLFL.

Open and close the log file optionally used in TKINI2, with TKOPEN and

TKCLFL.

Close the toolkit with TKCLOS, at the end of each run.


24/215


Close the summary file and the log file with TKCLFL, at the end of eachrun.

Do not use TKOPEN and TKCLFL for opening and closing the files yourapplication reads from or writes to.

Using Fortran to Call RoutinesUse the Fortran default naming and calling conventions for calls to the

summary file toolkit shared library, when compiling code. You do not have to

carry out any special steps to call the summary file toolkit routines.

When linking the application, make sure a reference to the zetoolkit shared

library is included in the list of libraries, and that its pathname is included in

the list of library directories.

You must write your code and any setup procedures so that the zetoolkit

shared library is in your run time path.

Changes in the ToolkitAspenTech tries to avoid changing the arguments to these routines but

occasionally changes are necessary. Sometimes these changes are made to

support changes in Aspen Plus; because of this, sometimes old versions of thetoolkit will not work with newer summary files. However, the latest version ofthe toolkit should always work with all older Aspen Plus summary files.

The changes likely to affect users are listed here:

In version 11.1, all of the arguments holding stream IDs and block IDs

(including sensitivity blocks and the like) became variable length, changingfrom CHARACTER*8 to CHARACTER*(*) to support hierarchy. See Using the

Toolkit With a Hierarchical Aspen Plus Run on page11 for more info.

In version 12.1, the filename argument in TKOPEN changed fromCHARACTER*80 to CHARACTER*(*) to support using the toolkit with

summary files with long file paths, although the documentation was not

updated to reflect this change until version 2006. We recommend using aCHARACTER of length 256 to hold this filename, as there may be otherproblems with a longer file path.


25/215

2 General Subroutines 15

2 General Subroutines

This chapter describes the purpose and use of subroutines in the Aspen PlusSummary File Toolkit. Use the subroutines described in this chapter for:

Initializing the summary file toolkit.

Retrieving run information.

Retrieving flowsheet balance results.

Setting and changing units of measurement.

Retrieving component information.

Retrieving sensitivity results.


26/215

16 2 General Subroutines

Initializing the Summary FileToolkitBefore you can retrieve any results from a summary file, you must call

subroutine TKINIT or TKINI2 to initialize the summary file toolkit.

TKINIT assigns Fortran unit numbers and unit names for files used by the

toolkit. See Initializing the Toolkit, Chapter 1, for information on identifying

the necessary files.

The scratch file is a direct access file used by the toolkit to store intermediate

data. You must supply a Fortran unit number for the scratch file.

To open the summary file and connect it to a unit number, you can:

Use a Fortran OPEN statement in your program.

Call TKOPEN routine (see Opening and Closing Files, this chapter), if using

the Windows DLL.

The property number file and the unit definition file are delivered with AspenPlus. The file names you specify to call TKINIT depend on the computer andoperating system you are using (see Getting Property and Units File Names,

Chapter 1).

TKINIT sets the default units set for all results data to the value of UNISET.This can be one of four values: SI, ENG, MET, or OUT. The first three values

correspond to the Aspen Plus units sets with these names. OUT can be used

to retrieve the results from the summary file without any UOM conversion.The data is retrieved in the same units as the Aspen Plus out units for therun.

Calling Sequence for TKINITCALL TKINIT (UNISET, IDIRAC, ISUMMF, IPROPN, RCPROP, IUNITS,RCUNIT, RMISS, IERR)

Argument List Descriptions for TKINIT

Variable I/O Type Dimension Description

UNISET I CHARACTER*4 Units set for retrieved values (SI, ENG,MET, or OUT)

IDIRAC I INTEGER Fortran unit number for scratch file

ISUMMF I INTEGER Fortran unit number for summary file

IPROPN I INTEGER Fortran unit number for propertynumbers file

RCPROP I CHARACTER*80 File name for property numbers file

IUNITS I INTEGER Fortran unit number for units definitionfile

RCUNIT I CHARACTER*80 File name for units definition file

RMISS I REAL*8 Real value flag for missing values


27/215



IERR O INTEGER Error flag (0=No error)

I = Input to subroutine, O = Output from subroutine

If you initialize the toolkit with TKINIT, Aspen Plus writes errors or warnings

from the toolkit run to the screen. TKINI2 works in the same way as TKINIT,except that it allows you to specify a Fortran unit number for error andwarning messages. This is useful for applications where messages should not

be written directly to the screen. Like the summary file, this file shouldalready be opened before calling TKINI2. If you specify a negative unit

number for the error and warning messages, they are turned off.

Calling Sequence for TKINI2CALL TKINI2 (UNISET, IDIRAC, ISUMMF, IPROPN, RCPROP, IUNITS,RCUNIT, RMISS, IERR, ILOG)

Argument List Descriptions for TKINI2


UNISET I CHARACTER*4 Units set for retrieved values (SI,ENG, MET or OUT)



IPROPN I INTEGER Fortran unit number for propertynumbers file

RCPROP I CHARACTER*80 File name for property numbers file

IUNITS I INTEGER Fortran unit number for unitsdefinition file

RCUNIT I CHARACTER*80 File name for units definition file

RMISS I REAL*8 Real value flag for missing values


ILOG I INTEGER Fortran Unit number for log file.Negative for no messages.


Closing the Summary FileToolkitCall subroutine TKCLOS to close a summary file toolkit run. TKCLOS closes

files opened by TKINIT or TKINI2, so the argument list should use the

corresponding values passed to TKINIT or TKINI2. The summary file is notclosed by this routine, but is instead rewound to its first record. Use TKCLFLto close it.

Calling Sequence for TKCLOSCALL TKCLOS (ISUMMF, IDIRAC, IPROPN, IUNITS)


28/215


Argument List Descriptions for TKCLOS




IPROPN I INTEGER Fortran unit number for property numbersfile

IUNITS I INTEGER Fortran unit number for units definition file


Opening and Closing FilesTwo routines are provided to open and close files with a specified Fortran unitnumber. If you are using a DLL version of the summary file toolkit, you must

use these routines to open and close the summary file, and any log file used

by TKINI2. Unless you do so, the summary file toolkit DLL will not recognize

the Fortran unit numbers you pass it for these files. When using the DLL, youshould not call these routines to open and close files your code accesses.

Call subroutine TKOPEN to open the file with the specified Fortran unitnumber.

Calling Sequence for TKOPENCALL TKOPEN (IUNIT, FILNAM, ACCESS, FORM, IRECL, STATUS, MODE,IERR)

Argument List Descriptions for TKOPEN


IUNIT I INTEGER Unit number of the file being opened

FILNAM I CHARACTER*(*) Name of file to open

ACCESS I CHARACTER*16 File access (SEQUENTIAL, DIRECT)

FORM I CHARACTER*16 I/O format (FORMATTED,UNFORMATTED)

IRECL I INTEGER Record length

STATUS I CHARACTER*16 File status (SCRATCH, OLD, NEW,UNKNOWN)

MODE I CHARACTER*16 Open mode (READ, WRITE)

IERR O INTEGER Error flag(0=No error,1=Invalid argument,>0= IOSTAT error)


Call subroutine TKCLFL to close the file with the specified Fortran unit

number.

Calling Sequence for TKCLFLCALL TKCLFL (IUNIT, IERR)


29/215


Argument List Descriptions for TKCLFL


IUNIT I INTEGER Unit number of the file being closed



Retrieving Run InformationUse the subroutines in this section to retrieve general information about the

run.

Call TKINFO to obtain standard information about a run.

Call TKTITL to obtain the run title.

Call TKACCT to obtain run accounting information.

Standard Run InformationCall subroutine TKINFO to retrieve the following standard information about arun:

Aspen Plus release name.

Run ID of the Aspen Plus run.

Date of the run.

Input file name.

Input translator status.

Simulation program status.

Number of simulation objects (blocks, streams, property tables, sensitivity

tables).

Calling Sequence for TKINFOCALL TKINFO (VERSN, RUNID, DATE, INFILE, ISSTAT, ISTAT, NBLOCK,NSTRM, NTABLE, NSENS)


30/215


Argument List Descriptions for TKINFO


VERSN O CHARACTER*20 Aspen Plus release name

RUNID O CHARACTER*8 Aspen Plus run IDDATE O CHARACTER*80 Date of Aspen Plus run

INFILE O CHARACTER*80 Aspen Plus input file name

ISSTAT O INTEGER Input translator completion code

ISTATF O INTEGER 6 Simulation status flags for eachelement. See ISTATF, below.

NBLOCK O INTEGER Number of blocks

NSTRM O INTEGER Number of streams

NTABLE O INTEGER Number of property tables

NSENS O INTEGER Number of sensitivity tables


ISTATF

The values are:

0 = Completed without errors,1 = Completed with errors,2 = None in this simulation,

The elements represent:

ISTATF(1): Block status,(2): Convergence status,

(3): Sensitivity status,

(4): Case study status,

(5): Stream calculation status,(6): Fortran and transfer status

Run TitlesCall subroutine TKTITL to retrieve the run title.

Calling Sequence for TKTITLCALL TKINFO (TITLE)

Argument List Descriptions for TKTITL


TITLE O CHARACTER*64 Run title



31/215


Accounting InformationCall subroutine TKACCT to obtain accounting information for a run.

Accounting information is only available if requested in the Aspen Plus input.

Calling Sequence for TKACCTCALL TKACCT (ACCNT, PROJID, PRNAME, USER, IERR)

Argument List Descriptions for TKACCT


ACCNT O CHARACTER*8 Account number

PROJID O CHARACTER*8 Project ID

PRNAME O CHARACTER*32 Project name

USER O CHARACTER*20 User name



Retrieving Flowsheet BalanceResultsCall subroutine TKFLWB to retrieve the absolute and relative differences for:

Total mole balance.

Total mass balance.

Enthalpy balance.

Mole balance for each conventional component.

Mass balance for each nonconventional component.

Calling Sequence for TKFLWBCALL TKFLWB (ABSMOL, RELMOL, ABSMAS, RELMAS, ABSENT, RELENT, NCC,ABSCON, RELCON, NNCC, ABSNC, RELNC, IERR)


32/215


Argument List Descriptions for TKFLWB


ABSMOL O REAL*8 Absolute mole balance difference(UNITS=MOLE-FLOW)

RELMOL O REAL*8 Relative mole balance difference

ABSMAS O REAL*8 Absolute mass balance difference(UNITS=MASS-FLOW)

RELMAS O REAL*8 Relative mass balance difference

ABSENT O REAL*8 Absolute enthalpy balance difference(UNITS=ENTHALPY-FLOW)

RELENT O REAL*8 Relative enthalpy balance difference

NCC I INTEGER Number of conventional components

ABSCON O REAL*8 NCC Absolute mole balance difference for eachconventional component(UNITS=MOLE-FLOW)

RELCON O REAL*8 NCC Relative mole balance for eachconventional component

NNCC I INTEGER Number of nonconventional components

ABSNC O REAL*8 NNCC Absolute mass balance difference for eachnonconventional component(UNITS=MASS-FLOW)

RELNC O REAL*8 NNCC Relative mass balance difference for eachnonconventional component



Units ConversionUse the subroutines in this section to:

Change the units set for results.

Convert units for individual results.

Find units labels for results.

Changing Units SetsValues retrieved from the summary file are converted to the current units set.

The variable SETID takes the same values as UNISET does in TKINIT andTKINI2. The units set is initially defined in the call to subroutine TKINIT orTKINI2. You can change the units set at any point in your program, by calling

subroutine TKUNIT.

Use TKUNIT to define a new base units set and any units' options that shouldoverride the units' options in the base set.


33/215


Calling Sequence for TKUNITCALL TKUNIT (SETID, NTYPES, TYPES, LABELS, IERR)

Argument List Descriptions for TKUNIT


SETID I CHARACTER*4 Base units set(SI, ENG, MET, or OUT)

NTYPES I INTEGER Number of units types to changefrom the base set

TYPES I CHARACTER*12 NTYPES List of units' types to change fromthe base set. See Appendix A for alist of valid units' types.

LABELS I CHARACTER*16 NTYPES List of units labels for the units typesto change from the base set. SeeAppendix A for a list of valid units'labels.



Converting Units for Real NumbersCall subroutine TKCNVT to perform units conversion on a result or an array of

results. TKCNVT converts values from the current units set to units specifiedby a unit's label. TKCNVT will not convert a result if the current units set is

OUT units. (There is no such thing as a current unit for a particular units type

with OUT units.)

Calling Sequence for TKCNVT

CALL TKCNVT (TYPE, LABEL, NVAL, RVALI, RVALO)

Argument List Descriptions for TKCNVT


TYPE I CHARACTER*12 Units type. Valid units' types areshown in Appendix A.

LABEL I CHARACTER*16 Units label for output. See AppendixA for a list of valid units' labels.

NVAL I INTEGER Number of values to convert

RVALI I REAL*8 NVAL Array of values to be converted.These values are assumed to be in

the current units set.RVALO O REAL*8 NVAL Array of converted values


Determining Units Labels

Call subroutine TKLABL to determine the units' labels for a list of units' types

in the current units set. TKLABL will not retrieve a label for a type if the


34/215


current units set is OUT units. (There is no such thing as a current unit for aparticular units type with OUT units.)

Calling Sequence for TKLABLCALL TKLABL (NTYPES, TYPES, LABELS)

Argument List Descriptions for TKLABL


NTYPES I INTEGER Number of units types

TYPES I CHARACTER*12 NTYPES Units types. See Appendix A for a listof valid units' types.

LABELS O CHARACTER*16 NTYPES Units labels


Component InformationRetrievalUse the subroutines in this section to retrieve information about thecomponents in the simulation:

TKCOMP gets the number of components in the simulation.

TKCIDS gets the list of component IDs.

TKALIS gets lists of conventional components and their aliases.

TKCASN gets lists of components and their CAS numbers.

TKCPRP retrieves component properties, such as molecular weight, boiling

point, and standard volume.

Number of ComponentsCall subroutine TKCOMP to determine the number of components in a

simulation. TKCOMP returns the number of both conventional andnonconventional components.

Calling Sequence for TKCOMPCALL TKCOMP (NCC, NNCC)


35/215


Argument List Descriptions for TKCOMP


NCC O INTEGER Number of conventional components

NNCC O INTEGER Number of nonconventional components


Component IDsCall subroutine TKCIDS to retrieve the component IDs for conventional and

nonconventional components.

Calling Sequence for TKCIDSCALL TKCIDS (NCC, NNCC, COMPID, COMPNC)

Argument List Descriptions for TKCIDSVariable I/O

Type Dimension Description


NNCC I INTEGER Number of nonconventionalcomponents

COMPID O CHARACTER*8NCC Component IDs for conventionalcomponents

COMPNC O CHARACTER*8NNCC Component IDs for nonconventionalcomponents


Component Alias NamesCall subroutine TKALIS to retrieve conventional component IDs and theiraliases.

Calling Sequence for TKALISCALL TKALIS (NCC, COMPID, ALIAS, IERR)

Argument List Descriptions for TKALIS



COMPID O CHARACTER*8 NCC Conventional component IDs

ALIAS O CHARACTER*12 NCC Alias corresponding to componentIDs




36/215


Component CAS NumbersCall subroutine TKCASN to retrieve conventional component IDs and their

CAS numbers. CAS numbers will be blank for segments and user-defined

components.

Calling Sequence for TKCASNCALL TKCASN (NCC, COMPID, CASN, IERR)

Argument List Descriptions for TKCASN



COMPID O CHARACTER*8 NCC Conventional component IDs

CASN O CHARACTER*12 NCC CAS numbers corresponding to

component IDs



Component PropertiesCall subroutine TKCPRP to retrieve component properties for conventionalcomponents. The properties that you can retrieve are molecular weight,

boiling point, and standard volume.

Calling Sequence for TKCPRPCALL TKCPRP (PROP, NCC, RVALS, LABEL)

Argument List Descriptions for TKCPRPVariable I/O

Type Dimension Description

PROP I CHARACTER*8 Property name (MW, TB, or VSTD)

NCC I INTEGER Number of components

RVALS O REAL*8 NCC Property values (units areTEMPERATURE for TB andMOLE-VOLUME for VSTD)

LABEL O CHARACTER*16 Units label


Sensitivity Block ResultsYou can retrieve sensitivity table results from the summary file, using the

following three-step process:

1 Call TKNEXT to identify the next sensitivity block.

2 Call TKNSEN to retrieve the number of points and the number of columns

in the table.


37/215


3 Call TKSENS to retrieve the values for the table and the headers for thecolumns.

Identifying Sensitivity Blocks

Call subroutine TKNEXT to find the name of the next sensitivity block.

To find the block ID of the first sensitivity block, set IOFF to 1. To find thename of the second block, set IOFF to 2, and so on.

Calling Sequence for TKNEXTCALL TKNEXT (TYPE, IOFF, ID1, ID2, IERR)

Argument List Descriptions for TKNEXT


TYPE I CHARACTER*12 Object type (set to SENSITIVITY forsensitivity blocks)

IOFF I INTEGER Sequence number

ID1 O CHARACTER*(*) First ID of the object. For sensitivityblocks, it is the block ID. Returnscomplete hierarchy specification.

ID2 O CHARACTER*12 Second ID of the model name, forthe object. For sensitivity blocks, it isblank.



Determining Sensitivity Dimensions

Call subroutine TKNSEN to determine the number of points and number ofcolumns in the sensitivity table.

Calling Sequence for TKNSENCALL TKNSEN(SENSID, NPOINT, NCOL, IERR)

Argument List Descriptions for TKNSEN


SENSID I CHARACTER*(*) Sensitivity block ID

NPOINT O INTEGER Number of points in table

NCOL O INTEGER Number of columns in table




38/215


Retrieving Sensitivity ResultsCall subroutine TKSENS to retrieve the results for a sensitivity table. The

columns are identified by the variable HEADER. The actual argument to

RVALS should be declared as a one-dimensional array of length, equal to orgreater than (NPOINT*NCOL). The results in each column are stored

consecutively.

Calling Sequence for TKSENSCALL TKSENS (SENSID, NPOINT, NCOL, HEADER, RVALS, IERFLG, IERR)

Argument List Descriptions for TKSENS


SENSID I CHARACTER*(*) Sensitivity block ID(Full hierarchical path)

NPOINT I INTEGER Number of points in table

NCOL I INTEGER Number of columns in tableHEADER O CHARACTER*8 6, NCOL Table header of each table column

RVALS O REAL*8 NPOINT*NCOL

Results for sensitivity table

IERFLG O INTEGER NPOINT Error flag for each row of table(0=No error)




39/215

3 Block Result Subroutines 29

3 Block Result Subroutines

This chapter describes the use of block result retrieval subroutines in thesummary file toolkit. Use the subroutines described in this chapter for:

Block identification, connectivity, and results.

Compressor results.

Heat exchanger results.

Column results.

Tray reports and tray/packing sizing and rating.

Reactor results and property reports.

Pipeline results.

Block vapor-liquid equilibrium (VLE) results.

Heating/cooling curves.


40/215

30 3 Block Result Subroutines

Block IdentificationThe following subroutines are used to identify blocks in the summary file:

TKBIDS returns a list of blocks in the summary file. TKNBLK retrieves the next block ID in sequence.

Both routines return the model type for each block.

Block IDsCall subroutine TKBIDS to get the list of blocks and model types.

Calling Sequence for TKBIDSCALL TKBIDS (NBLOCK, BLKID, BLKTYP, IERR)

Argument List Descriptions for TKBIDS


NBLOCK I INTEGER Number of blocks. You can find thevalue of NBLOCK by calling TKINFO.

BLKID O CHARACTER*(*) NBLOCK Block ID(Full hierarchical path)

BLKTYP O CHARACTER*12 NBLOCK Model type



Next BlockCall subroutine TKNBLK to find the name of the next unit operation block.

To find the block ID of the first block, set IBLOCK to 1. To find the name of

the second block, set IBLOCK to 2, and so on.

Calling Sequence for TKNBLKCALL TKNBLK (IBLOCK, BLKID, BLKTYP, IERR)

Argument List Descriptions for TKNBLK


IBLOCK I INTEGER Block number

BLKID O CHARACTER*(*) Block ID

BLKTYP O CHARACTER*12 Model type




41/215


Block Connectivity InformationUse the subroutines in this section to retrieve the inlet and outlet stream

connectivity for a block. Retrieving the inlet and outlet streams of a block is atwo-step process:

1 Call subroutine TKCNTN to find the number of inlet and outlet streams.2 Call subroutine TKCNCT to retrieve the list of inlet and outlet stream

names.

Some blocks have additional connectivity information, such as stage number

and column number. For these blocks you can obtain the additionalinformation by calling TKPORT.

Number of Inlet and Outlet StreamsCall subroutine TKCNTN to determine the number of inlet streams and outlet

streams for a particular block.

Calling Sequence for TKCNTNCALL TKCNTN (BLKID, NIN, NOUT, IERR)

Argument List Descriptions for TKCNTN


BLKID I CHARACTER*(*) Block ID

NIN O INTEGER Number of inlet streams

NOUT O INTEGER Number of outlet streams



Stream Names and Types

Call subroutine TKCNCT to retrieve the names of the inlet and outlet streams

for a block, along with the stream types (MATERIAL, HEAT, or WORK).

Calling Sequence for TKCNCTCALL TKCNCT (BLKID, NIN, NOUT, BLKIN, TYPIN, BLKOUT, TYPOUT,

IERR)

Argument List Descriptions for TKCNCT



NIN I INTEGER Number of inlet streams

NOUT I INTEGER Number of outlet streams

BLKIN O CHARACTER*(*) NIN Inlet stream IDs

TYPIN O CHARACTER*8 NIN Stream type of inlet streams(MATERIAL, HEAT, or WORK)


42/215



BLKOUT O CHARACTER*(*) NOUT Outlet stream IDs

TYPOUT O CHARACTER*8 NOUT Stream type of outlet streams(MATERIAL, HEAT, or WORK)



Additional Port Information

Call subroutine TKPORT to obtain additional port information on inlet andoutlet streams for a block. The additional information includes the port name(for example, F indicating a feed port) and additional identifiers, such as

column number and stage number. Only the blocks with the model typesshown in Table 3.1 need this subroutine. The outlet types for the other blocksare implicit in the order that the streams are returned by TKCNT. For

example, vapor streams are returned before liquid streams.

Calling Sequence for TKPORTCALL TKPORT (BLKID, NIN, NOUT, INPORT, IDIN1, IDIN2, IOPORT,

IDOUT1, IDOUT2, IERR)

Argument List Descriptions for TKPORT



NIN I INTEGER Number of inlet streams

NOUT I INTEGER Number of outlet streams

INPORT O CHARACTER*4 NIN Inlet port names

IDIN1 O INTEGER NIN ID1 for inlet streams

IDIN2 O INTEGER NIN ID2 for inlet streams

IOPORT O CHARACTER*4 NOUT Outlet port names

IDOUT1 O INTEGER NOUT ID1 for outlet streams

IDOUT2 O INTEGER NOUT ID2 for outlet streams

IERR O INTEGER Error flag:0 = No error1 = Block ID not found2 = Block has no portinformation



43/215


Port Information Returned by TKPORT

Model Type Port Name Description ID1 ID2

Extract TF

BFSFTPBPSP

Top feed

Bottom feedSide feedTop productBottom productSide product

Stage

number

HeatX HFCFHPCPHWDCWD

Hot feedCold feedHot productCold productHot water decantCold water decant

Mcompr S1FIFWS

HSFLSLKWD

WSHS

Stage1 feedStage feedWork feed

Heat feedProductLiquid knockoutWater draw

Work outHeat out

Stagenumber

MheatX HFCFHP

CPHWDCWD

Hot feedCold feedHot product

Cold productHot water decantCold water decant

Streamnumber

MultiFrac F

HSVDLDRSPCWDHS

Feed

Heat feedVapor distillateLiquid distillateResidueSide productWater distillateHeat product

Column

number

Stage

number

PetroFrac MFSFMHFSHFPHFVDLD

BSPCWDSBPSCHSRHSMHPSHPPHP

Main column feedStripper steam feedMain column heat feedStripper heat feedPumparound heat feedMain column vapor distillateMain column liquid distillate

Main column bottoms productMain column side productMain column condenser water decantStripper bottom productPseudo streamCondenser heat streamReboiler heat streamMain column heat productStripper heat productPumparound heat product

Columnnumber

Stagenumber


44/215


Model Type Port Name Description ID1 ID2

RadFrac FHSVDLDRSPWDCHSRHS

FeedHeat feedVapor distillateLiquid distillateResidueSide productWater distillateCondenser heatReboiler heat

Stagenumber

RateFrac FHSVD

LDRSPCWDHS

FeedHeat feedVapor distillate

Liquid distillateResidueSide productWater distillateHeat product

Columnnumber

Sectionnumber

SCFrac F

SFDBSP

Feed

Steam feedDistillateBottomsSide product

The PetroFrac column number for the main column is one. The strippers arenumbered sequentially, starting with two.

Standard Block ResultsAll unit operations have standard scalar block results. For example, Flash2

results include the outlet temperature and pressure, the vapor fraction, and

the heat duty.

You can retrieve standard scalar results using a two-step process:

1 Call subroutine TKNRES to determine the dimensions of the results.

2 Call subroutine TKBRES to retrieve the results.

Dimensions of Standard Scalar Results

Call subroutine TKNRES to determine the dimensions of the standard resultsfor a block. TKNRES returns the number of results and the maximum numberof qualifiers for results. You can use this information to dimension arrays for

calling subroutine TKBRES, which retrieves the results.

Calling Sequence for TKNRESCALL TKNRES (BLKID, NRES, NQUAL, IERR)


45/215


Argument List Descriptions for TKNRES



NRES O INTEGER Number of resultsNQUAL O INTEGER Maximum number of qualifiers for a

result


I = Input to subroutine, O = Output from subroutine Some results have qualifiers needed to identify the result, such as the stream IDor substream ID. NQUAL is the maximum number of qualifiers for the results of ablock.

Standard Scalar Block Results

Call subroutine TKBRES to retrieve the standard scalar results of a block.

Treat the QUALS array as a one-dimensional array, with all the values foreach qualifier type stored consecutively.

Calling Sequence for TKBRESCALL TKBRES (BLKID, NRES, NQUAL, PNAMES, QUALS, ITYPE, IVALS,

CVALS, RVALS, TYPES, LABELS)

Argument List Descriptions for TKBRES



NRES I INTEGER Number of results

NQUAL I INTEGER Maximum number of qualifiers

PNAMES O CHARACTER*12 NRES Property name. See Appendix B fora description.

QUALS O CHARACTER*8 NRES*NQUAL Qualifiers

ITYPE O INTEGER NRES Data type of results (1=Integer,2=Real, 3=Character)

IVALS O INTEGER NRES Integer results

CVALS O CHARACTER*8 NRES Character results

RVALS O REAL*8 NRES Real results

TYPES O CHARACTER*12 NRES Units types

LABELS O CHARACTER*16 NRES Units labels

I = Input to subroutine, O = Output from subroutine Some results have qualifiers needed to identify the result, such as the stream IDor substream ID. NQUAL is the maximum number of qualifiers for the results of ablock. For each result, the value in ITYPE specifies whi

Aspen plus 8.0 GUIDE

Documents

Transcript of Aspen plus 8.0 GUIDE