Sie sind auf Seite 1von 71

Aspen Properties

Toolkit Manual
Version Number: 2006
October 2006
Copyright (c) 2006 by Aspen Technology, Inc. All rights reserved.

Aspen Properties, aspenONE, the aspen leaf logo and Plantelligence and Enterprise Optimization are trademarks or
registered trademarks of Aspen Technology, Inc., Cambridge, 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 AspenTech
proprietary and confidential information and may not be disclosed, used, or copied without the prior consent of
AspenTech or as set forth in the applicable license agreement. Users are solely responsible for the proper use of
the 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 NO
WARRANTY OR REPRESENTATION, EITHER EXPRESSED OR IMPLIED, WITH RESPECT TO THIS DOCUMENTATION,
ITS QUALITY, PERFORMANCE, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.

Aspen Technology, Inc.


Ten Canal Park
Cambridge, MA 02141-2201
USA
Phone: (1) (617) 949-1000
Toll Free: (1) (888) 996-7001
Fax: (1) (617) 949-1030
URL: http://www.aspentech.com
Contents
Who Should Read this Guide ...................................................................................1

Introduction ............................................................................................................2
The Manual ................................................................................................... 3
Organization........................................................................................ 3
Related Documentation ................................................................................... 3
Technical Support .......................................................................................... 4

1 Introduction to Aspen Properties Toolkit ............................................................5


About Aspen Properties Toolkit......................................................................... 5
How Aspen Properties Toolkit Works ................................................................. 6
Setting Up a Property Package ............................................................... 7
Running the Application Program ............................................................ 8
Creating an Aspen Properties Property Package .................................................. 8
Creating an Aspen Properties Property Package from an Existing Aspen Plus
Run .................................................................................................... 8
Creating a New Aspen Properties Property Package ................................... 8
Entering Input Specifications.................................................................. 9
Required Property Parameters...............................................................10
Making Preliminary Runs To Prepare Your Property Package ................................10
Using Advanced Aspen Properties Features .......................................................11
Qualifying an Application Program for Use with Aspen Properties..........................12

2 Writing or Modifying an Application Program ....................................................14


Aspen Properties Toolkit Initialization ...............................................................15
Thermodynamic Reference States....................................................................16
Property Calculations .....................................................................................17
Calling Sequences for Monitors........................................................................18
Calling Sequences for Phase Monitors.....................................................18
Calling Sequences for Property Monitors .................................................19
Argument List Descriptions for Monitors ...........................................................22
Calculating Heat Capacity .....................................................................26
Calculating Activity Coefficients .............................................................28
Calculating Average Molecular Weight ....................................................28
Calling Sequences for PROP-SET Property Monitors ............................................29
Argument List Descriptions for PROP-SET Property Monitors ................................29
PROPS ...............................................................................................31
PHASES .............................................................................................31
KWDBS..............................................................................................31
XPCLV ...............................................................................................31
KULAB ...............................................................................................31

Contents iii
CALUPP Results...................................................................................32
KERR.................................................................................................32
Universal Property Constants ..........................................................................32
Flash Calculations .........................................................................................34
Retrieving Phase Properties ..................................................................38
Work Space..................................................................................................39
Component Mapping......................................................................................40
Passing Component Arguments .............................................................40
Component Mapping Methods ...............................................................41
Identifying the Aspen Properties Component Number ...............................41
Retrieving the Number of Aspen Properties Components ...........................42
Property Methods ..........................................................................................42
Using Multiple Property Methods......................................................................43
Reports .......................................................................................................44
Component Information in Reports ........................................................44
Property Method Descriptions in Reports.................................................44

3 Run Procedures .................................................................................................46


Compiling the Application Program Containing Aspen Properties Toolkit Commons
and Routines ................................................................................................47
Linking Application Programs to Aspen Properties Toolkit ....................................47
Creating a Shared Library with Aspen Properties Toolkit............................47
Linking an Application Program with Aspen Properties Toolkit ....................48
Modifying Application Program Run Procedures for Use With Aspen Properties Toolkit49

4 Sample Application Program That Uses Aspen Properties .................................50


Source Code for FLCURVE ..............................................................................51
Compiling and Linking FLCURVE ......................................................................59
Aspen Properties Property Package for FLCURVE................................................60
Sample Input File for Running FLCURVE ...........................................................61
Run Procedures To Execute FLCURVE ...............................................................62
Report File from Running FLCURVE ..................................................................63

Index ....................................................................................................................64

iv Contents
Who Should Read this Guide

This manual is intended for developers who want to use the Aspen Properties
Toolkit to call property calculations from another program.

Who Should Read this Guide 1


Introduction

The Aspen Properties Toolkit Manual describes how to use the Aspen
Properties Toolkit. This version of the manual has been updated for Version
2006 of Aspen Properties. This manual can be used by:
• Individuals learning to use the Aspen Properties Toolkit.
• Application program managers and developers who want to develop an
interface to the Aspen Properties Toolkit.
• All levels of Aspen Plus and Aspen Properties users, from novice to expert.
The Aspen Properties Toolkit Manual assumes that you are familiar with
Aspen Properties. Refer to Aspen Properties documentation for information
about using Aspen Properties features. See Related Documentation, at the
end of this document.

Note: This manual does not describe actual run procedures for Aspen
Properties interfaces developed for commercial programs (such as those
available for Aspen Custom Modeler).

2 Introduction
The Manual
Organization
This manual contains the following:
Introduction − Provides a brief overview of the manual and a list of related
documentation.
Chapter 1 − Instructions to use Aspen Properties to create an Aspen
Properties property package. This chapter also provides information to help
you determine if an application program is suitable for use with the Aspen
Properties Toolkit.
Chapter 2 − Instructions to write or modify application program code to use
the Aspen Properties Toolkit.
Chapter 3 − Instructions to link the Aspen Properties Toolkit to an application
program. This chapter also describes how to modify an application program
run procedure for use with the Aspen Properties Toolkit.
Chapter 4 − A comprehensive example illustrating the development and use
of an application program that uses the Aspen Properties Toolkit. This chapter
includes sample code for an application program, Aspen Properties Toolkit link
procedures, application program run procedures, steps to set up an Aspen
Properties property package, and an input file for running the application
program.

Related Documentation
Title Content

AES Installation Manual Instructions for installing Aspen Plus


and other Aspen Engineering Suite
products
Aspen Properties User Guide Procedures for using Aspen
Properties
System Management and Customization Procedures for customizing Aspen
Guide Properties and creating custom
models.
Getting Started Guides Aspen Plus Tutorials
Reference Manuals Aspen Plus Manuals
Physical Property Data Information about property
databanks
Physical Property Methods and Models Information about property methods
and property models

Introduction 3
Technical Support
AspenTech 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.

4 Introduction
1 Introduction to Aspen
Properties Toolkit

Aspen Properties is an application designed to allow access to the Aspen


Physical Property System. The Aspen Properties Toolkit allows you to prepare
a physical property package for use with:
• In–house application programs.
• Selected third–party commercial engineering programs.
• Other computer–aided engineering tools.
Topics in this chapter include:
• About Aspen Properties Toolkit.
• How Aspen Properties Toolkit works.
• Creating an Aspen Properties property package.
• Making preliminary runs to prepare your property package.
• Using advanced Aspen Properties features.
• Qualifying an application program for use with Aspen Properties.

About Aspen Properties Toolkit


Aspen Properties Toolkit provides you with the ability to use:
• Features of the Aspen Physical Property System in other process
engineering programs.
• The same physical property methods and data in different process
engineering programs, for the same project. This ensures consistent
results in simulation, equipment design, and other tasks.
• The same physical property system for different applications. (For
example, you can use the same GUI, conventions, analysis and reporting
tools.) You need to learn only one physical property system.
In addition, Aspen Properties Toolkit provides a property system designed for
use in mathematical models requiring iterative or stepwise calculations. It
offers efficiency of calculation, continuity of results, and quality of
extrapolation.

1 Introduction to Aspen Properties Toolkit 5


It also offers an assured stream of future state–of–the art physical property
and user interface development. All the substantial physical property
development that goes into each new release of Aspen Plus is now part of the
Aspen Physical Property System used by Aspen Properties and the Toolkit.
The following table describes the key features of Aspen Properties Toolkit:
Feature Description

Aspen Physical Property Contains nearly 5,000 components and 37,000 binary
System databanks parameters.
Property Constant Uses group contribution methods to estimate the properties
Estimation System of components for which you have limited or no data.
(PCES)
UNIFAC activity Predict binary interactions in non–ideal mixtures.
coefficient models
Data Regression System Determines property parameters from experimental data.
(DRS) (For example, it can fit an activity coefficient model to
laboratory VLE data.)
All property methods and Include property methods and models for non–ideal, two–
models available in the liquid phase, electrolyte, and petroleum systems.
Aspen Physical Property
System
Robust flash utility Performs a variety of two–phase, rigorous three–phase,
free–water, and electrolyte equilibrium calculations.
Extensive reporting Generate property tables, flash curves, TPxy diagrams,
features residue maps, and PT–envelopes.
Aspen Properties Interactively prepares and analyzes a property package.
graphical user interface

Aspen Properties features an open architecture. You can customize Aspen


Properties to use your own pure component databanks, binary parameter
databank, electrolyte and reactions databank, and physical property models.

How Aspen Properties Toolkit


Works
To use Aspen Properties Toolkit with an application program, you must:
1 Write or modify the application program to use Aspen Properties Toolkit.
(See Chapter 2.)
2 Write or modify the application run procedure for use with Aspen
Properties Toolkit. (See Chapter 3.)
3 Use the Aspen Properties Toolkit link procedure to link the application
program to Aspen Properties Toolkit. (See Chapter 3.)
4 Set up a property package.
5 Run the application program.
This section describes how to:
• Set up a property package using Aspen Properties.
• Run the application program.

6 1 Introduction to Aspen Properties Toolkit


Setting Up a Property Package
A property package must include:
• A system of components.
• Property methods.
• Property data required to use, the property methods.
Use the Aspen Properties User Interface to set up a property package.
Use this form To do this

Components | Specifications Select components and databanks


Properties | Specifications | Global Select property methods
Properties | Parameters Enter property parameters

See the Aspen Properties User Guide, Chapters 5, 6, and 7 for more
information on these forms.
After you complete all the required information, you must run Aspen
Properties to generate the problem data file (APRPDF), which contains all the
processed data. The APRPDF file is used by the application program. To run
Aspen Properties, click Calculate from the Calculate menu.

Note: You can also use an APPDF file generated by Aspen Plus. To use Aspen
Plus to create a property package, select the Properties Plus Run Type on the
Setup | Specifications | General form.
You can save the property package with the name (ID) of your choice:
1 From the File menu, select Save As.
2 In the Save As dialog box, enter the name of your choice in the File name
field.
You do not need to set up a property package each time you run the
application program. You must set up the property package again only when
one of the following occurs:
• The properties information changes. (For example, you add new
components, or change the property methods.)
• You delete the APRPDF file. You might do this when upgrading to a new
version of Aspen Properties.

Important: APRPDF files are not compatible across different versions. You
should save a backup file (.aprbkp) file from your current version of Aspen
Properties before upgrading to a new version, and use this file to create a
new APRPDF file in the new version.
Once you establish properties for a project, it is recommended that you put
all components for the project into a single Aspen Properties property
package. Any application program run can use a subset of these components.
This avoids repeating the properties setup for each subset of components.

1 Introduction to Aspen Properties Toolkit 7


Running the Application Program
Run the application program using the run ID of a property package. The run
ID identifies the property data that the application program uses. See
Modifying Application Program Run Procedures for Use With Aspen
Properties Toolkit in Chapter 3.
You will usually run an application program many times with the same
components and properties.

Creating an Aspen Properties


Property Package
Use the Aspen Properties graphical user interface to create the Aspen
Properties property package. See the Aspen Properties User Guide, Chapter 1,
for instructions on how to start and use the Aspen Properties graphical user
interface.

Creating an Aspen Properties Property


Package from an Existing Aspen Plus Run
If you have already run an Aspen Plus simulation with the same properties
that you want to use with the application program, follow these steps to
create an Aspen Properties property package:
1 Start Aspen Plus and open the existing Aspen Plus run.
2 From the Data menu, click Setup, then Specifications.
3 The Setup | Specifications | Global sheet appears. In the Run Type
field, select Properties Plus.
4 From the Run menu, click Run.
You should give the property package a new name:
1 From the File menu, select Save As.
2 In the Save As dialog box, enter the name (ID) of choice in the File
name field.
Aspen Plus will save the document file (.apw), the problem data file (.appdf),
and the backup file (.bkp).

Creating a New Aspen Properties Property


Package
To create a new Aspen Properties property package, follow these steps:
1 Start Aspen Properties and create a new problem. (See the
Aspen Properties User Guide, Chapter 2.)
2 Enter the required input specifications. See the following section for
details.
3 Provide additional specifications if needed:

8 1 Introduction to Aspen Properties Toolkit


Use this form To

Chemistry Define electrolyte chemistry. (See the Aspen Properties User


Guide, Chapter 13.)
Miscellaneous Options Access Add–Input forms for adding input language not
generated by Aspen Properties
4 Make sure the completion status indicator at the bottom right of the main
window is Required Input Complete. If the status indicator is Required
Input Not Complete, select Next and enter the required input to complete
the forms.
5 From the Calculate menu, click Calculate.
You should give the property package a name:
1 From the File menu, select Save As.
2 In the Save As dialog box, enter the name (ID) of choice in the File
name field.
Aspen Properties will save the document file (.aprop) and the problem
data file (.aprpdf).
You should also save a backup file (.aprbkp). You will need this file if you
upgrade to a new version of Aspen Properties.
1 From the File menu, select Save As.
2 In the Save as type field, select Aspen Properties Backup Files
(*.aprbkp).
3 Enter the name (ID) of choice in the File name field.

Entering Input Specifications


You can enter required input specifications on the following forms:
Use this form To specify

Setup Global calculation options. (See the Aspen Properties User Guide,
Chapter 4.)
Components Chemical components, petroleum assays, and pseudocomponents in
the calculation. (See the Aspen Properties User Guide, Chapter 5.)
Properties Methods and data to use for calculating physical properties. (See the
Aspen Properties User Guide , Chapters 6 and 7.)

Although you can enter specifications in any order, it is recommended that


you let the Aspen Properties Expert System (the Next function) guide you.
When you select Next, Aspen Properties performs one of the following
actions:
• Takes you to the next step in completing the input.
• Displays messages telling what you need to do.
For more information about using Next and about status indicators, see the
Aspen Properties User Guide, Chapter 2.

1 Introduction to Aspen Properties Toolkit 9


Required Property Parameters
The parameters that an application program requires depend on:
• Aspen Properties property methods you choose.
• Properties that the application program calculates.
See the Aspen Proprties User Guide, Chapter 7, for information about how to
determine required parameters for a calculation.

Making Preliminary Runs To


Prepare Your Property Package
When preparing the property package, you may need to perform data
regression or estimate missing parameters and properties. You should also
analyze your property package for accuracy and appropriateness, before
using it in your application program.
The following table describes calculation options you can use to perform data
regression, property constant estimation, or assay data analysis. You can
select the desired options from the Tools menu. See also the
Aspen Properties User Guide in online help where you can find more
information about property analysis, data regression, property estimation,
and assay data analysis.
You must use Property Analysis to perform preliminary property calculations
before creating an Aspen Properties property package. With Property Analysis
you can:
• Use Tools/Analysis commands to analyze many common properties
interactively.
• Use Properties Analysis forms to perform other property analyses.
• Generate Aspen Properties reports.
You can use analysis commands to analyze your property package. Using the
commands you can interactively calculate and display:
• Pure component properties as a function of temperature.
• Txy, Pxy, and excess Gibbs free energy diagrams for binary systems.
• Residue maps for ternary systems.
Use Properties Analysis forms to perform these and other analyses, including
the generation of PT–Envelopes. See the Aspen Properties User Guide,
Chapter 15, for more information.
You can generate Aspen Properties reports you need to document your
property package. Use the Setup | Report Options form to control report
contents. See the Aspen Properties User Guide, Chapter 4, for more
information.

10 1 Introduction to Aspen Properties Toolkit


Using Advanced Aspen
Properties Features
Aspen Properties includes capabilities for modeling electrolyte systems. You
can use the Electrolytes Expert System to generate electrolyte species and
reactions. (See the Aspen Properties User Guide, Chapter 5.) Aspen
Properties provides two approaches for modeling electrolyte systems:
• Apparent component.
• True component.
If you use electrolytes with the apparent component approach, you must
define the reactions using the Chemistry forms.
If you use electrolytes with the true component approach, you must define
reactions in your application program and include all the true species in the
Aspen Properties property package. (See the Aspen Properties User Guide,
Chapter 5, and Physical Property Methods and Models, Chapter 5, for more
information.)
You cannot use nonconventional solids with the Aspen Properties Toolkit.
You can use any user or in–house models or databanks with Aspen Properties
Toolkit. Or you can use any other Aspen Properties property system
modifications that have been made at your site. Use the same property
specifications that you would use for a normal Aspen Properties run.
For detailed information about property methods, models, and routes, see
Physical Property Methods and Models. For information and listings of all
databanks, electrolyte data, functional groups, and property sets, see Physical
Property Data.

1 Introduction to Aspen Properties Toolkit 11


Qualifying an Application
Program for Use with Aspen
Properties
Most process engineering programs meet the required criteria for using Aspen
Properties. An application program suitable for use with Aspen Properties
must:
• Be written in standard Fortran 77 or a compatible language.
• Characterize a chemical system in terms of chemical species.
• Represent the state of a chemical system in terms of temperature,
pressure, and the mole fraction of each chemical species.
• Use point property evaluations of standard properties for pure
components, mixtures, vapor, liquid, and solid phases, as appropriate.
Aspen Properties includes property monitors to calculate standard
thermodynamic and transport properties.
Thermodynamic properties include:
• Equilibrium K–value.
• Vapor pressure.
• Ideal gas properties.
• Activity and fugacity coefficient.
• Heat capacity.
• Enthalpy and entropy.
• Gibbs free energy.
• Molar volume.
Transport properties include:
• Viscosity.
• Thermal conductivity.
• Diffusion coefficient.
• Surface tension.
Aspen Properties also provides a general flash utility that can handle single–
phase, two–phase, three–phase, free–water, and electrolyte systems. See
Chapter 2 for more information about calculating standard properties and
flash calculations.
Aspen Properties allows application programs to access the following
component properties, without calculation:
• Molecular weight.
• Critical temperature, pressure, volume, and compressibility factor.
• Normal boiling point.
• Specific gravity.
• Pitzer acentric factor.

12 1 Introduction to Aspen Properties Toolkit


• Standard heat and free energy of formation for ideal gas at 298.15 K.
• Ionic charge number (positive for cations, negative for anions).
All real variables in Aspen Properties are type REAL*8. All integer variables
are type INTEGER*4. You must declare all Aspen Properties variables
correctly. The following statement provides an example of how to declare
variables:
IMPLICIT REAL*8 (A–H, O–Z)
All properties and state variables in Aspen Properties use SI units and are on
a molar basis.

1 Introduction to Aspen Properties Toolkit 13


2 Writing or Modifying an
Application Program

This chapter describes how to write or modify an application program to use


Aspen Properties Toolkit. Topics in this chapter include:
• Aspen Properties Toolkit initialization.
• Thermodynamic reference states.
• Property calculations.
• Universal property constants.
• Flash calculations.
• Work space.
• Component mapping.
• Property methods.
• Reports.
• Fortran errors.
Chapter 4 contains a sample application that shows how to use the interfacing
tools and techniques described in this chapter.

14 2 Writing or Modifying an Application Program


Aspen Properties Toolkit
Initialization
Before an application program can call Aspen Properties Toolkit to perform
property calculations, it must call subroutine PPEXEC_APINIT to initialize
Aspen Properties Toolkit. This subroutine:
• Loads physical property parameters and methods from the Aspen
Properties Problem Definition File (APRPDF).
• Initializes internal Aspen Properties data structures.
• Sets Fortran unit numbers for files used by Aspen Properties.
All Aspen Properties data is stored in the APRPDF file. You must specify the
file name of the APRPDF file from the Aspen Properties setup run in the call to
PPEXEC_APINIT. Application programs do not and should not read from or
write to the APRPDF file.
A file that Aspen Properties Toolkit uses must have a unit number associated
with it. You must assign unit numbers for the following files:
• History.
• Terminal.
• Report.
History File: All Aspen Properties error and diagnostic messages are written
to the unit number assigned for the history file. A history file contains traces,
history, progress, errors, and diagnostic messages.
You should direct history file output to the application program file that
contains similar information. The variable KDIAG in the argument list for the
property monitors controls the amount of information that Aspen Properties
writes to the history file. All Aspen Properties information written to the
history file is in SI units.
Terminal: Aspen Properties writes severe or fatal error messages to the unit
number assigned to the terminal. For applications that can run interactively,
you should direct terminal output to the user's terminal. For batch
applications, you can direct the terminal output to a log file. If the output is
not needed, you can direct output to a dummy file.
Report File: If you request Aspen Properties reports, they are written to the
unit number assigned for the report file. You should direct this output to the
application program's report file.

Calling Sequence for PPEXEC_APINIT


Call subroutine PPEXEC_APINIT only once, before any Aspen Properties flash
or property monitor calls. The Fortran unit numbers assigned must
correspond to the unit numbers defined in the application program run
procedures. (See Chapter 3.)
CALL PPEXEC_APINIT (NHIST, NTERM, XPDF, NRPT, IABORT, KEY)

2 Writing or Modifying an Application Program 15


Argument List Descriptions for PPEXEC_APINIT

Variable I/O Type Dimensions Description

NHIST I INTEGER*4 — History file unit number (Note 1)


NTERM I INTEGER*4 — Terminal unit number (Note 1)
XPDF I CHARACTER *255 — Problem data file name obtained
from the Aspen Properties setup run
(.aprpdf)
NRPT I INTEGER*4 — Report file unit number (Note 1)
IABORT I INTEGER*4 — Abort flag (Note 2):
0 = Aspen Properties will not
terminate when an Aspen Properties
terminal error occurs.
1 = Aspen Properties will terminate
when an Aspen Properties terminal
error occurs.
KEY I INTEGER*4 — Interface authorization key number
(Note 3)

I = Input to subroutine, O = Output from subroutine

Notes for PPEXEC_APINIT


1 The call to PPEXEC_APINIT specifies history file, report file, and terminal
unit numbers. Aspen Properties stores this information in the labeled
common PPEXEC_USER, as shown in the following statement.
COMMON / PPEXEC_USER / USER_RUMISS, USER_IUMISS, USER_NGBAL,
USER_IPASS, USER_IRESTR,
USER_ICONVG, USER_LMSG, USER_LPMSG, USER_KFLAG, USER_NHSTRY,
USER_NRPT, USER_NTRML
You can retrieve these values from the common PPEXEC_USER at other
points in the application program. Include this statement:
#include "ppexec_user.cmn"
The values of diagnostics message level for calculations (variable
USER_LMSG) and physical properties (variable USER_LPMSG) specified on
the Setup Specifications Diagnostics sheet are also stored in common
PPEXEC_USER.
2 The abort flag specifies the action taken by Aspen Properties if an Aspen
Properties terminal error occurs. A terminal error usually prevents
successful continued execution of a program. It is recommended that you
set IABORT to 1.
3 Enter 400 for this argument. You must also be licensed for Aspen
Properties with Aspen License Manager in order to use the Toolkit.

Thermodynamic Reference
States
Aspen Properties lets you choose between the component reference state and
the elemental reference state. If you choose the component reference state,

16 2 Writing or Modifying an Application Program


enthalpy is zero for pure components in the ideal gas state at 298.15 K. If
you choose the elemental reference state, enthalpy is zero for the elements in
their standard state at 298.15 K. The difference between the two enthalpies is
the standard heat of formation of the pure components in the ideal gas state
at 298.15 K.
The elemental reference state is preferred. When you choose the elemental
reference state, enthalpy balances implicitly include the heat effects of
reactions. You do not need to specify heat of reaction. Do not include heat of
reaction terms in enthalpy balance equations. You must use the elemental
reference state with Aspen Properties electrolyte systems.
Use the variable KBASE in Aspen Properties monitor argument lists to specify
the thermodynamic reference state (see Calling Sequences for Phase
Monitors).

Property Calculations
To calculate properties using Aspen Properties, you must call Aspen Properties
monitor routines. For example, call PPMON_VMTHRM for vapor mixture
thermodynamic properties. Aspen Properties returns the properties calculated
by the monitor to the calling program, through the argument list. Activity
coefficients are an exception. You must obtain activity coefficients from the
plex. See Calculating Activity Coefficients.
When calling a property monitor, you must include the following specifications
in the argument list:
• State variables (temperature, pressure, and composition) that describe
the system.
• Calculation codes that indicate required properties.
• Calculation methods to use (such as property methods).
Aspen Properties provides two types of monitors: property and phase
monitors.
Property monitors calculate individual properties, such as vapor enthalpy.
Phase monitors can:
• Simultaneously calculate fugacity coefficients, enthalpies, entropies, Gibbs
free energies, and molar volumes.
• Avoid redundant calculations where possible (for example, when an
equation of state is used to calculate several properties of a given
mixture).
• Increase computational efficiency.
You should use phase monitors whenever appropriate, instead of making calls
to several individual property monitors.
Aspen Properties does not assume that all components defined in the Aspen
Properties property package are present when a monitor is called. See
Component Mapping, for information about how to generate component
index arrays and packed mole fraction arrays to represent components
actually present.

2 Writing or Modifying an Application Program 17


The following sections contain information about:
• Calling sequences for phase monitors.
• Calling sequences for property monitors.
• Calculating heat capacity.
• Calculating activity coefficients.
• Calculating average molecular weight.

Calling Sequences for Monitors


Calling Sequences for Phase Monitors

Calling Sequences for Pure Component Phase


Monitors

Vapor:
CALL PPMON_VTHRM (T, P, N, IDX, NBOPST,
KDIAG, KBASE, KPHI, KH, KS,
KG, KV, PHI, H, S,
G, V, DPHI, DH, DS,
DG, DV, KER)

Liquid:
CALL PPMON_LTHRM (T, P, N, IDX, NBOPST,
KDIAG, KBASE, KPHI, KH, KS,
KG, KV, PHI, H, S,
G, V, DPHI, DH, DS,
DG, DV, KER)

Solid:
CALL PPMON_STHRM (T, P, N, IDX, NBOPST,
KDIAG, KBASE, KPHI, KH, KS,
KG, KV, PHI, H, S,
G, V, DPHI, DH, DS,
DG, DV, KER)

18 2 Writing or Modifying an Application Program


Calling Sequences for Mixture Phase Monitors

Vapor:
CALL PPMON_VMTHRM (T, P, Y, N, IDX,
NBOPST, KDIAG, KBASE, KPHI, KH,
KS, KG, KV, PHI, HMX,
SMX, GMX, VMX, DPHI, DHMX,
DSMX, DGMX, DVMX, KER)

Liquid:
CALL PPMON_LMTHMY (T, P, X, Y, N,
IDX, NBOPST, KDIAG, KBASE, KPHI,
KH, KS, KG, KV, PHI,
HMX, SMX, GMX, VMX, DPHI,
DHMX, DSMX, DGMX, DVMX, KER)

Solid:
CALL PPMON_SMTHRM (T, P, X, N, IDX,
NBOPST, KDIAG, KBASE, KPHI, KH,
KS, KG, KV, PHI, HMX,
SMX, GMX, VMX, DPHI, DHMX,
DSMX, DGMX, DVMX, KER)

Calling Sequence for Ideal Gas Phase Monitor


CALL PPBASE_IDLGAS (T, Y, N, IDX, KDIAG,
KBASE, KHI, KSI, KGI, KH,
KS, KG, H, S, G,
DH, DS, DG, HMX, SMX,
GMX, DHMX, DSMX, DGMX, KER)

Calling Sequences for Property Monitors

Calling Sequences for Equilibrium Ratio (K-Value)

Vapor–Liquid:
CALL PPMON_KVL (T, P, X, Y, N,
IDX, NBOPST, KDIAG, KK, EK,
DK, KER)

Liquid–Liquid:
CALL PPMON_KLL (T, P, X1, X2, N,
IDX, NBOPST, KDIAG, KK, EK,
DK, KER)

2 Writing or Modifying an Application Program 19


Calling Sequences for Mixture Diffusion
Coefficient

Vapor:
CALL PPMON_DIFCOV (T, P, Y, N, IDX,
NBOPST, KDIAG, DIFCO, KER)

Liquid:
CALL PPMON_DIFCOL (T, P, X, N, IDX,
NBOPST, KDIAG, DIFCO, KER)

Calling Sequences for Mixture Enthalpy

Vapor:
CALL PPMON_ENTHV (T, P, Y, N, IDX,
NBOPST, KDIAG, KBASE, KH, HMX,
DHMX, KER)

Liquid:
CALL PPMON_ENTHL (T, P, X, N, IDX,
NBOPST, KDIAG, KBASE, KH, HMX,
DHMX, KER)

Solid:
CALL PPMON_ENTHS (T, P, X, N, IDX,
NBOPST, KDIAG, KBASE, KH, HMX,
DHMX, KER)

Calling Sequences for Mixture Fugacity Coefficient

Vapor:
CALL PPMON_FUGV (T, P, Y, N, IDX,
NBOPST, KDIAG, KPHI, PHI, DPHI,
KER)

Liquid:
CALL PPMON_FUGLY (T, P, X, Y, N,
IDX, NBOPST, KDIAG, KPHI, PHI,
DPHI, KER)

Solid:
CALL PPMON_FUGS (T, P, X, N, IDX,
NBOPST, KDIAG, KPHI, PHI, DPHI,
KER)

20 2 Writing or Modifying an Application Program


Calling Sequences for Mixture Molar Volume

Vapor:
CALL PPMON_VOLV (T, P, Y, N, IDX,
NBOPST, KDIAG, KV, VMX, DVMX,
KER)

Liquid:
CALL PPMON_VOLL (T, P, X, N, IDX,
NBOPST, KDIAG, KV, VMX, DVMX,
KER)

Solid:
CALL PPMON_VOLS (T, P, X, N, IDX,
NBOPST, KDIAG, KV, VMX, DVMX,
KER)

Calling Sequence for Mixture Surface Tension


CALL PPMON_SRFTNY (T, P, X, Y, N,
IDX, NBOPST, KDIAG, SRFTEN, KER)

Calling Sequences for Mixture Thermal


Conductivity

Vapor:
CALL PPMON_TCONV (T, P, Y, N, IDX,
NBOPST, KDIAG, TCON, KER)

Liquid:
CALL PPMON_TCONL (T, P, X, N, IDX,
NBOPST, KDIAG, TCON, KER)

Solid:
CALL PPMON_TCONS (T, P, X, N, IDX,
NBOPST, KDIAG, TCON, KER)

Calling Sequences for Mixture Viscosity

Vapor:
CALL PPMON_VISCV (T, P, Y, N, IDX,
NBOPST, KDIAG, VISC, KER)

2 Writing or Modifying an Application Program 21


Liquid:
CALL PPMON_VISCL (T, P, X, N, IDX,
NBOPST, KDIAG, VISC, KER)

Calling Sequence for Vapor Pressure


CALL PPBASE_PL001 (T, N, IDX, NDS, KP,
KDIAG, PVAP, DPVAP)

Calling Sequence for General Property Monitor


CALL PPMON_CALPRP (T, P, Z, NX, N,
IDX, NBOPST, KDIAG, KBASE, PROPS,
NPROP, PHASES, NPHASE, RESULT, NRESULT,
IRESULT, KERR)

Note: To avoid excessive memory usage in simulations with many


components, you may not request dx (mole fraction) and dn (mole number)
derivatives in a single call to PPMON_CALPRP.

Argument List Descriptions for


Monitors
Variable I/O† Type Dimensions Description

DG O REAL*8 N Array of partial derivatives for pure


component Gibbs free energies with
respect to temperature (J/kmol-K) (Note
2)
DGMX O REAL*8 — Partial derivative of mixture Gibbs free
energy with respect to temperature
(J/kmol-K)
DH O REAL*8 N Array of partial derivatives for pure
component enthalpies with respect to
temperature (J/kmol-K) (Note 2)
DHMX O REAL*8 — Partial derivative of mixture enthalpy with
respect to temperature (J/kmol-K)
DIFCO O REAL*8 N Array of diffusion coefficients for
components in a mixture (m2/sec) (Note
2)
DK O REAL*8 N Array of partial derivatives for equilibrium
ratios (K-values) of components in
coexisting phases with respect to
temperature (Note 2)
DPHI O REAL*8 N Array of partial derivatives with respect to
temperature of fugacity coefficients, for
pure components or for components in
mixture (K-1) (Note 2)

22 2 Writing or Modifying an Application Program


Variable I/O† Type Dimensions Description

DPVAP O REAL*8 N Array of partial derivatives for natural


logarithm of pure component vapor
pressure with respect to temperature
(Note 2)
DS O REAL*8 N Array of partial derivatives for pure
component entropies with respect to
temperature (J/kmol-K2) (Note 2)
DSMX O REAL*8 — Partial derivative of mixture entropy with
respect to temperature (J/kmol-K2) (Note
2)
DV O REAL*8 N Array of partial derivatives for pure
component molar volumes with respect to
temperature (m3/kmol-K) (Note 2)
DVMX O REAL*8 — Partial derivative of mixture molar volume
with respect to temperature (m3/kmol-K)
(Note 2)
EK O REAL*8 N Array of equilibrium ratios (K-values) for
components in coexisting phases (Note 2)
G O REAL*8 N Array of pure component Gibbs free
energies (J/kmol) (Note 2)
GMX O REAL*8 — Mixture Gibbs free energy (J/kmol)
H O REAL*8 N Array of pure component enthalpies
(J/kmol) (Note 2)
HMX O REAL*8 — Mixture enthalpy (J/kmol)
IDX I INTEGER*4 N Component index array (Note 1)
IRESULT O INTEGER*4 NPROP* Index into RESULT for each property in
NPHASE each phase. (see CALPRP Results)
KBASE I INTEGER*4 — Thermodynamic reference state code.
(See Thermodynamic Reference State,
page 16.)
KBASE = 0 - Pure compounds in ideal gas
state at 298.15 K
KBASE = 1 - Elements in their standard
states at 298.15 K
KDIAG I INTEGER*4 — Diagnostic level (Note 3). Recommended
value is 4.
KER O INTEGER*4 — Not used
KERR O INTEGER*4 — Error flag for CALPRP. (Note 5)
KG I INTEGER*4 — Gibbs free energy calculation code (Note
4)
KGI I INTEGER*4 — Pure component ideal gas Gibbs free
energy calculation code (Note 4)
KH I INTEGER*4 — Enthalpy calculation code (Note 4)
KHI I INTEGER*4 — Pure component ideal gas enthalpy
calculation code (Note 4)
KK I INTEGER*4 — K–value calculation code (Note 4)
KP I INTEGER*4 — Vapor pressure calculation code (Note 4)
KPHI I INTEGER*4 — Fugacity coefficient calculation code (Note
4)

2 Writing or Modifying an Application Program 23


Variable I/O† Type Dimensions Description

KS I INTEGER*4 — Entropy calculation code (Note 4)


KSI I INTEGER*4 — Pure component ideal gas entropy
calculation code (Note 4)
KV I INTEGER*4 — Molar volume calculation code (Note 4)
N I INTEGER*4 — Number of components present
NBOPST I INTEGER*4 6 Property Methods array. (See Property
Methods, page 42.)
NDS I INTEGER*4 — Data set number of the model parameters
(normally NDS = 1)
NPHASE I INTEGER*4 — Number of phases in PHASES (Note 5)
NPROP I INTEGER*4 — Number of properties in PROPS
NRESULT I/O INTEGER*4 — Number of elements in RESULT. (Note 5)
NX I INTEGER*4 — Number of phases in the composition
vector Z (Note 5)
P I REAL*8 — Pressure (N/m2)
PHASES I CHARACTER NPHASE Vector of phases for which properties are
to be calculated (Note 5)
PHI O REAL*8 N Array of fugacity coefficients for pure
components or components in mixture
(Note 2)
PROPS I CHARACTER NPROP Vector of properties. Properties are
calculated for all phases (Note 6)
PVAP O REAL*8 N Array of natural logarithms for pure
component vapor pressure (Note 2)
RESULT O REAL*8 * Calculated properties. (Note 5)
S O REAL*8 N Array of pure component entropies
(J/kmol-K) (Note 2)
SMX O REAL*8 — Mixture entropy (J/kmol-K)
SRFTEN O REAL*8 — Mixture surface tension (N/m)
T I REAL*8 — Temperature (K)
TCON O REAL*8 — Mixture thermal conductivity (J/sec-m-K)
V O REAL*8 N Array of pure component molar volumes
(m3/kmol) (Note 2)
VISC O REAL*8 — Mixture viscosity (N–sec/m2)
VMX O REAL*8 — Mixture molar volume (m3/kmol)
X I REAL*8 N Liquid mole fraction array (Note 2)
X1 I REAL*8 N Liquid 1 mole fraction array (Note 2)
X2 I REAL*8 N Liquid 2 mole fraction array (Note 2)
Y I REAL*8 N Vapor mole fraction array (Note 2)
Z I REAL*8 N*NX Mole fraction matrix for all phases for
PPMON_CALPRP (Note 2)
† I = Input to subroutine, O = Output from subroutine

Notes for Monitors Argument List Descriptions


1 IDX is an array containing Aspen Properties component numbers of the
components actually present. Components are numbered in the order that

24 2 Writing or Modifying an Application Program


they appear in the Components Specifications Selection sheet of the
Aspen Properties property package. For example, if only the first and third
components listed in the Components Specifications Selection sheet are
present, N = 2 and IDX = (1,3). (You can use the subroutine
PPUTL_PPGIDX to obtain the Aspen Properties component number for a
component. See Component Mapping.)
2 Y, X, X1, and X2 are packed mole fraction arrays of length N. These arrays
contain the mole fractions of the components to be used in the
calculations. The corresponding IDX array defines the component order.
For example, if N = 2 and IDX = (1,3), Y(2) is the vapor mole fraction of
the third component in the Components Specifications Selection sheet.
Arrays of pure component properties (for example, liquid enthalpy) and
the properties of components in a mixture (for example, equilibrium
K-value) calculated by Aspen Properties are also packed in the order
defined by the corresponding IDX array. (See Component Mapping.)
For PPMON_CALPRP, Z is a packed mole fraction matrix of dimension N by
NX. The first N elements correspond to phase 1, the next N to phase 2,
and so on. The identity of each phase (e.g. liquid or vapor) is determined
by the PHASES specification.
Aspen Properties does not normalize the mole functions Y, Z, X, X1, and
X2.
3 KDIAG controls the generation of error, warning, and diagnostic
information. If KDIAG = M, Aspen Properties generates all messages at
level M and below. These messages are written to Fortran unit number
NHIST for the history file. You must specify NHIST in the argument list of
subroutine PPEXEC_APINIT. (See Aspen Properties Initialization.)
The following table describes the message levels:
Level Message Description

0 Terminal Error Execution cannot continue.


1 Severe Error Execution can continue, but subsequent processing is
likely to be erroneous.
2 Error Execution can continue, but subsequent processing may
be erroneous.
3 Warning Execution can continue, but a condition has been
encountered that you should know about. (For example,
a correlation has been extrapolated beyond its normal
limits.)
4 Information Messages allow you to trace the progress of a run.
5+ Diagnostic Messages are used for debugging only.

Aspen Properties generates messages at levels 0 to 3 when it cannot


calculate requested properties due to missing required data. You should
not suppress these messages.

2 Writing or Modifying an Application Program 25


The value of the physical properties diagnostics level specified on the
Setup Specifications Diagnostics sheet is stored in common
PPEXEC_USER, variable USER_LPMSG:
COMMON / PPEXEC_USER / USER_RUMISS, USER_IUMISS,
USER_NGBAL, USER_IPASS, USER_IRESTR, USER_ICONVG,
USER_LMSG, USER_LPMSG, USER_KFLAG, USER_NHSTRY,
USER_NRPT, USER_NTRML
You should use the variable USER_LPMSG for KDIAG to control the
amount of diagnostics generated.
4 A calculation code specifies what to calculate. When the calculation code
specifies not to calculate a particular property (code=0), the monitor does
not change the argument list values.
This code Specifies that the monitor

0 Does not calculate property or its temperature derivative


1 Calculates property only
2 Calculates temperature derivative of property only
3 Calculates property and temperature derivative
5 CALPRP accepts phase specifiers V=vapor, L=liquid, S=solid. NX is usually
the same as NPHASE.
The results from CALPRP are arranged in this order:
o All properties for phase 1
o All properties for phase 2
o …
o All properties for phase NPHASE
NRESULT should be set to the length of the RESULT vector provided. If
NRESULT is 0, no calculations are performed and NRESULT is set to the
actual size required; user should allocate required storage and call the
PPMON_CALPRP property monitor again. If NRESULT is insufficient, results
are truncated and an error code of –3 is returned.
IRESULT provides indices into RESULT for each property in each phase.
IRESULT allows you to easily retrieve the desired property in each phase.
KERR error codes for PPMON_CALPRP are:
0 No error
–1 Error in parsing property specifications
–2 Invalid phase specification
–3 Insufficient size for result vector
–4 Insufficient size of mole fraction vector
6 To avoid excessive memory usage in simulations with many components,
you may not request dx (mole fraction) and dn (mole number) derivatives
in a single call to PPMON_CALPRP.

Calculating Heat Capacity


Heat capacity at constant pressure (Cp) is the partial derivative of enthalpy
with respect to temperature. It can be calculated by calling phase monitors.
Use the calculation code KH=2 to call phase monitors. For pure components
call PPMON_VTHRM, PPMON_LTHRM, or PPMON_STHRM. For mixtures call

26 2 Writing or Modifying an Application Program


PPMON_VMTHRM, PPMON_LMTHMY, or PPMON_SMTHRM. For example, use
the following statements to calculate Cp for a vapor mixture (CPMX):
KH=2
CALL PPMON_VMTHRM (T, P, Y, N, IDX,
NBOPST, KDIAG, KBASE, KPHI, KH,
KS, KG, KV, PHI, HMX,
SMX, GMX, VMX, DPHI, CPMX,
DSMX, DGMX, DVMX, KER)
Heat capacity at constant volume (Cv) is calculated from Cp using the
following thermodynamic relationship:
⎛ ∂V ⎞ ⎛ ∂P ⎞
C v = Cp−T ⎜⎜ ⎟ ⎜
⎟ ⎜


⎜ ∂T ⎟ ⎜ ∂T ⎟
⎝ ⎠p ⎝ ⎠v
2
⎛ ∂V ⎞ ⎛ ∂V ⎞
⎜ ⎟ ⎜ ⎟
= Cp+T ⎜ ⎟ ⎜ ⎟
⎜ ∂T ⎟ ⎜ ∂P ⎟
⎝ ⎠p ⎝ ⎠T

The heat capacity, Cp, and the partial derivative of molar volume with respect
⎛ ∂V ⎞
to temperature, ⎜ ⎟ , can be calculated by calling the phase monitor. The
⎝ ∂T ⎠P
⎛ ∂V ⎞
partial derivative of molar volume with respect to pressure ⎜ ⎟ must be
⎝ ∂P ⎠T
determined numerically. The following example calculates Cv for a vapor
mixture (CVMX).

Example of Calculating Cv for a Vapor Mixture (CVMX)


Cv can be calculated using a three-step procedure:
⎛ ∂V ⎞
1 Calculate Cp and ⎜ ⎟ by calling the vapor mixture phase monitor, with
⎝ ∂T ⎠P
KH=2 and KV=3. The calculation code KV=3 also specifies calculation of
the molar volume VMX:
KH=2
KV=3
CALL PPMON_VMTHRM (T, P, Y, N, IDX,
NBOPST, KDIAG, KBASE, KPHI, KH,
KS, KG, KV, PHI, HMX,
SMX, GMX, VMX, DPHI, CPMX,
DSMX, DGMX, DVMX, KER)
⎛ ∂V ⎞
2 Calculate ⎜ ⎟ numerically, by perturbing the system pressure. Then
⎝ ∂P ⎠T
call the property monitor PPMON_VOLV to calculate the mixture molar
volume at the new pressure:
⎛ ∂V ⎞ V p + Δp −V p
⎜ ⎟ ≈
⎝ ∂P ⎠T ΔP

2 Writing or Modifying an Application Program 27


KV = 1
PDEL = 1.001D0 * P
CALL PPMON_VOLV (T, PDEL, Y, N, IDX,
NBOPST, KDIAG, KV, VDELMX, DUM,
KER)
DVDP = (VDELMX – VMX) / (PDEL – P)
3 Calculate Cv:
IF (DVDP .NE. 0D0) CVMX = CPMX + T * DVMX * DVMX / DVDP

Calculating Activity Coefficients


Aspen Properties does not return activity coefficients through a monitor
argument list. You can calculate activity coefficients by calling the liquid
fugacity coefficient monitor, PPMON_FUGLY. Then retrieve the activity
coefficients from the plex, using the following function and statements:
#include "dms_plex.cmn"
REAL*8 B(1)
EQUIVALENCE (IB(1), B(1))
C
C CALCULATED PROPERTIES OFFSETS, E.G., FOR GAMMA
C
#include "dms_ipoff3.cmn"
INTEGER GAMMAL, LGAMA, I
C
C Statement function
GAMMAL(I) = LGAMA + I
C
C set plex offsets
LGAMA = IPOFF3_IPOFF3(24)
B(GAMMAL(1)) through B(GAMMAL(N)) store the natural logarithms of the
activity coefficients for components 1 through N. B(GAMMAL (N+1)) through
B(GAMMAL(2*N)) store the temperature derivatives of the natural logarithms
of the activity coefficients, if the temperature derivatives are requested.
Activity coefficients are packed in the same way as properties retrieved
through monitor argument lists.

Calculating Average Molecular Weight


Aspen Properties provides a Fortran function subprogram, PPUTL_AVEMW, for
calculating the average molecular weight of a mixture:
AMW = PPUTL_AVEMW (N, IDX, X)
The argument list description for PPUTL_AVEMW is:
Variable I/O† Type Dimensions Description

AMW O REAL*8 — Calculated average molecular weight


N I INTEGER*4 — Number of components present
IDX I INTEGER*4 N Component index array
X I REAL*8 N Mole fraction array
† I = Input to subroutine, O = Output from subroutine

28 2 Writing or Modifying an Application Program


Calling Sequences for PROP-
SET Property Monitors
General PROP-SET Property Monitor (CALUPP)
CALL UPP_CALUPP (T, P, X, N, IDX,
NBOPST, IAS, PROPS, PHASES, KWDBS,
XPCLV, KULAB, NL2C, KL2C, NATOMS,
KATOMS, NPKODE, RESULT, KERR)
This monitor is used to calculate the prop-set properties listed in Chapter 4 of
the Physical Property Data Reference Manual.

PROP-SET Property Monitor (CALUP1)


CALL UPP_CALUP1 (PROPS, LDT, LDP, LDN, KERR)
This utility can be used to query the dependency of the given property on
temperature, pressure and composition.

PROP-SET Property Monitor (CALUP2)


CALL UPP_CALUP2 (IDPSET, NPROP, PROPS, NTEMP, TEMP,
NPRES, PRES, NPHASE, PHASES, NCOMP,
IDCOMP, NBASIS, KWDBS, NUNIT, KULAB,
NLVPCT, XPCLV, NL2C, KL2C, KERR)
This utility can be used to query the property names, phase, basis, unit, and
other qualifiers for the given Prop-Set ID.

PROP-SET Property Monitor (CALUP3)


CALL UPP_CALUP3 (T, P, X, N, IDX,
NBOPST, IAS, PROPS, LP, LDT,
LDP, LDN, PHASES, KWDBS, XPCLV,
KULAB, NL2C, KL2C, NATOMS, KATOMS,
NPKODE, RESULT, RESUDT, RESUDP, RESUDN,
KERR)
This monitor is used to calculate the property and derivatives of the prop-set
properties listed in Chapter 4 of the Physical Property Data Reference Manual.
This monitor is similar to CALUPP.

Argument List Descriptions for


PROP-SET Property Monitors
Variable I/O† Type Dimension Description

T I REAL*8 — Temperature (K)


P I REAL*8 — Pressure (Pa)
X I REAL*8 N Composition vector

2 Writing or Modifying an Application Program 29


Variable I/O† Type Dimension Description

N I INTEGER — Number of components


IDX I INTEGER N Vector of component index
NBOPST I INTEGER 6 Physical property option set vector
IAS I INTEGER — ID of entry ASSAY for petroleum
properties
PROPS I/O INTEGER (2,*) Matrix of property which is calculated
(see PROPS)
PHASES I/O INTEGER * Vector of index of phase for which
property to be calculated (see PHASES)
KWDBS I/O INTEGER * Vector of basis index (see KWDBS)
XPCLV I/O REAL *8 * Vector of Liquid volume percent % (see
XPCLV)
KULAB I/O INTEGER (4,*) Matrix of unit output of result (see
KULAB)
KL2C I/O INTEGER NL2C Vector of key component index of the
second liquid phase
NL2C I/O INTEGER — Number of component index in KL2C
NATOMS I INTEGER — Number of atom entries in KATOMS
KATOMS I INTEGER NATOMS Vector of atom entries
LP I LOGICAL — .TRUE. : Property required.
.FALSE. : No calculation
LDT I/O LOGICAL — .TRUE. : DT required
.FALSE. : No calculation
LDP I/O LOGICAL — .TRUE. : DP required
.FALSE. : No calculation
LDN I/O LOGICAL — .TRUE. : DN required
.FALSE. : No calculation
NPROP O INTEGER — Number of properties
NPHASE O INTEGER — Number of phases
NBASIS O INTEGER — Number of basis
NUNIT O INTEGER — Number of units
NLVPCT O INTEGER — Number of liquid volume %
NCOMP O INTEGER — Number of properties
IDCOMP O INTEGER NCOMP Vector of ID of components
NTEMP O INTEGER — Number of temperature points
TEMP O REAL*8 NTEMP Vector of temperature
NPRES O INTEGER — Number of pressure points
PRES O REAL*8 NPRES Vector of pressure
RESULT O REAL*8 * Calculated property (see CALUPP results)
RESUDT O REAL*8 * Calculated DT (see CALUPP results)
RESUDP O REAL*8 * Calculated DP (see CALUPP results)
RESUDN O REAL*8 * Calculated DN (see CALUPP results)
KERR O INTEGER — Error flag for CALUPP (see KERR)

I = Input to subroutine, O = Output from subroutine

30 2 Writing or Modifying an Application Program


PROPS
PROPS is an integer vector containing the name of the requested prop-set
property. The valid property names are listed in Chapter 4 of the Aspen Plus
Reference Manual, Vol. 3: Physical Property Data.
For example, to request pure-component heat capacity CP:
INTEGER PROPS(2)
DATA PROPS /4HCP ,4H /

PHASES
PHASES is the index of the phase qualifier (see the Physical Property Data
Reference Manual, Chapter 4).
1 V (vapor)
2 L (liquid phase)
3 S (solid phase)
4 L1 (first liquid phase)
5 T (total mixture for mixed substream)
6 L2 (second liquid phase)
For example, to request a property for the vapor phase:
INTEGER PHASES
DATA PHASES / 1 /

KWDBS
KWDBS is the index of the WET/DRY basis qualifier (Default is WET)
1 WET (to include water in the calculation)
2 DRY (to exclude water from the calculation)
For example, to specify DRY basis for a property calculation:
INTEGER KWDBS
DATA KWDBS / 2 /

XPCLV
XPCLV is the liquid volume percent (0-100), which is used only for TBPT,
D86T, D1160T, VACT, D86T-API5, TBPTWT, D86TWT, D1160TWT, VACTWT,
D86TWT-API, D2887T, D86TCK, D86TWTCK. For other properties, set XPCLV
to 0.

KULAB
KULAB is an integer vector containing the UNITS qualifier for the calculated
property (result). For default, OUT-UNITS is to be used.
For example, to request mixture enthalpy in Btu/hr:
INTEGER KULAB(4)
DATA KULAB /4HBTU /,4HHR ,4H ,4H /

2 Writing or Modifying an Application Program 31


To use the default, OUT-UNITS, set KULAB = 0 or blank:
INTEGER KULAB(4)
DATA KULAB / 4H ,4H ,4H ,4H /
To specify a units set, such as SI, for the results, set KULAB to the units set
name:
INTEGER KULAB(4)
DATA KULAB / 4HSI ,4H ,4H ,4H /

CALUPP Results
CALUPP can only handle one property for one phase, one basis, one liquid
volume percent and one unit label in the same call. If you need several
properties for multiple phases, basis and so on, you must make multiple calls
to the property monitor.
You must define (dimension) the length of the result vectors (RESULT,
RESUDT, RESUDP and RESUDN) to be of sufficient size. For mixture
properties, RESULT has length 1. For pure component and partial properties,
RESULT has length N. Temperature and pressure derivative require the same
storage area as the property itself. Mole number derivative requires storage
area equal to N times the area required for the property.

KERR
Error codes for UPP_CALUPP are:
0 No error; the property is to be calculated
>0 Error in processing property set; no calculation
1 Error for creating prop-set
2 No property requested
3 Dry basis is invalid because no water in the component list
4 No component in composition vector
5 Liquid volume percent value is outside
>6 Flash failure

Universal Property Constants


You can retrieve universal property constants for components, such as
molecular weight or normal boiling points, directly from the plex. Place the
following statements in your application program, to retrieve universal
constants or calculated properties, such as activity coefficients:
#include "dms_plex.cmn"
REAL*8 B(1)
EQUIVALENCE (IB(1), B(1))
C
C PROPERTY PARAMETERS OFFSETS, E.G., FOR MW
#include "dms_ipoff1.cmn"
C
C CALCULATED PROPERTIES OFFSETS, E.G., FOR GAMMA
#include "dms_ipoff3.cmn"

32 2 Writing or Modifying an Application Program


The plex stores parameter values for all components defined for the property
package. The plex offsets (ipoff1 or ipoff3) store pointers to the area in the
plex where the values for a given parameter are stored. A given element of
each plex offset corresponds to a given parameter. For example,
ipoff1_ipoff1(306) stores the offset for molecular weight (MW).
Use the Aspen Properties component number as the index. For example, the
molecular weight of the third component entered in the Aspen Properties
Components | Specifications | Selection sheet is:
B(IPOFF1_IPOFF1(306)+3)
Molecular weight of the nth component is:
B(IPOFF1_IPOFF1(306)+N)
To simplify retrieval of these property constants, you can use a statement
function:
XMW(I) = LXMW + I
Where the plex offset is
LXMW = IPOFF1_IPOFF1(306)
The statement function must be declared INTEGER:
INTEGER XMW
The molecular weight of the first component is B(XMW(1)). The molecular
weight of the nth component is B(XMW(N)).
The statement function must be the first executable statement in your
program.
To retrieve universal property constants, place the appropriate statements
from the following table in your application program. All variables are double
precision (REAL*8 and INTEGER*4). Be sure to declare the name for all
statement functions as type INTEGER.
These statements Retrieve

XMW(I) = LXMW + I Molecular weight


LXMW = IPOFF1_IPOFF1(306)
TC(I) = LTC + I Critical temperature (K)
LTC = IPOFF1_IPOFF1(416)
PC(I) = LPC + I Critical pressure (N/m2)
LPC = IPOFF1_IPOFF1(326)
VC(I) = LVC + I Critical volume (m3/kmol)
LVC = IPOFF1_IPOFF1(439)
ZC(I) = LZC + I Critical compressibility factor
LZC = IPOFF1_IPOFF1(469)
TB(I) = LTB + I Normal boiling point (K)
LTB = IPOFF1_IPOFF1(414)
SG(I) = LSG + I Specific gravity
LSG = IPOFF1_IPOFF1(400)
OMEGA(I) = LOMEG + I Pitzer acentric factor
LOMEG = IPOFF1_IPOFF1(314)

2 Writing or Modifying an Application Program 33


These statements Retrieve

DHFORM(I)= LDHFM + I Standard heat of formation for ideal gas at


LDHFM = IPOFF1_IPOFF1(68) 298.15K (J/kmol)
DGFORM(I)= LDGFM +I Standard Gibbs energy of formation for ideal
LDGFM = IPOFF1_IPOFF1(55) gas at 298.15K (J/kmol)
CHARGE(I)= LCHRG + I Ionic charge number (positive for cations,
LCHRG = IPOFF1_IPOFF1(14) negative for anions)

You can use the subroutine PPUTL_PPGIDX to obtain the Aspen Properties
component number for a component. See Component Mapping.
Aspen Properties stores a special value to indicate that a property constant
for a given component is not available (that is, missing). This special value,
USER_RUMISS, is stored in the labeled common PPEXEC_USER. In some
cases, –USER_RMISS may be used to represent missing data. Place the
following statement in your application program to retrieve USER_RUMISS:
#include "ppexec_user.cmn"
You should always check to see if a property constant is missing before you
use it. For example, the following relation is true if molecular weight is
missing for Aspen Properties component number I:
DABS(B(XMW(I))) .EQ. USER_RUMISS

Flash Calculations
You can use the Aspen Properties general flash utility, FLSH_PFLASH, to
perform several types of thermodynamic calculations, including:
• Bubble and dew point pressures.
• Bubble and dew point temperatures.
• Electrolyte calculations.
• Free-water calculations.
You must specify one of the following combinations of information for two-
and three-phase flash calculations:
• Temperature and pressure (TP flash).
• Pressure and molar vapor fraction (PV flash).
• Temperature and molar vapor fraction (TV flash).
• Temperature and enthalpy (TH flash).
• Pressure and enthalpy (PH flash).
FLSH_PFLASH calculates all unspecified state variables, phase splits, phase
compositions, and phase thermodynamic properties. Phase transport
properties can be calculated by calling transport property monitors
immediately following FLSH_PFLASH. In a typical application—given
temperature, pressure, and total mixture composition—FLSH_PFLASH
determines:
• Phase split.
• Vapor and liquid compositions.

34 2 Writing or Modifying an Application Program


• Properties for each phase.
When FLSH_PFLASH is called repeatedly for the same mixture at similar
conditions and compositions (for example, in an iterative calculation), an
application program can save the FLSH_PFLASH retention arrays from call to
call. This accelerates convergence.
For flash calculations involving solids, you must use the Aspen Plus flash
utility FLSH_FLASH. (See Aspen Plus User Models, Chapter 2.) This routine
requires that you create dummy stream vectors.

Calling Sequence for FLSH_PFLASH


CALL FLSH_PFLASH (KODE, SPEC1, SPEC2, F, N,
IDX, NPHASE, KPHASE, MAXIT, TOL,
NBOPST, LDIAG, KDIAG, KBASE, TEMP,
PRES, HTOTAL, VFRAC, BETA, X,
X1, X2, Y, EKVL, EKVL2,
IRSTRT, RETEN, IRETEN, KER)

Argument List Descriptions for FLSH_PFLASH


Variable I/O† Type Dimension Description

KODE I INTEGER*4 — Flash option code (Note 3):


1 - PH
2 - TP
3 - PV
4 - TH
5 - TV
Must be 1 or 2 if NPHASE = 1 or 11
SPEC1 I REAL*8 — First specified variable:
KODE = 1,3 - Pressure (N/m2)
KODE = 2, 4, 5 - Temperature (K)
SPEC2 I REAL*8 — Second specified variable:
KODE = 1, 4 - Enthalpy per mole feed
(J/kmol)
KODE = 2 - Pressure (N/m2)
KODE = 3, 5 - Molar vapor fraction
F I REAL*8 N Total mixture mole fraction array (Note
1)
N I INTEGER*4 — Number of components present
IDX I INTEGER*4 N Component index array (Note 2)
NPHASE I INTEGER*4 — Phase calculation code:
1 - Single-phase calculation, phase
specified by KPHASE
2 - Two-phase, vapor-liquid flash
3 - Three-phase, vapor-liquid-liquid
flash
11 - Liquid-water, two-phase,
free-water calculation
12 - Vapor-liquid-water, three-phase,
free-water calculation
KPHASE I INTEGER*4 — Phase when NPHASE = 1:
1 - Vapor
2 - Liquid

2 Writing or Modifying an Application Program 35


Variable I/O† Type Dimension Description

MAXIT I INTEGER*4 — Maximum number of iterations.


Recommended value is 100.
TOL I REAL*8 — Convergence tolerance. Recommended
value is 1D-4.
NBOPST I INTEGER*4 6 Property Methods array. (See Property
Methods, page 42.)
LDIAG I INTEGER*4 — Flash diagnostic level (Note 4).
Recommended value is 4.
KDIAG I INTEGER*4 — Property diagnostic level (Note 4).
Recommended value is 4.
KBASE I INTEGER*4 — Thermodynamic reference state code.
(See Thermodynamic Reference
States.) (Note 5):
KBASE = 0 - Pure compounds in ideal
gas state at 298.15 K
KBASE = 1 - Elements in their standard
states at 298.15 K
TEMP O REAL*8 — Temperature (K)
PRES O REAL*8 — Pressure (N/m2)
HTOTAL O REAL*8 — Total mixture enthalpy per mole feed
(J/Kmol)
VFRAC O REAL*8 — Moles vapor/moles total mixture
BETA O REAL*8 — Moles first liquid/moles total liquid
X O REAL*8 N Total liquid mole fraction array (Note 1)
X1 O REAL*8 N First liquid mole fraction array (Note 1)
X2 O REAL*8 N Second liquid mole fraction array (Note
1)
Y O REAL*8 N Vapor mole fraction array (Note 1)
EKVL O REAL*8 N Vapor-liquid K-values (Note 1)
EKVL2 O REAL*8 N Vapor-liquid K-values for second-liquid
phase (Note 1)
IRSTRT I INTEGER*4 — Retention flag:
1 = Do not use retention arrays.
2 = Use retention arrays (Note 6).
RETEN R REAL*8 (Note 7) Real retention array (Note 6)
IRETEN R INTEGER*4 6 Integer retention array (Note 6)
KER O INTEGER*4 — Convergence flag:
0 = Converged
–1 = Not converged

I = Input to subroutine, O = Output from subroutine, R = Retention variable

Notes for FLSH_PFLASH Argument List Descriptions


1 F, Y, X, X1, and X2 are packed mole fraction arrays of length N. These
arrays contain the mole fractions of the components used in the
calculations. The corresponding IDX array defines the component order.
For example, if N = 2 and IDX = (1,3), Y(2) is the vapor mole fraction of
the third component in the Components | Specifications | Selection
sheet. Arrays of pure component properties (for example, liquid enthalpy)

36 2 Writing or Modifying an Application Program


and the properties of components in a mixture (for example, equilibrium
K-value) calculated by Aspen Properties are packed in the order defined
by the corresponding IDX array. (See Component Mapping.)
2 IDX is an array containing Aspen Properties component numbers of the
components actually present. Components are numbered in the order that
they appear in the Components | Specifications | Selection sheet of
the Aspen Properties property package. For example, if only the first and
third components listed in the Components Specifications Selection sheet
are present, N = 2 and IDX = (1,3). (See Component Mapping.)
3 To perform bubble and dew point calculations, specify NPHASE = 2 and a
vapor fraction of 0 or 1, as indicated in the following table:
To calculate Specify

Bubble point KODE = 5, NPHASE = 2, SPEC2 = 0, SPEC1 = temperature


pressure
Bubble point KODE = 3, NPHASE = 2, SPEC2 = 0, SPEC1 = pressure
temperature
Dew point pressure KODE = 5, NPHASE = 2, SPEC2 = 1, SPEC1 = temperature
Dew point KODE = 3, NPHASE = 2, SPEC2 = 1, SPEC1 = pressure
temperature
4 KDIAG and LDIAG control the generation of error, warning, and diagnostic
information messages. The following table describes the message levels. If
KDIAG = M, Aspen Properties generates all messages at level M and
below. These messages are written to Fortran unit number NHIST for the
history file. You must specify NHIST in the argument list of subroutine
PPEXEC_APINIT. (See Aspen Properties Initialization.)

Level Message Description

0 Terminal Error Execution cannot continue.


1 Severe Error Execution can continue, but subsequent processing is likely to
be erroneous.
2 Error Execution can continue, but subsequent processing may be
erroneous.
3 Warning Execution can continue, but a condition has been encountered
that you should know about (for example, the extrapolation of
a correlation beyond its normal limits).
4 Information Messages allow you to trace the progress of a run.
FLSH_PFLASH prints a one-line message summarizing the
results of a calculation.
5+ Diagnostic Messages are used for debugging only.
The values of calculation and physical properties diagnostics levels
specified on the Setup Specifications Diagnostics sheet are stored in
common PPEXEC_USER in variables USER_LMSG and USER_LPMSG,
respectively.
COMMON / PPEXEC_USER / USER_RUMISS, USER_IUMISS,
USER_NGBAL, USER_IPASS,USER_IRESTR, USER_ICONVG,
USER_LMSG, USER_LPMSG, USER_KFLAG, USER_NHSTRY,
USER_NRPT, USER_NTRML

2 Writing or Modifying an Application Program 37


You should use the variables USER_LMSG for LDIAG, and USER_LPMSG
for KDIAG, to control the amount of diagnostics generated.
5 If you specify enthalpy (KODE = 1, 4), Aspen Properties will calculates
enthalpies during the flash calculation using the reference state specified
by KBASE. (See Thermodynamic Reference State.)
6 To disable the FLSH_PFLASH retention feature, specify IRSTRT = 1. You
must still specify RETEN and IRETEN arrays of the appropriate size.
If you use the retention capability:
o On the first call for a mixture, specify IRSTRT = 1.
o Immediately on return from FLSH_PFLASH, if the flash is successful
(KER = 0), set IRSTRT = 2. If the flash is unsuccessful (KER < 0), set
IRSTRT = 1.
For the retention area, you can use the work space created by Aspen
Properties for this purpose. A pointer to this work space is stored in the
ppexec_reten common. To access the pointer, place the following
statement in your program:
#include "ppexec_reten.cmn"
For the real retention array, RETEN, use B(RETEN_LRRETE+1). For the
integer retention array, IRETEN, use IB(IRETEN_LIRETE+1).
7 The size of RETEN is 6N+37 in problems without electrolytes. For
electrolyte systems, the size is 2 times the number of chemistry reactions
+ 11N + 37.

Retrieving Phase Properties


The FLSH_PFLASH flash utility automatically calculates a number of scalar
properties for the co-existing phases. These properties are returned in labeled
common PRPLUS. Place the following statement in your application program
to retrieve these scalar phase properties. All values are molar quantities in SI
units.
#include "flsh_prplus.cmn"
This common contains the following variables:

Argument List Descriptions for PRPLUS


Variable Type Dimension Description

PRPLUS_ENTHV REAL*8 — Vapor enthalpy (J/kmol)


PRPLUS_ENTHL REAL*8 — Liquid enthalpy (J/kmol)
PRPLUS_ENTHL1 REAL*8 — Enthalpy of the first liquid phase (J/kmol)
PRPLUS_ENTHL2 REAL*8 — Enthalpy of the second liquid phase (J/kmol)
PRPLUS_ENTRV REAL*8 — Vapor entropy (J/kmol-K)
PRPLUS_ENTRL REAL*8 — Liquid entropy (J/kmol-K)
PRPLUS_ENTRL1 REAL*8 — Entropy of the first liquid phase (J/kmol-K)
PRPLUS_ENTRL2 REAL*8 — Entropy of the second liquid phase
(J/kmol-K)
PRPLUS_VOLV REAL*8 — Vapor volume (m3/kmol)
PRPLUS_VOLL REAL*8 — Liquid volume (m3/kmol)

38 2 Writing or Modifying an Application Program


Variable Type Dimension Description

PRPLUS_VOLL1 REAL*8 — Volume of the first liquid phase (m3/kmol)


PRPLUS_VOLL2 REAL*8 — Volume of the second liquid phase (m3/kmol)
PRPLUS_AMWV REAL*8 — Vapor average molecular weight
PRPLUS_AMWL REAL*8 — Liquid average molecular weight
PRPLUS_AMWL1 REAL*8 — First liquid phase, average molecular weight
PRPLUS_AMWL2 REAL*8 — Second liquid phase, average molecular
weight

Work Space
Aspen Properties subroutine argument lists contain many arrays. The length
of each array depends on the number of components present. It is desirable
for your application program code to be written such that it is independent of
the number of components. To help you accomplish this goal, Aspen
Properties automatically generates appropriately-dimensioned work space
within the plex. You can use this space to store these arrays and pass them to
the Aspen Properties monitors and subroutines.
Aspen Properties uses labeled commons to store the pointers to the area in
the plex where work space is allocated. Each labeled common contains a
variable that is the plex offset for the work space. For example, labeled
common PPEXEC_IWNC points to integer work space, dimensioned to be the
number of components. To access this work space, include the following
declaration in your application:
#include "ppexec_iwnc.cmn"
The first element of this space is:
IB(IWNC_LIWNC + 1)
Use the following commons to reference space for storing mole fraction arrays
and component-dependent property arrays:
COMMON Name Variable Name Type† Dimension††

PPEXEC_IWNC IWNC_LIWNC INTEGER*4 NC


PPEXEC_WNC1 WNC1_LWNC1 REAL*8 NC
PPEXEC_WNC2 WNC2_LWNC2 REAL*8 NC
PPEXEC_WNC3 WNC3_LWNC3 REAL*8 NC
PPEXEC_WNC4 WNC4_LWNC4 REAL*8 NC
PPEXEC_WNC5 WNC5_LWNC5 REAL*8 NC
PPEXEC_WNC6 WNC6_LWNC6 REAL*8 NC
PPEXEC_WNC7 WNC7_LWNC7 REAL*8 NC
PPEXEC_WNC8 WNC8_LWNC8 REAL*8 NC
PPEXEC_WNC9 WNC9_LWNC9 REAL*8 NC
PPEXEC_WNC10 WNC10_LWNC10 REAL*8 NC

Data type for the plex space pointed to by the variable name,
††
NC is the total number of components defined in the Aspen Properties property
package.

2 Writing or Modifying an Application Program 39


Use the following commons to reference work space allocated for
FLSH_PFLASH retention arrays:
COMMON Name Variable Name Type† Dimension

PPEXEC_IRETEN IRETEN_LIRETE INTEGER*4 6


††
PPEXEC_RETEN RETEN_LRRETE REAL*8

Data type for the plex space pointed to by the variable name,
††
Real retention array size is 6*NC+37 in problems without elecrtolytes. For
electrolyte systems, the size is 2 times the number of chemistry reactions + 11NC +
37. NC is the total number of components defined in the Aspen Properties property
package.
The real retention area starts at B(RETEN_LRRETE+1). The integer retention
area starts from IB(IRETEN_LIRETE+1).

Component Mapping
This section discusses how to identify components, defined in the Aspen
Properties Components | Specifications | Selection sheet, in the
application program. This is an important consideration when developing an
interface between an application program and Aspen Properties.
This section includes information about:
• Passing component arguments.
• Component mapping methods.
• Identifying the component number.
• Retrieving the number of defined components.

Passing Component Arguments


When calling an Aspen Properties subroutine for a mixture, an application
program must generate and pass the following arguments to define the
mixture composition:
Argument Definition

N Number of chemical components in the mixture


IDX An array of length N, containing the component numbers of the
components in the mixture. This array defines the order and identity of
components in the mixture.
X, Y, or F An array of length N, containing the mole fractions of the components in
the mixture

A component number identifies the component to Aspen Properties. The


component number is the position of the component in the list of components
in the Aspen Properties Components | Specifications | Selection sheet.
The first component listed is component number 1. The second component
listed is component number 2, and so on.
Similarly, when calling a pure component monitor, N and IDX define the list of
components for which properties are to be calculated.

40 2 Writing or Modifying an Application Program


Component Mapping Methods
An application program must map its components to Aspen Properties
component numbers. The following table describes some possible methods for
this mapping:
Method Description

A All application program component-dependent entries and storage locations


exactly match the full Aspen Properties component list.
B The application program user enters Aspen Properties component numbers
to identify components. The IDX array can be generated directly from these
component numbers.
C The application program user enters Aspen Properties component IDs to
identify components.

Method A provides ease of implementation. Method C is recommended, when


possible, for maximum flexibility and ease of use. It is usually possible to
modify an application program to use method B or C.
In Method A, N = NC. The IDX array is 1, 2, . . ., NC, where NC is the number
of components in the Aspen Properties component list. NC can be obtained
from the Aspen Properties labeled common DMS_NCOMP. (See Retrieving the
Number of Aspen Properties Components.)
In Method C, the corresponding component numbers can be obtained using
the Aspen Properties subroutine PPUTL_PPGIDX. (See Calling Sequence for
PPUTL_PPGIDX, page 41.) Aspen Properties does not require internal storage
of the component IDs. They can be converted to component numbers as soon
as they are read, using subroutine PPUTL_PPGIDX. Aspen Properties
component IDs are up to eight characters long. They must be read and stored
as CHARACTER*8 Fortran variables.
Methods B and C have an important advantage. Any given run of the
application program needs to include only a subset of the components defined
in the Aspen Properties configuration. Once an Aspen Properties configuration
is made for a system of components, it does not need to be repeated for
application program runs that use any subset of these components. A single
Aspen Properties configuration can generate a properties database that an
entire project team can use for an application program, not just the
properties for a single application program run.

Identifying the Aspen Properties


Component Number
Aspen Properties subroutine PPUTL_PPGIDX returns the Aspen Properties
component number corresponding to an Aspen Properties component ID. Use
the following calling sequence for subroutine PPUTL_PPGIDX:

Calling Sequence for PPUTL_PPGIDX


CALL PPUTL_PPGIDX (COMPID, NUMBER, KER)

2 Writing or Modifying an Application Program 41


Argument List Descriptions for PPUTL_PPGIDX
VariableI/O† Type Dimensions Description

COMPID I CHARACTER*8 — Aspen Properties component ID


NUMBER O INTEGER*4 — Aspen Properties component
number
KER O INTEGER*4 — Error flag:
1 = Component not found in the
Aspen Properties property package

I = Input to subroutine, O = Output from subroutine

Retrieving the Number of Aspen Properties


Components
Place the following statement in your application program to retrieve the
number of components defined in the Aspen Properties property package:
#include "dms_ncomp.cmn"
The variable NCOMP_NCC is the number of components entered in the
Components | Specifications | Selection sheet for the Aspen Properties
configuration.

Property Methods
One of the arguments to the Aspen Properties monitors and flash utility is
NBOPST, the property methods array. NBOPST contains pointers and codes
that determine physical property methods, models, and options used to
calculate any requested properties. The Properties | Specifications |
Global sheet specifies this information.
The NBOPST array is stored in labeled common PPUTL_OPSET. Include the
following statement in any subroutine that calls an Aspen Properties monitor
or the subroutine FLSH_PFLASH:
#include "pputl_opset.cmn"
The property methods array is stored in the labeled common as
OPSET_NBOPST(6).
You must use OPSET_NBOPST for NBOPST in the calling sequences for Aspen
Properties monitors and subroutines. (See Property Calculations.) The six
elements of OPSET_NBOPST correspond to the entries in the Properties |
Specifications | Global sheet, as the following table shows.

Note: Descriptions in this table are for your information only. Application
programs should not change OPSET_NBOPST.

42 2 Writing or Modifying an Application Program


OPSET_NBOPST Properties Description
Element Specifications Entry

1 Property Method Property method name


2 Henry Components Henry's component-list ID
3 Chemistry ID Electrolytes chemistry ID
4 Use True Components Electrolytes equilibrium calculation approach:
selected = Use true component approach
cleared = Use apparent component approach
5 Free-Water Method Free-water phase property method
6 Water Solubility Method for calculating the K-value of water in
the organic phase

Using Multiple Property


Methods
You can define more than one property method in the Aspen Properties setup
run. Aspen Properties stores property method information in labeled common
PPUTL_OPSET. (See Property Methods.) By default Aspen Properties uses the
global property method in the application programs. To use another property
method in your application program, call Aspen Properties subroutine
PPUTL_PPSWOP.

Calling Sequence for PPUTL_PPSWOP


CALL PPUTL_PPSWOP (OPSET, HENRY, CHEM, ITRUE, FREEW, ISOLU, IERR)

Argument List Descriptions for PPUTL_PPSWOP


Variable I/O† Type Dimensions Description

OPSET I CHARACTER*8 — Property method name


HENRY I CHARACTER*8 — Henry's component-list ID
CHEM I CHARACTER*8 — Electrolytes chemistry ID
ITRUE I INTEGER — Electrolytes equilibrium calculation
approach:
1 = True component approach
0 = Apparent component approach
FREEW I CHARACTER*8 — Free-water phase property method
name
ISOLU I INTEGER — Method for calculating the K-value
of water
in the organic phase (0, 1, 2, 3, or
4)
IERR O INTEGER — 0 = Option set switching
successful
>0 = Option set not switched

I = Input to subroutine, O = Output from subroutine

2 Writing or Modifying an Application Program 43


Aspen Properties places the new property method you specify in the labeled
common PPUTL_OPSET:
COMMON / PPUTL_OPSET / OPSET_NBOPST (6)

Reports
You should not attempt to generate detailed property reports from an
application program. But you can use the Aspen Properties analysis features
to generate detailed property reports. See the Aspen Properties User Guide,
Chapter 15, for details about Property Analysis.
An application program often needs to report component IDs, formulas and
names, and property method descriptions. You may also need the program to
report certain key universal constants for the components, such as molecular
weight. This section describes procedures for retrieving the following
information from Aspen Properties, for use in reports:
• Component information.
• Property method descriptions.

Component Information in Reports


The Aspen Properties subroutine PPUTL_PPGNAM can retrieve component IDs
and names, when you supply the Aspen Properties component number. You
can use subroutine PPUTL_PPGIDX, in conjunction with PPUTL_PPGNAM, to
retrieve component names, when you supply Aspen Properties component
IDs. Use the procedure described in Universal Property Constants to retrieve
universal constants.

Calling Sequence for PPUTL_PPGNAM


CALL PPUTL_PPGNAM (NUMBER, COMPID, ALIAS, CNAME, OUTID)

Argument List Descriptions for PPUTL_PPGNAM


VariableI/O† Type Dimensions Description

NUMBER I INTEGER*4 Aspen Properties component number

COMPID O CHARACTER*8 Aspen Properties component ID

ALIAS O CHARACTER*12 Aspen Plus databank alias (formula)

CNAME O CHARACTER*32 Aspen Plus databank name

OUTID O CHARACTER*8 Aspen Properties output ID

I = Input to subroutine, O = Output from subroutine

Property Method Descriptions in Reports


You can use Aspen Properties subroutine PPUTL_PPWROP to write the
contents of the NBOPST array in a format suitable for reports. PPWROP writes
up to six 38-character lines to the unit number NRPT, specified in the call to
PPEXEC_APINIT. (See Aspen Properties Initialization.)

44 2 Writing or Modifying an Application Program


Calling Sequence for PPUTL_PPWROP
CALL PPUTL_PPWROP (OPSET_NBOPST)

Argument List Description for PPUTL_PPWROP


Variable I/O† Type Dimensions Description

OPSET_NBOPSTI INTEGER*4 6 Aspen Properties property methods


array from labeled common
PPUTL_OPSET

I = Input to subroutine, O = Output from subroutine

2 Writing or Modifying an Application Program 45


3 Run Procedures

After you create an Aspen Properties property package and develop an


application program that uses Aspen Properties Toolkit, you must:
• Compile the application program that contains Aspen Properties Toolkit
commons or makes calls to Aspen Properties Toolkit routines.
• Use the Aspen Properties Toolkit link procedure to link the application
program to the Aspen Properties Toolkit, or modify the application
program linking procedure to link to Aspen Properties libraries.
• Modify the application program run procedure for use with Aspen
Properties Toolkit.
Link procedures are command language procedures that link application
object code to the Aspen Properties Toolkit library. Run procedures are
command language procedures that run the application program. The
procedures and instructions for modifying or writing link and run procedures
depend on the type of computer and operating system you use.
This chapter discusses how to:
• Compile the application program that contains Aspen Properties Toolkit
commons or makes calls to Aspen Properties Toolkit routines.
• Link Aspen Properties Toolkit to an application program.
• Modify the application program run procedure for use with Aspen
Properties Toolkit.
Chapter 4 contains examples of both Aspen Properties Toolkit link procedures
and application program run procedures.

46 3 Run Procedures
Compiling the Application
Program Containing Aspen
Properties Toolkit Commons
and Routines
To compile any application program files containing Aspen Properties
commons and routines, use the aspcomp utility provided with Aspen
Properties. For a detailed description of the aspcomp utility, refer to
Aspen Plus User Models, Chapter 1.

Note: The Intel Fortran 9.0 compiler is required.

Linking Application Programs


to Aspen Properties Toolkit
To link an application program to Aspen Properties Toolkit, you can use Aspen
Properties Toolkit link procedures, or modify application program link
procedures to include Aspen Properties Toolkit libraries.

Creating a Shared Library with Aspen


Properties Toolkit
Use this Aspen Properties Toolkit link procedure to generate a shared library.
The steps to link an application program with Aspen Properties are:
1 Define the application program name. Use this name to identify the
application program in the Aspen Properties Toolkit link procedure. You
can choose this name arbitrarily.
2 Specify the name and location of the application program object/library
files and any application-specific linker directives in a dlopt file. For use of
dlopt files, refer to Aspen Plus User Models, Chapter 1. By default, the
linking procedure uses all the object files in the current working directory.
To create an executable file, at least one of the object files must contain
the main application program.
3 Use asplink to create a shared library for the application program that
uses Aspen Properties Toolkit with the format:
ASPLINK appl
Where appl is the name of the shared library or executable to be created
for the application program.
For a detailed description of asplink, refer to Aspen Plus User Models,
Chapter 1.

3 Run Procedures 47
You must avoid name conflicts between application program subroutines and
routines in the Aspen Properties Toolkit library. Due to the modular nature of
Aspen Properties, unpredictable results may be obtained if there are name
conflicts.

Linking an Application Program with Aspen


Properties Toolkit
To link an application program to Aspen Properties Toolkit, the following
Aspen Properties Toolkit libraries should be linked to the application program.
These libraries are available in the APrSystem <version>\Engine\lib directory.
In addition, Fortran and C runtime libraries may need to be linked. Chapter 4
provides an example of linking these libraries to create an executable
program.
Description Windows library file name

Data Management System atdms.lib


Stream Handling System zeshs.lib
Math library zemath.lib
SQP module zesqp.lib
Report Writer zereport.lib
Stub DLL for Installable modules ppstub.lib
Aspen Properties Utilities pputil.lib
Aspen Properties base routines ppbase.lib
Aspen Properties Equation of State module ppeos.lib
Aspen Properties Monitors ppmon.lib
Aspen Properties Executive ppexec.lib
Aspen Properties Flash module ppflash.lib
Stream Utilities zestreamu.lib
Aspen Properties UPP module ppupp.lib
Variable Accessing Utilities zevaraccu.lib
Aspen Properties Reaction module pprxn.lib
Flowsheeting tools zeftools.lib
Unit Operation Module utilities zeuosutl.lib
Input Translation Utilities zeitutl.lib
Aspen Properties Estimation module pppces.lib

To use asplink to compile an executable program, you must give it the genexe
option before the name of the program, as in:
asplink genexe appl

48 3 Run Procedures
Modifying Application Program
Run Procedures for Use With
Aspen Properties Toolkit
The application program must be provided with the run ID used during the
Aspen Properties property package configuration run. The Aspen Properties
run ID enables the program to access the physical property data and
methods, created by the configuration and stored in the problem data file
(.aprpdf file). You must modify the application program run procedure to pass
the run ID to the program.
Common methods for passing the Aspen Properties run ID to the application
program include:
• Passing the run ID as an argument on the application program command
line.
• Writing the run ID to a file read by the application.
• Setting a symbol or environment variable accessed by the application
program.
For the operating system to find Aspen Properties Toolkit libraries at runtime,
the PATH environment variable needs to be modified as follows to include
Aspen Properties shared library location:

Example
set path=C:\Program Files\AspenTech\APrSystem
<version>\Engine\xeq;%path%
The application program can dynamically link user property routines during
execution. See Aspen Plus User Models, Chapter 1 for more information about
dynamic linking.

3 Run Procedures 49
4 Sample Application
Program That Uses Aspen
Properties

This chapter presents a simple but comprehensive example to illustrate the


development and use of an application program that uses Aspen Properties.
The application program FLCURVE generates a table showing temperature,
duty, heat capacity, and density, versus molar vapor fraction. This table is for
a user-specified mixture at a specified pressure. The input to FLCURVE uses
Aspen Properties component IDs to identify components. It expresses
composition in terms of mass fractions. SI units are used for all input,
computation, and reports.
Comments within the program provide detailed explanations of important
considerations in the process of developing the sample application program
interface.
The steps for using Aspen Properties Toolkit in an application program are:
1 Compile the application program.
2 Link the application program to Aspen Properties Toolkit.
3 Make the Aspen Properties setup run to create a property package.
4 Run the application program.
This chapter illustrates these steps by providing the following samples:
• Application program.
• Application program run procedures.
• Aspen Properties property package.
• Input file for running the application program.
• The results for the application program in the file flcurve.rep.

50 4 Sample Application Program That Uses Aspen Properties


Source Code for FLCURVE
The complete Fortran source code for the FLCURVE application program
appears in Figure 4.1. The Aspen Properties Toolkit libraries provide all
subroutines called by FLCURVE.
This program illustrates important points in developing an Aspen Properties
interface. It does not include all features that an actual application program
should have. For example, it does not check to see if input pressure and mass
fractions lie in valid ranges.

Figure 4.1 FLCURVE Main Program


C---------------------------------------------------------------
C SAMPLE Aspen Properties APPLICATION PROGRAM
C
C
C This program computes a flash curve for a mixture,
C given pressure and the mass fractions of a list of
C components from those that have been defined in a
C properties setup run.
C
C This sample program is meant only to illustrate the
C use of Aspen Properties Toolkit and is not meant to
C represent a practical application.
C---------------------------------------------------------------
C
C Type declarations - Note that all real variables in Aspen
C Properties are double precision
C
IMPLICIT NONE
C
C
C DECLARE ARGUMENTS
C
INTEGER LMSG, LPMSG, LIDX, LF, LX,
+ LX1, LX2, LY, LKVL, LKVL2,
+ LFMASS,NHIST, NTERM, NRPT, IABORT,
+ KBASE, I, IARG, KEY,
+ N, ICOMP, KER, IRSTRT,KPHASE
REAL*8 B(1), PRES, VFRAC, TCALC, PCALC,
+ HCALC, VFCALC,BETA, DUMMY, CPV,
+ CPL
C
C
C DECLARE SYSTEM FUNCTIONS
C
INTEGER LIB$ESTABLISH
REAL*8 DMS_DGSQZ

C
C DECLARE LOCAL VARIABLES
C
INTEGER NC, IMISS, NIN, LMW, ISTAT,

4 Sample Application Program That Uses Aspen Properties 51


+ IPOINT
REAL*8 RMISS, HV, HL, HL1, HL2,
+ SV, SL, SL1, SL2, VV,
+ VL, VL1, VL2, FMT, XX,
+ FSUM, HCALC0,DUTY, RHOV, RHOL
CHARACTER*255 XPDF
CHARACTER*8 COMPID, OUTID
CHARACTER*12 ALIAS
CHARACTER*32 CNAME
LOGICAL ERROR
C
C The following character declarations are for filenames
C for open statements.
C
CHARACTER*255 INPUT, RUNID, FILNAM
C
C Commons containing information from Aspen Properties.
C Note that the message levels, LMSG and LPMSG, are from
C the calculation and physical properties diagnostics
C message level specifications on the Setup Specifications
C Diagnostics sheet. Use of these flags in your application
C program enables the user to control the amount of
C diagnostics generated.
C
#include "dms_plex.cmn"
EQUIVALENCE (IB(1), B(1))
#include "dms_ipoff1.cmn"
INTEGER MW
#include "dms_ncomp.cmn"
EQUIVALENCE (NC, NCOMP_NCC)

#include "ppexec_user.cmn"
INTEGER IDUM(4)
EQUIVALENCE (RMISS, USER_RUMISS)
EQUIVALENCE (IMISS, USER_IUMISS)
EQUIVALENCE (IDUM(1), USER_NGBAL)
EQUIVALENCE (IDUM(2), USER_IPASS)
EQUIVALENCE (IDUM(3), USER_IRESTR)
EQUIVALENCE (IDUM(4), USER_ICONVG)
EQUIVALENCE (LMSG, USER_LMSG)
EQUIVALENCE (LPMSG, USER_LPMSG)
#include "pputl_opset.cmn"
#include "flsh_prplus.cmn"
EQUIVALENCE (HV, PRPLUS_ENTHV)
EQUIVALENCE (HL, PRPLUS_ENTHL)
EQUIVALENCE (HL1, PRPLUS_ENTHL1)
EQUIVALENCE (HL2, PRPLUS_ENTHL2)
EQUIVALENCE (SV, PRPLUS_ENTRV)
EQUIVALENCE (SL, PRPLUS_ENTRL)
EQUIVALENCE (SL1, PRPLUS_ENTRL1)
EQUIVALENCE (SL2, PRPLUS_ENTRL2)
EQUIVALENCE (VV, PRPLUS_VOLV)
EQUIVALENCE (VL, PRPLUS_VOLL)
EQUIVALENCE (VL1, PRPLUS_VOLL1)
EQUIVALENCE (VL2, PRPLUS_VOLL2)
C
C Work commons generated by Aspen Properties. The length of

52 4 Sample Application Program That Uses Aspen Properties


C these commons is >= NC, the number of components defined
C in the properties setup run. They provide properly
C dimensioned space,for mole fraction and other component-
C dependent arrays used by Aspen Properties, or the
C application program.
C
#include "ppexec_iwnc.cmn"
EQUIVALENCE (LIDX, IWNC_LIWNC)
#include "ppexec_wnc1.cmn"
EQUIVALENCE (LF, WNC1_LWNC1)
#include "ppexec_wnc2.cmn"
EQUIVALENCE (LX, WNC2_LWNC2)
#include "ppexec_wnc3.cmn"
EQUIVALENCE (LX1, WNC3_LWNC3)
#include "ppexec_wnc4.cmn"
EQUIVALENCE (LX2, WNC4_LWNC4)
#include "ppexec_wnc5.cmn"
EQUIVALENCE (LY, WNC5_LWNC5)
#include "ppexec_wnc6.cmn"
EQUIVALENCE (LKVL, WNC6_LWNC6)
#include "ppexec_wnc7.cmn"
EQUIVALENCE (LKVL2, WNC7_LWNC7)
#include "ppexec_wnc8.cmn"
EQUIVALENCE (LFMASS, WNC8_LWNC8)
C
C The following commons are also generated by Aspen
C Properties. They provide properly dimensioned space for
C the PFLASH retention arrays
C
#include "ppexec_ireten.cmn"
#include "ppexec_reten.cmn"
C
C Set the Fortran unit numbers and the abort flag passed
C to APINIT
C
C
C DATA STATEMENTS
C
DATA NIN, NHIST, NTERM, NRPT, IABORT
1 / 1 , 6 , 5 , 12 , 1 /

C
C Set the enthalpy basis for Aspen Properties
C
DATA KBASE
1 / 1 /
C
C Format statements
C
10 FORMAT(I2,1X,G15.5)
C
20 FORMAT(/,1X,'ERROR: NUMBER OF COMPONENTS ENTERED (',I2,
1 ') GREATER'
2 /,1X,'THAN NUMBER DEFINED IN PROPERTIES SETUP RUN ('
3 ,I2,')'/,1X,'EXECUTION TERMINATED')
C

4 Sample Application Program That Uses Aspen Properties 53


30 FORMAT(A8,1X,G15.5)
C
40 FORMAT(/,1X, 'ERROR: COMPONENT (',
1 A8,') NOT DEFINED IN PROPERTIES SETUP RUN')
C
50 FORMAT(/,1X,
1 'ERROR: MOLECULR WEIGHT MISSING FOR COMPONENT (',A8,')')
C
60 FORMAT(/,1X,
1 'EXECUTION TERMINATED BECAUSE OF ERRORS IN INPUT')
C
70 FORMAT('1FLASH CURVE FOR FOLLOWING SYSTEM AT ',G15.5,
1 ' N/M2')
C
80 FORMAT(' COMP ID COMP NAME',23X,'MOLE WEIGHT',6X,
1 'MASS FRACTION MOLE FRACTION')
C
90 FORMAT(2X,A8,2X,A32,3(2X,G15.5))
C
100 FORMAT(' VAPOR FRACTION TEMPERATURE ',
1 ' DUTY VAPOR CP LIQUID CP ',
2 ' VAPOR DENSITY LIQUID DENSITY',/,
3 ' K ',
4 ' J/S J/KMOLE-K J/KMOLE-K ',
5 ' KG/M3 KG/M3')
C
110 FORMAT(7(2X,G15.5))

C
120 FORMAT(/,' ERRORS OCCURED IN CACLULATIONS. CHECK HISTORY FILE')
C
130 FORMAT(/,' FLASH CURVE CALCULATIONS COMPLETED NORMALLY')
C
C Property parameters can be accessed using function
C declarations
C
C
C BEGIN EXECUTABLE CODE
C
MW(I) = LMW + I
C
C The report, history, and input files must be opened.
C Also, we must determine the name of the APRPDF file.
C
C The Aspen Properties Run ID and the application program
C input file are stored in the file PPLUS.NAM.
C
C DGSQZ is used to squeeze blanks from the file names.
C
FILNAM = 'PPLUS.NAM'
OPEN(UNIT=50,FILE=FILNAM,STATUS='OLD')
READ(50, FMT='(A)') RUNID
READ(50, FMT='(A)') INPUT
CLOSE(50)
FILNAM = INPUT
FILNAM(250:253) = '.INP'
XX = DMS_DGSQZ(FILNAM)

54 4 Sample Application Program That Uses Aspen Properties


OPEN(UNIT=NIN, FILE=FILNAM, STATUS='OLD')
FILNAM = INPUT
FILNAM(250:253) = '.HIS'
XX = DMS_DGSQZ(FILNAM)
OPEN(UNIT=NHIST, FILE=FILNAM, STATUS='UNKNOWN')
FILNAM = INPUT

FILNAM(250:253) = '.REP'
XX = DMS_DGSQZ(FILNAM)
OPEN(UNIT=NRPT, FILE=FILNAM, STATUS='UNKNOWN')
FILNAM = 'CON'
OPEN(UNIT=NTERM, FILE=FILNAM, STATUS='UNKNOWN')
XPDF = RUNID
XPDF(248:254) = '.APRPDF'
XX = DMS_DGSQZ(XPDF)
C
C Call the Aspen Properties initialization routine. This
C call must be made before any other Aspen Properties
C calls, and before any values are retrieved from Aspen
C Properties commons. The variable KEY contains the Aspen
C Properties Toolkit's authorization key number.
C
KEY = 400
CALL PPEXEC_APINIT (NHIST, NTERM, XPDF, NRPT, IABORT, KEY)
C
C Now that Aspen Properties is initialized, we can set the
C offset to labeled commons used in the statement function
C declarations.
C
LMW = IPOFF1_IPOFF1(306)
C
C
C Read in number of components and pressure
C
READ (NIN,10) N, PRES
C
C Make sure the number of components is less than or equal
C to the number defined in the properties setup run. If
C not, write an error message to the history file and
C terminate.
C
IF (N .GT. NC) THEN
WRITE (NHIST,20) N, NC
STOP
ENDIF
C
C Read in the components and their mass fractions.
C
ERROR = .FALSE.
FSUM = 0D0
DO 200 ICOMP=1,N
READ (NIN,30) COMPID, B(LFMASS+ICOMP)
C
C Call PPGIDX to get the Aspen Properties component number
C for the component and to make sure the component was
C defined in the properties setup run. If not, write an
C error message to the history file and set the error flag.

4 Sample Application Program That Uses Aspen Properties 55


C
CALL PPUTL_PPGIDX(COMPID, IB(LIDX+ICOMP), KER)
IF (KER.LT.0) THEN
WRITE(NHIST,40) COMPID
ERROR = .TRUE.
C
C Check to make sure the molecular weight of the
C component is available. If not, write an error message
C to the history file and set the error flag. Aspen
C Properties uses the value RMISS or -RMISS (stored in
C common USER) to flag missing properties.
C
C Note that the Aspen Properties component number
C IDX(ICOMP) is used as the XMW array index, since this
C array was generated by Aspen Properties.
C
ELSE IF (DABS(B(MW(IB(LIDX+ICOMP)))) .EQ. RMISS) THEN
WRITE (NHIST,50) COMPID
ERROR = .TRUE.
C
C Compute the unnormalized mole fraction of the
C component.
C
ELSE
B(LF+ICOMP) = B(LFMASS+ICOMP)/B(MW(IB(LIDX+ICOMP)))
FSUM = B(LF+ICOMP) + FSUM
ENDIF
200 CONTINUE
C
C If any components were not defined in the properties
C setup run, or are missing molecular weight, write an
C error message to the history file and terminate
C
IF (ERROR) THEN
WRITE (NHIST,60)
STOP
ENDIF
C
C Normalize the mole fractions.
C
DO 210 ICOMP=1,N
B(LF+ICOMP) = B(LF+ICOMP)/FSUM
210 CONTINUE
C
C Write the mixture description to the report file.
C
WRITE (NRPT,70) PRES
WRITE (NRPT,80)
DO 220 ICOMP=1,N
C
C Call PPGNAM to get the Aspen Properties component ID and
C component name for the report.
C
CALL PPUTL_PPGNAM (IB(LIDX+ICOMP)
+ , COMPID, ALIAS, CNAME, OUTID)
WRITE (NRPT,90) COMPID, CNAME, B(MW(IB(LIDX+ICOMP))),
1 B(LFMASS+ICOMP), B(LF+ICOMP)

56 4 Sample Application Program That Uses Aspen Properties


220 CONTINUE
C
C Write the option set vector description to the report.
C
CALL PPUTL_PPWROP (OPSET_NBOPST)
C
C Generate the flash curve for vfrac=0.0,0.1,...,1.0.
C Vfrac=0 represents the bubble point, vfrac=1 represents
C the dew point.
C
C If any of the property data required for the computations
C is missing, or if the computations fail, messages will be
C written to the history file.
C
WRITE (NRPT,100)
VFRAC = 0D0
C
C It is necessary to set the restart flag, IRSTRT, to 1
C before the first call to PFLASH, even if the restart
C feature is not used.
C
IRSTRT = 1
ERROR = .FALSE.
DO 230 IPOINT=0,10
C
C Call PFLASH to flash the mixture. Note that all arrays in
C the argument list must be allocated, even if only single-
C phase or two-phase calculations are performed. For
C example, PFLASH fills in the X2 array with zeros when a
C two phase flash is performed.
C
CALL FLSH_PFLASH (3, PRES, VFRAC, B(LF+1), N,
+ IB(LIDX+1), 2, KPHASE, 30, 1D-4,
+ OPSET_NBOPST, LMSG, LPMSG, KBASE, TCALC,
+ PCALC, HCALC, VFCALC, BETA, B(LX+1),
+ B(LX1+1), B(LX2+1), B(LY+1), B(LKVL+1),
+ B(LKVL2+1), IRSTRT, B(RETEN_LRRETE+1),
+ IB(IRETEN_LIRETE+1), KER)
C
C Set the error flag if the flash failed.
C
IF (KER .LT. 0) ERROR = .TRUE.
C
C Since the same mixture is flashed repeatedly at similar
C conditions, the restart feature is used. If the flash is
C successful, set the restart flag to 2.
C
IF (KER .EQ. 0) IRSTRT = 2
C
C Duty is calculated as the enthalpy difference from
C the bubble point
C
IF (VFRAC .EQ. 0D0) HCALC0 = HCALC
DUTY = HCALC - HCALC0
C
C The enthalpy monitors are called with KH=2 to compute
C heat capacity, since PFLASH does not calculate this

4 Sample Application Program That Uses Aspen Properties 57


C property.
C
C You can pass a dummy variable to monitors for both scalar
C and vector properties that are not requested, such as
C enthaply in this case
C
CALL PPMON_ENTHV (TCALC, PRES, B(LY+1), N, IB(LIDX+1),
+ OPSET_NBOPST, LPMSG, KBASE, 2, DUMMY, CPV, KER)
IF (KER .LT. 0) ERROR = .TRUE.
C
CALL PPMON_ENTHL (TCALC, PRES, B(LX+1), N, IB(LIDX+1),
+ OPSET_NBOPST, LPMSG, KBASE, 2, DUMMY, CPL, KER)
IF (KER .LT. 0) ERROR = .TRUE.
C
C
C If errors occured during calculations, write a message to
C the report directing the user to the history file
C
IF (ERROR) WRITE (NRPT,120)
C
C Write a termination message to the history file
C
WRITE(NHIST,130)
C
STOP
END

58 4 Sample Application Program That Uses Aspen Properties


Compiling and Linking FLCURVE
Figure 4.2 displays a script of the commands used to compile FLCURVE,
generate a link definition file, and link FLCURVE.

Note: These commands must be used from an Aspen Properties Calculation


Engine window, not from a regular command prompt. An Aspen Properties
Calculation Engine window can be opened from Start menu | Programs |
AspenTech | Aspen Engineering Suite | Aspen Properties <version> |
Aspen Properties Calculation Engine.

Figure 4.2 FLCURVE Compile and Link Script


@echo off
echo
echo -----------------------------------------------
echo Compilation and Linking procedure for Flcurve
echo For Aspen Properties
echo Date: 31 October, 2001
echo -----------------------------------------------
echo
echo Compiling and linking flcurve.f
echo
call aspcomp flcurve.f
@echo %aprsys%\lib\zever.lib > link.def
@echo %aprsys%\lib\zetoolkit.lib >>link.def
@echo %aprsys%\lib\zeshs.lib >>link.def
@echo %aprsys%\lib\ppoli.lib >>link.def
@echo %aprsys%\lib\pppetromod.lib >>link.def
@echo %aprsys%\lib\ppthermo.lib >>link.def
@echo %aprsys%\lib\pptabpoly.lib >>link.def
@echo %aprsys%\lib\ppgamma.lib >>link.def
@echo %aprsys%\lib\pptransport.lib >>link.def
@echo %aprsys%\lib\ppncsolid.lib >>link.def
@echo %aprsys%\lib\ppelec.lib >>link.def
@echo %aprsys%\lib\pptransporti.lib >>link.def
@echo %aprsys%\lib\pptabpolyi.lib >>link.def
@echo %aprsys%\lib\ppgammai.lib >>link.def
@echo %aprsys%\lib\ppeleci.lib >>link.def
@echo %aprsys%\lib\ppeosi.lib >>link.def
@echo %aprsys%\lib\ppthermoi.lib >>link.def
call asplink dlopt=link.def flcurve.exe
echo -----------------------------------------------
echo
echo End of flcurve compilation and link

4 Sample Application Program That Uses Aspen Properties 59


Aspen Properties Property
Package for FLCURVE
This section describes the steps needed to set up an Aspen Properties
property package named HCGAS. The property package sets up the
properties for 18 hydrocarbons and light gases. It specifies the
Redlich-Kwong-Soave equation of state for use in all property calculations.
See the Aspen Properties User Guide, Chapters 5, 6 and 7, for more
information about specifying properties.
This property package is not specific to the FLCURVE application program. You
could use this property package with any application program that uses Aspen
Properties and needs the same components and properties.
To set up the HCGAS property package:
1 Start Aspen Properties and create a new problem.
2 From the Data menu, select Components.
3 On the Components | Specifications | Selection sheet, define the
following components:
Component ID Formula

N2 N2
CO2 CO2
H2S H2S
CH4 CH4
C2 C2H6
C3 C3H8
IC4 C4H10–2
NC4 C4H10–1
IC5 C5H12–3
NC5 C5H12–1
NC6 C6H14–1
NC7 C7H16–1
NC8 C8H18–1
NC9 C9H20–D1
IC9 C9H20–D1
NC10 C10H22–1
NC11 C11H24
NC12 C12H26
4 From the Data menu, select Properties.
5 On the Properties | Specifications | Global sheet, select RK-SOAVE in
the Property Method field. Click Next.
6 From the File menu, select Save As.
7 In the Save As dialog box, enter hcgas in the File name field.

60 4 Sample Application Program That Uses Aspen Properties


8 From the Calculate menu, select Calculate to create the hcgas property
package (hcgas.appdf file).
9 From the File menu, select Save As.
10 In the Save As dialog box, select Aspen Properties Backup Files in the
Save as type field to save the hcgas property package in the backup
format.

Sample Input File for Running


FLCURVE
Figure 4.3 displays an input file named CASE1 for an FLCURVE run. The
mixture in this file contains 16 of the 18 components defined in the properties
setup run. It is not necessary to enter the components in the same order as
in the Aspen Properties property package.
Note that the first line specifies the number of components (16) and the
pressure of the mixture in N/m2. The subsequent lines specify component IDs
and the corresponding weight fractions for each component.

Figure 4.3 CASE1 Input File


16 .439E+6
H2 0.0053195
CO2 0.1158
H2S 0.006131
CH4 0.025475
C2 0.046189
C3 0.053554
IC4 0.018614
NC4 0.047446
IC5 0.030231
NC5 0.043214
NC6 0.080980
NC8 0.1116
NC9 0.1134
NC10 0.062730
NC11 0.1006
NC7 0.1384

4 Sample Application Program That Uses Aspen Properties 61


Run Procedures To Execute
FLCURVE
Figure 4.4 displays a sample run procedure to execute FLCURVE. This
procedure is kept as simple as possible in these examples, to illustrate
important points relevant to Aspen Properties. Actual procedures should check
for the existence of files, provide prompts, and so on.

Figure 4.4 FLCURVE Run Procedure FLCURVE.BAT


@echo off
echo
echo ------------------------------------------------
echo Run procedure for example Flcurve
echo For Aspen Properties
echo Date: 31 october, 2001
echo Assume that the property package has been
echo created. The property package Run ID and the
echo flcurve input file name are stored in the
echo file pplus.nam
echo ------------------------------------------------
echo hcgas >pplus.nam
echo case1 >>pplus.nam

echo Running flcurve.exe

flcurve.exe

echo ------------------------------------------------
echo End of flcurve test

In this example, the first line written to the pplus.nam file (hcgas) is the run
ID of the Aspen Properties package, and the second line (case1) is the name
of the input file for the program (the file in Figure 4.3).
To run the application program, enter this command in an Aspen Properties
Calculation Engine window:

FLCURVE.BAT
Additional FLCURVE runs can be made with different pressures, components,
and compositions, without rerunning the properties setup step. You can do
this by defining all components in the HCGAS property package.

62 4 Sample Application Program That Uses Aspen Properties


Report File from Running
FLCURVE
Figure 4.5 shows the report from the FLCURVE run:

Figure 4.5 FLCURVE Report


1FLASH CURVE FOR FOLLOWING SYSTEM AT 0.43900E+06 N/M2
COMP ID COMP NAME MOLE WEIGHT MASS FRACTION MOLE FRACTION
N2 N2 28.013 0.53195E-02 0.12865E-01
CO2 CO2 44.010 0.11580 0.17826
H2S H2S 34.082 0.61310E-02 0.12187E-01
CH4 CH4 16.043 0.25475E-01 0.10758
C2 C2H6 30.070 0.46189E-01 0.10407
C3 C3H8 44.097 0.53554E-01 0.82279E-01
IC4 C4H10-2 58.123 0.18614E-01 0.21696E-01
NC4 C4H10-1 58.123 0.47446E-01 0.55303E-01
IC5 C5H12-3 72.150 0.30231E-01 0.28387E-01
NC5 C5H12-1 72.150 0.43214E-01 0.40578E-01
NC6 C6H14-1 86.177 0.80980E-01 0.63663E-01
NC8 C8H18-1 114.23 0.11160 0.66188E-01
NC9 C9H20-1 128.26 0.11340 0.59900E-01
NC10 C10H22-1 142.28 0.62730E-01 0.29869E-01
NC11 C11H24 156.31 0.10060 0.43602E-01
NC7 C7H16-1 100.20 0.13840 0.93573E-01

VAPOR FRACTION TEMPERATURE DUTY VAPOR CP LIQUID CP VAPOR DENSITY LIQUID DENSITY
K J/S J/KMOLE-K J/KMOLE-K KG/M3 KG/M3
0.00000E+00 154.30 0.00000E+00 32717. 0.12433E+06 0.15755E-01 0.16582
0.10000 196.67 0.60654E+07 34668. 0.13411E+06 0.12037E-01 0.13975
0.20000 221.09 0.10283E+08 36481. 0.14694E+06 0.86484E-02 0.11956
0.30000 242.10 0.14222E+08 39110. 0.16309E+06 0.71078E-02 0.10129
0.40000 269.50 0.19171E+08 44167. 0.18588E+06 0.59128E-02 0.84112E-01
0.50000 303.77 0.25458E+08 53729. 0.21630E+06 0.47760E-02 0.69263E-01
0.60000 339.87 0.32660E+08 68364. 0.25113E+06 0.37848E-02 0.57644E-01
0.70000 370.83 0.39806E+08 86528. 0.28411E+06 0.30425E-02 0.49313E-01
0.80000 395.52 0.46472E+08 0.10587E+06 0.31399E+06 0.25273E-02 0.43082E-01
0.90000 416.49 0.52880E+08 0.12565E+06 0.34253E+06 0.21553E-02 0.38034E-01
1.0000 434.96 0.59158E+08 0.14574E+06 0.36948E+06 0.18742E-02 0.34003E-01

4 Sample Application Program That Uses Aspen Properties 63


Index

Calculation methods 17
A Calling sequences 18–22
Chemistry forms 11
Activity coefficients Commands, run 62
calculating 28 Compiling
UNIFAC model 6 application files 47
Advanced features 11 aspcomp utility 47
Analysis example 59
features 44 Compiling application files 46
property 10 Components
APPDF file 7 arguments 40
Application programs mapping 40
compiling 46 numbers 33, 34, 40, 41
determining suitability 12–13 reference state 16
qualifying 12 reporting 44
running, reusing 6, 8 retrieving number of 42
sample 50 Creating property packages 8–10
APRPDF file 7, 15 customer support 4
Arguments
components 40
D
flash 35
monitors 22–24 Data Regression System 6
Arrays Data storage 15
work 39 Databanks
Aspcomp utility 47 Aspen Physical Property System
Aspen Physical Property System 6
databanks 6 in-house 11
AspenTech support 4 Defining components, example 60
AspenTech Support Center 4 Diagnostic messages 15, 16, 25,
37
B Diffusion coefficient property
monitors 20
Binary interactions DRS 6
predicting 6 Dynamic linking 49

C E
Calculating activity coefficients 28 e-bulletins 4
Calculating Cv 27 Electrolytes 11, 17, See also Flash
Calculating flashes 34 calculations
Calculating heat capacity 26 Elemental reference state 17
Calculating molecular weight 28 Enthalpies 17
Calculating properties 17–28 Enthalpy property monitors 20
Calculation codes 17, 26 Entropies 17

64 Index
Equilibrium ratio property monitors I
19
Ideal gas phase monitor 19
Estimating properties 6
Identifying components 40
Examples
In–house models, databanks 11
compiling 59
Initializing Aspen Properties Toolkit
executing run 62
15
input file 61
Input file example 61
linking 59
Input File example See also Setting
property package 60
up property packages
report 63
run procedures 62
source code 51 K
Examples of Calculating Cv, vapor Key features 6
mixture 27 K-value property monitors 19
Executable files 47
Executing runs example 62
L

F Libraries
list 48
Features location 49
advanced 11 Link procedures 46
analysis 44 Linking
key 6 application files 47
reporting 6 dynamic 49
File unit numbers 15 example 59
Fitting models to data 6 Liquid fugacity coefficients 28
Flash calculations 6, 34
FLCURVE example 50
M
Forms
Chemistry 11 Mapping components 40
for setting up property packages Message levels 25
7 Mixture phase monitors 19
Setup Report Options 10 Mixtures
Free-water calculations See Flash composition 40
calculations non-ideal 6
Fugacity coefficient property Models
monitors 20 fitting to data 10
Fugacity coefficients 17 in-house 11
Modifications of property system
G 11
Modifying run procedures 49
Gibbs free energies 17 Molar volume property monitors 21
Global information Molecular weight 28
specifying 42 Monitors see Phase monitors and
Group contribution methods 6 Property monitors
argument descriptions 22–24
H liquid fugacity coefficients 28
routines 17
Heat capacity
Multiple property methods 43
calculating 26
Heat of reaction 17
help desk 4 N
History file 15 Name conflicts 48

Index 65
Nonconventional solids 11 Property packages
Non–ideal mixtures 6 creating 8–10
example 60
O setting up 7
Property system
Open architecture 6 modifications 11
Overview 5 PT–Envelopes 10
Pure component phase monitors 18
P
Parameters Q
property 6 Qualifying application programs 12
values 33
PCES 6
R
Phase monitors 17
ideal gas 19 Reference states, thermodynamic
mixture 19 16
pure component 18 Report file 15
Phase properties 38 Reporting
Plex 33 component information 44
Predicting binary interactions 6 Reporting features 6
Preliminary runs 10 Reporting property methods 44
Problem data file Reports, sample 63
generating 7 Required property parameters 10
Procedures Retention feature 38, 40
link 46 Retrieving
run 46, 49, 62 universal property constants 33
Properties Retrieving number of components
analysis 10 42
calculating 17–28 Retrieving phase properties 38
constants, universal 32 Routines, monitor 17
estimating 6 Run commands 62
methods 6, 42 Run procedure example 62
parameters 10 Runs
phase 38 IDs 8, 49, See also Setting up
specifications 9, 42 property packages
Property Constant Estimation preliminary 10
System 6 procedures 46, 49, 62
Property methods 5, 42 types 10
multiple 43
reporting 44 S
Property Methods See Property
packages Sample application file 50
Property monitors 17 Setting up property packages 7, 60
diffusion coefficient 20 Setup Report Options form 10, See
enthalpy 20 also Reporting
equilibrium ratio (K-value) 19 Solids, nonconventional 11
fugacity coefficient 20 Source code example 51
molar volume 21 Specifying components, example
surface tension 21 60
thermal conductivity 21 Specifying global information 42
vapor pressure 22 State variables 17
viscosity 21 support, technical 4

66 Index
Surface tension property monitors
21

T
technical support 4
Terminal unit numbers 15, 16
Thermal conductivity property
monitors 21
Thermodynamic reference states
16
Types of runs 10

U
UNIFAC activity coefficient models
6
Unit numbers, file 15, 16
Universal property constants 32,
33

V
Values, parameters 33
Vapor pressure property monitors
22
Variables, state 17
Viscosity property monitors 21

W
web site, technical support 4
Work arrays 39

Index 67