Aspen OnLine™

User Guide
Version 12.1

OnLine Modeling Solutions

Part Number: Aspen Plus® 12.1
June 2003
Copyright (c) 1981-2003 by Aspen Technology, Inc. All rights reserved.

Aspen Plus, Aspen Online, Aspen Plus Online, Aspen Engineering Suite, Aspen Custom Modeler, Aspen Water,
Aspen Utilities, 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 manual 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.

Corporate
Aspen Technology, Inc.
Ten Canal Park
Cambridge, MA 02141-2201
USA
Phone: (1) (617) 949-1021
Toll Free: (1) (888) 996-7001
Fax: (1) (617) 949-1724
URL: http://www.aspentech.com

Division
Design, Simulation and Optimization Systems
Aspen Technology, Inc.
Ten Canal Park
Cambridge, MA 02141-2201
USA
Phone: (617) 949-1000
Fax: (617) 949-1030
Contents

About Aspen OnLine 1-1

Online Modeling ..............................................................................................................1-1
Types of Online Applications ..........................................................................................1-2
Real-Time Closed-Loop Optimization.................................................................1-3
Performance monitoring.......................................................................................1-3
What-if analyses...................................................................................................1-4
Aspen OnLine Operator Advisor .........................................................................1-4
Technical Support ............................................................................................................1-6
Online Technical Support Center.........................................................................1-6
Contacting Customer Support ..............................................................................1-6
Hours ....................................................................................................................1-6
Phone....................................................................................................................1-7
Fax........................................................................................................................1-8
E-mail ...................................................................................................................1-8

Concepts and Definitions 2-1

Projects .............................................................................................................................2-1
Tags ..................................................................................................................................2-1
Global Tags ..........................................................................................................2-1
Local Tags ............................................................................................................2-2
Plant or DCS Tags................................................................................................2-2
Internal Application Tags.....................................................................................2-2
Current Values Table ...........................................................................................2-5
Model Variables ...............................................................................................................2-6
X Files ..................................................................................................................2-6
External Components .......................................................................................................2-7
Aspen Plus............................................................................................................2-7
Hysys....................................................................................................................2-8
Aspen Custom Modeler........................................................................................2-8
DCS/IMS..............................................................................................................2-8
Cim-IO .................................................................................................................2-8
The Aspen OnLine Client/Server Architecture................................................................2-9
System Architecture .........................................................................................................2-9
Database Files ....................................................................................................2-10
The Aspen OnLine Server..................................................................................2-10

Aspen OnLine 12.1 User Guide Contents • iii

 The Aspen OnLine Client ..................................................................................2-15
Online Sequence.............................................................................................................2-16
Full Optimize Case.............................................................................................2-20
Generic Validity Check Functions .....................................................................2-20
Setpoint Implementation Module (Ramper) ......................................................2-22
Watchdog Program.........................................................................................................2-32
Data Validation ..............................................................................................................2-34
Validity Range....................................................................................................2-34
Clamping ............................................................................................................2-34
Replacement of Bad Data...................................................................................2-34
Steady-State Detection ...................................................................................................2-35
Heuristic Method................................................................................................2-37
Statistical Method...............................................................................................2-37

Online Project Development 3-1

Steps to Develop an Online Project..................................................................................3-1
Testing Cim-IO Access to Plant Data ..................................................................3-1
Verifying the Running of the Model ....................................................................3-3
Understanding the Model Variable Structure.......................................................3-4
Development of an Aspen OnLine Application...............................................................3-4
Creating a New Project ....................................................................................................3-5
Files Within a Project...........................................................................................3-5
Project Configuration .......................................................................................................3-7
Backing up Project Configuration Information....................................................3-8
Launching Client GUI and Connecting to Server ................................................3-8
Defining Engineering Units ...............................................................................3-11
Defining Tags.....................................................................................................3-11
Define Models ....................................................................................................3-17
Variable Attributes .............................................................................................3-21
Data Validation for Tags ....................................................................................3-23
Steady State Detection Specifications................................................................3-25
Manual Tag Specifications.................................................................................3-27
Formula Tag Specifications ...............................................................................3-27
Tag Initialization ................................................................................................3-28
Model Execution Scheduling .............................................................................3-29
Cim-IO Connection Form ..................................................................................3-30
Tag Average Specifications ...............................................................................3-32
Miscellaneous Specifications .............................................................................3-32
GUI Development ..........................................................................................................3-32
GUI Builder Features .........................................................................................3-33
Recommendations for features to incorporate in end-user GUI forms ..............3-38
Deleting an Aspen OnLine project.................................................................................3-39

Running Online Projects 4-1

Introduction to Running Online Projects .........................................................................4-1
Run Time Server and Client Functions ................................................................4-1

iv • Contents Aspen OnLine 12.1 User Guide

 What Programs Are Running and When..........................................................................4-2
Steady-State Detection Program ..........................................................................4-3
Engine Program....................................................................................................4-5
Connecting the Client GUI to the Engine ........................................................................4-5
Stopping Project Execution..............................................................................................4-6
Modes of Operation..........................................................................................................4-7
Test Mode versus Connect to Plant Data Mode...................................................4-7
Interactive versus Engine Watch..........................................................................4-7
Execution of Scheduled Calculations...................................................................4-8
Run-time Application Displays........................................................................................4-8
Run-time Logs and System Information ..........................................................................4-9
About Log Files....................................................................................................4-9
Event Log ...........................................................................................................4-10
Run Log..............................................................................................................4-11
Engine Log .........................................................................................................4-11
System Information ............................................................................................4-11
Cim-IO Logs ......................................................................................................4-11
Saving the Model Backup File .......................................................................................4-12

Advanced Features 5-1

Migration of Online Projects from Version 10.2 .............................................................5-1
Migration of Online Projects from Version 11.1 .............................................................5-1
Migration of Online Projects from Aspen Plus Online or RT-Exec ................................5-2
Backing Up Online Projects.............................................................................................5-3
Backing Up Project Configuration Only..............................................................5-3
Backing Up the Whole Project in Binary Format ................................................5-3
Backing Up the Whole Project in ASCII Format.................................................5-4
Managing Multiple Projects .............................................................................................5-6
Creating Projects ..................................................................................................5-6
Registering Projects..............................................................................................5-9
Renaming Projects..............................................................................................5-10
Project Password Protection...............................................................................5-10
Unregistering Projects ........................................................................................5-11
Deleting Projects ................................................................................................5-11
Case History System ......................................................................................................5-11
Database Reports............................................................................................................5-13
Command Journaling .....................................................................................................5-14
Differences Between Interactive Aspen Plus and Aspen OnLine......................5-16
Read/Write Suppress ......................................................................................................5-16
Using Grids on End-User GUI Forms............................................................................5-17
User-Defined Add-in Control Buttons ...........................................................................5-18
Features of the User Add-in Button DLL...........................................................5-19
Installing the User Add-in Button DLL .............................................................5-19

Troubleshooting 6-1
Database Locking.............................................................................................................6-1

Aspen OnLine 12.1 User Guide Contents • v

 Recovering from Abnormal Executions...........................................................................6-2
Setting Up Aspen Plus for Running Online Cases...........................................................6-3
Setting Up Hysys for Running Online Cases ...................................................................6-3
Starting and Stopping the Service Manually....................................................................6-3
Change Log ......................................................................................................................6-4
Changing Your Password for DCOM ..............................................................................6-5
Engine Fails to Load a Model ..........................................................................................6-5

Appendix A-1
Cim-IO Data Source Types ............................................................................................. A-1
Pre-defined Signal Tags .................................................................................................. A-1
Aspen OnLine Status Values........................................................................................... A-4
Steady-State Detection Algorithms................................................................................. A-5
Heuristic Method................................................................................................. A-5
Statistical Method................................................................................................ A-7
Run-Time Messages........................................................................................................ A-8
Normal Execution ............................................................................................... A-8
Abnormal Execution ........................................................................................... A-9
Hints and Recommendations......................................................................................... A-10
Plant Data .......................................................................................................... A-10
Process models .................................................................................................. A-11
Project execution ............................................................................................... A-12

Glossary of Terms G-1

vi • Contents Aspen OnLine 12.1 User Guide

 CHAPTER 1

About Aspen OnLine

Aspen OnLine allows automation of the transfer of validated plant

data to rigorous process models, removing the need for engineers
to perform the laborious and repetitive task. It is also closely
integrated with DMCPlus. Aspen OnLine provides all the essential
capabilities for communicating with any running DMCPlus
controllers. It has been used in many real-time closed-loop
optimization (CLRTO) projects around the world. Besides the
CLRTO application, Aspen OnLine has also been used in
inferential property calculation, performance monitoring, and
open-loop optimization applications. It is the platform for driving
various model types in the AES suite of modeling tools. Aspen
OnLine can drive Aspen Plus, ACM (Aspen Custom Modeler) and
HYSYS models. It is the enabling technology that provides the
means for deploying rigorous process models in plant operations.

Online Modeling
The design and process engineering work of a plant involves
extensive process knowledge and know-how. Much of this
knowledge is captured in rigorous process models developed
during the design phase of a project. These models have
traditionally been very effectively utilized in exploring various
plant designs or plant modifications, and in troubleshooting serious
plant design issues encountered during plant operations. However,
the fundamental knowledge of the process encapsulated within
these models has only been utilized sparingly in day-to-day plant
operations.
The collection of plant data, the analysis and validation of the
collected plant data, and the transfer of validated plant data into the
model have typically been performed manually only if use of the
process model is desired. This is obviously a very time consuming
step. It is also the step where many mistakes can be made. A small

Aspen OnLine 12.1 User Guide About Aspen OnLine • 1-1

 mistake in this step can easily invalidate the whole engineering
analysis. This can further prolong the process of utilizing the
rigorous process model. If all the above described steps are done
successfully, an engineer still faces the challenge of how to present
the results to plant supervisors or operators. As a result, the
utilization of a rigorous plant process model in plant operations is
very infrequent.
Online modeling involves the automation of plant data collection,
validation, and transfer of validated plant data to the process
model. At the end of the model calculation, results are
communicated back to plant databases, or report files are generated
and archived automatically. All these steps are performed
automatically on a continuous basis, 24 hours a day. Hence, a
complete plant heat-and-material balance is available at various
plant operating conditions and production rates. This information
can be very useful in engineering analysis related to plant
operations or process design.
In the case of real-time closed-loop optimization, after a model is
parameterized to match current plant operating conditions, an
optimization run is executed. At the end of the optimization run,
optimized plant operating conditions are downloaded to multi-
variable controllers (DMCPlus). This then allows the controllers to
move the plant toward the optimized plant operating conditions.
The complete cycle, from collecting plant data to sending
optimized plant operating targets, is done automatically 24 hours a
day. The closed-loop optimizer continuously calculates new plant
setpoints as plant conditions change. Essentially, the optimizer is
monitoring all process areas that are in the scope of the optimizer,
and it tries to keep the plant in the optimum plant conditions based
on the process economics provided.

Types of Online Applications

Online models can be used in plant operations in a variety of
applications, ranging from simple estimation of properties, such as
viscosity, to complex applications, such as plant-wide real-time
closed-loop, optimization, depending on the objective of the
application. Aspen OnLine version 12.1 supports steady-state
applications developed using Aspen Plus, Hysys, and Aspen
Custom Modeler. It also supports real-time closed-loop
optimization using equation-oriented models in Aspen Plus.
Although one can write a dynamic model using Aspen Custom
Modeler, Aspen OnLine does not currently support dynamic model
applications.

1-2 • About Aspen OnLine Aspen OnLine 12.1 User Guide

 Online modeling applications typically include calculations based
on one or more of the following scenarios:
• Real-time closed-loop optimization
• Performance monitoring
• What-if analyses
• Aspen OnLine Operator Advisor
Real-Time Closed- Rigorous process models of the plant are used to optimize plant
Loop Optimization operating conditions. The typical scope of such an application
covers the full plant starting from the raw feed to final products.
The optimizer monitors the plant 24 hours a day and optimized
setpoints are communicated to multi-variable controllers
(DMCPlus). Many successful applications have been
commissioned worldwide in the petrochemical, chemical and
refining industries. Besides delivering online benefit, the optimizer
also provides valuable information about the process such as
unmeasured stream compositions or properties, performance of
various pieces of equipment and other offline benefits. Many sets
of heat and material balance of the full plant are available for
engineering analysis offline.
Performance Equipment performance monitoring: Frequently there is
monitoring equipment performance information that would be quite useful to
operators and plant engineers. Unfortunately, a majority of the
information cannot be measured or is too difficult to measure.
Examples of such information are the current efficiency of trays,
tray loadings, composition profiles in a tower, or other tower
internals; the level of fouling in a heat exchanger; the current
activity of a catalyst; and temperature and conversion profiles in a
reactor. These data and other equipment-related information can be
determined by using an appropriate model and actual operating
plant data.
Stream property performance monitoring: Often a property is
needed as a final or intermediate product specification and yet it
cannot be easily or timely measured at the plant. Virtually every
property that requires a sample to be taken to a laboratory is a
candidate for stream property performance monitoring if a process
model is available to predict the property reliably. The use of a
suitable property model or a rigorous process model and other
more readily measurable data can provide the desired property
online while the material is still being processed. The calculated
model results can provide operators information ahead of
laboratory report. This then gives the operators more frequent
information about the performance of certain equipment or process
areas. If changes are necessary in order to meet some product

Aspen OnLine 12.1 User Guide About Aspen OnLine • 1-3

 specifications, the operators will have some extra time to make the
desired adjustments.
Economic based performance monitoring: Performance
monitoring can also be extended to economic quantities. Operators
are routinely inundated with technical information from the plant
or process they are supposed to control, but are given very little
information on the economic impact of their actions. For example,
a model of a finishing distillation column could be used to predict
the economic impact of changing the targeted separation in an
upstream product separation column.
What-if analyses These applications allow operators to confirm the technical
feasibility and economic impact of an operating change before
implementing it. These analyses can also be used to identify the
implications of a process change, a product change, or a feedstock
change. What-if analyses can also be used as a component of
operator training by helping operators to better understand the
process by observing the responses of different variables to
changes in control variables from a steady-state perspective.
Aspen OnLine Aspen OnLine Operator Advisor enables operators to make better-
Operator Advisor informed decisions and thus improve plant operations. They can
include one or more of the applications listed above. For example,
an Operator Advisor could provide a comparison of actual plant
and model predicted operations, both in technical and economic
terms; thus indicating the potential for economic improvement as
well as providing advice on how to achieve it. The same Operator
Advisor could also incorporate what-if analysis and equipment
performance monitoring.
A typical Aspen OnLine Operator Advisor is linked to three types
of models: Calibration, Inferential, and Prediction.
Calibration model: A calibration model uses measured plant
inputs and outputs to determine one or more parameters required to
characterize current operation. For example, a calibration model
could be used to determine a heat exchanger’s fouling factor from
the measured input and output temperatures and flow rates.
Parameters obtained from a calibration model are normally stored
in the plant information management system (such as IP.21). A
calibration model is normally scheduled to run automatically
(perhaps once per shift).
Inferential model: An inferential model uses the parameters
determined by calibration to predict current plant performance
based on current plant measured inputs. The fidelity of the model
can be demonstrated by comparing current measured plant outputs
and inferential model outputs. Model results from an inferential
run are normally stored in the plant information management

1-4 • About Aspen OnLine Aspen OnLine 12.1 User Guide

 system. An inferential model is normally scheduled to run
automatically, at a frequency greater than the calibration model
(perhaps once per hour). It is also possible to save all of the
inferential model files (initialized with then-current plant data) for
offline troubleshooting outside of the Aspen OnLine application.
Prediction model: The prediction model is designed to simulate a
single what-if scenario. The prediction model uses the parameters
determined by calibration and operator inputs to predict how the
plant would operate under different conditions (different feedstock,
different control set points, etc.). Typically, there are many
possible operator inputs, but only one or two need changing. The
operator inputs for a prediction model are normally set to default to
current plant operating conditions. Because the results from a
prediction model do not necessarily correspond to any time period
of actual plant operation, prediction model results are not stored in
the plant information management system. A prediction model
only runs when an operator initiates model execution.

Aspen OnLine 12.1 User Guide About Aspen OnLine • 1-5

 Technical Support
Online Technical AspenTech customers with a valid license and software
Support Center maintenance agreement can register to access the Online Technical
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
• Search for and review known limitations
• Send suggestions
Registered users can also subscribe to our Technical Support
e-Bulletins. These e-Bulletins are used to proactively alert users to
important technical support information such as:
• Technical advisories
• Product updates
• Service Pack announcements
• Product release announcements
Contacting Customer Customer support is also available by phone, fax, and email for
Support customers with a current support contract for this product. For the
most up-to-date phone listings, please see the Online Technical
Support Center at http://support.aspentech.com.
Hours
Support Centers Operating Hours (Monday-Friday)
North America 8:00 – 20:00 Eastern Time
South America 9:00 – 17:00 Local time
Europe 8:30 – 18:00 Central European time
Asia and Pacific Region 9:00 – 17:30 Local time

1-6 • About Aspen OnLine Aspen OnLine 12.1 User Guide

 Phone Support Phone Numbers
Centers
North 1-888-996-7100 Toll-free from U.S., Canada, Mexico
America 1-281-584-4357 North America Support Center
(52) (55) 5536-2809 Mexico Support Center
South (54) (11) 4361-7220 Argentina Support Center
America (55) (11) 5012-0321 Brazil Support Center
(0800) 333-0125 Toll-free to U.S. from Argentina
(000) (814) 550-4084 Toll-free to U.S. from Brazil
(0800) 100-2410 Toll-free to U.S. from Venezuela
Europe and (32) (2) 701-95-55 European Support Center
Africa Country specific toll-free numbers:
Austria (0800) 111-900
Belgium (0800) 40-687
Denmark 8088-3652
Finland (0) (800) 1-19127
France (0805) 11-0054
Germany (0800) 101-0068
Ireland (1) (800) 930-024
Italy (800) 905-826
Netherlands (0800) 023-2511
Norway (800) 13817
South Africa (0800) 996-852
Spain (900) 951846
Sweden (0200) 895-284
Switzerland (0800) 111-470
UK (0800) 376-7903
Asia and (65) 6395-39-00 Singapore
Pacific (81) (3) 3262-1743 Tokyo
Region

Aspen OnLine 12.1 User Guide About Aspen OnLine • 1-7

 Fax Support Fax Numbers
Centers
North 1-281-504-3999
America
South (54) (11) 4361-7220 (Argentina)
America (55) (11) 5012-4442 (Brazil)
Europe (32) (2) 701-94-45
Asia and (65) 6395-39-50 (Singapore)
Pacific (81) (3) 3262-1744 (Tokyo)
Region

E-mail Support Centers E-mail

North America [email protected] (Engineering Suite)
[email protected] (Hyprotech products)
[email protected] (Aspen ICARUS products)
[email protected] (Aspen MIMI products)
[email protected] (Aspen PIMS products)
[email protected] (Aspen Retail products)
[email protected] (Advanced Control products)
[email protected] (Manufacturing Suite)
[email protected] (Mexico)
South America [email protected]
[email protected] (Argentina)
Europe [email protected] (Engineering Suite)
[email protected] (Hyprotech products)
[email protected] (CIMVIEW products)
[email protected] (Metals products)
[email protected] (All other suites)
Asia and Pacific [email protected] (Singapore: Engineering Suite)
Region [email protected] (Hyprotech products)
[email protected] (Singapore: Aspen MIMI)
[email protected] (Singapore: Aspen
Retail)
[email protected] (Singapore: All other suites)
[email protected] (Tokyo: Engineering Suite)
[email protected] (Tokyo: All other suites)

1-8 • About Aspen OnLine Aspen OnLine 12.1 User Guide

 CHAPTER 2

Concepts and Definitions

Projects
Aspen OnLine is capable of handling multiple process models on
the same server. These models are called projects.
Each Aspen OnLine project may contain multiple sequential-
modular Aspen Plus models, Hysys models, and Aspen Custom
Modeler models. When using Aspen Plus equation-oriented (EO)
models, only one EO model and no other models can be configured
in the project.

Tags
In the Aspen OnLine context, a tag is an identifiable and accessible
collection of information. These collections hold:
• Information originating from the plant,
• Information being sent to the model and being returned from
the model, and
• Information entered by the user and being presented to the
user.
Tags are used to hold, manipulate, and display all data in Aspen
OnLine.
Aspen OnLine tags can be categorized as Global or Local Tags,
depending on their accessibility, and as Plant (DCS) or Internal
Application Tags, depending on their source and use.
Global Tags Global tags are those that possess an attribute that is common to all
users or clients. A plant tag is a global tag since it presents the
same value to all users at any one time. A manual input tag is static

Aspen OnLine 12.1 User Guide Concepts and Definitions • 2-1

 at run-time and thus is also a global tag. Average tags and steady-
state detection tags are also global tags.
Local Tags A local tag is used to hold or display information specific to a
given user or client.
For example, the tag F-302-WI for a flow into a tower used in a
What-If analysis would be a local tag. Client A may want to see
the impact of a 10,000 lb/hr flow while client B may be interested
in seeing the impact of a 20,000 lb/hr flow. Local tags would also
be used for all model outputs associated with What-If analysis.
Plant or DCS Tags Plant tags are tags that:
• Actually reside in the plant information management system
(IMS) or the distributed control system (DCS), and
• Provide plant data as input to the Aspen OnLine application or
receive data from Aspen OnLine.
The tag name used in Aspen OnLine is the same as the tag name in
the DCS or IMS. When connected to these tags, Aspen OnLine
retrieves the values and attributes associated with these tags. They
are global tags and are referred to as DCS tags in the Aspen
OnLine configuration system.
A typical plant tag would be:
F-101 Reactor feed flow rate
Most plant tags are used as input into Aspen OnLine. However,
there are plant tags that receive new values from Aspen OnLine.
These are typical in real-time closed-loop optimization
applications. New setpoints are sent to the controller at the end of
the optimization run. In addition, some signal values are sent to the
DCS as well, to provide information to the operators.
Internal Application Internal application tags are tags that:
Tags • Allow entry of input data other than Plant DCS/IMS tags (such
as what-if analysis inputs), or
• Provide the means to display model-calculated results, or
• Provide the means for further data manipulation or calculations
within Aspen OnLine.
The value of any internal application tag can be sent back to an
information management system (IMS) for further data analysis
and trending. A tag needs to be created for these purposes in the
IMS. The tag name used in Aspen OnLine and in the IMS must be
the same.
Internal Application tags include static user input tags (Manual
tags), Formula tags, Average tags, Local GUI tags, steady-state
detection tags (or SSD tags) and Signal tags.

2-2 • Concepts and Definitions Aspen OnLine 12.1 User Guide

 Manual tags, SSD tags, Average tags and Signal tags are global
tags. Formula tags and Local GUI tags are local tags.
Manual Tags Manual tags are used to enter values that are essentially static and
do not change very often. They may be used, for example, to hold
a product spec or unit cost of a utility that does not need to be
updated regularly. The values for these tags are entered or
modified on the Aspen OnLine Client GUI | Data Browser | Tags
| Grid View | Manual Input sheet.
A typical Manual tag would be CO2-SPEC, which would contain
the value for the maximum amount of CO2 allowed in pipeline
gas.
Manual tags are global tags and provide the same information to
all users.
Formula Tags Aspen OnLine can be used to create mathematical functions of tag
values and then compute these function values. Any function that
is supported by Microsoft Excel can be used. The value computed
by the function is stored in a Formula Tag.
As an example of the use of formula tags, one may want to use a
column efficiency of 75% for feed flows above 10,000 lbs/hr and
60% otherwise. The feed flow is provided by DCS tag F-101, and
the efficiency value would be stored in formula tag EFF-101. The
formula expression for EFF-101 would be:
If ([F-101]>10000, 0.75, 0.60)
Note that this is the same syntax as that used by Microsoft Excel
formulas, with Excel cell names replaced with tag names within
square brackets. Users must be careful to ensure that each of the
term in the equation is consistent in units of measure. Aspen
OnLine does not perform a units-of-measure consistency check in
an equation within formula tags.
Local GUI I/O Tags The Local GUI I/O tags are designed to allow the user to input data
at run time through the GUI, and to display model calculation
results. Such input/output information is specific to each user or
Aspen OnLine client, and as such, these tags are local tags.
Consider, for example, a distillation application where one wishes
to see the impact of a purity specification change on reflux rate and
condenser duty, given the current feed rate, inlet composition and
other existing operational conditions of the tower remain the same.
A GUI I/O tag COL-SPEC could be used to enter varying values of
the purity specification at run-time. GUI I/O tags E-303-Calc and
T-103-RR-Calc could be used to display the calculated condenser
duty and reflux rate. As their name implies, the Local GUI I/O
Tags are local tags, since each Aspen OnLine client would have

Aspen OnLine 12.1 User Guide Concepts and Definitions • 2-3

 the ability to use and to be presented different values for these tags.
In the above example, each Aspen OnLine client could enter
different product specification values and see correspondingly
different duties and reflux rates.
Average Tags An average tag is used to calculate and hold the time average value
of a given plant (DCS) tag, over a user-specified time period.
While many IMS's and DCS's are capable of providing average
values, they are typically very inflexible. For instance, it is not
possible to specify different average windows for different tags.
As an example, one may wish to use the average concentration of
component B over the past 6 hours to make some operational
recommendation. Assuming the analyzer plant tag for component
B is A-302-B, one could create an average tag A-302-B-Avg with
a user-configurable averaging period of 6 hours to hold the desired
averaged value of component B.
Average tags are global tags that provide the same information to
all users.
SSD Tags An SSD tag is used to store steady-state detection results of
another tag. They can either store the averaged values or the status
of the averaged tag. SSD tags are global tags and provide the same
information to all users.
Signal Tags Signal tags are used to hold project-specific run-time information.
Signal tags are global tags and provide the same information to all
users. Signal tag values are shown to the end-users on the Aspen
OnLine Client GUI | Control Panel | Tags sheet or sent to the
DCS or plant database to display the current status of the online
application.
Many signal tags are pre-defined in Aspen OnLine. Users can view
the list of these tags or define additional signal tags on the Setup |
Specifications | Signals sheet to replace the default signal tag
chosen when the project is created initially. For example, the value
of Signal tag RUNMODE indicates whether the Aspen OnLine
project is connected to IMD or is running with test mode. This
information is also displayed in the status bar of the Aspen OnLine
Client GUI main window.
Signal Value Types The current values of signal tags are always represented by
numeric values. The values should be interpreted according to the
value type for their signals. In many cases, when signals are sent to
the DCS/IMS, it may be desirable to translate the numeric value
into a more meaningful text string that can be displayed on the
DCS/IMS. The following value types are used:

2-4 • Concepts and Definitions Aspen OnLine 12.1 User Guide

 Value Type Description
Counter An integer number used as a counter. Counters are
used for watchdog-reset values and statistics that
count certain events.
Date A floating-point number in the format of
MONTH.DAY. For example, 10.31 represents
October 31.
Digital An integer number that may have a value of 0 or 1.
Digital tags are used as switches to control the online
system and indicators.
Elapsed A floating-point number containing the elapsed time,
in minutes, for an event.
Float A floating point number.
Status An integer number that indicates the current status of
the online system. Used only for the Aspen OnLine
Status signal.
Time A floating-point number in the format of
HOUR.MINUTE. For example, 13.55 represents
1:55 PM.
Current Values Table The current values table is an area of shared memory containing
the last values for all tags, both DCS and local, in the tag database.
Aspen OnLine programs use the current values table as a common
place to access tag values via the following mechanisms:
• DCS/IMS values defined as inputs to programs such as
averaging and steady-state detection are read from the
DCS/IMS into the current values table. Only online programs
such as steady-state detection can load DCS/IMS values into
the current values table.
• DCS/IMS values set by Aspen OnLine (such as calculated
targets) are first loaded into the current values table. These
values are then written to the DCS/IMS by the ramper module.
• The values of signal tags are changed when you change
parameters in the GUI that control the online system. These
parameters are stored as local tags in the current values table.
• Any tag's value can be manually changed via the GUI.
Values stored in the current values table can be either of two types:
• Single-precision floating point numbers
• Character strings of up to 79 characters in length
The GUI can display the latest value for any tag from the current
values table.
The steady-state program periodically saves values in this table to
the disk. Each time the interface computer is restarted, it loads the
saved values into the table.

Aspen OnLine 12.1 User Guide Concepts and Definitions • 2-5

 Model Variables
Model variables, in the Aspen OnLine context, are those variables
in a model that can receive their input values from Aspen OnLine
tags, and those that can provide output values to Aspen OnLine
tags. X Variables, in general, are all variables in the Aspen Plus,
Hysys, or ACM models.
Aspen Plus provides a Variable Explorer in its user interface to
display all variables in a model. This same capability is provided in
Aspen OnLine. Thus, at configuration time, you can browse
through the Aspen Plus model variables and select a variable of
interest. In an adjacent window, the Aspen OnLine tag that
contains its input value or receives its result value can be dragged
and dropped onto the model variable, thereby linking the tag and
model variable. One can also use a user-defined delimiter file to
define the connection between model variables and tags.
Aspen OnLine also generates and presents variable trees for Hysys
and ACM-based models. Model variables from these applications
can be linked to tags in the same manner as Aspen Plus model
variables are.
X Files The Save Variables command in the Aspen Plus equation-oriented
environment saves the current values of X Variables to a file,
called an X file. Aspen OnLine automatically saves an X file after
certain phases in an online cycle. These files serve as a record of
any changes made to the plant X variables by Aspen OnLine. For
more information, see Online Sequence.
Each X file contains the following variable attributes:
Attribute Description
NAME Variable name
VALUE Current value
LOWER Lower bound
UPPER Upper bound
STEP Step bound
SPEC Specification
UNITS Units of measure
The following real-time data files can be generated or used by the
online system. They are stored in the plant_ONL directory, where
plant is the name of the current plant .
File Description
base.x Initial values for all variables
case_dcs.x Results of the data fetch with current values from the
DCS/IMS.

2-6 • Concepts and Definitions Aspen OnLine 12.1 User Guide

 File Description
case_vc.x Results after the generic validity check for the case.
case_pre.x Results of any pre-solve scripts before calling the
solver.
case_res.x Results of a case run by the Aspen Plus equation-
oriented kernel.
In the above file names, case represents the type of the current
case:
Value of case Description
REC Data reconciliation with degrees of freedom
PAR Parameter estimation (data reconciliation) with no
degrees of freedom
OPT Optimization with degrees of freedom
SIM Optimization with no degrees of freedom
FULL_OPT A rerun of the optimize case with all loops on control
and optimization
The final result of a successful optimization run will be a new set
of some or all of the above files, depending on configuration. The
creation of some of the files may be turned off through the Data
Browser | Models | A+ Optimizer sheet. If the optimize or full
case is not being run, files associated with these cases will not be
generated.

External Components
Aspen OnLine communicates with other programs to perform all
the necessary tasks in a typical online application. These programs
can include:
• Aspen Plus
• Hysys
• Aspen Custom Modeler
• Aspen Utilties and Aspen Water
• DCS/IMS
• Cim-IO
Aspen Plus Aspen Plus is Aspen Technology’s steady-state modeling software.
It combines the sequential-modular and equation-oriented
paradigms seamlessly together. It is the preferred tool for many
closed-loop optimization projects. Many successful optimization
applications have been commissioned with Aspen Plus. It is the
standard modeling tool in many engineering and operating

Aspen OnLine 12.1 User Guide Concepts and Definitions • 2-7

 companies. Aspen Plus version 12.1 brings the full power of Aspen
Plus to the Windows 2000 and Windows XP environments.
Hysys Hysys is another steady-state modeling software from Aspen
Technology (formerly from Hyprotech). Hysys models can be
brought online using Aspen OnLine. Hysys has generally been
used in refining and upstream areas.
Aspen Custom Aspen Custom Modeler is Aspen Technology’s tool for developing
Modeler and deploying custom models. Aspen OnLine can take Aspen
Custom Modeler steady-state models and deploy them online.
Currently, Aspen OnLine does not support Aspen Custom Modeler
dynamic models.
DCS/IMS Distributed Control Systems (DCSs) utilize multiple
microprocessors for controlling industrial processes. These
microprocessors are usually linked to a central computer that
records all of the process variable and control information.
Further processing, analysis, display, and archiving of process data
are typically done by a plant information management system or
IMS for short.
Aspen OnLine can communicate directly with the DCS or plant
database, such as Aspen Technology’s IMS product InfoPlus.21™
(IP.21), using Aspen Technology’s Cim-IO interface. In addition
to simply communicating, Aspen OnLine has been integrated with
IP.21 to take full advantage of additional capabilities provided by
IP.21, such as automating plant tag entry via the Tag Browser of
Process Explorer™, the IP.21 visualization software, and access to
graphical plant trend data. These functionalities are particularly
useful for a remote Aspen OnLine client while adding new tags in
a project.
Cim-IO Aspen Technology’s Cim-IO™ is a general purpose interface
software system that allows communications with a wide variety of
DCSs, plant Information Management Systems, and plant devices
such as PLCs.
Cim-IO has a client/server architecture. A Cim-IO client issues
requests to read data from or write data to a Cim-IO server. Both
client and server components incorporate a Cim-IO Kernel that
contains the functions that both clients and servers use for
communication. The Cim-IO Kernel is independent of any Cim-IO
client or server.
The Cim-IO Kernel relies on TCP/IP to provide reliable,
transparent communications between a Cim-IO client and a Cim-
IO server.

2-8 • Concepts and Definitions Aspen OnLine 12.1 User Guide

 Aspen OnLine has an embedded Cim-IO client. It can
transparently communicate with any of the roughly 100 device-
specific Cim-IO servers available today.

The Aspen OnLine Client/Server

Architecture
In a network of computers, the server provides services to all of the
client computers. In many cases the server is simply a repository of
a large amount of data that must be shared among a number of
clients. In some cases the server also provides computational
services. The client issues a request for information or services
provided by the server.

System Architecture
This diagram illustrates the layers that make up an Aspen OnLine
system:

Computation Layer Aspen Plus or

Aspen Custom Modeler
Interface Routines

Aspen OnLine Aspen OnLine Modules Database

Layer
Connect/ Cim-IO

DCS/IMS Layer DCS/IMS

The computation layer consists of the Aspen Plus, Hysys, Aspen

Custom Modeler (ACM), or Aspen Utilities models that perform
the actual process model calculations for the online plant model.
Aspen OnLine communicates with this layer via a set of high-level
interface routines.
The Aspen OnLine layer consists of Aspen OnLine modules, the
database, and the Cim-IO access routines. Aspen OnLine modules
use information from the database to control data transfer between
the computation and DCS/IMS layers. The Cim-IO routines
perform the low-level data transfer between the DCS/IMS and the

Aspen OnLine 12.1 User Guide Concepts and Definitions • 2-9

 interface programs. Each DCS/IMS type requires a different Cim-
IO server.
The DCS/IMS layer is normally a distributed control system where
optimization targets are sent. It may also be software running on
the same computer that acts as middleware through which targets
are communicated to a regulatory control system.
Database Files The primary database for each plant consists of two binary files,
the TAG file and the XDB file. These files can only be viewed or
changed within Aspen OnLine.
The TAG file contains all data directly related to DCS/IMS
variables. It contains a record for each DCS tag referred to by the
optimization system. This record is used to connect DCS tags to
model variables.
The TAG file also contains data for local tags that do not refer to
any DCS/IMS. Current values for local tags are maintained in the
current values table; otherwise, these tags are treated the same as
DCS tags. The TAG file also stores configuration data for the
steady-state detection program.
The XDB file contains a record for each X variable in the plant
model that is accessible by Aspen OnLine. These variables are
commonly called linked variables when they are linked to tags.
They may be referred to as being linked to a DCS tag for input or
output. Aspen OnLine uses these links to transfer data between the
DCS/IMS and X variables for process model calculations.
Note that the XDB file contains no references to the DCS/IMS
database. Links in the XDB file refer only to records in the TAG
file. The TAG file can be thought of as the interface between the
model's variables and the process database.
When transferring data between X variables and the DCS/IMS,
Aspen OnLine first reads the XDB file to determine which X
variables require data from the DCS/IMS database. Then it reads
the linked records in the TAG file. Finally, it reads and writes data
to the DCS/IMS database.
The Aspen OnLine Aspen OnLine server is the engine and the executive of the online
Server application as well as the repository of the application data and
configuration information.
Aspen OnLine server connects the plant data server (either a DCS
or an IMS), from which it retrieves process data, to the Aspen
OnLine client computers, which it serves.
Server Components The server components include:
• The Aspen OnLine 12.1 service module for automatically
starting a DCOM module

2-10 • Concepts and Definitions Aspen OnLine 12.1 User Guide

 • The Aspen OnLine DCOM module for starting Aspen OnLine
projects automatically as specified by the user
• The Aspen OnLine project management module for project
maintenance such as project creation and deletion
• One data service module for each project for fetching data from
IMS, steady-state detection, sending data to IMS, and data
repository functions
• One engine module for each running project for fetching data
from IMS, executing models, sending data to IMS, and serving
data for clients.
• One configuration module for each project on the server
machine that has one or more clients connected to it. This
module is activated by the Aspen OnLine Client GUI. This
module is terminated automatically when all Aspen OnLine
Client GUIs connecting to it have been closed.
Note that each running project uses certain resources on the server
computer. Therefore, you may want to limit the number of running
projects on any given computer based on the computing resources
available. Be sure to consider this when setting projects to start up
automatically.
In addition, the Aspen OnLine server makes use of:
• A Cim-IO client, for communications with the plant data Cim-
IO server
• The Aspen Plus COM object for communications with Aspen
Plus, if Aspen Plus is installed and used in Aspen OnLine
projects
• Automation servers of Hysys and ACM-based applications, if
they are installed and used by Aspen OnLine projects
Note that Aspen OnLine requires the presence of an Aspen OnLine
client on the same computer on which the Aspen OnLine server
resides.
The Engine module consists of several programs:
• The optimization program performs case-specific calculations
by invoking the Aspen Plus solver. It also controls the process
I/O and validation module and the setpoint implementation
(ramper) module.
• The steady-state detection and averaging program continually
monitors the plant to determine whether it is at steady state.
The optimize steady-state check determines if the plant is
steady enough to attempt an optimization cycle. The ramp
steady-state check determines if the plant is steady enough to
implement new optimization targets at the end of optimization

Aspen OnLine 12.1 User Guide Concepts and Definitions • 2-11

 calculation. This program also calculates running averages that
are used as inputs for the parameter case.
• The watchdog program monitors the steady-state program and
the optimization program. If it detects a problem with either
program, it sets the Aspen OnLine Status signal to a value as a
notification that a problem has occurred. If the Restart on
Failure signal is set to 1, the watchdog program will
automatically restart the optimization program when a failure
occurs. It always restarts the steady-state program when it fails.

2-12 • Concepts and Definitions Aspen OnLine 12.1 User Guide

 This diagram illustrates the interaction between these programs:

Watchdog

Steady-State Detection
DCS and Averaging

and

Current
Aspen OnLine Control Logic
Values

Table
Setpoint Custom Validity
Implementation Checks

Process I/O and Aspen Plus Solver

Validation

Disk-Resident Database, Scripts and X Files

Symbol Legend

Process Local Values Program/Module

Signal Information Data Source or Destination

Program Control Communication

Disk file I/O

The steady-state program is independent of the optimization

program. It is continually calculating averages and monitoring the
plant for steady-state condition even when the optimizer is not
running. The averages are stored in the current values table and can
be read at any time by the optimization program. The only

Aspen OnLine 12.1 User Guide Concepts and Definitions • 2-13

 communication between these two programs is through the steady-
state signal.
The optimization program controls the actions of the setpoint
ramper, process I/O, and the Aspen Plus equation-oriented kernel.
The watchdog program monitors the health of the steady-state and
process model computation engine programs.
There is no independent DCS/IMS scan program that loads data
from the DCS/IMS. Each program performs its own DCS/IMS
reads and writes through the Connect/Cim-IO server provided for
that DCS/IMS.
Server Functionality The first Aspen OnLine component to start is the Aspen OnLine
12.1 service. The Aspen OnLine installation sets this service to
start automatically after the server machine is rebooted. It performs
two tasks:
• It checks for an Aspen OnLine license.
• If an Aspen OnLine license is available, it starts DCOM.
If the service fails to obtain an Aspen OnLine license, DCOM will
not be started. In such a case, you should examine
ApoSettings.mdb in the Aspen OnLine system directory using
Microsoft Access. The ApoSysLog table in this database logs the
Aspen OnLine 12.1 service process. Please make sure that you do
not modify this database and do not view any table in this database
using design view. Doing so may cause Aspen OnLine programs to
behave incorrectly. If Microsoft Access is not installed on the
server machine, you can copy ApoSettings.mdb to a machine that
has Microsoft Access installed. Alternatively, you can contact
AspenTech Support and send ApoSettings.mdb to AspenTech
personnel for help.
When DCOM is started by the Aspen OnLine 12.1 service, it will
examine all registered Aspen OnLine projects and start projects
that have been configured to be started automatically. Aspen
OnLine project registration and automatic startup will be discussed
later.
Aspen OnLine Project Manager is a GUI interface for project
management. After you specify a server machine, it will connect to
the DCOM component on that server machine and start
communications with the DCOM component. A dialog box will
appear if it fails to connect to the DCOM on the server machine. In
such a case, click the Help button on this dialog box to view a list
of possible reasons for the connection failure.
Note: Aspen OnLine Project Manager is a component of the Aspen
OnLine server. You can only run it from a computer where the
server is installed. You can use Aspen OnLine Project Manager to

2-14 • Concepts and Definitions Aspen OnLine 12.1 User Guide

 connect to a different Aspen OnLine server machine, but you can
only create or register projects when connecting to the server on
the same computer.
The data server module is a project-specific module. This module
performs steady-state detection, tag averaging, tag trending, and
tag value storage for a specific project. It is also responsible for
communicating with IMS via Cim-IO for relevant tags. More
specifically, it is responsible for fetching data from IMS for any
DCS tag for which steady-state detection is performed, average
value is calculated, or tag value is trended. It is also responsible for
sending values to IMS for SSD tags, Average tags and Signal tags
which are configured to be sent to IMS. It also stores the global set
of values and qualities for all tags in the project.
The engine module is also a project-specific module. Its main task
is to drive model executions for all models in the project according
to schedules specified by the user. It also communicates with IMS
via Cim-IO for fetching values for any DCS tag which is not
averaged or trended and for which steady-state detection is not
performed. It is also responsible for sending values to IMS for
Local tags, Formula tags and Manual tags.
The configuration module is yet another project-specific module. It
serves the Aspen OnLine Client GUI for any configuration needs.
The first client of a project starts this module, and when the last
client for the project terminates, the configuration module
terminates. This is the middle tier between the Client GUI and the
configuration database.
The Aspen OnLine The Aspen OnLine Client GUI is the client component for the
Client project-specific presentation and user interaction layer of Aspen
OnLine for both project configuration and project execution.
Multiple clients are supported. Clients can be located remotely as
well as in control rooms and plant engineering offices. The ability
to use remote clients makes it easier to view model results and
monitor online applications. This also provides easy access for
running online models to various groups of people.
The Aspen OnLine client consists of only one component, the
Aspen OnLine Client GUI.
Client Functionality Aspen OnLine Client GUI is used for both project configuration
and project execution. The Control Panel in the Client GUI is
opened by default as the Client GUI is launched. All GUI elements
within the Control Panel are used for project execution or run-time.
Only one Control Panel window can be opened for each Client
GUI instance.

Aspen OnLine 12.1 User Guide Concepts and Definitions • 2-15

 Use the Data Browser for project configuration. Multiple Data
Browsers can be opened in each Client GUI instance.

Online Sequence
The online sequence consists of a series of phases. These phases
occur in a specific order as defined in the optimization program.
Normally a phase will consist of reading data from some source
such as the DCS/IMS, performing operations on the data, and
storing the results for the next phase.
The following diagram illustrates the normal path the online
system follows as it goes through various phases in the complete
cycle. It includes actions taken by the optimizer, process I/O and
validation module, and the setpoint ramper module. For complete
details of the ramper module, see Setpoint Implementation Module
(Ramper).
Because neither the steady-state program nor the watchdog is
directly involved in the sequence, they are not included in this
diagram. Also not included in the diagram are the success/error
checks that are made at the end of each phase. If a fatal error is
detected, the optimization program will stop. The watchdog
program may restart it if it is configured to do so. If a non-fatal
error is detected, the optimizer will return to waiting for steady
state status.

2-16 • Concepts and Definitions Aspen OnLine 12.1 User Guide

 Start up initialization
Next Wait short period
cycle

No
Is plant steady?

Yes

Ramper
Fetch control and optimization status for No
all ramped loops Is ramp switch on?

Yes
Process I/O
Fetch current averages and case 1 Ramper
bounds Ramp new targets
Perform case 1 generic validity check
functions

No
Run full optimize
Aspen Plus (Optimizer if needed) case?
Solve solution case 1
(normally Parameter)
Yes

Process I/O
Process I/O Set all loops on optimize
Store parameter case outputs

Aspen Plus Optimizer

No Solve solution case 2
Run second
solution case?

Process I/O
Yes Store full optimize case results

Process I/O
Fetch case 2 bounds
Perform case 2 generic validity check Line out period
functions

Aspen Plus Optimizer Go to

Solve solution case 2 Next
(normally Optimize) Cycle

Process I/O
Store optimize case targets

Data Flow The following tables illustrate the data flow in Aspen OnLine
during the online cycle. A data source or destination includes a
variety of file types such as scripts, X files, and reports, as well as
one or more distributed control systems (DCS) or plant
Information Management Systems (IMS). All steps are controlled

Aspen OnLine 12.1 User Guide Concepts and Definitions • 2-17

 by the scheduler, except for the initialization phase. The
initialization phase is started when steady state is detected. In the
file names, plant and case represent the names of the current plant
and current case, respectively.

Initialization Phase
Activity Direction Sheet/Data Source/Destination
Load APPDF ! plant.appdf
Invoke Initialization Script ! Defined on Setup | Options | Scripts sheet
Create/Update base values file ! base.x (If it exists)
" base.x

Solution Case 1
Activity Direction Sheet/Data Source/Destination
Restore X variable values, bounds and ! base.x
specifications from base
Update Aspen Plus script parameters ! DCS/IMS/ Current Values
from DCS/IMS
Invoke Problem Setup Script ! Defined on Setup | Options | Scripts sheet
Update X variable values and bounds ! DCS/IMS/ Current Values
from DCS/IMS
" case_dcs.x
Invoke Pre VC Script ! Defined on Setup | Options | Scripts sheet
Generic validity checks " case_vc.x
Invoke Post Plant data Script ! Defined on Setup | Options | Scripts sheet
Save input to Aspen Plus " case_pre.x
Solve case " case_res.x
If case fails invoke Failure Script ! Defined on Setup | Options | Scripts sheet
If case successful update values in " base.x
base.x
If case solves invoke Post Solution ! Defined on Setup | Options | Scripts sheet
Script
Write case 1 variable results to " DCS/IMS/ Current Values
DCS/IMS
Write Aspen Plus script parameter " DCS/IMS/ Current Values
values to DCS/IMS

Solution Case 2
Activity Direction Sheet/Data Source/Destination
Get initial state of control system for ! DCS/IMS/ Current Values
implementation phase

2-18 • Concepts and Definitions Aspen OnLine 12.1 User Guide

Activity Direction Sheet/Data Source/Destination
Update Aspen Plus script parameters ! DCS/IMS/ Current Values
from DCS/IMS
Band in config.
Restore X variable bounds and ! base.x
specifications from base
Invoke Problem Setup Script ! Defined on Setup | Options | Scripts sheet
Update X variable bounds from ! DCS/IMS/ Current Values
DCS/IMS
" case_dcs.x
Invoke Pre VC Script ! Defined on Setup | Options | Scripts sheet
Generic validity checks " case_vc.x
Invoke Post Plant data Script ! Defined on Setup | Options | Scripts sheet
Save input to Aspen Plus " case_pre.x
Solve case " case_res.x
If case fails invoke Failure Script ! Defined on Setup | Options | Scripts sheet
If case solves invoke Post Solution ! Defined on Setup | Options | Scripts sheet
Script
Write optimization results to DCS/IMS " DCS/IMS/ Current Values
Write Aspen Plus script parameter " DCS/IMS/ Current Values
values to DCS/IMS

Setpoint Implementation
Activity Direction Sheet/Data Source/Destination
Update control system with new targets. ↔ DCS/IMS/ Current Values

Solution Case 3 (Full Optimize)

Activity Direction Sheet/Data Source/Destination
Restore X variable values, bounds and ! opt_dcs.x
specifications from Case 2 inputs
Invoke Pre VC Script ! Defined on Setup | Options | Scripts sheet
Generic validity checks (Set all control " full_case_vc.x
loops on optimize)
Invoke Post Plant data Script ! Defined on Setup | Options | Scripts sheet
Save input to Aspen Plus " full_case_pre.x
Solve case " full_case_res.x
If case fails invoke Failure Script ! Defined on Setup | Options | Scripts sheet
If case solves invoke Post Solution ! Defined on Setup | Options | Scripts sheet
Script
Write Full Optimization results to " DCS/IMS/ Current Values
DCS/IMS
Write Aspen Plus script parameter " DCS/IMS/ Current Values
values to DCS/IMS

Aspen OnLine 12.1 User Guide Concepts and Definitions • 2-19

 Full Optimize Case The full optimization cycle is a repeat of the optimization run with
no specification or bound changes made to allow for control loops
being off optimization or control. The purpose of this run is to
determine what targets the optimizer would have calculated if all
loops were on optimization and control. These targets can be
written to DCS/IMS and compared with the actual targets
implemented in the optimization case. This information is often
used to evaluate the impact of certain controlled variables or
sensitivities of optimized model variables.
The full optimization results are for information only and have no
effect on the control actions taken by Aspen OnLine. For this
reason, in a multi-plant system, the full optimization run will not
occur if another plant is currently solving. Allowing it to run would
increase solution times for the other plant.
If you set the Number of cases on the Models | Case and
Directory sheet to 1 or 2, the Full Optimize case will not be run.
Generic Validity The generic validity check functions are performed as part of the
Check Functions data fetch operations by the process I/O and validation module.
The purpose of validity check is to prepare the input data and
model specifications when certain conditions are detected in the
values from the DCS/IMS. The module performs a different set of
checks for each case.
Parameter Case Generic Aspen OnLine passes a quality flag to Aspen Plus equation-
Validity Check oriented kernel for each variable that is connected to a tag as input.
Aspen Plus equation-oriented kernel handles bad measurement
processing automatically based on user configuration.
Quality flag Description
GOOD Source tag quality is good.
BAD Source tag quality is bad and last good value was used.
Perform any necessary specification changes.
OVERRIDE Override value has been used. Perform any necessary
specification changes.
BADIGNORE Source tag quality is bad and last good value was used. Do not
perform any specification changes.
Optimize Case Generic Sometimes, a loop whose target is set by the optimization system
Validity Check may have its control or optimization switch set to OFF. This check
handles these conditions by taking one of two actions:
• Limit the move on the variable by setting the step bound to 0.0.
• Spread the upper, lower, and step bounds so that the variable is
effectively not constrained.
If the X variable has been linked to a manipulated/controlled
variable pair, the check routine can be configured to act on either

2-20 • Concepts and Definitions Aspen OnLine 12.1 User Guide

 the controlled or manipulated variable. The following flow chart
illustrates the checks and actions taken for the optimize case:
For Each Variable
Next
Variable

NO FAIL
XLVL < XVAL < XUVL

YES

NO
Ramp input point Variables
X = Variable being checked
YES M = Manipulated pair
Variable Attributes
Fetch XOPT & XCTL CTL = Loop control status
OPT = Loop optimization status
YES STP = Step bound
OFOOFC = Off optimization, Off control flag
OFOONC = Off optimization, On control flag
VAL = Value
YES XOPT = "On" & UVL = Optimization upper value limit
XCTL = "On" LVL = Optimization lower value limit

NO

YES
XCTL = "Off" Set XOPT = "Off"

NO

Manipulated pair NO
defined

YES
YES XCTL = "On"

NO

MANIPULATED
OR NO ACTION
XOFOOFC XOFOONC

CONTROLLED CONTROLLED

Set XSTP = 0.0 Set XSTP = 0.0

Go to
Next
Variable

YES
XCTL = "On"

NO

CONTROLLED NO ACTION CONTROLLED

XOFOOFC XOFOONC

MANIPULATED MANIPULATED

Set XSTP = 0.0 Set MSTP = 0.0 Set XSTP = 0.0 Set MSTP = 0.0
Go to
Next
Variable

Aspen OnLine 12.1 User Guide Concepts and Definitions • 2-21

 Setpoint The setpoint implementation module is a complex module that
Implementation implements targets calculated by Aspen Plus. An individual target
Module (Ramper) can be sent to the control system in a single move or gradually
over a period of up to 30 minutes. A target can also be sent to a
single setpoint or to a pair of DMCplus controller limits. Use the
Variables | Specifications | Ramp sheet to configure how a
particular target should be implemented. This section describes the
algorithm of the setpoint implementation module itself.
The setpoint implementation module is actually called twice during
the optimization cycle. It is called at the start of the optimize case
to get the control and optimization status of all loops being
optimized. Any loop that is off at this point will not be ramped
even if it is turned on before the setpoint implementation module
attempts to send setpoints. The second call is made when the
targets are actually sent to the DCS/IMS. In this phase, the setpoint
implementation module cycles up to 30 times (once per minute).
During each cycle, setpoints or limits will be adjusted by an
incremental move.
The following logic diagram illustrates the basic actions taken by
the setpoint implementation module as it sends targets.

2-22 • Concepts and Definitions Aspen OnLine 12.1 User Guide

 Start Initialization

Scheduler Wait for request

from Scheduler

Get initial
Initialize loops control and
Request type optimize
status for all
Ramp setpoints loops

Get all current data for

ramp points

∗ Pre-ramp overall checks ∗ See details in

following sections

NO
OK to continue

YES

For each ramp point

No move
for point
∗ Pre-ramp point checks
NO

NO
Critical
OK to continue
point

YES
YES
YES
Any points left
Go to
Scheduler
NO

Send out ramp status values

YES Write print file

Is print flag on?
DMORMP.PRT

NO

Next
move
cycle For each move cycle
(up to 30 minutes)

Wait 1
minute
NO Go to
Is ramp on?
Scheduler

YES

Fetch bounds on status

for all loops

Aspen OnLine 12.1 User Guide Concepts and Definitions • 2-23

 For each ramp point

No move
for point
∗ Ramping point checks
NO
No
NO
move Critical
OK to continue
for point
point
YES
YES

NO
Past time delay Go to
for point Scheduler

YES

YES Past end of

ramp time for
point

NO

∗ New setpoint calculations

YES Go to
Any points left Scheduler

NO
YES

Any setpoints NO Is ramping

to send this complete for all
cycle points

NO
YES

Send out new setpoints

YES Go to
Any move Next move
cycles left cycle

NO

Go to
Scheduler

Pre-Implementation These are basic checks performed immediately after the setpoint
Overall Checks implementation module is called by the scheduler to do the output
phase. If any of these tests fail, no implementation will occur. The
following is checked:
• There must be at least one point to be implemented.
• At least one of the points must have been on control and
optimization in the initialization phase.

2-24 • Concepts and Definitions Aspen OnLine 12.1 User Guide

 • The plant must currently be steady enough to implement points
(determined by the steady-state detection program).
Pre-Implementation Point These checks are performed once for each point before the
Checks program goes into its main output loop. Their purpose is to check
the initial conditions for each point to determine if it should be
moved. If a point fails any of these tests, its new setpoint will not
be sent. If it is a critical point, no output will occur for all other
points.
• The point must have been on control and optimization in the
initialization phase.
• Good values must be available from the DCS/IMS for the
point.
• The point must currently be on control and optimization.
• The bounds for the point cannot be crossed.
• If high and low limits are being output, these limits must not be
crossed.
• The operator cannot make a change to the setpoint during the
optimization run that is disallowed by the setpoint change
allowed flag.
Several non-critical checks are also made. Failure of these checks
will cause the point not to be sent but it will not stop all other
output even if the point is critical.
The resulting move cannot cause a setpoint to be moved farther
from its bound. For example, if both the target and current setpoint
value were above a high bound and the target was above the
current setpoint, then this point would not be sent. By moving the
setpoint higher than the target, the setpoint would be moved farther
from the upper bound.
Implementation Point These checks are performed at the start of each cycle in the main
Checks ramp loop for each active point to output. The purpose of these
checks is to determine if conditions of a loop have changed such
that it should no longer be output. If a point fails any one of these
tests, it will not be sent. If it is a critical setpoint, all setpoint
implementation will stop.
• The point must be on control and optimization.
• The bounds for the point cannot be crossed.
• If high and low limits are being sent, these limits must not be
crossed.
Incremental Move These calculations are performed once for each output point before
Calculation the program goes into its main implementation loop. The
calculated result for each point is the size of the incremental move
that will be written to the setpoint(s). If the output time configured

Aspen OnLine 12.1 User Guide Concepts and Definitions • 2-25

 for the point is 0 minutes, the incremental move will be equal to
the full move. The following pseudo-code describes the algorithm
used in the calculations:
!
! Variable Descriptions
!
! IMP_START Value of "Always Implement Setpoints From Start
! Position" flag defined on Setup | Options | Ramp sheet
! OBEY_STEP Value of "Obey Step Bound in Implementation"
! flag defined in GUI
! START_POSPV Current value of Start Position process value
! AP_TARGET Target Calculated By Aspen Plus
! FULL_MOVE Unbounded calculated move
! INCR_MOVE Calculated incremental move

! LOWER_BOUND Lower Bound (Aspen Plus limit)

! MOVE_SIGN Sign of move
! +1 = positive
! -1 = negative,
! 0 = no move
! RTO_TARGET Actual final Implementation target
! IMP_TIME Configured ramp time in minutes for the point
! RTO_TYPE Type of Ramp point
! "S" - Single Setpoint
! "U" - Upper Setpoint Limit
! "L" - Lower Setpoint Limit
! "B" - Both Upper and Lower limit
! SP_HIGH Setpoint high limit for RTO_TYPE = "U/L/B"
! SP_LOW Setpoint low limit for RTO_TYPE = "U/L/B"
! SP_TOLERANCE Setpoint crossing tolerance
! SP_VALUE Setpoint value for RTO_TYPE = "S"
! START_VALUE Starting value of point.
! STEP_BOUND Step Bound (Aspen Plus limit)
! UPPER_BOUND Upper Bound (Aspen Plus limit)
!
! Calculate the setpoint tolerance to be used when preventing crossed
! setpoint limits
!
IF ABS(AP_TARGET) <= 0.1 THEN
SP_TOLERANCE = 0.0005
ELSE
SP_TOLERANCE = ABS(AP_TARGET) * 0.0005
ENDIF
!
! Set the starting value based on point type
!
IF RTO_TYPE = "S" THEN
IF START_POSPV is valid THEN
IF IMP_START THEN
START_VALUE = START_POS
ELSE
START_VALUE = SP_VALUE
ENDIF
ENDIF
IF RTO_TYPE = "U" THEN START_VALUE = SP_HIGH
IF RTO_TYPE = "L" THEN START_VALUE = SP_LOW
IF RTO_TYPE = "B" THEN START_VALUE = START_POSPV
!
! Calculate the unbounded move and sign
!
FULL_MOVE = AP_TARGET - START_VALUE
MOVE_SIGN = ABS(FULL_MOVE) / FULL_MOVE

2-26 • Concepts and Definitions Aspen OnLine 12.1 User Guide

!
! Bound move with any Aspen Plus Step bounds
!
IF OBEY_STEP THEN
IF ABS(FULL_MOVE) <= STEP_BOUND THEN
RTO_TARGET = AP_TARGET
ELSE
RTO_TARGET = START_VALUE + (MOVE_SIGN * STEP_BOUND)
ENDIF
ENDIF
!
! If the target is above the Aspen Plus upper bound do one of the
! following
!
! 1. If the start position is less than the upper bound then force the
! target to the upper bound
! 2. If the start position is less than the target then don't move
! any further from the bound, so don't ramp this one.
! 3. If neither of the above is true then let the ramper move the value
! to the target but don't force the target to the bound unless the
! Honor Absolute Bound flag has been set

!
IF RTO_TARGET > UPPER_BOUND THEN
IF START_VALUE <= UPPER_BOUND THEN
RTO_TARGET = UPPER_BOUND
ELSEIF START_VALUE < RTO_TARGET THEN
RTO_TARGET = UPPER_BOUND
MOVE_SIGN = 0
ELSEIF ABSOLUTE BOUNDS HONORED THEN
RTO_TARGET = UPPER_BOUND
ENDIF
ENDIF
!
! Repeat for lower bound
!
IF RTO_TARGET < LOWER_BOUND THEN
IF START_VALUE >= LOWER_BOUND THEN
RTO_TARGET = LOWER_BOUND
ELSEIF START_VALUE > RTO_TARGET THEN
RTO_TARGET = LOWER_BOUND
MOVE_SIGN = 0
ELSEIF ABSOLUTE BOUNDS HONORED THEN
RTO_TARGET = LOWER_BOUND
ENDIF
ENDIF
!
! Calculate the incremental move
!
INCR_MOVE = (RTO_TARGET - START_POS) / (IMP_TIME + 1)
!
! End move calculation

New Setpoint These calculations are performed at the start of each cycle in the
Calculations main implementation loop for each active output point. The result
is the new setpoint value(s) that is sent to the DCS/IMS. The
following pseudo code describes how the new setpoint(s) is
calculated in each cycle. These calculations use variables from the
previous pseudo code.

Aspen OnLine 12.1 User Guide Concepts and Definitions • 2-27

!
! Variable descriptions
!
! NEW_VALUE New calculated value for setpoint
!
! Calculate the new setpoint value and bound it
!
NEW_VALUE = START_VALUE + INCR_MOVE
IF MOVE_SIGN > 0 THEN
IF NEW_VALUE > UPPER_BOUND THEN
NEW_VALUE = UPPER_BOUND
END IF
ELSEIF MOVE_SIGN < 0 THEN
IF NEW_VALUE < LOWER_BOUND THEN
NEW_VALUE = LOWER_BOUND
ENDIF
ENDIF
!
! Variable Descriptions
!
! IMP_START Value of Always Implement Setpoints From Start
! Position flag defined on Setup | Options | Ramp sheet
! OBEY_STEP Value of Obey Step Bound in Implementation
! flag defined in GUI
! START_POSPV Current value of Start Position process value
! AP_TARGET Target Calculated By Aspen Plus
! FULL_MOVE Unbounded calculated move
! INCR_MOVE Calculated incremental move
! LOWER_BOUND Lower Bound (Aspen Plus limit)
! MOVE_SIGN Sign of move (+1 = positive, -1 = negative,
! 0 = no move)
! RTO_TARGET Actual final Implementation target
! IMP_TIME Configured ramp time in minutes for the point
! RTO_TYPE Type of Ramp point
! S - Single Setpoint
! U - Upper Setpoint Limit
! L - Lower Setpoint Limit
! B - Both Upper and Lower limit
! SP_HIGH Setpoint high limit for RTO_TYPE = U/L/B
! SP_LOW Setpoint low limit for RTO_TYPE = U/L/B
! SP_TOLERANCE Setpoint crossing tolerance
! SP_VALUE Setpoint value for RTO_TYPE = S
! START_VALUE Starting value of point.
! STEP_BOUND Step Bound (Aspen Plus limit)
! UPPER_BOUND Upper Bound (Aspen Plus limit)
!
! Calculate the setpoint tolerance to be used when preventing
! crossed setpoint limits
!
IF ABS(RTOPT_TARGET) <= 0.1 THEN
SP_TOLERANCE = 0.0005
ELSE
SP_TOLERANCE = ABS(AP_TARGET) * 0.0005
ENDIF
!
! Set the starting value based on point type
!
IF RTO_TYPE = S THEN
IF START_POSPV is valid THEN
IF IMP_START THEN
START_VALUE = START_POS
ELSE
START_VALUE = SP_VALUE

2-28 • Concepts and Definitions Aspen OnLine 12.1 User Guide

 ENDIF
ENDIF
ENDIF
IF RTO_TYPE = U THEN START_VALUE = SP_HIGH
IF RTO_TYPE = L THEN START_VALUE = SP_LOW
IF RTO_TYPE = B THEN START_VALUE = START_POSPV
!
! Calculate the unbounded move and sign
!
FULL_MOVE = AP_TARGET - START_VALUE
MOVE_SIGN = ABS(FULL_MOVE) / FULL_MOVE
!
! Bound move with any Aspen Plus Step bounds
!
IF OBEY_STEP THEN
IF ABS(FULL_MOVE) <= STEP_BOUND THEN
RTO_TARGET = AP_TARGET
ELSE
RTO_TARGET = START_VALUE + (MOVE_SIGN * STEP_BOUND)
ENDIF
ENDIF
!
! If the target is above the Aspen Plus upper bound do one of the following
!
! 1. If the start position is less than the upper bound, force the
! target to the upper bound
! 2. If the start position is less than the target, don't move
! any further from the bound, so don't ramp this one.
! 3. If neither of the above is true, let the ramper move the value
! to the target but don't force the target to the bound unless the
! Honor Absolute Bound flag has been set
!
IF RTO_TARGET > UPPER_BOUND THEN
IF START_VALUE <= UPPER_BOUND THEN
RTO_TARGET = UPPER_BOUND
ELSEIF START_VALUE < RTO_TARGET THEN
RTO_TARGET = UPPER_BOUND
MOVE_SIGN = 0
ELSEIF ABSOLUTE BOUNDS HONORED THEN
RTO_TARGET = UPPER_BOUND
ENDIF
ENDIF
!
! Repeat for lower bound
!
IF RTO_TARGET < LOWER_BOUND THEN
IF START_VALUE >= LOWER_BOUND THEN
RTO_TARGET = LOWER_BOUND
ELSEIF START_VALUE > RTO_TARGET THEN
RTO_TARGET = LOWER_BOUND
MOVE_SIGN = 0
ELSEIF ABSOLUTE BOUNDS HONORED THEN
RTO_TARGET = LOWER_BOUND
ENDIF
ENDIF
!
! Calculate the incremental move
!
INCR_MOVE = (RTO_TARGET - START_POS) / (IMP_TIME + 1)
!
! End move calculation

Aspen OnLine 12.1 User Guide Concepts and Definitions • 2-29

! If this point type is a setpoint limit and only one limit is active
! check if the inactive limit will
! be crossed. If the inactive limit will be crossed then make it active
!
IF RTO_TYPE = U THEN
IF NEWPOS <= SP_LOW THEN RTO_TYPE = B
ELSEIF RTO_TYPE = L THEN
IF NEWPOS >= SP_HIGH THEN RTO_TYPE = B
ENDIF
!
! Set the new setpoint(s) value and check for limit crossing. Bound
! crossing should also be checked again for points with both limits
! active.
!
IF RTO_TYPE = S THEN
SP_VALUE = NEW_VALUE
ELSEIF RTO_TYPE = U THEN
SP_HIGH = NEW_VALUE
IF SP_HIGH <= SP_LOW THEN
SP_HIGH = SP_LOW + SP_TOLERANCE
ENDIF
ELSEIF RTO_TYPE = L THEN
SP_LOW = NEW_VALUE
IF SP_LOW >= SP_SP_HIGH THEN
SP_LOW = SP_HIGH - SP_TOLERANCE
ENDIF
ELSEIF RTO_TYPE = B THEN
SP_HIGH = NEW_VALUE + (SP_TOLERANCE * 0.5)
SP_LOW = NEW_VALUE - (SP_TOLERANCE * 0.5)
IF SP_HIGH > UPPER_BOUND THEN
SP_HIGH = UPPER_BOUND
SP_LOW = SP_HIGH - (SP_TOLERANCE * 0.5)
ELSEIF SP_LOW < LOWER_BOUND THEN
SP_LOW = LOWER_BOUND
SP_HIGH = SP_LOW + (SP_TOLERANCE * 0.5)
ENDIF
ENDIF
!
! Set the start value for the next cycle
!
START_VALUE = NEW_VALUE
!
! End Calculations

Typical Implementation Normally the setpoint implementation module will have to handle
Situations one of three typical situations when sending a single point:
• Implement a single setpoint or setpoint limit with no crossing
of setpoint limits.
• Implement a pair of setpoint limits.
• Implement a single setpoint limit but cross other limit(s) before
the end of output time.
The following figures illustrate how the values of the
setpoints/limits will change over the implementation period for
these three situations. Note that the setpoint crossing tolerance is
exaggerated for clarity.

2-30 • Concepts and Definitions Aspen OnLine 12.1 User Guide

 RTO Target

Current Value

Setpoint Value
or Single Limit

Implementation

Single Setpoint Limit Implementation

Setpoint Crossing
RTO Target

Setpoint High

Current Value

Limits pinched to current value

Setpoint Low start of implementation

Implementation

High- and Low-Limit Implementation

Setpoint Crossing
RTO Target

Setpoint High

Current Value
Both limits
when crossing detected
Setpoint Low

Implementation

Single-Limit Implementation with Crossing Limits

Aspen OnLine 12.1 User Guide Concepts and Definitions • 2-31

 Watchdog Program
The purpose of the Watchdog program is to monitor the health of
the on-line optimization program and the steady-state detection
program.
The watchdog monitors these programs by checking the following
two things:
2 Is the program currently running?
3 Is the program resetting its watchdog countdown signal
properly? The tags for these signals are defined on the Setup |
Specifications | Signals sheet (APOL Watchdog and Steady-
State Watchdog). The watchdog monitors this by decrementing
these signals by two each cycle (watchdog normally runs on a
two-minute cycle). If the value of the signal counts down to 0,
then the watchdog assumes the program has a problem and
stops it.
If the steady-state program has a problem and is shut down for any
reason, the watchdog program will always attempt to restart it. If
the optimization program has a problem, the watchdog will attempt
to restart it if the tag associated with the signal SigRestart on the
Setup | Specifications | Signals sheet is set to 1.

2-32 • Concepts and Definitions Aspen OnLine 12.1 User Guide

 The following logic diagram illustrates the algorithm of the
watchdog program:
Start Initialization
Next
cycle

Online system fail = False

Steady state fail = False
Wait 2
minutes

YES
Did steady state
fail last cycle?

NO

Decrement steady state Restart steady state

watch dog signal Steady state fail = False

YES
Is steady state watch
dog signal < 0.0?

NO

NO
Is steady state
program active?

Stop online system

YES
Online system fail = True

Stop steady state

Steady state fail = True

YES
Did online system
fail last cycle?

NO

Decrement online system

NO
watch dog signal Automatic
restart?

YES YES
Is online watch
dog signal < 0.0?

Restart steady state

NO
Steady state fail = False

NO
Is scheduler
process active?

Stop online system YES

Online system fail = True

Go to
next
cycle

Aspen OnLine 12.1 User Guide Concepts and Definitions • 2-33

 Data Validation
When automating data entry for a process model, data validation
must be carefully done in order to avoid using bad data in the
simulation. Bad data may lead to completely erroneous model
results, or the process model calculation may not converge at all.
Aspen OnLine provides a method for detecting gross errors and
out-of-limit variables. At configuration time, validity limits are
entered for each tag, except those of type Signal. You can choose
to clamp the value of a tag at the validity limit when a value
exceeds this limit.
You may declare critical variables, which are key variables that
have a strong impact on model-computed results. When a critical
variable is outside its validity limits, model calculations will not
proceed, since the results may totally misleading or the process
model may not converge. In addition, plant data provided by a
DCS or IMS ordinarily carries an attribute defining the quality of
the data as Good or Bad. Aspen OnLine also provides capabilities
to replace bad data.
Aspen OnLine provides capabilities to validate model results or
values of formula tags that are sent for storage and trending in the
information management system.
Any abnormalities detected during data validation are recorded in
Aspen OnLine’s Event Log.
Validity Range This is the range of values for a variable that would be considered
normal. Ordinarily, this validity range would correspond to the
normal operating range of the variable. Validity Range is defined
by the tag's corresponding Lower Limit and Upper Limit.
Clamping When a tag has a value that goes beyond its validity range, its
value can be clamped or replaced by the limit value that has been
exceeded.
Replacement of Bad Aspen OnLine provides capabilities to replace plant data that has
Data been flagged as bad by the DCS or IMS. You can choose to:
• Replace the bad value with the last good value
• Substitute a default value that has been previously defined
during configuration
• Use a combination of these two methods. The last good value
is used if available; otherwise, the default value is used.
The selection is made on the Tags | Specifications | Parameter
sheet.

2-34 • Concepts and Definitions Aspen OnLine 12.1 User Guide

 Steady-State Detection
The steady-state detection and averaging program monitors the
plant for steady-state condition and calculates running averages
that will be used as input to the optimization program. The
program reads new values for all points configured for averaging
or steady-state detection from the DCS/IMS on a regular frequency
(normally every one or two minutes). The results are stored in a
local rolling buffer that can save up to the last 360 values
(normally six to twelve hours) for each point.
Using this history of tag values, the program calculates a new
running average for each point every time a new value is collected.
The program also uses this tag history when checking points to
determine if the plant is currently steady to start the optimization
cycle.
Use the Tags | Specifications | Steady State/Trend sheet and
Average sheet to configure individual points for steady-state
detection and averaging, respectively. Use the Setup |
Specifications | Steady-State Detection sheet to configure the
steady-state detection program.
There are two critical steps which depend on the steadiness of the
plant:
• Optimization steady-state status determines whether the plant
is steady enough to start to calculate a new optimization cycle.
This status is stored in a signal tag showing that the plant is
currently steady.
• Implementation steady-state status determines whether the
plant is still steady enough to receive new setpoints calculated
by the optimizer. This status is stored in a separate signal tag.
Any point configured for steady-state detection can be used in
either of the two checks or both. Normally, the optimization steady
state is a more inclusive check that monitors a larger number of
points than the implementation check. In other words, the points
used in the implementation check are normally a subset of the
points used for the optimization check.
Models used with Aspen OnLine are steady-state models. For them
to provide reliable results, the plant data must reflect conditions
close to steady state. Aspen OnLine ensures that the process is at
steady state before data is sent to the models. Plant data are
continuously collected and steady-state detection calculation is
performed continuously as well. There are two techniques
available in Aspen OnLine to define the average of a tag: a
heuristic method and a statistical method. A brief description is

Aspen OnLine 12.1 User Guide Concepts and Definitions • 2-35

 provided below. A more comprehensive description is given in the
appendix.
The following logic diagram illustrates the algorithm of the steady-
state program. Due to their complexity, the detailed algorithms
used in checking each point for steady state are not included in the
diagram.
Start Initialization

Get list of all steady-state

Next and average points
cycle

Set all average

outputs to Bad Log "Bad Delta
Wait delay Time" Message
period
YES
Is print
flag on?
Is time since last NO
cycle within
tolerance? NO Output print file
RTESSD.PRT
YES

Get new values for all DCS inputs

Initialize: Steady State=True Output maximum
Ramp Steady State = True deviations for all points

Next
point For each steady state point
Is steady YES
state force
flag on?
Statistical Heuristic
Steady state
method
NO Steady state =
True

∗ Perform statistical
steady state calculation
Perform heuristic
steady state calculation
∗
Calculate new averages
Output averages
Output steady state and
ramp steady state flags
YES
Is point steady or
type neither

NO
Is it time to YES
resolve
Optimize Ramp database?
Steady state
point type
Scan database
NO
for new steady
Steady state = False Ramp steady state=False state and
Both
average points

Ramp steady state=False

Steady state = False
Go to
Next
cycle

Go to YES NO
Next Any points
point left
∗ See details in following sections

2-36 • Concepts and Definitions Aspen OnLine 12.1 User Guide

 Heuristic Method The heuristic method uses two filters on the raw data, a light filter
and a heavy filter. A time span is specified and the maximum
absolute difference between the heavy-filtered data and the light-
filtered data is compared to the maximum limit allowed. If the
difference exceeds the limit, the plant is not at steady-state
conditions.
A second test is made to determine whether the plant data is
trending. This test compares the difference between the starting
and ending values for the heavy filter results. If the absolute value
of the difference exceeds a specified limit, then the plant is not at
steady state.
See the appendix for details.
Statistical Method This method uses a statistical check on the recent history values for
each tag to evaluate if there is a trend in the data. Two values are
determined, the variance and the mean square successive
difference. The ratio of mean square successive difference to the
variance is calculated. Ideally, a value near 2 or greater for this
ratio indicates that there is no trend in the data and the tag can be
considered steady. Because this is a statistical check, the actual
determination must take into account the number of samples used
to calculate the ratio. Given the number of samples, a 95%
confidence level value is established. This value is used to
determine if the calculated ratio is indicative of a steady tag.
See the appendix for details.

Aspen OnLine 12.1 User Guide Concepts and Definitions • 2-37

2-38 • Concepts and Definitions Aspen OnLine 12.1 User Guide
 CHAPTER 3

Online Project Development

Users of Aspen OnLine fall into two major categories, those who
use it to develop online applications, and those who are end-users
of the online applications. This chapter focuses on online project
development and the next chapter focuses on project execution.
This chapter discusses development of new project. To migrate
Aspen OnLine projects created using earlier versions of Aspen
OnLine, or projects created using Aspen Plus OnLine or RT-Exec,
please refer to Chapter 5, titled Advanced Features.

Steps to Develop an Online Project

In this documentation the terms online project and online
application are used interchangeably. The creation of an online
project involves the following procedure:
1 Verification of access to plant data.
2 Verification of the ability to run the process models. (The
development of a model that is able to accurately represent
plant behavior is beyond the scope of this document. However,
such a model must be developed and thoroughly tested before
attempting to run the model within Aspen OnLine.)
3 Creation of a new Aspen OnLine project.
4 Configuration of the Aspen OnLine project.
5 Placing the project online.
Each of these topics is discussed in further detail below.
Testing Cim-IO Before configuring an Aspen OnLine project to access plant data,
Access to Plant Data access to the DCS/IMS from the server PC should be confirmed
manually.
Verifying access to plant data involves using the Cim-IO test
utility to test a GET or a PUT. Before you start, confirm network

Aspen OnLine 12.1 User Guide Online Project Development • 3-1

 access to the DCS/IMS computer. From a DOS prompt, ping the
DCS/IMS computer by name. For example, ping DCShost.
Once you get replies from the DCS/IMS computer, follow the
procedure below to verify access of tags using the appropriate
Cim-IO Server:
1 Start the Cim-IO test utility. (Click Start | Programs | Aspen
Manufacturing Suite | Cim-IO | Test API.)
2 Enter 9 to test a Cim-IO GET.
3 Enter the logical device name at the prompt.
4 Press the enter key to accept 1 as the default for unit number.
5 Press the enter key to accept 1 as the default for Number of
Tags.
6 Press the enter key to accept 1 as the default for Priority.
7 Press the enter key to accept 1 as the default for Timeout.
8 Press the enter key to accept CIMIO_AT_SYNC as the default
(Synchronous access).
9 Press the enter key to accept 1 as the default for Frequency.
10 Enter –1 for the List ID to ensure that a new list is built.
11 Enter 1 to choose to enter tag information one tag at a time.
12 Enter an existing, valid tag name, for example T-101.PV, for
Tagname. Note that depending on the information
management system being accessed, it may be necessary to
append a suffix or a prefix to the tag name. See the partial list
of possible suffixes and prefixes below.
Information Prefix/Suffix for Example for tag
Management System Cim-IO access T-101.PV
Get from InfoPlus Prefix: P,value, P,value,T-101.PV
Put to InfoPlus Prefix: P,value, P,value,T-101.PV
Get from IP.21 Suffix: ip_value T-101.PV ip_value
Put to IP.21 Suffix: ip_input_value T-101.PV ip_input_value
13 Enter 1 for Datatype
If the GET is successful, the Cim-IO test utility should reply
with a GET Successful message and provide the current value
of the tag.
14 From the top level Cim-IO utility, enter a to test a Cim-IO
PUT.
15 Enter the logical device name at the prompt.
16 Press the Enter key to accept 1 as the default for the Unit
number.

3-2 • Online Project Development Aspen OnLine 12.1 User Guide

 17 Press the Enter key to accept 1 as the default for the Number
of tags.
18 Press the Enter key to accept 1 as the default Priority.
19 Press the Enter key to accept 1 as the default Timeout period
in seconds.
20 Press the Enter key to accept CIMIO_AT_SYNC as the default
(Synchronous access).
21 Press the Enter key to accept enter list id as the default.
22 Enter 1 to choose to enter tag information one tag at a time.
23 Enter the tag name for an existing tag, noting that the current
value will be overwritten by this procedure. Depending on the
information management system being accessed, it may be
necessary to append a suffix or a prefix to the tag name. See
the partial list of possible suffixes and prefixes above.
24 Enter 1 to choose the 32-bit floating point data type
25 Enter 1 to choose the 32-bit floating point device data type
26 Enter the value for the tag.
27 Enter 1 to output the value.
At this point the Cim-IO test utility should reply with a PUT
Successful message and provide the current value of the tag.
If the Cim-IO test of PUT and GET are not successful, Aspen
OnLine will not be able to retrieve (or send) values to the
DCS/IMS.
Verifying the Running Aspen OnLine 12.1 is capable of running steady state process
of the Model models developed using the following modeling tools:
• Aspen Plus 12.1 (sequential-modular or equation-oriented
models)
• Aspen Custom Modeler 12.1
• Aspen Utilities 12.1
• Aspen Water 12.1
• Hysys 3.0 or later
To verify the models:
1 Copy a version of each model onto the Aspen OnLine server
computer.
2 Run the model on the online machine. Verify that the model
can run successfully on this computer.
The model must run and complete without any errors, under all
sets of conditions presented by the historical and anticipated plant

Aspen OnLine 12.1 User Guide Online Project Development • 3-3

 behavior. Results will not be loaded into Aspen OnLine if the
model completes with errors.
For Aspen Plus SM models, the models must not be set to Load
Results Interactively. This can be set in the Aspen Plus User
Interface: In the Tools | Options dialog box, on the Run tab, clear
Load Results Interactively. If results are loaded interactively,
values of output variables in Aspen Plus will not be available to the
tags to which they are linked in the project.
Understanding the Having successfully run the model, you must identify variables
Model Variable that are going to be connected to tags for either input or output.
Structure Locate them and their current values in the various input and
results forms of the Aspen Plus User Interface.
Aspen OnLine establishes links based on the full Aspen Plus
variable name. Aspen Plus organizes its variable names in a tree
structure that is accessible by invoking the Variable Explorer
from the Tools menu. Aspen OnLine uses the same tree structure
at configuration time to establish online links.
To understand the variable structure of a given model, invoke the
Variable Explorer and locate each variable that is to be connected.
If you need to confirm you have located the correct variable, you
can compare the value displayed by the Variable Explorer with the
value given in the input or results form of the Aspen Plus User
Interface.
An alternative method for identifying the correct variable name is
to locate it on the Aspen Plus interface, then copy the variable and
paste-link it to an Excel spreadsheet. The formula line will give the
complete name of the variable.
Aspen OnLine also generates model variable tree views for models
from Hysys and ACM-based applications. There are three types of
variables: Flowsheet variables, Block variables and Stream
variables. Models containing hierarchical blocks are supported as
well. In the case of Aspen Plus EO models, the model variables are
essentially the variables that one sees in the EO Variable form
within the Aspen Plus GUI.

Development of an Aspen OnLine

Application
Once connections to plant data are established and a process model
is ready and operational, one may proceed with the development of
an online application. The development of an Aspen OnLine
project involves:

3-4 • Online Project Development Aspen OnLine 12.1 User Guide

 • Creating a new project using Aspen OnLine Project Manager
• Configuring project using Aspen OnLine Client GUI

Creating a New Project

The first step in the development of an online application is the
creation of a new project on the Aspen OnLine server machine.
This requires:
• Specifying the project name, and
• Specifying the location of the project folder or directory.
Please refer to Aspen OnLine Tutorial version 12.1, Chapter 3,
Create a New Project, for detailed instructions on how to create a
new project.
The directory structure and files for the newly-created project is
shown below:
Directory Structure Files
[C:]___
| AOL 12-1 Work
| AOLSample Config.mdb
| Hist
| OffLine
| OnLine
Where AOLSample is the project name the user specified during
project creation and C:\AOL 12-1 Work is the project location
specified by the user.
The Hist folder is the base directory for the Aspen OnLine history
system. All case history directories are created within this
directory. The hist.dat file in this directory is an index of the case
histories used by Aspen OnLine. This file is a binary file and users
should not edit it.
The OffLine folder is the recommended location for models that
will be brought into the project. However, models can be placed in
other directories as well. Furthermore, models in a project can be
placed in different folders as long as they are all accessible to the
Aspen OnLine server components.
The OnLine folder is used for holding files such as model files,
databases for model variable trees, log files, and report files. Aspen
OnLine creates various working files within this folder. Also, this
is the working directory of the online model.
Files Within a Project Config.mdb, located in the main project directory, is a
configuration database created by Aspen OnLine Project Manager.

Aspen OnLine 12.1 User Guide Online Project Development • 3-5

 It holds all project configuration information. Do not directly edit
this file because it may cause unexpected or undesirable results.
The OnLine folder contains the following database and statistical
files:
File Description
stats.dat Aspen OnLine overall case statistics
ssdstats.dat Steady-state detection statistics
In addition, the OnLine folder contains the following log files,
where plant is the name of the current plant and case is the name
of the current case:
File Description
rtessd.log Log file for steady-state detection program
rtewdg.log Log file for watchdog program
plant.log Log file for online optimizer
engine.log A common log file to which online programs may
log errors. A new version is generated each time the
online system is started. The scheduler also logs
major phases of the optimization cycle here. Use this
file as a source for run-time statistics and for
diagnostics when problems occur.
rtessd.prt Results of steady-state calculations. Useful for
determining what process tags are preventing the
plant from being declared as steady. Generated when
Steady-State Print is on.
rteimp.prt Results of the setpoint implementation module
calculations that are performed in preparation for
output. Useful in monitoring the moves to be made
by the setpoint implementation module as well as
determining why an optimization target is not
ramped. It is generated when Ramper Print is on.
prmgvc.log Log of all changes to X variables made by the
parameter case (case1) generic validity check routine
optgvc.log Log of all changes to X variables made by the
optimize case (case2) generic validity check routine
pparm.rpt Log of all parameter variables that were updated by
measurements and the associated measurement that
was used. The file is generated at the end of the first
solution case (normally parameter case).
inpprm.rpt The same data given in pparm.rpt, but in script file
format. The data reported can be used as input to off-
line runs. This file is also generated at the end of the
first solution case (normally parameter case).

3-6 • Online Project Development Aspen OnLine 12.1 User Guide

 File Description
move.rpt The moves calculated for all ramped tags. Contains
the parameter case value, the optimization case
value, the move value, and the control and
optimization status for the loop. This file is generated
at the end of the optimization case.
fullmove.rpt Identical to the move.rpt except that it is generated at
the end of the full optimization case, if the model is
configured to make such a run. The values displayed
will be the result from the full optimization case
rather than the optimization case.
case.itr Log of the Aspen Plus EO solver iteration
information that normally goes to the Aspen Plus EO
kernel history device

Project Configuration
The next step is configuring the project. Configuration can be
performed using the Aspen OnLine Client GUI that resides either
on the Aspen OnLine server machine or an Aspen OnLine Client
machine on the network. An Aspen OnLine Client machine is a PC
that has Aspen OnLine Client installed but does not have Aspen
OnLine Server installed.
Project configuration consists of the following steps:
1 Backing up project configuration information
2 Launching Client GUI and connecting to DCOM on server
machine
3 Defining engineering units that do not exist in the built-in
engineering units system
4 Defining tags
5 Entering formulas for Formula tags
6 Defining models
7 Performing Offline-to-Online operation for each model
8 Scheduling model execution
9 Defining model variables and establish links between tags and
model variables
10 Configuring end-user GUI
11 Making miscellaneous specifications
These steps are described in detail below.

Aspen OnLine 12.1 User Guide Online Project Development • 3-7

 Backing up Project Aspen OnLine 12.1 is a client-server application using an Access
Configuration database for storing project configuration information. As you
Information modify project configuration using the Data Browser within the
Client GUI, modifications are saved immediately to the Access
database. After changes are made, you cannot easily undo changes.
In the current release, there is an option that you can configure to
force Aspen OnLine to make a backup copy of the configuration
database automatically. To specify this option, select Options in
the Tools menu. It is recommended that regular backups of the
current project database be made while working on the online
application. The methods of backing up online projects are
described in Chapter 5, Advanced Features.
Launching Client GUI After a new project is created, use the Client GUI to configure the
and Connecting to project. To start project configuration, click Start | Programs |
Server AspenTech | Aspen Engineering Suite | Aspen OnLine 12.1 |
Client GUI. The Aspen OnLine main window appears with the
Aspen OnLine Startup dialog box in front of it.

The Server name is the name of the machine that has Aspen
OnLine Server installed and running and has the project you want
to connect to. Use the dropdown list for Server name to select a
known server, or type the server machine name and then press the
enter key.
After server name is specified, select the Project name from the
dropdown list. In this example, we select AOLSample.

3-8 • Online Project Development Aspen OnLine 12.1 User Guide

 When a new project is created, the project password is blank by
default. Project password can be set or modified using Aspen
OnLine Project Manager. A password is not needed if you just
want to view project configuration information or use the control
panel to control or monitor project execution. The password is
required to modify project configuration.
The Checked out by field is read-only and displays the machine
name of the client that has connected to this project for editing. At
any given moment, only one client can connect to the project and
edit project configuration, although multiple clients can view
configuration and perform run-time tasks for the project at the
same time.
The Check project out for editing checkbox allows you to
connect to the project in read-only mode to avoid unintended
project modifications.
Click OK to connect to the project. The Startup dialog box
disappears and the Client GUI main window is displayed along
with the Control Panel.
The Control Panel is used for viewing project run-time
information, controlling project execution and performing
interactive runs. It can be closed during configuration. Although
Aspen OnLine project configuration modifications are possible
while the steady-state detection component and engine component
are running, it is recommended that those two components be
stopped when many modifications of project configuration are
being performed.
Project configuration is performed using Data Browsers within
Client GUI. There are three ways to open a Data Browser:

Aspen OnLine 12.1 User Guide Online Project Development • 3-9

 1 Click the Data Browser icon on the toolbar of the main window
2 Select the Data Browser command on the Data menu of the
main window
3 Press the F8 key
A Data Browser is shown below:

Multiple Data Browsers can be opened at the same time. Project

configuration information is grouped into several categories:
Setup, Tags, Models, Variables, Units Conversion and User
GUI. These groups are shown in a tree view on the left of the Data
Browser. The upper right portion of a Data Browser displays GUI
elements corresponding to the configuration group selected in the
tree view on the left. The lower right area of the Data Browser is
used to display the prompt or description of the selected GUI
element.
The status bar of the main window has four panels. The purpose of
the first panel is obvious. Information displayed in the second and
fourth panels is applicable only at run-time. Client configuration
mode indicates whether or not the project configuration can be
edited.
At this point, the Client GUI has been connected to the server and
the Data Browser is ready to accept user input for project
configuration.

3-10 • Online Project Development Aspen OnLine 12.1 User Guide

 Defining Engineering Aspen OnLine comes with a built-in units system, which should
Units satisfy most units conversion needs. Currently, Aspen OnLine does
not perform any units conversion or checking for Aspen Plus
equation-oriented models. For all other model types, automatic
conversion of units of measure is done. You can specify additional
units when necessary. You can either add custom units to an
existing units type, or add a custom units type and custom units. To
perform either of these operations, click the Units Conversion
node in a Data Browser to display the Units Conversion |
Specifications sheet.

The three command buttons on the left apply to units types. Click
New, Rename or Delete to add, rename or delete a custom units
type, respectively. You cannot rename or delete built-in units
types.
The two buttons on the right, New and Delete, can be used to add
and delete custom units, respectively. Built-in units cannot be
deleted or modified.
Use the grid on the right to rename custom units and to modify
conversion factor and offset. Aspen OnLine uses the convention
used in Perry’s Chemical Engineers’ Handbook. That is:
(Value in base units) = (Value in custom units)*Factor + Offset
Note that the base units of a custom units type cannot be deleted.
You must the delete corresponding custom units type instead.
Defining Tags As a new project is created, Aspen OnLine Project Manager
creates default Signal tags automatically. You can add new Signal
tags and configure them to receive the values of the various Signal

Aspen OnLine 12.1 User Guide Online Project Development • 3-11

 tags set by Aspen OnLine. However, you cannot add a new Signal
status within Aspen OnLine.
Adding tags You must add and define all project tags other than Signal tags. To
add a new tag to the project, open a Data Browser in the Client
GUI and then expand the Tags folder in the tree. There are two
views for tags: Specifications view (or single view) and Grid
View. With the single view, you can view information about one
tag at a time. Grid view allows you to view many tags
simultaneously. Click the Tags | Grid View form to use grid view.

If Aspen Process Explorer (an Aspen Manufacturing Suite

product) is installed on the machine Client GUI is running, there
will be six command buttons on the Tags | Grid View | Tag
Definition sheet: Tag Browser, New, Edit, Delete, Spec view,
and Plot. Otherwise, the Tag Browser button will not be present.
The Tag Browser button makes definition of DCS tags much
easier. See the Select Plant Tags Using Tag Browser section on
page 4-4 of Aspen OnLine Tutorial version 12.1 for step-by-step
instructions. If Aspen Process Explorer is not available, then DCS
tags have to be manually entered. Local tags, Formula tags,
Manual tags, SSD tags and Average tags are always entered
manually or using a delimited text file.
The New, Edit and Delete buttons are used to add, edit and delete
tags respectively. To manually add a tag, click New. The following
dialog box will appear:

3-12 • Online Project Development Aspen OnLine 12.1 User Guide

 Use this dialog box to specify Tag name, tag Description, Units
type, Source units, Display units, Tag type and Output to IMS
option. Data type is typically Float. There are other data types
available depending on the tag. Set Output to IMS to Yes if the
value of the tag is to be sent to an IMS. (This is not applicable for
Aspen Plus EO models.) Setting Output to IMS to Yes for DCS
tags is not allowed.
Note: Tag names must be unique within an online project. Aspen
OnLine is case-insensitive, which means that tag names f-test2 and
F-TEST2 are considered to be the same, so you cannot use them
for two different tags within the same project.
Specifications for a sample tag are shown below:

Aspen OnLine 12.1 User Guide Online Project Development • 3-13

 Notice that there is an extra Validate button on this dialog box.
This button appears when the tag to be added is a DCS tag or if
Output to IMS is set to Yes. Click Validate to open another
dialog box, shown below:

The dropdown list for Cim-IO device contains a list of Cim-IO

devices defined in the Cim-IO logical device file on the server
machine. Click OK to close the above dialog box and fill the
original Add Tag dialog box with information from the IMS for
the corresponding tag.

There are several items to be noticed here. First, the IMS

corresponding to the Cim-IO device (IOSETCIM200, in the
example above) must have a tag of the same name defined;
otherwise, validation will fail. Secondly, tag Description and
Source units are retrieved and used to fill the above dialog box if
the unit for this tag is defined in the corresponding IMS.
Lastly, if Aspen OnLine cannot find a match between the units
defined in the IMS for the tag and the existing units (built-in and
custom), then a dialog box will appear asking you to find a match.

3-14 • Online Project Development Aspen OnLine 12.1 User Guide

 Either search for a match or create a new units type and/or new
units.
This validation process also fills the Cim-IO device and Cim-IO
source attributes for the tag.
If the tag to be added is not a DCS tag and its value will not be sent
to any IMS, then the Validate button will be invisible. Click Add
to complete the addition of the tag.
Important: Click Add for the last tag to be added before clicking
Quit. This forces Aspen OnLine to save the last-specified tag.
Writing Aspen OnLine tag The values of internal application tags (all tags other than DCS
values to the plant IMS tags) can be written to the plant IMS for further data analysis and
later trending. Thus, equipment performance parameters such as
heat exchanger fouling coefficients or catalyst activities that are
calculated in Aspen OnLine projects can be stored in the plant IMS
and trended. However, values are written only after the successful
execution of scheduled calculations (automatic, background runs).
Important: The value of any internal application tag can be
written to any valid tag in the plant IMS. You must ensure that
Aspen OnLine tag values are written only to tags that are created
in the plant IMS specifically for the purpose of storing these
values. Extreme care should be taken to prevent the accidental use
of tags that are configured for purposes other than storing model
results. If Aspen OnLine tag values are carelessly written to IMS
tags that have other uses, this can trigger undesirable effects.
To enable the writing of Aspen OnLine tag values to the plant
IMS:
1 Create a tag in the plant IMS to receive and store Aspen
OnLine tag values; this tag will be referred to as the target IMS
tag.
2 Create an internal application tag in Aspen OnLine with a
name identical to the tag in the IMS that will receive its value.
3 Set the Output to IMS attribute of this Aspen OnLine internal
application tag to Yes. This tag will henceforth be referred to
as a write-back tag.
To store the values of an Aspen OnLine tag in the plant IMS:
1 Create a tag in the plant IMS to receive values from Aspen
OnLine. Initialize this tag with an initial value using the IMS’s
own desktop tools.
2 On the Data Browser | Tags | Grid View | Tag Definition
sheet, click the Tag Browser button and drag and drop the
newly created IMS tag. Then click the Edit button to change
the tag type from DCS to any internal application tag type.

Aspen OnLine 12.1 User Guide Online Project Development • 3-15

 Alternatively, use the New button to create a new internal
application tag with a name that is identical to the newly
created target IMS tag.
3 Select Yes for the Output to IMS option in the Edit Tag or
Add Tag dialog box.
4 Ensure that the Source units for the write-back tag are the
same as the units specified for the target IMS tag. If the units of
the write-back tag are different than those of the target IMS
tag, the value of the former will be sent to the latter without
performing units conversion.
Editing tag information To edit an existing tag, select the corresponding row of the grid on
the Data Browser | Tags | Grid View | Tag Definition sheet, then
click Edit. The following dialog box will appear:

Make changes and then click OK to save changes.

Deleting tags To delete a tag, select the corresponding row of the grid on the
Data Browser | Tags | Grid View | Tag Definition sheet and then
click Delete. Note that Aspen OnLine will check whether the tag to
be deleted is referenced by another part of the configuration such
as a variable or a formula tag. If it is referenced anywhere within
the project, then deletion is not allowed.
If you want to delete multiple tags, an efficient method is to list the
tags to be deleted in a text file, then select the Import command
from the File menu to open the Import Project Configuration
Information dialog box. Click the Tags tab, and select Delete tags
at the top. Specify the name of the text file as the Input file name,
then click Import. Tags in the text file will be deleted if they are
not referenced by other specifications.

3-16 • Online Project Development Aspen OnLine 12.1 User Guide

 Define Models Process models from Aspen Plus, Hysys, and ACM-based
applications can be brought into online projects. Models that are
being used with an online project should be thoroughly tested
before they are used in the project.
Ensure that Aspen Plus models are not set to Load Results
Interactively. This is set in the Aspen Plus User Interface. Clear
Load Results Interactively in the Run tab of the Tools | Options
dialog box. If results are loaded interactively, values of output
variables in Aspen Plus will not be available to the tags to which
they are linked in the project.
Add process models 1 In Aspen OnLine Client GUI window, open a Data Browser.
2 Click the Models node in the tree view on the left portion of
the Data Browser. The Model Selector sheet appears.
3 Click New. The Open dialog box appears. The default Files of
type are *.bkp and *.apw. To bring in a model from an ACM-
based application, change Files of type to the appropriate type.
4 Browse to select the desired file and then click the Open
button. Note that the directory where the model resides is the
model’s offline directory, which may or may not be the
OffLine folder within the project’s directory structure.
5 The Open dialog box closes and the new model name appears
on the Models grid on the Model Selector sheet. Also, the
model name is listed under the Models folder as a new folder.
Model names must be unique within a project. Aspen OnLine is
case-insensitive in this regard, so model names pfdtut.bkp and
PFDTUT.BKP are considered the same and are not allowed to
exist in the same project.
Perform offline-to-online After a model is added to the Aspen OnLine project, the model
for process models name appears as a folder under the Models folder in the Data
Browser. Clicking this folder will display a form for model-
specific specifications. The first thing to do for this model is to
perform an offline-to-online operation. This operation will do the
following:
1 Generate the model variable list.
2 Copy files from the model’s offline directory to the model’s
online directory.
By default, the model’s online directory is the OnLine folder
within the project’s directory structure. However, this can be
changed on the Data Browser | Models | model name | Case and
Directory sheet. Note that the directory path is the path on the
server machine.

Aspen OnLine 12.1 User Guide Online Project Development • 3-17

 To perform offline-to-online for a model, open the Data Browser |
Models | model name | Specifications sheet and click Offline to
online.
The following dialog box appears:

The Messages field is used to display operation status. The Offline

model time stamp displays the time stamp of the model in the
model’s offline directory. The Variable list time stamp displays
the time stamp of the variable list for this model. File not found is
displayed when the offline-to-online step has never been
performed before and the variable list does not exist. If the variable
list does not exist or the time stamp of the variable list is older than
that of offline model file, then, (Re)create variable tree from
model is selected by default. If this checkbox is selected, the

3-18 • Online Project Development Aspen OnLine 12.1 User Guide

 variable list is generated and files from the offline directory are
copied to the online directory. You can choose which files from the
offline directory should be copied to the online directory.
Click Start to begin the offline-to-online operation. When
complete, the above dialog box will close automatically and the
model variable tree becomes available on the Variable-Tag
Mapping sheet for this model. At this point, you can link variables
and tags.
Link model variables to It is very important to correctly identify model variables when
tags linking them to tags. Read the Understanding the Model
Variable Structure section in this chapter if help is needed. To
link a model variable to a tag, follow these steps:
1 Open the Aspen OnLine Client GUI | Data Browser | Models |
model name | Variable-Tag Mapping sheet. All tags in the
project are displayed in the All tags grid on the upper left
portion. The variable tree for the model is displayed on the
upper right portion. The Mapping summary grid summarizes
variable-tag mapping between variables in this model and
project tags.
2 In the variable tree, locate the model variable to be mapped to a
tag.
3 Select a project tag from the All tags grid, then drag it and drop
it onto the model variable of interest.
4 The Tag links for model variable dialog box appears:

Note that the Variable name with full path and the Variable
units in model are retrieved and displayed. The program uses
the units to match existing units in the project and fills
Variable units type and Variable units automatically. If the

Aspen OnLine 12.1 User Guide Online Project Development • 3-19

 program fails to find a match, Dimensionles and Unitless are
used as Variable units type and Variable units respectively. In
such a case, you must find a match manually or create custom
units type or custom units if necessary. You can change
Variable units type and Variable units, but not Variable
units in model. It is very important to ensure that the units
type of the variable and the units type of the tag are the same.
Otherwise, an error will occur during run-time due to unit
conversion failure.
5 A tag can be linked to a variable from an Aspen Plus or Hysys
model as Source tag or Target tag. Source tags supply values
to variables and target tags accept values from model variables.
A tag can be linked to a variable from an ACM-based model as
a Source tag, Simulation output tag, Estimation output tag
or Aspen Utilities Optimization output tag.
6 Click OK to complete the link.
Linking variables to tags actually defines variables for the
online project. Linked model variables are listed on Data
Browser | Variables | Grid View | Specifications sheet.
To undo a link that has been made between a project tag and a
model variable, in the model variable tree, click the right
mouse button on the model variable and then click Break link
to tag. Another way to break a link is to delete the variable on
the Data Browser | Variables | Grid View | Specifications
sheet.
Alternatively, you can use a delimited text file to define links
between model variables and tags.
Update process models Even after process models have been brought into an online
project, you may still find it necessary to update models in offline
directories. Understanding how Aspen OnLine programs access
model variables will make the model updating process an easy
task.
Aspen OnLine programs identify a variable by model name (such
as HEATXN1.BKP) and variable name with full path (such as
ROOT.DATA.BLOCKS.VALVE.INPUT.P_OUT). Aspen OnLine
is case-insensitive in this regard. If the name of the model file has
been changed, you must rename it within the project in order for
Aspen OnLine to recognize it as the same model. To do so, on the
Models | Model Selector sheet, select the row listing the old name
of the model, and click Rename. In the Rename Model dialog
box, enter the new name of the model.
After a model update, you should perform the offline-to-online
operation again to update model files in the online directory and to
update the variable list. Note that the variable list also contains

3-20 • Online Project Development Aspen OnLine 12.1 User Guide

 information such as variable units and values. Therefore, variable
list should be updated if model variable structure, variable units, or
new variables have been added.
Delete process models The following steps show how to delete a model from a project.
1 Open a Data Browser in the Client GUI and then go to the
Data Browser | Models | Model Selector sheet
2 On the Models grid, select the row corresponding to the model
to be deleted and then click Delete. The model will be deleted
from the project.
Note that all links between tags and variables from this model
are also deleted automatically. In other words, variables
associated with this model that have been defined in the project
are also deleted.
Deleting a model from the project does not affect model files in
the offline directory.
Data analysis options Aspen OnLine provides capabilities to independently specify
whether data for a given model is to be subjected to steady-state
detection and/or data validation requirements. For example,
models used for what-if analysis are, by their very nature, based on
the hypothetical data the user enters and therefore are not
dependent on whether the plant is at steady-state. Similarly, what-
if analysis may be used to evaluate potential plant modifications
and, as such, one may wish to evaluate conditions that are beyond
the validity limits of some plant tags.
These are examples of cases where it would be acceptable not to
impose steady-state detection requirements or data validation on
the specific what-if models. The online project may involve other
models that should require steady-state detection and data
validation. Regardless of the options selected for any one model,
Aspen OnLine performs data validation (DV) and steady state
detection (SSD) according to specifications on the Data Browser |
Tags | Grid View | Data Validation sheet and SS Detection sheet.
The options only apply to whether or not a model will be allowed
to execute if there are data validation or steady-state detection
violations.
To choose an option simply select or clear the Steady-state
detection required or the Data validation required boxes.
Variable Attributes As mentioned earlier, linking tags to model variables actually
defines variables for the online project. All model variables that
have any links to tags are listed on the Data Browser | Variables |
Grid View | Specifications sheet. Use sheets in the Variables |
Grid View form to specify other attributes for variables.

Aspen OnLine 12.1 User Guide Online Project Development • 3-21

 Variable units When you link a tag to a model variable, you have the chance to
specify the variable units type and units. The Data Browser |
Variables | Grid View | Specifications sheet is another place
where you can modify variable units type and units. This is not
applicable for Aspen Plus EO models.
Default values for model Aspen OnLine can provide default values for model variables
variables when the quality of data values for model inputs is deemed bad.
This applies to either actual plant values (whose quality is denoted
by the plant DCS/IMS quality attribute for each tag) or internal
application tags. The default value is in the same units as the
model variable units.
1 Enter desired default values for model input variables in the
Default value column of the grid on the Data Browser |
Variables | Grid View | Backup Data sheet.
2 Select the appropriate bad plant data replacement option in the
Bad data flag column on the same grid. See the Bad plant
data replacement options section below.
Aspen OnLine does not use default values for model output
variables.
Critical variables A critical variable is one for which the model cannot tolerate bad
input data of any sort. Thus, if the input data for a critical variable
fails data validation, model execution is not allowed. Similarly, if
the associated plant data has bad quality, model execution is not
allowed.
As an example, a feed stream to a purification tower has an
impurity that normally ranges from 3% to 6%. This stream is the
product of a reactor. It is known that the maximum physically
possible concentration on the outlet of the reactor is 10%. The
online application focuses on the purification system and is
entirely dependent on the amount of this impurity. This variable is
specified as critical and its upper validity limit is set at 10%.
Performing any modeling calculations when the plant value is
greater than 10% may actually cause the model to encounter
convergence problems.
To specify a variable as critical, do the following:
1 Go to Data Browser | Variables | Grid View | Specifications
sheet.
2 Locate the row corresponding to the variable of interest on the
grid.
3 Select the checkbox in the Critical column.
Note that if a variable is specified as critical, validity limits for the
corresponding source tag should be provided, but the Clamp at

3-22 • Online Project Development Aspen OnLine 12.1 User Guide

 lower limit and Clamp at upper limit check boxes for the linked
tag should be cleared (Data Browser | Tags | Grid View | Data
Validation sheet). If clamping is specified, the criticality definition
of the variable is the overriding criterion, and model execution will
not proceed with a critical variable whose value has been clamped.
Bad plant data Tags in the online project have values and qualities. Examples of
replacement options qualities include Good, Bad, Clamped and Exceeded validity limit.
For example, if Aspen OnLine fails to get the value from IMS via
Cim-IO for a DCS tag, then this DCS tag will have a bad quality.
Aspen OnLine allows you to specify optional backup data to use in
place of bad data, using the Bad data flag column on the Data
Browser | Variables | Grid View | Backup Data sheet. Backup
data options are:
• Last good value, default is the default option. If this option is
selected, Aspen OnLine will first look for the last good value
available for the model input variable. If a last good value
cannot be found, then it will use the default value provided in
the Default value column for this variable on the Data
Browser | Variables | Grid View | Backup Data sheet.
• Last good value – If this option is selected, Aspen OnLine will
only look for the last good value available for the model input
variable. If a last good value cannot be found then model
execution will not proceed.
• Default – If this option is selected, Aspen OnLine will use the
default value provided in the Default value column for this
variable on the Data Browser | Variables | Grid View |
Backup Data sheet. If the default value is unacceptable, that
is, it violates validity limits, then model execution will not
proceed.
Data Validation for Validity ranges and options to handle out-of-limit data are
Tags specified on the Data Browser | Tags | Grid View | Data
Validation sheet.
• Enter the desired lower limit value for a tag in the Lower limit
column. This will be the lowest allowable valid value for this
tag.
• Enter the desired upper limit value for a tag in the Upper limit
column. This will be the highest allowable valid value for this
tag.
Upper limit and lower limit values can be provided for all write-
back tags. This is to ensure that unreasonable values are not sent to
and stored in the IMS.
There are three possible actions if a tag value violates its upper or
lower validity limit.

Aspen OnLine 12.1 User Guide Online Project Development • 3-23

 • A warning is recorded in the project’s event log file but the
model execution is allowed to proceed with the value in excess
of the validity limit.
• The tag value is clamped, or replaced with the validity limit
value that is being violated. Model execution then proceeds
with this clamped value.
• Model execution is not allowed.
As for data validation of write-back tag values:
• If validity limits are not provided for write-back tags, Aspen
OnLine will record a warning in the Event Log upon initial
execution of the application that the values will not be checked
against validity limits since none were provided.
• For write-back tags that are Local tags, Formula tags or
Manual tags, if validity limits are provided and the write-back
tag value violates a limit, the value will not be stored in the
IMS and the data validation error will be recorded in the Event
Log.
• For write-back tags that are SSD tags, Average tags or Signal
tags, if validity limits are provided and the write-back tag value
violates a limit and the clamp flag is on for this limit, then the
clamped value is sent to the IMS.
• Of course, the actual value of any write-back tag with good
quality (its value does not violate any validity limit) will be
sent to the IMS.
The Clamp at lower limit and Clamp at upper limit checkboxes
on the Data Browser | Tags | Grid View | Data Validation sheet
and the Critical checkbox of the linked model variable on the
Data Browser | Variables | Grid View | Specifications sheet
control these options:
• To allow model execution with a value that exceeds validity
limits with a warning only, clear all three checkboxes.
• To allow model execution with a value clamped at its validity
limit, select the Clamp at lower limit box and/or the Clamp at
upper limit box and clear the Critical box.
• To prevent execution when a tag value exceeds its validity
limit, select the Critical box. It is irrelevant whether the
clamping is specified, as it is superseded by the critical
definition of the model variable.
The tag values made available to the end-user GUI at run time are
the actual values sent to the model. The status (such as clamped) is
also available so that, in building the GUI, you can graphically
establish its condition. For example, if a tag was clamped at its
limit, the background color of the display field could be changed to

3-24 • Online Project Development Aspen OnLine 12.1 User Guide

 yellow as a visual warning. All abnormalities and how they were
handled are noted in the Event Log. Values sent to the model are
recorded in the Run Log.
Steady State The Data Browser | Tags | Grid View | SS Detection sheet is
Detection used to provide criteria with which Aspen OnLine can judge if the
Specifications plant is running at steady-state conditions or not. Models that are
specified to require steady-state conditions (Data Browser |
Models | model name | Specifications sheet) will not be executed
if any of the tags specified in the SS Detection sheet violate their
corresponding steady-state criteria.
Typically, steady-state detection is performed for DCS tags.
However, Aspen OnLine allows steady-state detection for Local
tags and Formula tags as well.
1 Select the tags to be used to determine if the plant is in steady
state operation. Typically, a small number of the plant tags
used in an online project can be used as reliable indicators of
steady plant operation. For those tags, enter information as
described below. Tags that have zero values for Tolerance and
Trend tolerance are not used in steady-state detection.
2 In the SS method field for each of these tags, select one of the
two SS methods, Heuristic or Statistical. A brief description of
SSD methods is given in the Steady-State Detection section in
Chapter 2, Concepts and Definitions. A more detailed
description can be found in the Appendix. Each tag can use
either method independently of the method selected for other
tags. When the overall plant steady-state check is performed,
each tag is checked individually using the method that is
specified on this form.
3 Enter the Tolerance value for each tag of interest. In the
heuristic method, if the maximum absolute value of the
difference between any two corresponding light-filtered and
heavy-filtered values exceeds the tolerance value, the tag will
fail the SSD criterion. The tolerance value for the heuristic
method should be based on a knowledge of the range over
which a tag value fluctuates during normal, steady operation. A
tolerance value is not mandatory with the statistical method.
However, a positive value for tolerance could have the effect of
increasing the probability that a tag will be considered steady.
4 Enter the Trend tolerance value for each variable that will be
checked with the heuristic method. Trend tolerance is used to
determine if a tag value has a significant trend over a time
period. If the absolute difference between the oldest and newest
heavy-filtered values of a tag exceeds the trend tolerance value,
the tag will fail the SSD criterion. Trend tolerance is used only

Aspen OnLine 12.1 User Guide Online Project Development • 3-25

 with the heuristic method. A trend tolerance input value for a
tag should be based on an understanding of the typical tag
value fluctuation range for normal, steady-state operation.
5 Enter fractional values for Light filter and Heavy filter factors
to calculate moving averages of tag values for the heuristic
method. The default values are 0.8 and 0.2 respectively for the
Light filter and Heavy filter. A light filter is one that
emphasizes the current value. Thus a light filter of 0.85 will
give 85% consideration to the current tag value and 15% to its
previous values. In much the same fashion the heavy filter
emphasizes the previous values over the current value. Light
filter values typically range from 0.7 to 0.95 and heavy filter
values from 0.05 to 0.3. The values of the light and heavy
filters are independent of each other and they do not have to
add to 1.
6 Enter a time span in minutes over which historical values are to
be considered for SSD. For each tag, Aspen OnLine uses the
history of values in the user-specified SS timespan to calculate
light-filtered and heavy-filtered values to implement the steady
state check according to the heuristic method. In the statistical
method, the SS timespan determines the number of samples for
calculation of the variance and mean values for each tag. A
value of zero for SS timespan means no steady-state detection
for this tag. The minimum number of values needed to
implement steady-state detection for a tag is 5.
7 The result of the steady-state detection for individual tag can be
sent to an SSD tag by specifying an SSD tag in the SSD output
tag column.
Any one model in the project can be independently required to
meet steady-state detection criteria. This is specified on the Data
Browser | Models | model name | Specifications sheet. Models for
which steady-state conditions are required will be executed only if
all tags selected for SSD evaluation meet their corresponding SSD
criteria. Any single tag failing its criteria will prevent the model
from being executed.
These specifications are required for each tag with steady state
detected by the heuristic method:
• SS method = Heuristic
• Tolerance
• Trend tolerance
• Light filter (default = 0.8)
• Heavy filter (default = 0.2)
• Time span

3-26 • Online Project Development Aspen OnLine 12.1 User Guide

 These specifications are required for each tag with steady state
detected by the statistical method:
• SS method = Statistical
• Tolerance
• Time span
In addition, you may specify an SSD output tag for any tag with
steady state detection.
Manual Tag Values for Manual tags should be input on the Data Browser |
Specifications Tags | Grid View | Manual Input sheet. Use the Manual input
value column to enter values for each of the Manual tags in the
same units as the corresponding source units.
Manual tags are used to hold values that require only infrequent
updates online.
Formula Tag Formula tags are related to other tags in the online project by
Specifications mathematical formulas defined on the Data Browser | Tags | Grid
View | Formula sheet.
All Formula tags created on the Data Browser | Tags | Grid View
| Tag Definition sheet are also listed on the Data Browser | Tags |
Grid View | Formula sheet.
The syntax for a formula in Aspen OnLine is
[FormulaTag] = Mathematical function of [project tags]
where any project tag, including another Formula tag, may be used
as part of a mathematical expression on the right hand side.
In the Formula column, enter the formula by which a Formula tag
is related to any other project tag(s). Any mathematical operation
permitted in Microsoft Excel may be used. The mathematical
operators used should be identical to those in Microsoft Excel. A
formula may include any tag for which a value is available. Hence
one Formula tag may be related to another Formula tag as long as a
circular relationship is not established.
• In the formula, each tag name must be enclosed in square
brackets. For example to multiply tag F-206 by tag F-403, the
formula is typed in as [F-206]*[F-403].
• In the Formula column, entering a square bracket causes all
project tags to be listed. The desired tag can be selected from
this list.
Formulas with no Formula tags in the right hand side are
calculated first. After that, formulas involving Formula tags in the
right hand side whose values have already been computed are
calculated.

Aspen OnLine 12.1 User Guide Online Project Development • 3-27

 Users must ensure dimensional consistency while creating
formulas.
Encrypted formulas Password-protected formula encryption is allowed. You can
selectively encrypt individual formulas. On the grid, first click a
formula cell to make it active. Then click the right mouse button
and select Encrypt Formula, Decrypt Formula, or Delete
Encrypted Formula from the menu.
For each Data Browser, you must confirm the password for
formula encryption before any encryption or decryption can be
performed. This password is initialized to an empty string and can
be changed. To change it, click Change encryption password on
the Data Browser | Tags | Grid View | Formula sheet. A dialog
box appears, allowing you to change the password. The password
should not exceed 31 characters.
The password for formula encryption is project-specific or project-
based rather than computer user-based. This gives the flexibility
that an engineer who does not have full control of one project can
have full control of another project.
If a formula is encrypted, "PROTECTED:*******" is displayed in
the corresponding cell, where the number of "*"s is equal to the
number of characters in the original formula. Once encrypted, the
cell cannot be manually edited except for deletion.
To delete an encrypted formula, right-click on the cell and select
Delete Encrypted Formula.
To edit an encrypted formula, first decrypt the formula to convert it
back to the formula in plain text. After you finish editing, you may
choose to encrypt the formula again.
If you forget your password for formula encryption, Aspen OnLine
customer support should be contacted to retrieve the password.
There is almost no way to recover the original formulas without
the password.
To reset a password without knowing the original password, delete
all encrypted formulas and then choose a new password for
encryption. It is recommended that a hard copy of formulas to be
encrypted be kept in a secure place.
128-bit encryption is not used during encryption implementation to
avoid international export regulations on encryption technologies.
Tag Initialization The value of any Local input tag may be initialized with the value
of another tag such as a DCS tag or a Manual tag. Data Browser |
Tags | Grid View | Initialization sheet may be used to specify the
source of initialization of the values of the Local tags.

3-28 • Online Project Development Aspen OnLine 12.1 User Guide

 1 Click the Init tag column in the row for the Local tag whose
value is to be initialized. A list of all tags in the project
appears. Select a tag whose value should be used to initialize
the value of the Local tag.
If a tag has previously been configured to be initialized by
another tag, but now initialization is to be canceled, select the
blank item (the first item) in the tag list. Alternatively, you can
just delete the tag name from the Init tag column.
2 The Init Data button action in the GUI Configuration
initializes tags in run mode.
Local tags that are used to present output results are not initialized.
Model Execution Model calculations can be specified to be automatically performed
Scheduling at desired times of the day and/or at a desired frequency every day
or based on the steady-state condition of the plant. This can be
configured on the Data Browser | Models | model name |
Schedule sheet. To schedule automatic model executions for a
model, follow these steps:
1 In the Client GUI, open a Data Browser and go to the Models |
model name | Schedule sheet
2 Select the Enable fixed time scheduling checkbox to automate
model execution at specified times during the day. If you select
this option:
• Specify the number of fixed-time runs. Up to eight fixed-
time runs can be specified for each day. For instance, a
model may be scheduled to execute at 10:00 AM, 1:45 PM,
and 7:35 PM each day.
• In each of the boxes that appear below, use the two
underlined input fields to specify the time of day when the
run should be executed. Use two digit numbers for hours
and minutes. For instance, to specify 10 AM and 7:35 PM,
enter 10:00 and 19:35 respectively.
3 Select the Enable fixed-interval schedule checkbox to specify
model execution at fixed intervals during the day. For example,
a model may be scheduled to execute every 2 hours during a
day. If you select this option:
• Specify the interval in minutes at which the model
calculations are to be run. For instance, to run the model
calculations every two hours type in the number 120 in the
Interval field. Do not use fractional values for the interval.
• Use the two underlined input fields in the Start every day
at field to specify the time of day when the first model
calculation should start each day. Use two digit numbers

Aspen OnLine 12.1 User Guide Online Project Development • 3-29

 for hours and minutes. For instance, 7:35 PM should be
entered as 19:35.
• Input the time duration in minutes after which model
calculations should be automatically retried when
scheduled calculations fail to execute. If no time duration is
specified, the model calculations will be retried according
to the defined schedule.
For Aspen Plus EO models driven by steady-state detection, these
two options should not be selected.
Cim-IO Connection Sources of DCS tags and the device in which target IMS tags are
Form located should be specified on the Data Browser | Tags | Grid
View | Cim-IO sheet. In addition, data to mimic a plant may also
be provided in this form. This can facilitate testing online project
execution without actually connecting to plant data. It is
recommended that a test be made using the same values for model
variables as those used in the stand-alone version of the model
(before being incorporated into the online application). Comparing
results can confirm that all transfer of data, back and forth, has
been configured properly.
Tag name DCS tags (which provide input values to the online projects) and
write-back tags (which transmit values from the online projects to
plant IMS) that are specified on the Data Browser | Tag | Grid
View | Tag Definition sheet are automatically listed on the Cim-
IO sheet.
Cim-IO device Enter the device name corresponding to the data source or the
write-back destination of the tag. This is the same device name as
the one entered during the Cim-IO configuration (see Specifying
Logical Devices in the AES Installation Manual). IOSETCIM200
was the device used in the example given in the Testing Cim-IO
Access to Plant Data section. Device names for which Cim-IO
has been configured can be selected from a drop-down list. Only
device names that are listed in the drop-down list can be selected.
In case of multiple Cim-IO devices, you must know which tags
correspond to which devices. If device names are not specified, tag
values cannot be retrieved from the data source or written to data
targets.
Cim-IO device information can be found in
%CIMIOROOT%\etc\cimio_logical_devices.def
This information is server dependent. Please refer to the specific
Cim-IO interface document for more information.
Ordinarily, the first step in online application development is the
verification of access to plant data. This ensures that the
communication links are working properly and that information

3-30 • Online Project Development Aspen OnLine 12.1 User Guide

 from the various DCS/IMS tag types can be properly accessed.
Aspen OnLine communicates with the Cim-IO server to verify the
existence of plant tags during configuration and execution.
In special situations where you are developing a project and do not
yet have access to the plant data server, development of the project
can proceed, but you must be careful not to specify a Cim-IO
device on the Data Browser | Tags | Grid View | Cim-IO sheet.
This will prevent Aspen OnLine from attempting to verify the tag
and disqualifying it upon not being able to access it, which would
result in the tag not being stored in the engine database.
Cim-IO source This is the data source or destination type. The most commonly
used type is DBVL and should be used as a default entry. This
information refers to the data type source of the variable value in
the Cim-IO kernel and in the corresponding source Cim-IO device.
For example, DBVL implies that the kernel treats the value as real
and the source Cim-IO device treats it as real. A list of other Cim-
IO source data types is given in the Appendix.
Cim-IO format Typically this entry is left blank. It refers to a two-letter database
format code. Its use is reserved for special circumstances.
The first character indicates tag case sensitivity and the second
character indicates tag space sensitivity.
The first character can be U for converting to Uppercase, L for
converting to Lowercase, or N for No change to the case.
The second character can be T for Trimming of trailing spaces, C
for Compressing spaces, or N for No change to spacing.
The default format is UN, that is, uppercase and no change in
spacing.
Cim-IO unit Ordinarily this entry is left blank. It refers to the Cim-IO unit
number that is treated as the gateway ID.
Note: Cim-IO unit information can be found in
%CIMIOROOT%\etc\cimio_logical_devices.def.
This information is Cim-IO server-dependent. Please refer to the
specific Cim-IO interface document for more information.
Test value This is an input test value that can be used for a tag when the
project runs in test mode (without connecting to plant DCS/IMS).
This input is optional. See the Test Mode versus Connect to
Plant Database Mode section below for more details.
Test value status Select whether the quality of the test value is to be considered good
or bad. This is to mimic a real plant where data may be good or
bad depending on the instrumentation. This is for off-line testing of
the bad data replacement procedure in Aspen OnLine. Test value

Aspen OnLine 12.1 User Guide Online Project Development • 3-31

 status is used when online project runs in test mode. See the Test
Mode versus Connect to Plant Database Mode section below for
more details.
Tag Average Values of DCS tags, Local tags and Formula tags can be averaged.
Specifications To enter average specifications, do the following:
1 In the Client GUI, open the Data Browser | Tags | Grid View |
Average sheet.
2 Specify average period in minutes and optionally average
output tags. The default value of average period is 0 minutes. A
value of zero for average period means no average to be
performed. Average tags are used to store average values for
tags.
Miscellaneous DCS tag values, and any project tag values that depend on them,
Specifications can be updated at user-specified frequencies for display in the end
Update Interval user GUIs of the project. The Update interval should be specified
in minutes. The default value for display update frequency is 1
minute. The value can be changed on the Data Browser | Setup |
Specifications | General sheet.
Maximum Log File Size The size of log files grows as run-time messages are added. When
the file reaches its maximum size, Aspen OnLine renames the
current log file and creates a new log file using the same filename.
The default maximum log file size is 45,000 bytes. The default
value can be changed on the Data Browser | Setup |
Specifications | Reports sheet.

GUI Development
Aspen OnLine allows the user to build end-user GUI forms to
show various process areas and plant data together with model
results. These same GUI forms can be used to make what-if runs
(only for SM models). End-user GUI forms can be created and
configured using the Data Browser within the Client GUI. The
process of GUI development and its configuration consist of some
or all of the following activities:
• Adding forms for interactive run and presentation of online
project run-time information
• Adding pictorial representations of processing units to forms
• Specifying the project tags whose values are to be displayed
• Depicting other derived online project information, such as
values of economic performance parameters, that are calculated
within Aspen OnLine
• Adding any additional text to forms

3-32 • Online Project Development Aspen OnLine 12.1 User Guide

 • Providing interactive user input to model calculations
• Specifying conditional display of forms during project
execution based on values of tags
• Providing control buttons on the forms for common actions
that are to be executed via the screens, such as running
calculations, printing, navigating to other forms, and reading
log files
GUI Builder Features To add forms:
To add User GUI forms 1 In the Client GUI, open the Data Browser | User GUI |
Specifications sheet.
2 Click New.
3 Give a name for the form that is being added, and click OK.
The name of the new form appears in the grid on this sheet and
a blank end-user GUI form appears.
Forms may also be deleted or renamed.
To select and display To add a tag display on a form:
tags on forms
1 If the form is not yet open in design mode, open the Data
Browser | User GUI | Specifications sheet. Select the row
corresponding to the form where a tag display is to be added
and then click Edit. This puts the form into design mode.
2 Click the Add Tag button on the toolbar of the form
(Alternatively, click the Add Tag command on the Tools menu
of the main window). A Tag Browse dialog box appears. The
Tag name list contains all tags whose names match the Match
string. The default for the Match string is *, which means that
all tags that have not already been displayed on this form will
be listed. You can modify the match string to narrow down the
tag list.
3 Select a tag from the list and click the Display tag tagname
button.
The selected tag appears along with its units in the top left of
the form as a selected group.
4 Click the selected tag display group (tag value box and unit)
with the left mouse button and drag it to any desired location
on the form.
5 If the tag is not selected (because some other object on the
form has been selected), click the right mouse button on the tag
value box and select All GUI elements to select all the
elements of the tag display group. Then you can move it.
The tag value box can be resized. You can also right-click on the
object to access other properties of the tag value box.

Aspen OnLine 12.1 User Guide Online Project Development • 3-33

 To use graphical A wide variety of graphical images can be used to enhance the
representations of the graphical representation of the process on the GUI. Any image
process format supported by the Microsoft Picture object can be used.
Aspen OnLine provides a small library of 3D images representing
commonly used equipment such as vessels, heat exchangers, and
valves. Microsoft PowerPoint and other programs can be used to
create other images. It is recommended that the images have
transparent outlines; otherwise, a white (or other color) rectangle
will frame a non-rectangular object, such as a spherical vessel.
To incorporate graphical images:
1 In the Client GUI, open the form of interest in design mode.
2 Click the New Image button on the toolbar or click the Add
Image command on the Tools menu.
A highlighted image box appears at the cursor.
3 Select the location on the screen for the image and click to
place the image box.
4 Click the image box with the right mouse button and select
Load Image.
5 Browse to the location of the Aspen OnLine graphics library (a
subfolder in the Aspen OnLine system directory) or to any
image file created with any other software and select the image
file to be loaded by double-clicking the file name.
The selected image file is loaded in the image box on the
project screen. The image can be resized.
It is also possible to cut or copy and paste pictures from other
applications such as Microsoft PowerPoint directly to the image
box on the end-user GUI form in design mode.
Various images representing several pieces of equipment can be
copied to a project screen and connected using the line feature,
described below.
The display properties of an image can be accessed by clicking the
right mouse button while the cursor is on its image window.
To use lines to connect The line feature is a simple connector that can be used to connect
images two or more images and also indicate the direction of flow.
1 Begin the addition of a line to the form in design mode in
either of two ways:
• Click the New Line button on the toolbar
• From a project screen menu bar, select Tools | Add Line
An arrow within the line indicates the source of the line and its
destination.

3-34 • Online Project Development Aspen OnLine 12.1 User Guide

 A line can be originated only from an image box and must also
be terminated in another image box.
2 To connect two images by a line, click inside the image where
the line originates, then click inside the other image where the
line terminates.
3 To make corners on a line, while drawing the line click at a
point outside of image boxes where a turn in the line is desired.
Make as many turns as necessary and then terminate the line by
clicking in an image box..
To create a line that does not originate from or terminate at an
image box, place an image box at the desired point but do not load
an image into it. Draw the line as above and then delete the empty
image box.
To modify line and directional arrow properties, select Line
Properties from the Options menu. Changing these settings will
cause any lines drawn thereafter to inherit these properties. The
display properties of a specific line that has already been drawn
can be accessed by right-clicking on the line.
To display text and time Text and time stamps are displayed by means of size-adjustable
stamps on forms Labels. To add a label:
1 Click the New Label button on the toolbar, or select Add
Label from the Tools menu.
2 Click the location on the screen where the label is to be
displayed.
3 Click the right mouse button on the label box and select
Properties from the drop-down menu of options.
Text or Time Stamp display information can be provided from the
Label Properties dialog box.
To Display Text
Any text can be displayed on an Aspen OnLine end-user GUI
form. It can be formatted in many ways using frames or colors or
fonts.
1 Select Plain Text from the options available on the Label
Properties dialog box.
2 Enter the text that is to be displayed and select the desired
format for the label box.
3 To modify the display properties for the text itself, click the
text with the right mouse button and choose from the available
display properties.
4 If a text box is used as a frame for other text boxes, ensure that
its display property is set to send to back.

Aspen OnLine 12.1 User Guide Online Project Development • 3-35

 To Display Time Stamps
Time stamps of plant data and model calculations can be used to
indicate the last time a particular model was executed. To use time
stamps:
1 Select Time Stamp from the options available on the Label
Properties dialog box.
2 Select a time stamp of data or model calculations. For a time
stamp of model calculations, select the project model whose
calculation time stamp is to be displayed.
3 Select the desired format for the label box.
4 To modify the display properties for the time stamp, click the
time stamp with the right mouse button and choose from the
available display properties.
To incorporate command Aspen OnLine contains a library of built-inaction buttons for
buttons several common run-time commands such as run model, move to
another display form, and read log. Project screens can be
configured to use any of these buttons. To access a list of available
control buttons:
1 Click the New Button button on the toolbar of the form and
place a button on the screen. Alternatively, select Add Button
from the Tools menu.
2 Once the button has been placed on the form, right-click the
button and select Properties to enter a button caption and
select its function.
The default button commands provided include:
• Run Model – used to run any project model. A list of all
project models is provided. More than one model can be made
to run from a single command button by selecting the models
in the sequence in which they should run.
• Init Data – used to initialize run-time user-input fields with
plant data. This button must be used when a Local tag has been
configured to be initialized by another tag.
• Read Log – used to read the run-time Event Log, Run Log, or
Engine Log.
• Link to – used to link or move from one form to another.
• Print Form – used to send the current form to the printer.
• Timing – used to provide timing information on when the last
successful runs of each model were made, and how long they
took.
• System Information – used to provide Aspen OnLine system
information such as the availability of the Aspen Plus engine,

3-36 • Online Project Development Aspen OnLine 12.1 User Guide

 the number of clients connected to the server, the steady state
detection status, the tags that are presently clamped, and the
tags that presently do not meet steady state conditions.
• Exit With Saving – used to exit a project and save the
information that is displayed on the forms. Thus, the next time
the project is activated, the forms would display this saved
data, except for plant data tags (which are always updated with
current plant data) and formula tags that are based on plant
tags.
• Exit Without Saving – used to quit a project without saving
the information currently displayed on the screens.
• User Add-ins – used to provide additional functionality by
Aspen OnLine users. Trending of plant tags using Process
Explorer trend objects can be implemented within an Aspen
OnLine application by using the Trend Function provided in
the User Add-ins button. Incorporation of user-made
functionalities requires coding and is discussed in the
Advanced Features chapter.
Properties of display A brief description of various properties of display objects such as
objects Tags, Labels, Images, and Lines is given below.
• Hide/Unhide units – hide or make visible the units of
measurement of a tag.
• Number format – format the display of numerical values; i.e.
the number of decimal points, etc. The format is the same as in
Excel 2000.
• Freeze Data – do not allow the data to be changed from the
project screens.
• Locked – write-protect the field. Run-time user input fields
should not be write-protected.
• Font – modify font of text.
• Back Color – modify background color of display object.
• Fore Color – modify foreground color of display object.
• Bring to Front – bring display object to the front.
• Send to Back – send display object to the back.
• Condition Display – change the appearance of a selected
display object or enable an action based on user-specified
conditions.
To use conditional Aspen OnLine end-user GUI forms can be configured so that the
displays and actions appearance of display objects is triggered at run time when user-
specified conditions are satisfied. As a simple example, if the value
of a plant tag was outside its validity limits and it was configured
to clamp at its limit before sending to the model, you may want to

Aspen OnLine 12.1 User Guide Online Project Development • 3-37

 change the background of its display field to yellow as a visual
warning of this non-critical abnormality.
To make use of the conditional display capabilities of the end-user
GUI objects:
1 Select a display object (Tag, Image, Label, Line) whose
appearance is to be changed during run-time or a button whose
execution is to be enabled/disabled based on certain run-time
conditions.
2 Click the right mouse button and select Condition Display
from the menu, or, alternatively, select Condition Display
from the Features menu.
The Conditional Action dialog box appears.
3 Use the two left columns (the Action section) to specify the
run-time property change or action to be implemented with the
selected display object. Use the remaining four columns (the
Condition section) specify the criterion for implementing the
conditional action.
Each field has a dropdown list of possible choices. The list of
choices for the Value column in the Condition section will be
presented once the input in the Operator column has been
established.
Recommendations Below is a list of common buttons used in the development of end-
for features to user GUI forms:
incorporate in end- • Data Time Stamp – displays the last update time for data. This
user GUI forms is useful in diagnosing any difficulties arising out of failure to
communicate with the plant data server.
• Model Time Stamp – displays the time of the last model
calculation. This is useful in judging whether calculated values
are still valid.
• Run Model button – required to run on-demand, unscheduled,
model calculations from a GUI form.
• Print Form button – prints the GUI form on the default
printer.
• Read Event Log button – the Read Log function button with
the Event Log option. The Event Log records abnormal events
during project execution.
• Read Run Log button – the Read Log function button with
the Run Log option. The Run Log records values of input to
and output from Aspen Plus with the time-stamp of the
calculation. These values can be very useful in troubleshooting
problems related to model calculations.

3-38 • Online Project Development Aspen OnLine 12.1 User Guide

 • Read Engine Log button – the Read Log function button
with the Engine Log option. The Engine Log records the
actions the Aspen OnLine server engine takes and the
corresponding ID of the client that makes each request for
action.
• Init Data button – required if any tag display on the form is
configured (Data Browser | Tags | Grid View | Initialization
sheet) to be initialized by another tag.
• System Info – provides information on the Aspen OnLine
system, such as the status of the Aspen Plus modeling engine
(busy or available) and the current steady-state detection and
data validation conditions.
• Exit With Saving button – exits the project after saving the
information that is displayed on the forms. The next time the
project is activated, the forms would display this saved data,
except for the tags that are always updated.
The main form may be kept uncluttered by placing all system and
log access controls in a secondary form. This secondary form can
be reached by using the Link to function button.

Deleting an Aspen OnLine project

Aspen OnLine Project Manager can be used to manage online
projects on the server machine. Deleting a project is just one of the
management tasks. To delete a project, do the following:
1 Stop the steady-state detection program and engine program
associated with the online project to be deleted, using the
Control Panel in the Client GUI. Then, stop all clients that are
currently connected to this project.
2 Log on to the Aspen OnLine server machine hosting the online
project to be deleted. Alternatively, log on to an Aspen OnLine
server machine that can access the DCOM on the Aspen
OnLine server machine hosting the online project to be deleted.
3 Launch Aspen OnLine Project Manager by clicking Start |
Programs | AspenTech | Aspen Engineering Suite | Aspen
OnLine 12.1 | Project Manager. The Aspen OnLine 12.1
Project Manager dialog box will appear.
4 In the Computer field, enter the name of the Aspen OnLine
server machine hosting the project to be deleted. A list of
online projects hosted by the server machine is provided.
5 Select the online project to be deleted, then click Delete.
6 If the online project has a password, you will be asked to
confirm the password.

Aspen OnLine 12.1 User Guide Online Project Development • 3-39

 7 Click Close to shut down Project Manager.

3-40 • Online Project Development Aspen OnLine 12.1 User Guide

 CHAPTER 4

Running Online Projects

Users of Aspen OnLine fall in two categories: those who use it to

develop online applications, and those who are end-users of the
online applications. This chapter focuses project execution by the
end-users. The previous chapter describes online project
development.
End-users of online applications are generally only interested in
executing a previously developed and fully configured project.

Introduction to Running Online

Projects
Aspen OnLine allows the user to make configuration changes to an
online project while the online project’s steady-state detection
program and model engine program are running. Multiple online
projects can run simultaneously on a server machine.
Run Time Server and The basic functions of the Aspen OnLine Server and Clients are
Client Functions briefly described below:
• The Aspen OnLine Server provides:
− Plant data monitoring
− Control and execution of model calculations and any other
project calculations
− Management of the information flow between the plant
data server, the process models, and the user (client) GUIs
• The Aspen OnLine Clients are the interaction and presentation
layer to the end user of the online application. Thus, a client
transmits users’ run-time commands to the server and presents
the results of the server’s responses back to the users.
• Model executions scheduled on the Data Browser | Model |
model name | Schedule sheets are carried out by the server

Aspen OnLine 12.1 User Guide Running Online Projects • 4-1

 automatically, without any action from a client. All other
project calculations requested by users are executed only
interactively, when a client requests the server to do so.
• The Aspen OnLine client running on the same computer as the
Aspen OnLine server will be referred to as the local client.
Other Aspen OnLine clients running on separate computers
will be referred to as remote clients. Remote clients can
connect to an Aspen OnLine server accessible on the network.

What Programs Are Running and

When
The diagram below describes major components of Aspen OnLine.
A solid line means that the communications occur between
components residing on the same computer. Dashed lines are used
to indicate communications that can occur across the network.

SSD Client GUI

Client GUI
Client GUI

Engine

NT Service
Configuration

DCOM
SSD Client GUI
Client GUI
Client GUI

Engine

Configuration

Project Manager
Project Manager
Project Manager

If the Aspen OnLine 12.1 service is set for automatic startup, then
the Service component starts as the computer starts. The Service
then checks for an Aspen OnLine license. If the license check is
successful, it will then start DCOM. Otherwise, nothing further
will occur as far as Aspen OnLine is concerned.

4-2 • Running Online Projects Aspen OnLine 12.1 User Guide

 There can be only one Aspen OnLine 12.1 Service and one
instance of Aspen OnLine 12.1 DCOM running on each Aspen
OnLine server machine. When DCOM starts, it will start steady-
state detection programs and Aspen OnLine engine programs for
online projects that are hosted on this server if the projects are set
to start automatically upon reboot of the computer. More details
will be given about how to set the steady-state detection program
and engine program for automatic startup later.
For each online project, there could be three components running
on the server side:
• Steady-state detection component
• Aspen OnLine engine program
• Configuration server
The Configuration server component provides services to clients
for project configuration. For example, the user may want to
validate a DCS tag. The Client GUI component delegates the task
to the Configuration server component. The Configuration server
component is started when the first client connects to the online
project and is terminated when all clients disconnect from the
project.
Aspen OnLine Project Manager is a server component. It
communicates with DCOM components on Aspen OnLine 12.1
server machines. It is used to manage online projects. On each
server machine, only one instance of Project Manager can be
launched at any given time.
The Client GUI component can connect to online projects on a
server machine. Once connected to a project, a Client GUI session
only works with that particular project. On a client machine, there
can be multiple Client GUI sessions with each session connecting
to a different online project. Multiple Client GUI sessions from
different machines can connect to the same project on the same
server machine. However, please do not launch multiple Client
GUI sessions from the same computer and connect them to the
same online project.
Steady-State "Steady-state detection program" and "steady-state detection
Detection Program component" are used interchangeably in this document.
Sometimes, this component is also referred to as the Data Server
module. Use the Control Panel in the Client GUI to start and stop
this program.

Aspen OnLine 12.1 User Guide Running Online Projects • 4-3

 The upper left frame on the Control Panel | Status sheet in the
Client GUI is dedicated for controlling the steady-state detection
program and displaying its status. If the Automatic load and
Automatic run checkboxes are selected, then the steady-state
detection program will be automatically loaded and run the next
time the service starts. Use the Load button to manually load and
start this program when needed.
The steady-state detection component (or data server module)
performs steady-state detection, tag averaging, and tag value
storage for the online project. It is also responsible for fetching
data from IMS for any DCS tag for which steady-state detection is
performed and average value is calculated or tag value is trended.
It is also responsible for sending values to IMS for write-back tags
that are of types SSD, Average, and Signal. It also stores the global
set of values and qualities for all tags in the project. The Engine
component and Client GUI component retrieve the global set of
values and qualities from the steady-state detection program. The
term global set is used because the Engine component maintains
other sets of values and qualities for Client GUI clients, one set for
each Client GUI.

4-4 • Running Online Projects Aspen OnLine 12.1 User Guide

 Engine Program The main task of the Engine program (also called Engine module)
is to drive model executions for all models in the project according
to the schedule specified by the user. It also communicates with the
Cim-IO server to fetch values for any DCS tags for which either
steady-state detection is performed or the value is averaged or
trended. It is also responsible for sending values to IMS for write-
back tags of types Local, Formula, and Manual. The engine
program performs the following steps during a model execution:
1 Updates tag values by getting latest values from IMS and
recalculating values for formula tags
2 Performs steady-state and/or data validation check if required
by the model
3 Sets values for model input variables using corresponding
source tags
4 Launches relevant automation server (Aspen Plus, Hysys, or
ACM-based automation servers) to drive model run(s)
5 Retrieves values from model output variables and uses them to
set values of corresponding output tags
6 Unloads automation server
7 Sends values of write-back tags to IMS
The upper right frame on the Control Panel | Status sheet in the
Client GUI is dedicated to engine control and display. If Auto load
and Auto run boxes are checked, then the engine program will be
automatically loaded and run the next time the service starts. The
Load button and Start button (both dimmed in the screenshot
above) can be used to manually load and start this program. The
Engine program can be loaded and started only after the steady-
state detection program has been loaded because the steady-state
detection program is the data server for the other components of
the online project.

Connecting the Client GUI to the

Engine
To connect to the engine:
1 Ensure that the Aspen OnLine 12.1 service has been started on
the server machine hosting the online project.
2 Launch the Aspen OnLine Client GUI. The Aspen OnLine
Startup dialog box appears.
3 Select the appropriate server machine name and then project
name.

Aspen OnLine 12.1 User Guide Running Online Projects • 4-5

 If the client cannot connect to the server, it displays a dialog
box indicating this. Click the Help button on the dialog box to
see possible reasons for the failure.
4 The Startup dialog box closes and the Aspen OnLine Control
Panel appears within the Aspen OnLine main window.
5 Check the message displayed in the first panel of the status bar
at the bottom of the Control Panel. It should indicate whether
the client is connected to the engine.
If the client currently is not connected to the engine, check
whether the steady-state detection program and the engine
program have been loaded. Both programs must be loaded
before the client can connect to the engine. Click the Load
buttons to load both programs if necessary.
When the engine program is loaded from within the client, the
client connects to the engine automatically.
6 The user can disconnect this client from the engine or
reconnect to the engine using the first two buttons on the
toolbar of the Control Panel.
Note that when the steady-state detection program is loaded, the
Control Panel | Tag sheet is enabled and the user can view run-
time information for all tags. If the engine program is loaded and
the client is connected to the engine, the Control Panel | Engine
sheet and the Run-Time User GUI sheet are enabled. The
Control Panel | Engine sheet displays messages from the engine
program. The Control Panel | Run-Time User GUI sheet allows
the user to open end-user GUI forms in run-time mode.

Stopping Project Execution

On Client GUI | Control Panel | Status sheet, there are eight
buttons for controlling the steady-state detection program and
engine program. If the Unload button in the Steady-state
detection frame is enabled, clicking it will stop and unload both
the engine and the steady-state detection program. The user can
also choose to just stop and unload the engine program by clicking
the Unload button in the Aspen OnLine engine frame.
When the user interacts with the steady-state detection program
and engine program from the Client GUI, the request is passed to
the DCOM component. The DCOM component has direct control
over the steady-state detection and engine programs. Therefore,
when the Aspen OnLine 12.1 service stops, it stops the DCOM
component, which, in turn, will stop and unload steady-state
detection programs and engine programs of all online projects it
hosts.

4-6 • Running Online Projects Aspen OnLine 12.1 User Guide

 The steady-state detection program and the engine program are
started by the Aspen OnLine 12.1 service. These programs have
the characteristics of the DCOM services. Therefore, they continue
to run as users log on and off the machine, and they start and stop
as the service starts and stops.

Modes of Operation
Test Mode versus An online project can run in either of two modes:
Connect to Plant Data • Test mode – using test values and qualities entered on the
Mode Data Browser | Tags | Grid View | Cim-IO sheet
• Connect to plant data mode – using actual plant data
The mode is determined by the setting of the Disable Cim-IO
checkbox on the Data Browser | Setup | Specifications | Cim-IO
sheet. If this checkbox is selected, the Test mode is used.
Otherwise, Connect to plant data mode is used. This means that the
values of DCS tags are retrieved from the plant database and the
values of write-back tags are sent to the plant database.
The current mode is shown in the fourth panel of the status bar of
the main window. Note that each project can be in only one of
these two modes at any given time and all clients share the same
mode.
If the Disable Cim-IO checkbox is selected, then the online
project runs without connections to the plant database. The values
and qualities of DCS tags come from corresponding Test values
and Test value status, as specified on the Data Browser | Tags |
Grid View | Cim-IO sheet. Values of write-back tags are not sent
to the plant database. The Test values and their status are not
available for Aspen Plus EO models.
This Disable Cim-IO checkbox also affects tag validation during
project configuration. If you want to validate a DCS tag or write-
back tag, this checkbox must be cleared.
Interactive versus Clients connecting to the engine can operate in one of the
Engine Watch following two types of sessions:
• Interactive – A session in which the user can enter input data
and issue execution commands. The results presented are only
those in response to the data entered and to the commands
issued from this client.
• Engine Watch – in which the client passively watches the
automated scheduled calculations in the server engine.
Clients connecting to the engine can choose to run in Interactive
mode or Engine Watch mode independently of any other clients

Aspen OnLine 12.1 User Guide Running Online Projects • 4-7

 running at that moment. The user can switch between these modes
using Session options on the Control Panel | Run-Time User
GUI sheet.
In an Interactive session, users can issue run commands for model
calculations and other calculations to be performed by the server.
Users can also enter their own data, for example, for what-if
analysis. The information presented to a client running an
Interactive session is entirely in response to the client’s commands.
This information is specific to a client that is interacting with the
project and hence is not accessible by other clients.
In an Engine Watch session, a client can display results of the most
recent scheduled model calculations for the project. The scheduled
calculations are those that take place automatically and that have
been specified during project configuration. The Engine Watch
session is a passive session. User entry of information and on-
demand requests for calculations are not allowed in this passive
session.
Execution of Aspen OnLine enables model calculations to be scheduled to run at
Scheduled fixed times of the day and/or at fixed intervals daily or based on
Calculations steady-state detection.
• Since user action is not required to initiate scheduled model
calculations, the background running of model calculations
proceeds even if no client is interacting with the project.
• A client can view the results of the last scheduled calculation
by opening an engine watch session. The occurrence of the
scheduled calculation is logged in the Engine log and the
results and input data are logged in the Run log.
• You can specify that scheduled calculations only proceed after
both data validation and steady-state checks pass their criteria.
Use this method to specify a run when steady-state is reached.
• Schedule information for Aspen Plus EO models is ignored.
For Aspen Plus EO models, steady-state detection is checked
continuously except during the line out period. Line out occurs
after a successful solution is implemented or optionally after a
failed run.

Run-time Application Displays

End-user GUI forms have the dual purposes of interactively
executing online model calculations and presenting results of these
calculations. The following comments are intended to help users in
better understanding and interpreting the information displayed on
the screens.

4-8 • Running Online Projects Aspen OnLine 12.1 User Guide

 • Values displayed for plant tags and formula tags are updated at
the frequency specified as the Update interval on the Data
Browser | Setup | Specifications | General sheet.
• Plant and formula tag values are also updated any time model
calculations are requested. Additionally, formula tag values are
also updated soon after the model calculations are completed.
• User input values on end-user GUI forms are held until the user
modifies them again.
• User input fields on end-user GUI forms represented by Local
GUI tags can be initialized by plant tag values. If such tags
exist, the Init Data button should be provided on the project
screen. The user should click this button the first time that the
form is displayed to initialize the user-input fields with the
values of the corresponding plant tags. The user should also
enter values for all user-accessible entries. The user-input
fields are not updated every time the corresponding plant tag
values are updated. Rather, they hold the values previously
entered by the user or those obtained at the time of the last Init
Data action.
• Model output values on end-user GUI forms show the results
of the previous successful calculation.
Note: Values of all non-plant project tags could be different for
different clients depending on the input values used for any Local
GUI tags.

Run-time Logs and System

Information
Valuable run-time information is captured in log files and
displayed via system information windows.
About Log Files Run-time information written to log files can be accessed using
command buttons (Read Log function) on end-user GUI forms.
Log files are created for each online project and are placed in the
corresponding online project folder on the server machine.
Log files are plain text files and can be accessed by Microsoft
Notepad or Microsoft WordPad.
The log files have a maximum size limit, which is 45 KB by
default and can be modified on the Data Browser | Setup |
Specifications | Reports sheet. When a log approaches this size, it
is archived into a backup copy and a fresh log file is opened for
recording future entries.

Aspen OnLine 12.1 User Guide Running Online Projects • 4-9

 At any given time, only one historical version of the log files is
available. When the current log file approaches the maximum size,
the existing backup historical log file is purged and the contents of
the current log file are moved to the backup log file.
Event Log The Event Log is most easily accessed from a button on end-user
GUI forms. See To incorporate command buttons in Chapter 3
for instructions on creating this button. The Event Log is also
accessible via a log reader button on the Control Panel | Status
sheet.
The Event Log records any abnormalities encountered during
project execution, such as steady-state detection failures, data
validation failures, and run-time calculation errors and warnings.
All entries in the Event Log appear with the timestamp at which
the event occurred.
Structurally, the event messages are broken into three distinct
sections.
• The first section of the message indicates at what stage during
project execution the event occurs.
• The second section displays a cybercode number. The
cybercode number serves to indicate which module of Aspen
OnLine detects the particular event.
• The third section of the event message following the cybercode
number is a description of the event. This description may be
from the DCS/IMS, from Aspen Plus, or internally generated
by Aspen OnLine.
While the general information is aimed at assisting users in
identifying problems, cybercodes are meant for use by Aspen
OnLine code developers. Finally, errors reported by DCS/IMS or
Aspen Plus are simply passed through to Aspen OnLine.
Aspen OnLine execution errors include those arising during
communications with the plant DCS/IMS, during data exchange
between a model and Aspen OnLine, and during model
calculations.
When Aspen OnLine calculations are terminated with errors due to
failure of steady-state or data validation checks, the tags that are
cause the failure of these checks and the values of these tags are
recorded.
Warnings during execution include notification regarding non-
critical tags whose values are outside user specified validity
ranges. In these cases, project calculations continue and the event
log indicates whether the values were clamped.

4-10 • Running Online Projects Aspen OnLine 12.1 User Guide

 Run Log The Run Log is most easily accessed from a button on end-user
GUI forms. See To incorporate command buttons in Chapter 3
for instructions on creating this button.
The Run Log records model input and output values at the time of
model execution. The values are recorded in the same unit as they
appear in the model. If the model calculation was not completed
successfully, only the model input values are recorded in the log.
An entry to the Run Log is created each time a model calculation is
performed. The timestamp of each recorded batch of input and
output is the time at which the model calculation was begun.
The variable names in the Run Log are identical to those in Aspen
Plus.
The model variable values in the Run Log can be useful in
rerunning model calculations for diagnostic purposes. The entries
in the Run Log are in the same sequence as the order in which
variables are defined during project configuration, which is
reflected by variable ID. Each grid on the Data Browser |
Variables | Grid View sheets has a hidden column called VarID,
which is typically the last column. The user can sort the grid
display by VarID.
Engine Log The Engine Log is most easily accessed from a button on end-user
GUI forms. See To incorporate command buttons in Chapter 3
for instructions on creating this button. The Engine Log is also
accessible via a log reader button on the Control Panel | Status
sheet.
The Engine Log records the exact time at which model calculations
are commenced and completed for each client, as well as the name
of the client that issued the request.
An entry to the Engine Log is created each time a model
calculation is performed.
System Information Run-time information is data such as the availability of:
• The Aspen OnLine server
• The Aspen Plus simulation engine
• The results of background data monitoring of the plant tags in
the project
This information is made available to users on request. All this
information can be displayed on the run-time end-user GUI forms
by clicking a button configured to display System Info.
Cim-IO Logs Two log files are used to store error messages and debug
information for communication with Cim-IO. EngLstIO.log
contains this information for communication between the Aspen

Aspen OnLine 12.1 User Guide Running Online Projects • 4-11

 OnLine engine program and Cim-IO. SsdLstIO.log contains the
information for communication between the Aspen OnLine steady-
state detection program and Cim-IO.
These logs are very useful for troubleshooting Aspen OnLine
issues related to Cim-IO. The level of debug output is controlled
by the Debug print level on the Setup | Specifications | Reports
sheet of the Data Browser.

Saving the Model Backup File

Options are available to save the model backup file for each type
of session (Interactive and Engine Watch). These backup files
allow reviewing and re-running of cases. The backup files are
saved in the project’s Model folder. Each file saved has a unique
name that consists of a time stamp followed by the project name
with extension .BKP. There is no limit to the number of files that
can be saved.
The save options include Save After Run, which will always save a
backup file after every run, and Save If Run Fails, which will only
save a backup file if the run was not successful. These save options
may be set differently for each type of session (Interactive and
Engine Watch).
To set these options:
1 Launch the Aspen OnLine Client GUI and connect the client to
the engine.
2 Open the Control Panel | Run-Time User GUI sheet and
open an end-user GUI form in run mode. This implies that the
project must have at least one end-user GUI form.
3 When the end-user GUI form is selected, click the Options
menu on the main window and select the Save Run command.
Three options are available; the default is Not Save.
The HYSYS model file can also be saved using the steps described
above. The use of the end-user GUI to make model runs is not
currently supported for Aspen Plus EO models.

4-12 • Running Online Projects Aspen OnLine 12.1 User Guide

 CHAPTER 5

Advanced Features

Migration of Online Projects from

Version 10.2
If you are migrating from Aspen OnLine 10.2 or earlier, you must
pack existing online projects as .SPK files using the Server
Packing capability of the earlier version of Aspen OnLine before
uninstalling it. After Aspen OnLine 12.1 is installed, those online
projects can be easily migrated to version 12.1 using those .SPK
files. See Creating a project from an Aspen OnLine SPK file
later in this chapter.
As mentioned earlier, project names must be unique on the server
machine. If the name from SPK file conflicts with an existing
project name, you may have to temporarily unregister the existing
project or rename it. See Managing Multiple Projects later in this
chapter for details about unregistering and renaming projects.

Migration of Online Projects from

Version 11.1
If you are migrating projects from Aspen OnLine 11.1, you must
export existing projects to a folder using the menu command File |
Export in Aspen OnLine 11.1. On the Project tab, choose the
destination directory for the project and be sure to select the
options to copy all models and OBJ files.
After Aspen OnLine 12.1 is installed, you can rebuild the saved
projects by creating a new blank project and then importing the
saved data with the menu command File | Import. See Creating a
new blank project later in this chapter. On the Project tab of the
Import Project Configuration Information dialog box, select the

Aspen OnLine 12.1 User Guide Advanced Features • 5-1

 source directory where you exported the project, and be sure to
select the options to copy models and OBJ files.

Migration of Online Projects from

Aspen Plus Online or RT-Exec
To import a project from Aspen Plus Online (APOL) 11.1 or RT-
Exec:
1 Create a new blank project in Aspen OnLine using the Project
Manager GUI.
2 In the Tools menu, run the Load APOL/RT-Exec Dump
command. Note that this command will completely overwrite
the contents of the currently open project. A dialog box appears
stating this warning. By default, this option is not displayed
under the Tools menu. In order to get the migration item to be
shown under the Tools menu, select Options under the Tools
menu. Check the item related to migration project from Aspen
Plus Online.
3 Click Yes. The Load Aspen Plus Online / RT-Exec dump file
dialog box appears.

4 In the RTE ini file field, click . Browse to the online folder
of the existing APOL or RT-Exec project, and select the rte.ini
file. Click Open. Aspen OnLine will automatically fill in the
RTE dmp file field with the rte.dmp file in the same folder.
5 In the Model name field, specify a file name for the Aspen
Plus model, using the .apw extension.
6 In the Files to copy to offline folder frame, select the files to
be copied from the offline folder of the APOL or RT-Exec
project to the offline folder of the new Aspen OnLine project.
7 Click Load. Status messages will appear in the Messages
frame indicating the progress of the migration.
8 The message Migration process completed successfully appears
in the Messages frame when migration is complete. At the end
of the migration, click the Close button.
9 Open the Data Browser and go to the Model folder. Confirm
the offline, online and history directories. After verifying that
the directory locations are correct, perform an offline-to-online
step to copy the model files from the offline directory to the
online directory. During this step, a new X variable list will be
created.

5-2 • Advanced Features Aspen OnLine 12.1 User Guide

 Backing Up Online Projects
Modified information is saved during the course of working on a
project in one of two ways, depending on the setting of the
Commit changes to configuration database option on the Tools |
Options dialog box:
• Immediately as you move from field to field on Data Browser
sheets in the Client GUI
• When the user clicks Apply or with the user's
acknowledgement when data must be saved to proceed
In either case, saved changes cannot be automatically undone. This
makes backing up existing online projects necessary so that you
have something to fall back to if there is a need to return to the
original state of the project.
All project configuration information is stored in one file,
Config.mdb, which is located in the project folder on the server
machine. Config.mdb contains pointers to process models.
Therefore, you only need to backup Config.mdb, model files, and
files required by models (such as user *.obj files) in the offline
directory.
Backing Up Project If you do not intend to make any changes to models and files
Configuration Only required by models, and you only change project configurations
such as adding tags or modifying variable attributes, then you only
need to make a copy of Config.mdb and store it somewhere outside
the project folder.
Important: Do not store the backup copy of Config.mdb in the
project folder, because deleting a project deletes the entire project
folder.
After making a backup copy of Config.mdb, you can perform
project configuration modifications. If at some point, you decide to
abandon all modifications, you can restore the project
configuration using the backup copy of Config.mdb. To use the
backup Config.mdb, do the following:
1 Use the Client GUI to unload the steady-state detection
program and engine program if they are loaded.
2 Shut down all Client GUI sessions connecting to the project.
3 Copy the backup Config.mdb to the project folder, replacing
the existing Config.mdb.
Backing Up the To backup the whole project, make a copy of the whole project and
Whole Project in store it elsewhere. If model files are outside the project folder, they
Binary Format should be backed up separately. At a later time, if you want to use

Aspen OnLine 12.1 User Guide Advanced Features • 5-3

 the backup version, delete the project using Project Manager and
register the backup version of the project.
Important: Do not store the backup in the project folder, because
deleting a project deletes the entire project folder.
You can also use multiple projects to represent versions of an
online project using Project Manager. For example, if you have an
online project called Columns, you can create a new online project
called Columns 2.0 as a copy of the Columns project. Then, you
can work on project Columns 2.0 without affecting Columns. To
compare the two versions, load both projects using two Client GUI
sessions. Similarly, you can create project Columns 3.0 and so on.
See Managing Multiple Projects for details about copying
projects.
Note that this type of project backup is in binary format and can be
used only with the same version of Aspen OnLine. It is very likely
that these project backups will not be able to be loaded into future
versions of Aspen OnLine.
Backing Up the Project backup in ASCII format takes a little longer than the binary
Whole Project in format backup. However, backups in ASCII format can be loaded
ASCII Format into current and future versions of Aspen OnLine. Therefore, it is
very important to back up all online projects in ASCII format
before migrating to future versions of Aspen OnLine.
To back up the whole project in ASCII format, follow these steps:
1 Launch a Client GUI session and connect to the online project
to be backed up.
2 Click the Export command on the File menu. The Export
Project Configuration Information dialog box appears.
3 Specify the Destination directory without a backslash ( \ ) at
the end. Aspen OnLine will create a folder within this directory
using the current project name as the folder name. Then, the
program will dump project configuration information to an
ASCII file named Config.txt. It will also generate many files
to hold images on end-user GUI forms. Config.txt contains
references to these files. If Copy models and Obj files is
selected, files from the offline directory are also copied to this
new folder.
To reconstruct the project from Config.txt, follow these steps:
1 Use Project Manager to create a blank new project.
Note: You must launch Project Manager from the server computer
where the project is to be created in order to create a new project.
2 Launch a Client GUI session and connect to the newly created
blank project.

5-4 • Advanced Features Aspen OnLine 12.1 User Guide

 3 Click the Import command on the File menu. The Import
Project Configuration Information dialog box appears.
4 Specify the path name for the folder containing Config.txt and
click OK.
5 Aspen OnLine will load the project configuration.
After importing a project, check whether model files are available
in the OffLine folder within the project folder. Also check the
settings for the offline and online directories on the Data Browser
| Models | model name | Specifications and Case and Directory
sheets. Ensure that they correctly reflect the location of offline
model files.

Aspen OnLine 12.1 User Guide Advanced Features • 5-5

 Managing Multiple Projects
Aspen OnLine Project Manager allows you to manage multiple
Aspen OnLine projects.
Creating Projects With Aspen OnLine Project Manager, you can create a blank
online project, create an online project by copying from an existing
one, or create an online project using Aspen OnLine .SPK files
saved from earlier version of Aspen OnLine.
Creating a new blank To create a new blank project:
project
1 On the server machine where the new online project will
reside, launch Aspen OnLine Project Manager.

5-6 • Advanced Features Aspen OnLine 12.1 User Guide

 2 Enter the server machine name.
3 Click Create. A dialog box appears with three options. The
default is Create a blank project.
4 Enter the New project name. The name must not be the same
as any other project on the server.
5 Specify the New project location. The new project folder will
be placed within this folder. Do not include the name of the
project folder itself in the path and do not use a backslash ( \ )
at the end of the path. For example, if the desired project folder
name is D:\projects\Columns, enter D:\projects as the new
project location.
6 Click Create to complete the project creation. The new project
name appears in the Project Manager window.
Creating a project by You can create a copy of another project currently registered on
copying an existing the server. To do so:
project
1 On the server machine where the online project to be created
will reside, launch Aspen OnLine Project Manager.
2 Enter the server machine name.
3 Click Create. A dialog box appears with three options. Select
Copy from existing Aspen OnLine 12.1 project.
4 Enter New project name. The name must not be the same as
any other project on this server.
5 Specify the New project location. The new project folder will
be placed within this folder. Do not include the name of the
project folder itself in the path and do not use a backslash ( \ )
at the end of the path. For example, if the desired project folder
name is D:\projects\Columns, enter D:\projects as the new
project location.
6 Specify the full path and name of the Config.mdb file in the
Existing project file field.
7 Click Create to complete the project creation. The new project
name appears in the Project Manager window.
Creating a project from To create a project from an Aspen OnLine .SPK file:
an Aspen OnLine SPK
1 On the server machine where the online project is to be
file
migrated to, launch Aspen OnLine Project Manager.
2 Enter the name of the server machine and click Create. The
Create project on server machine name dialog box appears.
3 By default, the Create a blank project option is selected.
Change the selection to Import Aspen OnLine SPK file.

Aspen OnLine 12.1 User Guide Advanced Features • 5-7

 4 Specify the New project location. The new project folder will
be placed within this folder. Do not include the name of the
project folder itself in the path and do not use a backslash ( \ )
at the end of the path. For example, if the desired project folder
name is D:\projects\Columns, enter D:\projects as the new
project location.
5 Specify the full path and the name of the Aspen OnLine SPK
file to be used, then click Create.
6 Aspen OnLine Project Manager program starts migrating
project configuration information from the .SPK file to the new
online project. It also maps the unit conversion specifications
in the SPK file to the built-in unit conversion system. During
the mapping process, dialog boxes appear, asking you to
confirm/complete the mapping. A typical dialog box looks like
this:

5-8 • Advanced Features Aspen OnLine 12.1 User Guide

 7 Click Help for on-line help information about this mapping
process.
Important: When you click OK, the old units definition is
mapped to the units type highlighted in the Units type list and the
units highlighted in the Units for given units type grid.
8 After the unit mapping process is complete, Aspen OnLine will
continue to convert the remaining information from the .SPK
file to the new online project. The name of the new project will
appear in the project list on the Project Manager window. The
project name is retrieved from the .SPK file.
This new project can now be accessed using the Aspen OnLine
Client GUI.
9 Click Close to shut down Project Manager.
Registering Projects Any Config.mdb file generated by Aspen OnLine 12.1 and located
in any folder other than the top level of a drive can be registered to
form an online project. The name of the folder containing
Config.mdb file is used as the online project name. Before
registering the file, ensure that this name is not used by any
existing online project on the server machine. To register an online
project:
1 On the server machine where the online project to be registered
will reside, launch Aspen OnLine Project Manager.
2 Enter the server machine name.
3 Click Register. A Choose Aspen OnLine Project dialog box
appears.
4 In the Path field, enter the full path for the folder that contains
the Config.mdb file, without a backslash ( \ ) at the end.

Aspen OnLine 12.1 User Guide Advanced Features • 5-9

 5 Click OK. If the project file is not password-protected, the
registered project should appear on the project list. If the
project file Config.mdb has a password, a dialog box will
appear asking for the password. In this case, enter the password
and click OK.
After registration is complete, examine the offline and online
directories for models and locations of model files. Ensure that
they are consistent. If not, move model files or change directory
settings using the Client GUI, on the Data Browser | Models |
model name | Specifications and Case and Directory sheets.
Renaming Projects To rename a project:
1 On an Aspen OnLine server computer, launch Aspen OnLine
Project Manager.
2 Enter the server machine name.
3 Select the name of the online project and click Rename. A
dialog box appears.
4 Enter the new project name and the password of the project and
then click OK.
The new project name replaces the old project name in the
project list.
After renaming a project, examine the offline and online
directories for models and locations of model files. Ensure that
they are consistent. If not, move model files or change directory
settings using the Client GUI, on the Data Browser | Models |
model name | Specifications and Case and Directory sheets.
Project Password Aspen OnLine provides a password protection feature to prevent
Protection unauthorized changes made to project configurations. The project
password is project-specific. The password is needed to register
and unregister projects, change the project password, delete a
project, or edit project configuration. You can view project
configuration information without the project password.
The project password defaults to blank when a project is initially
created. It can be changed using Aspen OnLine Project Manager.
To change the project password:
1 On an Aspen OnLine server computer, launch Aspen OnLine
Project Manager.
2 Enter the server machine name.
3 Select the name of the online project of interest and click
Change Password. A dialog box appears.
4 Enter the old password, the new password, and confirm the
new password, then click OK.

5-10 • Advanced Features Aspen OnLine 12.1 User Guide

 Unregistering You can unregister online projects on a server machine which you
Projects do not expect to run online projects for a period of time. You might
unregister a project to rename it on the server, or to clean up the
list of projects available on a server with many projects.
Unregistering does not delete any files; it simply removes
references to the projects from Aspen OnLine programs. You can
later register these projects again and Aspen OnLine programs will
be able interact with them again. To unregister an online project:
1 On an Aspen OnLine server computer, launch Aspen OnLine
Project Manager.
2 Enter the server machine name.
3 Select the name of the online project of interest and click
Unregister.
4 The project will be unregistered if the project is not password-
protected. If there is a password for the project, you will have
to enter the password before the project can be unregistered.
Deleting Projects To delete a project:
1 On an Aspen OnLine server computer, launch Aspen OnLine
Project Manager.
2 Enter the server machine name.
3 Select the name of the online project of interest and click
Delete.
4 The project will be deleted immediately if the project is not
password-protected. If there is a password for the project, you
will have to enter the password before the project is deleted.

Case History System

Each time Aspen OnLine runs a cycle of one or more cases, it
generates many files in the online directory. These include X files
containing values and specifications for all variables, reports, log
files and journal scripts. Without a mechanism to save these output
files at the end of each cycle, they would be overwritten when
Aspen OnLine runs the next cycle. Aspen OnLine's case history
system provides the mechanism for saving files that are useful for
examining model results or reproducing the online calculation
offline.
The case history system is primarily a set of directories to which
output files are copied. The number of history directories is
configured on the Setup | Specifications | History sheet. Aspen
OnLine creates new directories to which files are saved. The
directories are named based on the date and time that the first case

Aspen OnLine 12.1 User Guide Advanced Features • 5-11

 starts. After the maximum number of directories has been created,
Aspen OnLine will start deleting previously created directories
along with all the files saved in the directories.
To examine or use any of the files saved, a utility on the Control
Panel | Options sheet has been provided to save the files from a
specified history directory to a working directory. Accessing the
files directly in the history directories is not recommended because
Aspen OnLine may access them as it runs. If any history is
available, a list of history directories will be displayed. Select any
history to view a summary of information about that history in the
History folder attributes frame, similar to the following:
Directory Name: 18apr1997_154813
Start Date: 18-APR-97 15:48:13
End Date: 18-APR-97 15:49:00
Case1 results: SUCCESSFUL
Case2 results: SUCCESSFUL
Full results: NOT RUN
Click the Refresh button to update the list of history directories.
Select a history directory and click Save to copy the files in that
directory to your working directory. At this point the files can be
examined and used for off-line runs.
Care should be taken when trying to perform off-line runs of
Aspen Plus in a directory updated by the history system. It is
possible that files necessary to run offline have not been copied by
the history system and Aspen Plus will fail because files it requires
are not in the current directory. A simple work around to this
problem may be to first copy all files from the offline directory to
the current directory and then update the same directory with the
history system.
Five settings are defined on the Setup | Specifications | History
sheet for configuring the case history system.
• Number of case history directories
• Minimum failed history cases
• Minimum solved history cases
• Files to be saved to history directory
• Files to be added to working history directory
The first parameter specifies the maximum number of history
directories. This can be a number up to 9999. For large problems,
each history directory may use a significant amount of disk space.
Because all history directories must reside on the same disk,
setting this number too high could cause the history system to use
all available disk space of the disk.

5-12 • Advanced Features Aspen OnLine 12.1 User Guide

 The second and third parameters are used to ensure that a
minimum number of solved and failed cases are always kept in the
history system. For example if you wished to ensure that at least
the last solved case was always kept in the history you should set
the parameter Minimum Solved History Cases to 1. In this way
even if the optimization system fails repeatedly for some reason,
the last solved case would be kept in the history.
The Files to be saved to history directory setting defines what
files are to be saved to the history directory. This can be a comma-
separated list of file names to be copied that may include the *
wildcard character. For example, *.ebs would cause all scripts or
ebs files to be copied to the history directory. The files will be
copied to the history directory with the same names.
The Files to be added to working history directory setting is
used to specify files that are to be added to the working directory
during the histsave operation. Due to disk space limitations, it may
be impractical to save large files such as the APPDF file after each
cycle. However, you will need a copy of these large files in your
working directory if you wish to run Aspen Plus offline. Specify
wildcards or destination filenames in the same manner as for Files
to be saved to history directory .
When using the Files to be added to working history directory
parameter to copy additional files to a working directory, you
should be aware that any files copied must be consistent with those
files saved at the end of the cycle. For example, if a new APPDF
file has been loaded into the online directory and this is added to a
working directory with files saved from the previous APPDF, you
may not be able to run Aspen Plus offline due to inconsistencies in
the files copied.
X files are automatically copied to the history directory and need
not be specified here.
There may be times when you wish to delete all the current files
saved to history and start with an empty history system. To do this,
stop the online system, then go to the Models | A+ Optimizer
sheet and click the X button next to the history field at the bottom.
This will delete all files within the history directories and remove
all history directories.

Database Reports
You can generate database reports using the Generate DB Report
command on the Tools menu. Reports available are summarized
below:

Aspen OnLine 12.1 User Guide Advanced Features • 5-13

Title Filename Description
X Variable Pairing xpair.rpt Lists all variable pairs defined in the database. These pairs are
used in the generic validity checker for the parameter and
optimization cases.
X In/Out Links xvarlnk.rpt Lists all X variables linked to the tag database for parameter
input or parameter/optimization result output.
X Bound Links xvarbnd.rpt Lists all X variables that have tags defined for upper or lower
bounds.
Average and Steady- taglnk.rpt Lists all tags that are linked to other tags through steady-state
State Output Tags or averaging in the database.
X File Differences xdiff.rpt Reports differences between two X files. Only X variables
linked to the DCS/IMS in some way (such as parameter input)
are checked for differences.
Change Log chglog.rpt Reports changes recorded in the change log. This includes any
database modifications as well as activities such as starting the
online system.
Measurement/Paramet prminp.rpt Reports all DCS tags that are used as inputs to the plant. This
er Input Tags includes the DCS tag, the average tag, validity limits, the bad
input critical flag, and the specification for the model variable
that receives the value.
Solution impcfg.rpt Reports all implementation (ramper) configuration information.
Implementation
Configuration
Output Tags outtag.rpt Reports all tags that receive values written by Aspen OnLine.
This can include all tags or only those for a specific DCS/IMS.
Unlinked Tags unlnktag.rp Reports all tags that are not linked.
t
X Variable Tag Links xlink.rpt Lists all X variables that are connected to tags. For each
variable, a list of all tag connections is given.
Tag/Aspen Plus tagprm.rpt Lists all tags to which script parameters have been defined for
Parameter Links reading or writing.

Command Journaling
Aspen OnLine's interaction with Aspen Plus equation-oriented
models uses Open Object Model Framework (OOMF) commands
similar to those generated or entered on the command line when
using the Aspen Plus EO environment interactively. Aspen OnLine
issues commands to Aspen Plus with the appropriate parameters
and Aspen Plus carries out the commands. This includes actions
such as invoking a script or changing a variable attribute such as
the value. Because the same mechanism is used to issue commands
to Aspen Plus, all Aspen OnLine commands can be captured
through the normal Aspen Plus journaling mechanism.

5-14 • Advanced Features Aspen OnLine 12.1 User Guide

 When running Aspen Plus interactively, the following two
commands are used to control journaling:
OOMF> set journal_device = openfile("file")
OOMF> set journal_level = number
The set journal_device command tells OOMF to journal all
commands issued to the file specified. The second command
specifies how script commands should be captured when scripts
are nested within other scripts. A journal_level of 0 tells Aspen
Plus to log script invocations but not to expand the actual script
commands in the journal file. A journal_level of 1 causes
commands within scripts invoked at the Aspen Plus command
prompt to be expanded, but scripts invoked by these scripts will
not be expanded. Increasing the journal level increases the nesting
level at which scripts are expanded for journaling.
You can specify the journal level and journal files on the Setup |
Options | Journal sheet. You can specify separate journal files for
initialization, for each case, and for portions of each case such as
commands related to reading DCS/IMS data used to set attributes
of model variables. The replay journal for each case includes the
initialization and case-specific commands to exactly duplicate an
Aspen OnLine case offline.
On this sheet, you can use the Disable replay journal checkbox to
disable certain commands performed by the online system solely
for the purpose of generating a complete and self-contained replay
script. For instance, the reloading of the values from the case 1
results X file at the start of case 2 will not be performed if this
checkbox is selected.
You can also generate plant data journal files offline, using the
Control Panel | Journal DCS sheet.
The following is a partial example of a journal file generated
during a reconcile case 1 run. Some of the date/time comments at
the ends of the lines have been truncated.
-------------------------------------------------------------------------------------
// --
// -- Aspen Plus Online rec case 6-APR-97 14:52:57 --
// --
// --
// -- Aspen Plus Online Starting Parameter updates from DCS/IMS --
// --
set RTEPARAM = 100 {KG/HR} // Wed Oct 15 15:41:10 1997
// --
// -- Aspen Plus Online Complete Parameter updates from DCS/IMS --
// --
restore variables [ NAME, LOWER, VALUE, UPPER, UNITS, SPEC, STEP ] from "base.x"
set MODE rec // Sun Apr 6 14:52:58 1997
invoke rec.ebs // Sun Apr 6 14:52:58 1997
// --
// -- Aspen Plus Online Starting Model variable updates from DCS/IMS --

Aspen OnLine 12.1 User Guide Advanced Features • 5-15

// --
// F101.PV
SETFEED.MAXFEED.STR.FLOW = 13105 {LBMOL/HR} // Sun Apr 6 14:52:58 1997
// F101_LB.PV
SETFEED.MAXFEED.STR.FLOW.LOWER = 0 {LBMOL/HR} // Sun Apr 6 14:52:58 1997
// F101_UB.PV
SETFEED.MAXFEED.STR.FLOW.UPPER = 20000 {LBMOL/HR} // Sun Apr 6 14:52:58
// F101_SB.PV
SETFEED.MAXFEED.STR.FLOW.STEP = 1000 {LBMOL/HR} // Sun Apr 6 14:52:58 1997
// --
// -- Aspen Plus Online Complete Model variable updates from DCS/IMS --
// --
save variables [ NAME, LOWER, VALUE, UPPER, UNITS, SPEC, STEP ] to "rec_dcs.x"
// --
// -- Aspen Plus Online Starting Param Generic validity check --
// --
// --
// -- Aspen Plus Online Complete Param Generic validity check --
// --
save variables [ NAME, LOWER, VALUE, UPPER, UNITS, SPEC, STEP ] to "rec_vc.x"
save variables [ NAME, LOWER, VALUE, UPPER, UNITS, SPEC, STEP ] to "rec_pre.x"

Differences Between In general, Aspen OnLine attempts to duplicate the sequence of

Interactive Aspen events from an interactive Aspen Plus run. However, you should
Plus and Aspen note the following differences:
OnLine • Aspen OnLine does not exit between cases. It remains
memory-resident until the engine is stopped and reloaded
again.
• Aspen OnLine performs model initialization steps only once at
startup time. It is the user’s responsibility to separate one-time
initialization activities from case-specific (parameter case,
optimization case, etc.) setup activities that must be done for
each cycle.
• While X files are written after each case, only base.x is used to
initialize specs and values before a case is run.
In order to minimize differences between the offline and online
environments, you should try to organize scripts in a manner
similar to the way Aspen OnLine does. Script functions should be
divided into different scripts, as follows:
• Initialization activities
• Case setup activities
• Post-solution reporting
These scripts can then be used directly by Aspen OnLine or
invoked by a master script for offline usage.

Read/Write Suppress
To test the online system it is sometimes useful to disable writing
and/or reading of values to the process database. To do so, set the

5-16 • Advanced Features Aspen OnLine 12.1 User Guide

 Read Suppress or Write Suppress signal tags to a value of 1.0. This
has the following effects:
• Write Suppress: No parameter or optimize case results will be
written to the process database.
• Read Suppress: No input is read from the process database and
no output is written to the process database, including setpoint
optimization.
Input data for read suppress mode is specified by read suppress
scripts configured on the Setup | Options | Read Suppress sheet.
Values from a table in RunInfo.mdb will be used to supply the
input data. If no read-suppress scripts are configured, Aspen
OnLine will run with data from base.x that normally contains the
result of the last solved case.
When the Read Suppress signal is set, the scheduler does not wait
for the plant to become steady to start the first case. Only the
Aspen OnLine On/Off signal must be turned on.
Read suppress and write suppress modes affect only programs that
transfer data for the optimization program. The signal tags and
steady-state detection programs are not affected.
The Disable Cim-IO checkbox on the Setup | Specifications |
Cim-IO sheet has an effect similar to read suppress mode. When
selected, communication to the DCS/IMS is disabled for all Aspen
OnLine programs. The result is that all tags are treated like local
tags. While running in this mode, values for tags can be set
individually in the GUI or the values of multiple tags can be set via
the File | Import command.

Using Grids on End-User GUI Forms

A summary of tag properties can be displayed in a grid format in
the end-user GUI form. For example, the grid can be used to
display a summary comparison of plant measured values and
model calculated values, or to display a summary of all properties
of selected tags.
The Client GUI can be used to add a grid to an end-user GUI form
and format this grid.
1 Launch the Aspen OnLine Client GUI and open the Data
Browser | User GUI | Specifications sheet.
2 Select the row listing the form of interest and click Edit.
The form appears, in design mode.
3 Click the New Grid icon in the toolbar of the form, or select
Add Grid from the Tools menu.

Aspen OnLine 12.1 User Guide Advanced Features • 5-17

 4 Click to place the grid at a location on the form. A 3 X 3 grid
appears.
5 With the grid selected, click the right mouse button and select
Properties. The Grid Properties dialog box appears.
6 Click the Columns and Rows tab of the Grid Properties
dialog box to modify the grid properties.
7 The numbers of columns and rows in the grid may be changed.
In the bottom portion of the Grid Properties dialog box,
where a picture of the grid is displayed, click the column or
row where the new column or row is to be added. Then click
the Add Column or Add Row button in the Columns or Rows
panel in the top portion of the form to add the column or row at
the chosen location. Similarly, columns and rows may be
deleted from the grid by clicking the Remove buttons in the
Columns and Rows panels.
8 For each column of the grid, specify a Title and a Field Name
to be displayed in that column. The Title will be displayed as a
column heading. The Field Name is a tag attribute, such as
Tag value or Units. The column displays this attribute for each
tag in the grid. You can use the Format Text field to specify
the formatting of the displayed attributes; a default format is
provided.
9 For each row, specify a Title and a Tag Name. Attributes of
this tag, as specified for the columns, will be displayed across
the row. Often, row titles will be the tag names or aliases for
them.
10 You can use the Style and Color tab to provide information on
formatting of the grid in regard to line styles, color of the grid
cells and border styles. You can use the Font and Alignment
tab to provide formatting information on text and value display
in the cells of the grid.
11 Click the Apply button to accept the changes made. Click OK
to close the Grid Properties dialog box.

User-Defined Add-in Control Buttons

In addition to the pre-defined command button functions in Aspen
OnLine, you can create custom buttons to execute commands of
your choice. To create a user add-in button action:
1 Open a DOS window and go to the directory where Aspen
OnLine 12.1 is installed.
2 Enter regsvr32.exe /U ExternFunctions111.dll
at the command prompt to unregister this component.

5-18 • Advanced Features Aspen OnLine 12.1 User Guide

 3 Create a new ActiveX DLL project named
ExternFunctions111.dll.
While the instructions given here are for using Visual Basic, the
DLL can also be created with C++.
Features of the User The ActiveX DLL needs to have these features:
Add-in Button DLL • A class named ExternFunctionsClass
• A method in this class named CustomFunction
• A read-only property in this class named FunctionList
The ability to access the trending capabilities of Process Explorer
was incorporated into Aspen OnLine as a user add-in button to
illustrate its use. The following Visual Basic code illustrates the
use of the above features. It would be placed in a ClassModule
named ExternFunctionsClass.
Private Functions(0) As String
Private FTrend As Object
Public Sub CustomFunction(FunctionName As String)
On Error GoTo errHandleX
Select Case FunctionName
Case Functions (0)
Set FTrend = CreateObject("Ftrend111.FTrending")
FTrend.ShowTrending
End Select

Exit Sub
ErrHandleX:
End Sub

Private Sub Class_Initialize()

Functions(0) = "Trending"
End Sub

Public Property Get FunctionList() As Variant

FunctionList = Functions
End Property

After writing the ExternFunctionsClass code, compile it as a DLL.

Installing the User These user add-in buttons will be used on the Aspen OnLine client
Add-in Button DLL computers. Thus, ExternFunctions121.dll needs to be placed on the
client computers (which also includes the server computer since it
has a local client on it) and registered on each of them. Although
the DLL could be placed just about anywhere on a client computer,
it is recommended that it be kept together with rest of the Aspen
OnLine files in the same directory in which Aspen OnLine was
installed.
To register ExternFunctions121.dll on a PC:
1 Click Start and select Run.

Aspen OnLine 12.1 User Guide Advanced Features • 5-19

 2 In the Run dialog box that is displayed, enter:
RegSvr32.exe drive:\pathname\ExternFunctions121.dll
Where drive denotes the drive letter on the computer and
pathname denotes the path to the directory location where
ExternFunctions121.dll has been placed.
3 Click OK.

5-20 • Advanced Features Aspen OnLine 12.1 User Guide

 CHAPTER 6

Troubleshooting

This section describes procedures for resolving the problems you

may encounter while using Aspen OnLine.

Database Locking
A system of database locking has been set up to control access to
the database files. Locking prevents multiple programs from
attempting to modify the database at the same time. It also prevents
modification of the database when the online programs are
accessing the data files.
Generally, you won't even be aware that locking occurs.
Occasionally, though, when using the utilities, an operation may
fail due to the database being locked by another program. When
this happens, you will be informed that the database is locked, and
asked to try again later. In most cases, the database is locked only
for a short time, and an immediate retry of the operation should
work.
Two situations could cause the database to be locked for an
extended period:
1 A large dbload operation will lock the database until it is
complete. This can only cause problems when the online
programs are scanning the database. It is recommended that
large dbload operations only be performed when the online
programs are down or when they are waiting for steady state.
2 A dbload operation aborted before completion may cause the
database to remain locked until the process that ran the dbload
is stopped or logged off.

Aspen OnLine 12.1 User Guide Troubleshooting • 6-1

 Recovering from Abnormal
Executions
It is recommended that you restart the Aspen OnLine service after
an abnormal termination of a project execution. Note that stopping
the service will stop all steady-state detection programs and engine
programs for all online projects on the server machine. All Project
Manager sessions and Client GUI sessions connecting to this
server machine will be terminated.
To restart the Aspen OnLine service:
1 Close any error message displayed.
2 Close any Aspen OnLine run-time message information (such
as Analyzing Data or Initializing Model) that has been
displayed for an unusually long time.
3 Exit from all Client GUI sessions and Project Manager
sessions.
4 Stop the Aspen OnLine 12.1 service. See the following section
for detailed instructions.
5 Open the Windows Task Manager.
6 Click the Processes tab and terminate any hanging Aspen
OnLine process and unexpected Excel sessions. Contact
AspenTech support if you are not sure whether a process is an
Aspen OnLine process. Also terminate unexpected processes
corresponding to automation servers such as apwn.exe and
apmain.exe. These are the Aspen Plus User Interface and
simulation engine executables respectively.
If the any of these processes are still running, select each one
and click the End Process button. When prompted, confirm
that the process is to be closed.
7 Click the Applications tab. If apown.exe or ApoManager,exe
is still running, select it and click the End Task button. When
prompted, confirm that the application is to be closed.
8 Restart the Aspen OnLine 12.1 service. See the following
section for detailed instructions.
9 The above procedure should allow all Aspen OnLine
functionalities to resume. If that is not the case, you may need
to reboot the computer.

6-2 • Troubleshooting Aspen OnLine 12.1 User Guide

 Setting Up Aspen Plus for Running
Online Cases
In order to run online cases in Aspen Plus, you must first run
Aspen Plus interactively and specify the server type and other
information needed for it to connect to the Aspen Plus simulation
engine, and select the Save as default connection checkbox to
save this information to be used automatically in future runs.
If Aspen OnLine stalls when trying to bring Aspen Plus models
online, waiting indefinitely, this may be your problem.

Setting Up Hysys for Running Online

Cases
In order to run online cases in Hysys 3.1, you must first run Hysys
interactively. From the Tools menu, select the Preferences
command. In the Simulation tab, clear the checkbox for Confirm
Before Adding if Active Correlations are Present, then click
Save Preferences. This prevents Hysys from asking "Would you
like to see a standard property set for all streams in addition to
those properties already being displayed?"
If Aspen OnLine stalls when trying to bring Hysys models online
or when running the models, this may be your problem.

Starting and Stopping the Service

Manually
Sometimes you may need to start or stop the Aspen OnLine service
manually, such as when recovering from abnormal executions. The
service can be started and stopped in the standard method for
starting and stopping Windows services:
1 Click the Windows Start button. Point to Settings, then click
Control Panel.
The Control Panel window appears.
2 Double-click the Administrative Tools icon.
3 Double-click the Services icon.
The Services dialog box appears.
4 Select Aspen OnLine Engine in the list.
5 Click Start to start the service, or Stop to stop it.
6 If you are stopping a service, another Services dialog box
appears, asking you to confirm your action. Click Yes.

Aspen OnLine 12.1 User Guide Troubleshooting • 6-3

 7 The Service Control dialog box appears briefly while the
service starts or stops.
8 Click Close to close the Services dialog box.

Change Log
The change log is used to track changes made to the online system.
This can be useful in determining why the online system is no
longer functioning correctly. In many cases, a problem may be the
result of what appeared to be a minor change to the system.
By determining when the online system stopped working, and
looking for changes made at or just before this time, it may
become apparent what caused the problem.
The following types of changes are tracked:
• All changes to the Tag and XDB database using GUI and
database load programs
• Starting and stopping of the online programs
The file where changes are stored is actually a rolling binary file
that is sized based on the initialization parameter Change Log
Size. The default for this is 2,000 changes.
To view the change log select the Tools | DB Rpt | Change Log
command. This will dump the report to a file called chglog.rpt.
The file can then be edited, viewed, or sent to a printer.
The change report will include the following for each change:
• Date and time change occurred
• User name of account from which change was made
• Name of program used to make change
• Up to three lines of description
The following is a partial listing of a change log report:
OPTIMIZATION SYSTEM CHANGE LOG REPORT
-------------------------------------------------
TIME USER PROGRAM CHANGE
-------------------------------------------------
08/21/93 16:45:01 RTO STARTRTO Starting Optimizer
08/21/93 16:44:02 RTO STARTWDG Starting Watchdog
08/21/93 11:17:04 RTO GUI IMPLMN.PV Added
08/21/93 10:36:23 RTO GUI F101.PV Modified
Window length
changed from (10) to (60)

6-4 • Troubleshooting Aspen OnLine 12.1 User Guide

 Changing Your Password for DCOM
After you change your Windows password for the account that
runs DCOM, you need to update the configuration of DCOM so
that the Aspen OnLine service can start correctly. However, you do
not need to repeat the entire process of configuring DCOM for
Aspen OnLine given in the Aspen OnLine chapter in the AES
Installation Manual. Instead, you only need to follow the steps
listed below.
You can also use this procedure if you need to change the account
that runs DCOM; this must be an account with Administrator
privilege on this computer.
1 From the Windows Start menu, click Run.
2 In the Run dialog box, enter DCOMCNFG and click OK.
The Distributed COM Configuration Properties window
appears.
3 On the Applications tab, select
APODCOM121.TheAPODCOM and click the Properties
button.
The APODCOM121.TheAPODCOM Properties dialog box
appears.
4 On the Identity tab, select This user and update the
Domain\UserName (if needed) and the password.
5 Click Apply, then click OK to close the dialog box.
6 Click Apply, then click OK again to close the Distributed
COM Configuration Properties window.

Engine Fails to Load a Model

The Aspen OnLine engine may fail to load an application model,
with an error similar to the following in EngineLog.log:
Monday, Sep-16-2002 14:16:30 Client 0 encountered
error loading Aspen Utilities model (Example.auf)
execution. Err description: (0)
There are two possible causes of this error.
• DCOM is incorrectly configured. For this case, refer to
Changing Your Password for DCOM or to the more detailed
configuration procedure in the AES Installation Manual.
• The service does not have enough memory. During the
installation, Aspen OnLine sets a parameter that controls the
amount of memory available to the service. However,
installation of other programs may change this parameter to a
smaller value.

Aspen OnLine 12.1 User Guide Troubleshooting • 6-5

 To change the value of this parameter:
1 From the Windows Start menu, select Run.
2 In the Run dialog box, type regedit and click OK.
3 In the Registry Editor, open the tree on the left to the folder:
HKEY_LOCAL_MACHINE | SYSTEM | CurrentControlSet |
Control | Session Manager | SubSystems
4 In the right pane, right-click Windows and select Modify. The
Edit String dialog box appears.
5 Click the Value data field, and use the arrow keys and
Home/End to locate the parameter SharedSection. It appears
with some numbers after it, such as:
SharedSection=1024,3072,512
The third number must be at least 1024 for Aspen OnLine to
run properly.
6 Change the third number to 1024 if it is less than this. For the
above example, you would change it to read:
SharedSection=1024,3072,1024
Do not modify the other parts of this string.
7 Click OK.

6-6 • Troubleshooting Aspen OnLine 12.1 User Guide

 APPENDIX A

Appendix

Cim-IO Data Source Types

This table lists all the available data source types for entry in the
Cim-IO Source column of the Cim-IO Connection form in the
Aspen OnLine engine configuration module.
Cim-IO Source Cim-IO Cim-IO Device Writeable
(Data Type) (Data Type)
DBVL Real Real Yes
DBST Short Real No
DBDV Short Short Yes
CBST Short CBST No
CBAW Short CBAW No
REAL Real Real Yes
SHRT Short Short Yes
LONG Long Long Yes
DBLE Double Double Yes
ENUM Short Enum Yes
ORD Short Ordinal Yes
DTIM Long DTIME Yes
EXID Long EXTID No

Pre-defined Signal Tags

The following signal tags are used by Aspen OnLine for a variety
of purposes. These include tags set by the operator or engineer that
control the online system, and tags which store status information
and performance statistics.

Aspen OnLine 12.1 User Guide Appendix • A-1

Tag Name Description Value Set By
Type
APOETIM Aspen OnLine elapsed time. Total elapsed time of Elapsed Program
last case 1 and case 2 in minutes.
APOONOFF Aspen OnLine on/off. 1 = online optimization on. Digital Engineer
APOSTAT Aspen OnLine status Status Program
APOTXST Aspen OnLine status (text) String Program
APOWAKE Aspen OnLine wake up flag. 1 = interrupt line out Digital Engineer
period.
APOWD Aspen OnLine watch dog. Used to monitor health Counter Program
of optimization program.
FORCESS Force steady-state. 1 = force a steady-state Digital Engineer
condition. Used in testing.
FULLDAT Full solution date stamp. Date when full Date Program
optimization results written to DCS/IMS.
FULLTIM Full solution time stamp. Time when full Time Program
optimization results written to DCS/IMS.
IMPCMN Current month solutions implemented Counter Program
IMPL24 Last 24 hours solutions implemented Counter Program
IMPLMN Last month solutions implemented Counter Program
INITSS Initialize steady-state. 1 = initialize steady-state Digital Engineer
history to undefined and restart calculations.
INVHIST Invalidate history. Internal value used to indicate Digital Program
validity of history system.
LASTRUN Last run Reserved
LASTSUC Last successful run Reserved
LOOPCTL Number of loops on control Counter Program
LOOPOFFCTL Number of loops off control Counter Program
LOOPOFFOPT Number of loops off optimization Counter Program
LOOPOPT Number of loops on optimization Counter Program
LOOPOPTNO Number of loops not being optimized (not Counter Program
receiving targets from optimizer)
LOOPOPTYES Number of loops being optimized (receiving Counter Program
targets from optimizer)
LOOPTOT Total number of output loops configured for Counter Program
ramping
ONLWDG Online system watch dog. Reset to Online System Counter Program
Reset Value if system is up and running normally.
May be counted down by DCS/IMS to monitor if
online system is active.
OPTDAT Solution date stamp. Date when optimization Date Program
solution written to DCS/IMS.
OPTTIM Solution time stamp. Time when optimization Time Program
solution written to DCS/IMS.

A-2 • Appendix Aspen OnLine 12.1 User Guide

Tag Name Description Value Set By
Type
PCSSCMN Percent steady this month 0-100 Program
PCSSL24 Percent steady last 24 hours 0-100 Program
PCSSLMN Percent steady last month 0-100 Program
READSUP Read-suppress flag. 1 = do not read data from Digital Engineer
DCS/IMS.
RESSS Resolve steady-state. 1 = steady-state program Digital Engineer
reloads database. This is normally not required due
to periodic automatic reloads.
RESTART Restart-on-failure flag. 1 = watchdog program will Digital Engineer
restart online system when it detects a failure.
RFORCESS Force ramp steady-state. 1 = force ramp steady- Digital Engineer
state condition.
RMPDAT Ramper complete data stamp. Date when ramper Date Program
completed implementing optimization results.
RMPONOFF Ramp on/off. 1 = implementation of optimization Digital Operator
targets enabled.
RMPOWDG Ramp output watch dog. Reset to Ramp Output Counter Program
Reset Value each time the ramper outputs
setpoints. May be counted down by DCS/IMS to
monitor if setpoints are being sent periodically.
RMPPRT Ramp print flag. 1 = print ramper calculations to Digital Engineer
rteimp.prt
RMPTIM Ramper complete time stamp. Time when ramper Time Program
completed implementing optimization results.
RSSDETECT Ramp steady-state detection. 1 = plant is steady Digital Program
enough to ramp.
RUNMODE Project run mode: Test mode or Connect to IMS. 1 Digital
= Test mode
SCANALT Number of alternates used (case 1 alternate source Counter Program
tags used due to bad qualities on primary tags)
SCANBAD Number of bad points (case 1 input points that Counter Program
were bad upon input)
SCANCLAMP Number of clamped points (case 1 inputs that were Counter Program
clamped)
SCANOVR Number of override points (case 1 inputs that were Counter Program
overridden)
SCANTOT Total number of scan points (points configured as Counter Program
parameter case inputs)
SOLCMN Current month solutions received Counter Program
SOLL24 Last 24 hours solutions received Counter Program
SOLLMN Last month solutions received Counter Program
SSDETECT Steady-state detection. 1 = plant is steady enough Digital Program
to start parameter case.

Aspen OnLine 12.1 User Guide Appendix • A-3

Tag Name Description Value Set By
Type
SSDPRT Steady-state print flag. 1 = print steady-state Digital Engineer
statistics to rtessd.prt
SSDWD Steady-state watch dog. Used to monitor health of Counter Program
steady-state program.
STARTCYCLE Start of cycle flag. Set to 1 at the start of the Digital Program
optimization cycle.
WDGKILL Watch dog kill. Internal value used to shut down Digital Program
watch dog.
WRITSUP Write suppress flag. 1 = do not write targets or Digital Engineer
implement setpoints.

Aspen OnLine Status Values

The APOSTAT (Aspen OnLine Status) tag may have the following
values:
Value Meaning
-4 Steady-state aborted
-3 Scheduler aborted
-1 Optimization shutdown
1 Startup initialization
2 Waiting for steady state
3 Aspen OnLine optimization off
4 Waiting on other plant
5 Initializing implementation module
6 Getting input data
7 Calculating parameters
8 Storing parameters
9 Getting optimize case bounds
10 Calculating setpoints
11 Storing targets
12 Implementing setpoints
13 Full optimize case fetch
14 Full optimize case
15 Full optimize case put
16 Waiting for line out
26 Waiting No Ramp delay
27 Setpoint implementation input data problem
28 Setpoint implementation module aborting
29 Get/put input data problem
30 Get/put aborting

A-4 • Appendix Aspen OnLine 12.1 User Guide

 Value Meaning
31 Parameter case did not solve
32 Parameter case aborting
33 Optimize case did not solve
34 Optimize case aborting
35 Full optimize case did not solve
36 Full optimize case aborting
37 Aspen OnLine time-out detected
38 Aspen OnLine process failure detected

Steady-State Detection Algorithms

The steady-state detection function provides two different
algorithms for checking whether a plant tag value is at steady state.
These are:
• Heuristic Method – This method is based on a light filter and
a heavy filter on tag values of the plant.
• Statistical Method – This method performs a statistical check
on the data.
To determine if the plant or process is at steady state or not, a
number of plant tags are selected to be analyzed. This is much like
the process that goes on in a plant operator’s mind when asked
how steady the plant has been running. The operator typically
examines a few key tags and their recent fluctuations to answer the
question. Select these same tags for automating the detection of
steady state. Any of the selected plant tags can be configured to be
analyzed by either algorithm while configuring the Engine
Database. When the overall plant steady-state check is performed,
each tag value is checked individually using the appropriate
algorithm. If any one of the selected plant tags fails the steady-state
check, the plant is deemed to be in an unsteady-state condition.
Heuristic Method The heuristic method utilizes two filters applied to each tag value
to generate two moving average values for each tag. A filter takes
the form
X t = f × X t + (1 − f ) × X t −1

Where the filter factor, f, lies between 0 and 1.0. When f equals 1.0
no filtering takes place, and the current average value, X t , is the
same as the current value, X t . When f equals 0, the previous
average value, X t −1 , is never updated with the current value.

Aspen OnLine 12.1 User Guide Appendix • A-5

 For the light filter, the value of f should be between 0.7 and 0.95
(default 0.8). This emphasizes the current value in the current
moving average, X t . For the heavy filter, the value of f should be
between 0.05 and 0.3 (default 0.2). In this case, the effect of noise
on the moving average is greatly reduced.
The Steady State function will provide the following checks and
calculations on each point configured for the heuristic method:
1 Light filter and heavy filter values will be calculated for each
designated plant tag value. The filter factors entered on the
Data Browser | Tags | Grid View | SS Detection sheet during
Engine Database configuration are used in the calculation. If a
plant tag has a history of 60 raw values (Data collected once
per minute for 60 minutes), then an array of 60 light filter
values and 60 heavy filter values would be calculated for the
tag. Each pair of filter values is calculated with the following
equations,
(X ) = f
L t L ( )
× X t + (1 − f L ) X L t −1

(X ) = f
H t H × X t + (1 − f H )(X )H t −1

Where
(X ) L t = Light filter value for plant tag history value at time t

(X ) H t = Heavy filter value for plant tag history value at time t

Xt = Raw unfiltered plant tag history value at time t

fL = Light filter factor

fH = Heavy filter factor

(X ) L t −1 = Light filter value at previous time increment

(X ) H t −1 = Heavy filter value at previous time increment

2 The steady-state criterion for each plant tag value is that the
absolute difference between the light filter value and the heavy
filter value over the specified time interval is less than the
tolerance configured on the SS Detection sheet.
3 To determine if the process is trending, the absolute difference
between the oldest and newest heavy filter tag values is
compared against the trend tolerance value. If this difference is
less than the allowable tolerance, then the plant tag value will
be considered to represent a steady-state condition.

A-6 • Appendix Aspen OnLine 12.1 User Guide

 Note that tolerance limits are in the same units as the variables.
They are not expressed in terms of a percentage of range, or other
relative measure.
Statistical Method The statistical method can only be used to detect if a plant is
trending. The method determines the ratio between the variance,
σ 2 , and the mean square successive differences, δ 2 . The variance
is given by
2
1 k
 __

σ =
2
∑  Xi − X 
(k − 1) i =1  
and the mean square successive difference is given by
1 k −1
δ =
2
∑ ( X i +1 − X i )2
(k − 1) i =1
Where
k = Number of values in the tag value history.
Xi = The ith history value.

X = The average of the interval history tag values.

The ratio ( δ / σ ) is then calculated and used as an indicator of

2 2

how steady the variable is. Ideally, a value near 2 or greater

indicates that there is no trend in the data. The data can then be
considered to represent a steady state condition.
Because this is a statistical check, the actual number of data points
used in the determination must be taken into account. The
statistical method uses a table of 95 percent confidence level
values versus the number of data points. A value of the ratio equal
to or greater than the 95 percent confidence level value
corresponds to no significant trending. The calculated value of
( δ / σ ) is compared to the appropriate value from the table to
2 2

determine if the value represents a steady state condition.

As an example consider the case with 60 data points. The 95
percent confidence limit value from the table is 1.5814. If the value
of ( δ / σ ) is greater than this value, then the tag value is
2 2

considered to represent steady state.

This statistical method can be tuned. This is accomplished by
adjusting the value, T , in the Tolerance field in the Steady State
Detection folder. The default value is 0, which corresponds to no
tuning. A positive value corresponds to a relaxation of the trend
test. The tolerance value is used to compute a δ T value from
2

Aspen OnLine 12.1 User Guide Appendix • A-7

 1 k −1 2
δ T2 = ∑
(k − 1) i =1
T =T2

If the value of δ T is greater than the value δ , then this value is

2 2

used to compute the ratio, (δ T / σ ) , which is then tested against

2 2

the 95 percent confidence level value. If the value of (δ T / σ ) is

2 2

greater than this value, then the tag value is considered to represent
steady state.

Run-Time Messages
During project execution, various messages are displayed to the
user indicating the status of the onlinr project. The messages
broadly fall into two categories:
• Messages indicating the progress of a successful run
• Messages indicating warnings and errors
These execution status messages are discussed in the following
sections.
Normal Execution During an error-free execution, a sequence of three run-time
messages is displayed to advise users of the progress of the project
execution. These messages appear in display boxes whose labels
indicate the names of the process models being executed.
Analyzing Data This message appears as soon as the user issues the command to
run a model calculation. This message signals the start of the
execution phase. During this phase of execution, the following
events occur:
• Model input data is gathered for transmittal to the model.
• Project configuration is checked to see if this model is to be run
with data validation and/or steady-state detection. If either of
these is required with the model calculation, the appropriate
procedures are initiated.
• Unit conversions are executed.
• Errors due to any of the above are displayed to the user.
Initializing Model This is the second message that appears during the execution
phase. During this phase of execution:
• The process model is opened for execution.
• The simulation engine for the process model is activated.
• The links between model variables and project tags are
activated.
• Data is transferred from the tags to the model variables.

A-8 • Appendix Aspen OnLine 12.1 User Guide

 Running the Model This is the last of the three messages displayed during a successful
model calculation. During this phase of execution, the model
calculations are started in the simulation engine and continued to
completion.
Abnormal Execution The following warning and error messages are displayed during
the project execution phase only when run-time conditions warrant
either the stoppage of execution or a warning about model
calculations that were completed with problems in processing of
input specifications or calculation sequence.
Gross Error Detection This message will appear after the Analyzing Data message
failed during project execution when a critical variable fails its data
validation.
The message will be displayed only if data validation has been
specified as a requirement for the execution of a particular model.
Data validation will fail either when the input value to a critical
variable in the model chosen for execution has been deemed to be
of bad quality or when the input value of the associated tag is out
of the validity range specified in the engine configuration. Model
calculation cannot proceed until the critical variable value becomes
good. Check the Event Log to determine which tags are declared as
bad.
Non-critical validation events, such as clamping of a tag value that
violates its validity limits will not trigger this message. These
events will, however, still be recorded in the Event Log.
Steady State Detection This message will appear after the Analyzing Data message
failed during project execution in case the process is detected to be in
unsteady operation. The message will be displayed only if steady-
state detection is specified as a requirement for the execution of a
particular model. Steady-state detection failure denotes that one or
more plant tags chosen to be indicative of steady operation of the
process have violated the steady-state criteria specified in the
engine configuration. Model calculations cannot proceed until the
tags once again satisfy the steady-state criteria. Consult the Event
Log or System Info to determine the tags that are not in steady
state.
Model Input Incomplete This message will appear after the Analyzing Data message if a
complete input specification is unavailable for model input forms.
For example, a stream that requires specification of its
temperature, pressure, flowrate, and composition may be missing
one or more of these values. It may also signify that a project tag is
linked to a model input variable that is associated with a calculated
product stream in the model that does not require inputs. For
example, if the properties of a distillation column overhead stream
are to be calculated, they do not require input information. When

Aspen OnLine 12.1 User Guide Appendix • A-9

 model input is deemed incomplete, model calculations do not
occur. To determine the cause of the problem, review the links
between model variables and project tags on the Data Browser |
Models | model name | Variable-Tag Mapping sheet.
Run Finished with errors This message will appear after the Running the Model message if
the model calculations complete with errors or severe errors. The
project screens will not be updated with values from the model, nor
will output values from the model be written to the Run Log. The
model input values from the Run Log should be reviewed and used
to re-run the model calculations from the model user interface
(rather than from Aspen OnLine) to diagnose the problem.

Hints and Recommendations

Plant Data Hints for the usage of plant data:
• Test Cim-IO connections to all plant data sources that are being
used in the online application. Use the Cim-IO test for IP.21
that is described in Chapter 3, Online Project Development.
For other DCS/IMS systems, refer to the Cim-IO manual for
test procedures.
• If a plant IMS or DCS has different categories of tags, test
Cim-IO connections to each tag category. For example, if the
online application will be accessing IP.21 tag categories named
IP_AnalogDef, IP_AIDef, etc. choose a tag from each of these
categories and test the Cim-IO connection to one example of
each tag category.
• A Cim-IO connection to unmapped tags in an IMS system may
be unsuccessful unless the label Value follows the tag name.
For example, tags of type AnalogDef in IP.21 fall in this
category. If the IP.21 AnalogDef tag FI-101 is to be used in an
online application, enter FI-101 Value rather than just FI-101
in the Tag Definition sheet of the engine configuration
interface. In performing the Cim-IO test, also use FI-101 Value
as the tagname to be tested to verify proper access to its value.
• If the Cim-IO service or the DCS/IMS server becomes
unavailable temporarily, online projects can still be executed if
no model variables have been configured to be critical. Aspen
OnLine will use the values from its data buffer to execute these
runs, but current plant values are not being used. Aspen
OnLine can continue to be used for What-if analysis or in Test
Mode when the Cim-IO service or the DCS/IMS server is
unavailable.
• Aspen OnLine does not have to be shut down and restarted
when a disconnected Cim-IO service or DCS/IMS server

A-10 • Appendix Aspen OnLine 12.1 User Guide

 becomes available again. Aspen OnLine will automatically
recognize that these resources are again available.
Process models Recommendations for the usage of process models:
• It is recommended that Aspen Plus backup files (*.bkp files) be
used to ensure compatibility across different versions of Aspen
Plus.
• Process models should be thoroughly tested using the Aspen
Plus User Interface before they are used with Aspen OnLine.
The model should be robust.
• In the Tools | Options | Run dialog box of Aspen Plus, ensure
that the Load Results Interactively option is not selected. If
this option is selected, model results will not become available
to tags even if model variables and tags are linked in Aspen
OnLine. Project execution will fail as a result.
• Before using the models with Aspen OnLine, prepare a list of
the model variables that will be linked to project tags. Either of
two methods can be used to determine the variable names used
in Aspen Plus after successfully running a model calculation:
• Open Tools | Variable Explorer in the Aspen Plus user
interface. The Variable Explorer is also used in Aspen OnLine
to display model variables. Navigate to the desired stream or
block in the variable tree. Open the Input or Output folder
under the stream or block to pick the required variable. A
variable that has an icon of a folder with a plus sign (+) in front
of it can be opened further. Only variables that are represented
by this icon: should be chosen to be linked to project tags.
Compare the value that appears in the Value field of the Value
Related Attributes section in the right portion of the Variable
Explorer screen with the variable value in the Aspen Plus
Data Browser to confirm that the proper variable has been
selected. When you are certain you have selected the right
variable, take note of its name from the Path to the Node field
in the right portion of the Variable Explorer screen. When
using the Variable Explorer in Aspen OnLine to link model
variables to tags, use the same variable names.
• Alternatively, after running the process model in Aspen Plus,
copy the value of a model variable that is to be linked to a tag
from the Data Browser of Aspen Plus, and paste it to a cell in
Excel as a link. The variable name is then displayed in Excel.
This can be used to navigate to the variable in Variable
Explorer when model variables are being linked to tags in
Aspen OnLine.

Aspen OnLine 12.1 User Guide Appendix • A-11

 • Do not link project tags to input variables associated with
product streams whose properties are calculated by the model.
These product stream properties do not require inputs so these
links are invalid. If such links exist, they will prevent model
execution.
• If changes are made to a model after it has already been linked
to an online project, ensure that the inputs in the engine
configuration are still compatible with the model changes. In
other words, ensure that all the model variables that were
linked before are also present with the exact same name (full
Aspen Plus variable name) in the new model.
Project execution Recommendations related to project execution:
• If there are fields in the project GUI requiring user inputs, enter
these input values before running the model. After entering
values, move the cursor to a different location in order for the
inputs to be accepted.
• If you make changes to steady-state detection or data validation
criteria, wait a few minutes before executing the next run. The
Aspen OnLine steady-state detection module takes a few
minutes to update its data buffer to reflect these changes.

A-12 • Appendix Aspen OnLine 12.1 User Guide

 GLOSSARY

Glossary of Terms

.apw
The file extension for Aspen Plus document files.

.bkp
The file extension for Aspen Plus backup files.

Aspen OnLine client

The Client GUI component, used to perform online project
configuration and execution monitoring and control.

Aspen OnLine engine

The component of Aspen OnLine that actually executes the online
application and controls the flow of data between the plant data
server, process model, and user interface.

Aspen OnLine server

Consists of the Aspen OnLine service and DCOM component. It
also includes components that are specific to each online project:
steady-state detection program, engine program and configuration
component.

Aspen Plus
State-of-the-art steady-state simulation technology from Aspen
Technology, Inc.

Aspen License Manager

The AspenTech software that determines if the terms of the
customer software license agreement are met each time an
AspenTech product is used.

Aspen OnLine 12.1 User Guide Glossary of Terms • G-1

 CIM/21
A plant Information Management System from Aspen Technology,
Inc..

Cim-IO
The general purpose interface software system from Aspen
Technology, Inc. for communication with a wide variety of DCSs,
plant Information Management Systems, and plant devices, such as
PLCs.

Clamping
The action of replacing the value of a tag that exceeds its validity
limit with the limit value being exceeded.

COM
Component Object Model, an industry standard used by
applications to expose objects to development tools and other
applications.

Critical Variable
A critical variable is a model variable that cannot tolerate bad input
data of any sort and for which replacement of bad data is not
applicable. Thus, if the input data fails data validation or the data is
deemed of bad quality, then model execution cannot be allowed.

Data Validation
A method for detecting gross errors and out-of-limit tag values.

DCOM
Distributed COM, Microsoft’s distributed object system, is an
ActiveX interface for distributed component network applications.
Distributed COM allows the seamless interoperation of ActiveX-
enabled applications running on different machines, using a
standards-based remote procedure call (RPC).

DCS
Distributed Control System, the process control system which
plant data is read from and control targets are sent to. This could be
a true DCS or software running on a host computer.

Discrete Variable (DV)

A discrete or Boolean variable within the DCS/IMS.

G-2 • Glossary of Terms Aspen OnLine 12.1 User Guide

 IMS
An acronym for plant Information Management System.

IP.21
InfoPlus.21 is a real-time information management system from
Aspen Technology, Inc. for the manufacturing and processing
industries. It collects, manipulates, and stores large volumes of
process data and makes this data accessible for analysis and
reporting by client users, business systems, and production
applications.

InfoPlus X
A plant information management system from Aspen Technology,
Inc.

Local client
The Aspen OnLine client that resides on the same computer as the
Aspen OnLine server.

Model Variables
Variables in a process model that receive their input values from
Aspen OnLine tags or that provide their result values to Aspen
OnLine tags.

Process Explorer
Aspen Process Explorer is a presentation system that graphically
delivers data to the desktop from InfoPlus.21 and other AspenTech
Information Management Systems.

Process Variable
A continuous variable within the DCS/IMS.

PLC
Acronym for Programmable Logic Controller, a microprocessor-
based programmable logic device that is used primarily for on/off
and sequencing control in an industrial process.

Remote client
An Aspen OnLine client that resides in a different computer than
the one in which the Aspen OnLine server resides.

Aspen OnLine 12.1 User Guide Glossary of Terms • G-3

 Setcim
A plant Information Management System from Aspen
Technology,. Inc.

Tag
An identifiable and accessible collection of information. This can
be actual data from the plant or the model, or an internal tag within
Aspen OnLine.

Target IMS tag

A tag in the plant Information Management System that has been
created to receive and store values provided by internal Aspen
OnLine tags.

TCP/IP
Acronym for Transmission Control Protocol/Internet Protocol. A
set of transport protocols for the Internet that provides both
connection-oriented (TCP) and connectionless (IP) data transfer.

Write-back tag
An internal Aspen OnLine tag whose value will be sent to a Target
IMS tag in the plant information management system.

X Variable
Any variable within the Aspen Plus, Hysys, or Aspen Custom
Modeler model.

G-4 • Glossary of Terms Aspen OnLine 12.1 User Guide