You are on page 1of 133

Aspen Simulation

Workbook

User Guide
Version Number: V7.1
January 2009
Copyright (c) 2004 - 2009 by Aspen Technology, Inc. All rights reserved.

Aspen Simulation Workbook, aspenONE, the aspen leaf logo and Plantelligence and Enterprise Optimization are
trademarks or registered trademarks of Aspen Technology, Inc., Burlington, MA.

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

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

Although AspenTech has tested the software and reviewed the documentation, the sole warranty for the software
may be found in the applicable license agreement between AspenTech and the user. ASPENTECH MAKES NO
WARRANTY OR REPRESENTATION, EITHER EXPRESSED OR IMPLIED, WITH RESPECT TO THIS DOCUMENTATION,
ITS QUALITY, PERFORMANCE, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.

Aspen Technology, Inc.


200 Wheeler Road
Burlington, MA 01803
USA
Phone: (1) (781) 221-6400
Fax: (1) (781) 221-6410
URL: http://www.aspentech.com
Contents
Contents.................................................................................................................iii

Section 1: Using Aspen Simulation Workbook ........................................................1


Introduction .................................................................................................. 1
Who Should Read this Guide?................................................................. 2
Related Documentation ......................................................................... 2
Technical Support................................................................................. 3
Getting Started with ASW................................................................................ 4
Aspen Simulation Workbook Toolbars ...................................................... 5
Getting Started with the ASW Organizer ............................................................ 8
Bringing a Simulation Model into ASW ..................................................... 8
Organizer Toolbar................................................................................13
Organizer Navigation Pane....................................................................15
Copying and Pasting within the Organizer ...............................................17
Selecting and Changing a Simulation Case ..............................................18
Embedding Simulation Case Files in MS Excel ..........................................22
Exporting Embedded Simulation Case Files from MS Excel.........................23
Removing Embedded Simulation Case Files from MS Excel ........................23
Using the Organizer for Exporting and Importing Variable Lists ............................24
Using the Variable Browser and Query Functions......................................27
Setting Variable Properties ...................................................................29
Copying Variables from the Model to the Organizer ..................................32
Navigating the Organizer Variable Grid ...................................................34
Identifiers ..........................................................................................35
Model Variable Tables ..........................................................................36
Placing the Table into Excel ..................................................................37
Pulling Tags into the Organizer........................................................................37
Linking Excel to Plant Data Tags ............................................................37
Mapping Tags to Model Variables ...........................................................38
Setting Tag Updates and Adding Tag Tables ............................................38
Using the Standard Table Wizards ...................................................................39
Creating Tables ...................................................................................39
Creating Table Templates .....................................................................40
Creating Model Variable Tables..............................................................42
Quick Tables.......................................................................................45
Instant Table Template ........................................................................47
Enhanced Table Template.....................................................................47
Running Scenarios (using the Scenario Wizard) .................................................55
Working with Dynamic Profiles ........................................................................56
Adding Graphics and Controls .........................................................................58
Aspen Simulation Workbook Process Graphics .........................................58
Inserting Complete Process Flow Diagrams .............................................59

Section 1: Using Aspen Simulation Workbook iii


Building a Model Interface ..............................................................................62
Developing a Model .............................................................................62
Deploying Models ................................................................................63
Connecting Models to Plant Data Tags ....................................................64
Retrieving Plant Tags into Organizer ......................................................64
Mapping Tags to Model Variables ...........................................................66
Preparing Models for Distribution ...........................................................69
Showing Simulation Status ...................................................................69
Changing the Path or Filename of a Linked Model.....................................69
Publishing the Model and Locking Features..............................................69
Writing Scripts for ASW..................................................................................70
Aspen Simulation Workbook Functions ...................................................70
Aspen Simulation Workbook Function Arguments .....................................71
Aspen Simulation Workbook Macros .......................................................71
Using Buttons and Other Controls to Run ASW Macros ..............................72
Running Simulation Cases Using ASW ..............................................................75
Workflow Overview..............................................................................75
Entering Model Variables ......................................................................76
Activating the Simulation Engine ...........................................................76
Running the Active Simulation Case .......................................................77
Viewing the Active Simulation Case........................................................79
Viewing Simulation Log Files .................................................................79
Saving the State of the Simulation Case .................................................80
Using Visual Basic Automation to Launch Simulation Cases........................80
Scheduling Simulation Runs ..................................................................80
Using Remote Execution.................................................................................84
Installing Aspen Remote Simulation Server (ARSS) on Windows Vista and
Windows 2008 Server ..........................................................................86
Running Aspen Remote Simulation Server on Windows Vista .....................86
Monitoring the Remote Simulation Server ...............................................87
Limiting End-User Access to Simulation Case Files and Data ................................88
MS Excel Worksheet Protection .......................................................................89
Using ASW to Automate Workflow .........................................................90
Mapping Tag Quality Definitions ............................................................95
Creating Tag Tables .............................................................................97
Getting the Most from MS Excel ......................................................................97
Conditional Formatting .........................................................................97
MS Excel Form Controls........................................................................99

Section 2: Working with Specific Simulation Platforms ......................................107


Using ASW with Esteco ModeFrontier ............................................................. 107
Using ASW with Oracle CrystalBall ................................................................. 107
Using Oracle Crystal Ball to perform Monte Carlo analysis with ASW
Simulations ......................................................................................108
Using ASW within Aspen Plus ........................................................................ 110
EO and SM Variables and Synchronization............................................. 110
Developing Interfaces to EO Models ..................................................... 111
Objective Function Variables ............................................................... 112
Accessing Spec-Groups ...................................................................... 113
Accessing Connections ....................................................................... 114
Troubleshooting EO Model Interfaces ................................................... 114
Accessing Calculator Blocks and Design Specifications ............................ 115

iv Section 1: Using Aspen Simulation Workbook


Using ASW within Aspen Modeler Products ...................................................... 115
Selecting and Copying Variables from Grids .......................................... 115
Selecting and Copying Variables Using the Aspen Modeler Variable Finder . 116
Accessing Solver Options and Run Options ............................................ 117
Activating and Deactivating Tasks in ASW ............................................. 118
Maximizing Performance of Dynamic Models Running Under ASW ............. 119

Section 3 Troubleshooting..................................................................................121
Required Software....................................................................................... 121
Managing Multiple Versions of ASW and Other MS Excel Add-Ins ........................ 122
Troubleshooting Guide ................................................................................. 122

Index ..................................................................................................................126

Section 1: Using Aspen Simulation Workbook v


Section 1: Using Aspen
Simulation Workbook

Introduction
Aspen Simulation Workbook (ASW) is a tool for interfacing AspenTech’s
process simulation models with Microsoft Excel worksheets. Aspen Simulation
Workbook also has tools to link model variables to plant data tags imported
using third-party applications. These capabilities allow modeling experts to
link models and plant data and publish the resulting models as Excel
worksheets for use by casual model users.
• Aspen Simulation Workbook is compatible with Microsoft Excel 2003 or
2007, and operates under Windows XP, or Vista environments.
• Aspen Simulation Workbook supports Aspen Plus. and is also compatible
with the Aspen HTFS Research Network family of products, including
Aspen Shell and Tube Exchanger, Aspen Air Cooled Exchanger, Aspen
Shell and Tube Mechanical, and Aspen Fired Heater, etc.
• Aspen Simulation Workbook supports Aspen Plus and Aspen HYSYS cases,
as well as the layered products based on these platforms for example,
Aspen Polymers Plus and Aspen HYSYS Refining
• Aspen Simulation Workbook supports steady-state HYSYS models,
including models based on HYSYS Upstream and Aspen HYSYS Refining.
• Aspen Simulation Workbook fully supports sequential-modular (SM)
variables in Aspen Plus. Equation-oriented (EO) models are supported
indirectly through the SM variables, which are synchronized with the EO
variables during simulation runs.
• Aspen Simulation Workbook is also compatible with the Aspen Modeler
family of products, including Aspen Custom Modeler (ACM), Aspen Plus
Dynamics (AD), Aspen Chromatography, Aspen Adsorption, and Aspen
Model Runner (AMR).
• Initialization, steady-state, and dynamic runs are also fully supported.
Although estimation and optimization run modes are supported, the
estimation data and results and optimization results variables are not
exposed in the current ACM adapter.

Section 1: Using Aspen Simulation Workbook 1


Who Should Read this Guide?
Customers with two types of roles are associated with Aspen Simulation
Workbook: Model Authors and Model Users.
Model Authors (model interface developers) use Aspen Simulation Workbook
to link process models and plant data tags to MS Excel workbooks. A typical
Model Author is familiar with the underlying simulation tools (for example,
Aspen Plus, Aspen HYSYS, etc.) and may also be familiar with process
information systems such as Aspen IP21. Most of the chapters in this Guide
address the steps required to interface the models and plant data to an Excel
sheet.
Once the model interface is developed, it can be deployed to a larger number
of Model Users (MUs). The typical Model User is comfortable using Excel and
has an understanding of the chemical process, but may not be an experienced
user of the underlying simulation tools. Model Users can refer to the rest of
Chapter 1 for the steps required to run simulations through Excel using Aspen
Simulation Workbook.

Related Documentation
Note: Within Aspen Simulation Workbook, Aspen Plus, and Aspen HYSYS,
press F1 to access the online help.
In addition to this document, a number of other documents are provided to
help users learn and use Aspen Simulation Workbook, Aspen Plus, and Aspen
HYSYS.

Aspen Plus Documentation

Title Content

Aspen Plus Getting Started Building Tutorials covering basic use of Aspen Plus. A
and Running a Process Model prerequisite for the other Getting Started
guides
Aspen Plus Getting Started Modeling Tutorials covering the Aspen plus features
Processes with Solids designed to handle solids
Aspen Plus Getting Started Modeling Tutorials covering the Aspen plus features
Processes with Electrolytes designed to handle electrolytes
Aspen Plus Getting Started Using Tutorials covering the use of equation-
Equation-Oriented Modeling oriented models in Aspen Plus
Aspen Plus Getting Started Tutorials covering the development of
Customizing Unit Operation Models custom unit operation models in
Aspen Plus
Aspen Plus Getting Started Modeling Tutorials covering the Aspen Plus features
Petroleum Processes designed to handle petroleum
Aspen Plus User Guide Procedures for using Aspen Plus
Aspen Plus Unit Operation Models Information related to specific unit operation
Reference Manual models in Aspen Plus
Aspen Plus System Management Information about customizing files provided
Reference Manual with Aspen Plus

2 Section 1: Using Aspen Simulation Workbook


Aspen Plus Documentation

Title Content

APrSystem Physical Property Methods Information about property methods and


and Models Reference Manual property models
APrSystem Physical Property Data Information about property databanks
Reference Manual
Aspen Engineering Suite Installation Instructions for installing Aspen Plus and
Manual other Aspen Engineering Suite products

Aspen HYSYS
Documentation

Title Content

Customization Guide This manual contains information on enhancing the


functionality of HYSYS by either using third-party tools to
programmatically run HYSYS (Automation), or by the addition
of user-defined Extensions.
Dynamic Modeling This manual contains information on building and running
Guide HYSYS simulations in Dynamic mode. Dynamic theory, tools,
dynamic functioning of the unit operations as well as controls
theory are covered.
HYSYS OLI Interface This manual contains information on applying HYSYS OLI
Reference Guide Interface package to a simulation. This property package
comprehensively and accurately simulates and predicts
electrolyte systems.
Operations Guide This manual contains information on steady state operation of
HYSYS unit operations, streams, and utilities.
Simulation Basis This manual contains all information relating to the available
Guide HYSYS Fluid Packages and components. This includes
information on the Oil Manager, Hypotheticals, Reactions, as
well as a thermodynamics reference section.
Tutorials & This manual provides a range of step-by-step to advance
Applications Guide instructions for building some industry-specific simulation
examples.
Upstream Option This manual contains information on building and applying
Guide HYSYS Upstream unit operations.
Multiflash for This manual contains information on applying Multiflash GUI
Windows User Guide in Microsoft Windows.
HYSYS Refining This manual contains information on building and applying
Option Guide HYSYS Refining unit operations and petroleum assay.
User Guide This manual provides in depth information on the HYSYS
interface and architecture.

Technical Support
AspenTech customers with a valid license and software maintenance
agreement can register to access the online AspenTech Support Center at:
http://support.aspentech.com
This Web support site allows you to:

Section 1: Using Aspen Simulation Workbook 3


• Access current product documentation
• Search for tech tips, solutions and frequently asked questions (FAQs)
• Search for and download application examples
• Search for and download service packs and product updates
• Submit and track technical issues
• Send suggestions
• Report product defects
• Review lists of known deficiencies and defects
Registered users can also subscribe to our Technical Support e-Bulletins.
These e-Bulletins are used to alert users to important technical support
information such as:
• Technical advisories
• Product updates and releases
Customer support is also available by phone, fax, and email. The most up-to-
date contact information is available at the AspenTech Support Center at
http://support.aspentech.com.

Getting Started with ASW


1 Follow the steps for installing Aspen Simulation Workbook described in the
Aspen Engineering Suite Installation Manual.
2 Choose your desired add-ins from the Aspen Simulation Workbook Add-in
Selector
3 Open Microsoft Excel
4 Note that the Design and Run toolbars are loaded, along with the
traditional Excel toolbars.

5 You're now ready to begin either working with an existing simulation or


creating your own.

4 Section 1: Using Aspen Simulation Workbook


Aspen Simulation Workbook Toolbars
Aspen Simulation Workbook adds two toolbar menus to Excel: the Aspen
Simulation Workbook Design Toolbar, and the Aspen Simulation Run Toolbar.

Note: Model Users or Model Authors using either Excel version 2007 (or
higher) will view the toolbar menus as ribbon bar menus as shown below.
Design Toolbar
Run Toolb

Design and Run Ribbon Bars

Design Toolbar
The Aspen Simulation Workbook Design toolbar is used by the Model Author
to access the Organizer and other options used during the development of the
model interface. This toolbar also includes an option that allows the Model
Author to lock the worksheet out of design mode to restrict user access to
various Aspen Simulation Workbook features.
The designer toolbar is used by the model developer to create an ASW
interface:
• Activate / Deactivate ASW
• Link simulation cases
• Link model variables
• Link plant tags
• Create tables in Excel
• Draw PFDs
• Lock features

Section 1: Using Aspen Simulation Workbook 5


Button Action

Enable or disable Aspen Simulation Workbook


/
Open the model variable organizer form

Create an instant table

Insert process equipment icons

Import selected tags into the organizer

Enable or disable automatic tag update (button shows state,


enabled or disabled, click button to toggle state)
Protect end user access; button shows state (locked or
unlocked). Click the button to toggle state
Refresh Excel with current simulation data

Run Toolbar
The Aspen Simulation Workbook Run toolbar contains the controls to activate,
view, run, and stop the models. This toolbar is convenient for the Model
Author and the final Model Users. The run-time toolbar is used by the model
operator to:
• Activate / Deactivate models
• Update plant tags
• Control / run simulation cases
• View messages
• View models

6 Section 1: Using Aspen Simulation Workbook


Button Action

Select (and display) active simulation case

Activate model / Deactivate model; this button shows


/ the state (a red X indicates the model is currently
deactivated).
Select (and display) active simulation environment

Select (and display) simulation run mode

Run active simulation / toggle solver


This button is active when the solver is on.
Step active simulation

Pause active simulation

Toggle solver (button is active when solver is off)

Restart simulation (rewind to start for dynamic runs)

Reinitialize simulation (Aspen Plus only)

Show / hide active simulation model

Load snapshot

View message logs

Update tags

Section 1: Using Aspen Simulation Workbook 7


Note: For Windows 2003 or earlier, the first time you open a new worksheet
the Aspen Simulation Workbook Toolbars may not be visible. To expose these
toolbars, select View, ToolBars through the Excel pull-down menus and check
the Aspen Simulation Workbook toolbars as shown below:

If you do not see these options on the Toolbars menu, check the Add-in
Manager and enable the Aspen Simulation Workbook Add-in. (For Windows
2007 or higher, check under the Aspen tab in the ribbon bar.)

Enable/Disable Toggle

Use the button on the Aspen Simulation Workbook Design toolbar to


activate the features of Aspen Simulation Workbook. Enabling Aspen
Simulation Workbook checks out a base ASW license, which remains checked
out until the worksheet is closed or the feature is disabled by clicking the

button.
The enabled/disabled state of the worksheet is retained when you save your
Excel workbook. If the Excel workbook is saved while Aspen Simulation
Workbook is enabled, this feature will be automatically enabled next time the
Excel workbook is opened.

Getting Started with the ASW


Organizer
The Organizer is a tool added to Excel when Aspen Simulation Workbook is
installed. The Organizer is used as a central location to define, retrieve, sort,
and organize model variables and process data tags. Within the Organizer,
the Model Author can view all of the properties associated with each variable
and tag.

Bringing a Simulation Model into ASW

Open the Simulation References Window


Use the Manage Simulation Case selection on the Run toolbar to open the
Simulation References window.
1 On the Run toolbar, choose the Active Simulation Case window, select
the drop down menu and choose Manage Simulations ....

8 Section 1: Using Aspen Simulation Workbook


2 The Aspen Simulation Workbook Organizer window will appear

3 Click on the green cross in the Aspen Simulation Workbook Organizer


toolbar. A browser window will appear allowing you to navigate to your
particular simulation case.

4 The simulation you want to add should show up in the main simulation list
on the simulation management page.

Section 1: Using Aspen Simulation Workbook 9


Working with the Manage Simulations Page

The various panes (highlighted in red) within the Organizer window allows
you to work with the simulation case.

10 Section 1: Using Aspen Simulation Workbook


Organizer Pane Description
Simulation Grid The Simulation Grid (top pane) is the area
where all current simulations are listed.
Link to Case This pane allows you to link to (or work
between) different simulation cases.
Embed Case This pane is used when you wish to
import or imbed a simulation case.
Remote Execution With the remote port set to "0" (the
default port), you can execute the
simulation case on a remote server.
Simulation Case Properties View/edit simulation case properties

Note: When using Microsoft Office 2007 or later, it is possible that the
product registration screen may appear behind the main screen at initial
start-up; preventing the software from running.
To fix this, hold the Alt and Tab buttons down simultaneously and any hidden
screens will move to the front and become visible.

Additional Activities using the Simulation Page


Deleting a simulation which has variables associated with
it in the Variable Organizer
1 Select ‘Manage Simulations’ from the simulation dropdown control on the
ASW toolbar. This causes the Variable Organizer simulation management
page to open.
2 Select the simulation that you want to delete in the simulation
management page.
3 Assuming that the simulation has variables associated with it currently in
variable organizer, a dialog shows you that all variables associated with
the simulation will also be deleted.
4 You are asked if you would like to proceed.
5 If you click on ‘yes’, then the simulation and all associated variables are
removed from Variable Organizer.

Changing links to a new simulation


1 Select ‘Manage Simulations’ from the simulation dropdown control on the
ASW toolbar.
2 The Variable Organizer simulation management page opens.
3 Select a simulation from the main simulation list.
4 Click the “browse” button from the “Change Simulation” group box, and
select the new simulation with which you wish to link.
5 The next time the case is activated, the simulation will link to the new
simulation file, and the existing variables will bind to the new simulation

Setting a Simulation to be Remotely Executed


1 Select ‘Manage Simulations’ from the simulation dropdown control on the
ASW toolbar.

Section 1: Using Aspen Simulation Workbook 11


2 The Variable Organizer simulation management page opens.
3 Select a simulation from the main simulation list.
4 Check ON the “Execute Remotely” checkbox, and fill in the remote server
hostname and port.
5 Click the ‘Test Connection’ and a message box tells you whether ASW
could see the remote server and if the required simulator existed on the
server.
6 Activate the simulation, and it is activated on the specified remote server.

Note: Zero (0) denotes the default port.

Embedding and exporting the simulation


1 Select "Manage Simulations" from the simulation dropdown control on the
ASW toolbar.
2 The Variable Organizer simulation management page opens.
3 Select a simulation from the main simulation list.
4 Activate it.
5 Click the "Embed Case" button
6 Check "ON" the Embed Simulation checkbox, and then activate the
simulation. The simulation is embedded
7 Later, click the “Export Simulation” button, and you are prompted to
browse to where you want to save the Simulation file. The simulation is
then saved in an external file.

8 To view the simulation, click the Show/Hide button

12 Section 1: Using Aspen Simulation Workbook


9 You may now use the ASW Organizer to work within the simulation.

Note: Aspen Simulation Workbook can link several simulation cases to the
same Excel workbook. Only one case, however, can be active at any given
time.
The name of the active case is shown in a combo box on the Aspen
Simulation Workbook Run toolbar and on the Sim Manager in the Organizer
Menu Bar when "Sim" is chosen.

Organizer Toolbar
The Organizer is composed of several controls. The Organizer Toolbar includes
a number of buttons to automate frequent tasks and launch tools such as the
ASW Variable Browser and Simulation Workbook Table Wizard.

Button Action

Enable or disable Aspen Simulation Workbook


/

Section 1: Using Aspen Simulation Workbook 13


Button Action

Activate model / Deactivate model


/
Show / hide activated simulation model

Fit columns in variable grid

Show column customization list

Expand all groups in variable grid

Collapse all groups in variable grid

Clear all column groups

Show / Hide variable property pane

Delete selected variables from the organizer

Create standard ASW table using standard table wizard to


generate a table using the selected variables
Create dynamic profile table using the selected variables

Create scenario table using the selected variables

Launch quick-table wizard to define a new table template or to


apply an existing template to the selected variables
Open the ASW variable browser

Copy variables from the paste buffer into the organizer

Export selected variables (creates an XML file with .ATMVO


extension containing the exported variables).
Import selected variables (imports an ATMVO variable file
previously exported from Aspen Simulation Workbook).

14 Section 1: Using Aspen Simulation Workbook


Organizer Toolbar
Shortcuts to
perform common
tasks

Variable Grid
Sort/View /Modify Variable Properties, Variable Properties Pane
Select variables for tables, add/delete tables View all properties of
Navigation Pane
selected variable - modify
Select which task
properties
to perform
Data Control
See number of variables - navigate
to a variable

Organizer Navigation Pane

Section 1: Using Aspen Simulation Workbook 15


The Navigation Pane on the left side of the Organizer allows the Model Author
to switch between various tasks within the Organizer. The Navigation Pane is
divided into five sub-areas.

1 Use Variable Access functions to manipulate model variables, tag


variables, and to map tag quality definitions:
• Use the Model Variables task to open the model variable grid;
• Use the Tag Variables task to open the tag grid;
• Use Tag Quality Map to map tag quality definitions from the external
plant data source to Aspen Simulation Workbook.

2 Use the Variable Mapping function to link model variables to process data
tags:
• Communication can be tag→model, model→tag, or bidirectional

3 Use the Table Manager view to access ASW Tables. This view summarizes
the names and locations of all of the tables inserted into an Excel
workbook. The Table Manager provides a convenient location to identify
and safely move, or delete tables from Excel.

16 Section 1: Using Aspen Simulation Workbook


4 The Configuration | Global view shows global Aspen Simulation Workbook
parameters including the list of linked simulations, the working directory
path, and several state variables.

5 The Configuration | Simulations view contains a list of the names and


attributes of all simulation cases attached to the Excel workbook. This
view can be used to launch a browser (the simulation references control)
to find and attach additional simulation cases. This view is also used to
change the default settings of the simulation case. For example, the Model
Author can force a linked simulation case to activate automatically when
the Excel workbook is opened. Select a simulation case from the list in the
central pane and then click one of the buttons on the right side of the
form to change the state of the case or to set options associated with the
case.

6 The Logs view shows status messages (warnings, errors, etc) from Aspen
Simulation Workbook and from the active simulation case.
Tip: Use the Table Manager or Simulation Workbook Table Wizard to
move or delete tables. The Simulation Workbook Table Wizard can also be
used to add/remove rows and/or columns (including empty rows and
columns) to tables and to auto-format the tables.

Copying and Pasting within the Organizer


Variables can be retrieved into the Organizer using two different mechanisms.
For most variables, using Copy/Paste is the best option for retrieving
variables since it allows the Model Author to navigate to the variable using the
native simulator user interface.
Some variables, however, may not be exposed through the interface in a
text-only format, making them inaccessible to the Copy/Paste mechanism.
The ASW Variable Browser can be used to retrieve all variables associated
with a simulation case. Users familiar with the variable explorer in Aspen Plus
may prefer navigating through this browser instead of using Copy/Paste.
The workflows for each option are described in detail below.

Section 1: Using Aspen Simulation Workbook 17


Pasting Variables Using Copy/Paste
1 Open the active simulation case.
2 Navigate to the variables of interest in the active simulation case using
the native simulation user interface.
3 Select the variable or range to be copied.
4 Press CTRL+C to copy.
5 Return to the Excel workbook.

6 Click the Organizer button on the Aspen Simulation Workbook


Design toolbar to open the ASW Organizer .
7 Select Model Variables in the Variable Access section of the Organizer
navigation pane. This opens the variable grid.

8 Use the Paste button on the ASW Organizer Toolbar to paste the
variables into the organizer grid.

Pasting Variables Using the ASW Variable Browser

1 Use the Organizer button on the Aspen Simulation Workbook


Design toolbar to open the ASW Organizer.

2 Use the Variable Browser button to open the ASW Variable Browser
wizard.
3 The ASW Variable Browser can browse though two types of variable trees:
• The appModel tree is application specific, and is generally the more
useful of the two options.
• The CCDMModel tree, or Common Core Data Model is a generic tree
that maps to common data representations across the base
simulators.
4 The user can browse through the data trees to find and select variables.
To select a variable:
• Click on the row containing the variable.
• Use the Add Selected button to paste the variable into the Organizer.
• Use the Close button to return to the Organizer variable view.

Tip: The ASW Organizer variable grid includes mechanisms to sort and
navigate through variables.

Selecting and Changing a Simulation Case


Simulation Cases
Within this guide we use the terms simulation case and model
interchangeably to refer to a single set of simulation files (for example a
single HYSYS case file or Aspen Plus backup file).

18 Section 1: Using Aspen Simulation Workbook


Using Multiple Cases
Aspen Simulation Workbook can link to one or more simulation cases,
however only one simulation case can be active at a given time. The model
user can activate and deactivate simulation cases at will.

Supported Case Types


Aspen Simulation Workbook supports Aspen Plus and Aspen HYSYS cases, as
well as the layered products based on these platforms (for example, Aspen
Polymers Plus and Aspen HYSYS Refining).
Aspen Simulation Workbook is also compatible with the Aspen HTFS Research
Network family of products, including Aspen Shell and Tube Exchanger, Aspen
Air Cooled Exchanger, Aspen Shell and Tube Mechanical, and Aspen Fired
Heater, etc.
Aspen Simulation Workbook is also compatible with the Aspen Modeler family
of products, including Aspen Custom Modeler (ACM), Aspen Plus Dynamics
(AD), Aspen Chromatography, Aspen Adsorption, and Aspen Model Runner
(AMR). Aspen Simulation Workbook supports HYSYS models, including models
based on HYSYS Upstream and Aspen HYSYS Refining.

Caution: Aspen Simulation Workbook fully supports sequential-modular (SM)


variables in Aspen Plus. Equation-oriented (EO) models are supported
indirectly through the SM variables, which are synchronized with the EO
variables during simulation runs.

Working with Columns


The ASW Organizer Variable Grid displays variables as rows and variable
attributes as columns. By default, the Organizer displays a subset of the
available variable attributes. Use the Column Customization button to get a
list of available attributes.
• Adding Columns. To add a new column to the variable grid, click and
hold the column name (variable attribute name) from the list of available
attributes, drag the header into the appropriate location of the variable
grid and release.
• Removing Columns. To remove a column from the grid, click and hold
the column header and drag it onto the column customization list.
• Moving Columns. To move a column, select and drag the column header
to a new location in the grid.
• Resizing Columns. Use the Best Fit button to automatically resize all
columns in the variable grid. The width of individual columns can be
adjusted by dragging the edge of the column left or right in the column
header.
• Sorting Variables. The ASW Organizer can display the variables in a
hierarchical form based on one or more of the variable attributes. To sort
by a particular attribute, drag the column header up to the black space
above the header row. Repeat this action with additional attributes to sort
by multiple categories. Use the Collapse All Rows and Expand All Rows
buttons to quickly expand or collapse the variable grid view. Variables can
be quickly sorted by any category by clicking the appropriate column

Section 1: Using Aspen Simulation Workbook 19


header. Hold down the Shift key when clicking a category header to
perform a secondary sorting operation (for example, to sort by component
ID and stage number in a column profile). Use the filtering control on the
right side of each category header to specify which variables are displayed
in the variable grid (this control pops up a list of options do define the
display filter).

Working with Variables and Variable Lists


Any number of model variables can be linked to an Excel sheet. Each model
variable is a complex named object consisting of several properties including:
type (integer, real, character, etc.), value, and units (where applicable). The
full set of variable properties is documented later in this guide.
Model variables can be input specifications, calculated results, or state
parameters (such as number of stages).

1 In the ASW Organizer, click to open the Variable Browser.


2 Click the Query tab at the bottom of the Variable Browser.

3 In the tree, select an object to query. The query will be limited to the
object selected and the sub-objects under it in the hierarchy.

4 In the query panel, optionally specify a filter at the top on the objects to
search.

20 Section 1: Using Aspen Simulation Workbook


5 Under Condition, specify one or more conditions for the variables to
match, and click Add. To specify multiple conditions, click the Insert AND
or Insert OR button to join conditions with an AND or OR. You can nest
ANDs and ORs to build up complex queries.

6 Click Run to run the query. The results appear in the bottom pane.
7 Select one or more variables from the results and click Add Selected to
add these variables to ASW.
For example, the following query searches for variables with Calculated Status
and names containing "TEMP" within units of measure equal to "2."

Section 1: Using Aspen Simulation Workbook 21


Embedding Simulation Case Files in MS
Excel
Aspen Simulation Workbook allows you to embed simulation case files into
hidden worksheets in MS Excel. This makes it significantly easier to deploy
models to end users, to save files in standard document management
systems, and to run files remotely on a server (see next section).
When using ASW with Aspen Plus, you can embed backup files (.BKP), binary
files (.APW), or the new compound case file (.APWZ). Use compound case
files when the Aspen Plus simulation case requires secondary files such as
Fortran objects, DLLs, and exchanger design EDR files.
When using ASW with an Aspen Modeler product, embed the physical
property data into the simulation file (for example in the ACMF file).
When files are run locally, the embedded files are extracted into a temporary
folder under your profile when the simulation is activated. The simulation runs
in this temporary directory. The embedded file is updated at the end of the
run. Temporary files are deleted when the simulation is deactivated.

To embed the simulation case files:


1 Open the ASW Organizer; select the Configuration | Simulations view.

22 Section 1: Using Aspen Simulation Workbook


2 Select the simulation case to be embedded.
Note: Only one case file may be embedded into Excel.
3 Click the Add Case button on the toolbar, and browse to the desired
simulation case.
4 After selecting the desired simulation case (in this example:
testprob.bkp), click the Import/Embed case button and the simulation
will be embedded.

Warning: Aspen Simulation Workbook can only embed a single file per case
into Excel. When using Aspen Plus, save the Aspen Plus case using the
compound file option to ensure all of the required dependent files are
available.

ASW file embedding cannot be used with Aspen Modeler files which require
APPDF files that cannot be embedded into the simulation case file. This
includes Aspen Plus Dynamics files that use RGIBBS, closed-form Polymers
Plus reaction models, or user reaction or property models written in FORTRAN
and compiled as DLL files.

Exporting Embedded Simulation Case Files


from MS Excel
Use the following procedure to extract embedded case files from an existing
Excel Worksheet:
1 Open the ASW Organizer; select the Configuration | Simulations view.
2 Select the simulation case to be extracted.
3 Click the Export embedded case button to extract the embedded
simulation case; this will open a file browse dialogue. Enter the file name
and point to the file destination using the file browse dialogue, then click
OK to export the file.

Removing Embedded Simulation Case Files


from MS Excel
Use the following procedure to remove embedded case files from an existing
Excel Worksheet:
1 Deactivate the simulation.
2 Open the ASW Organizer; select the Configuration | Simulations view.
3 Select the simulation case to be removed.

Section 1: Using Aspen Simulation Workbook 23


4 After selecting the desired simulation case (in this example:
testprob.bkp), click the Link case (remove embedded) button and the
simulation will be removed.

Using the Organizer for


Exporting and Importing
Variable Lists
Aspen Simulation Workbook can export an XML file containing a list of the
model variables. The variable export file is given the extension “ATMVO”
(AspenTech Model Variable Organizer) by default. The ATMVO file lists the
simulation file absolute path, variable name, variable path, and description for
each item in the variable grid. This list can be re-imported into the same
workbook later (as a data recovery mechanism) or imported into a new
workbook to rapidly build a new interface. Search and replace operations can
be performed during the variable import process. This feature allows you to
rapidly build model interfaces for process models containing repeating
sections (such as multiple hierarchy blocks or sub-flow sheets with similar
structures) or for new case files with structures similar to the original case file
used to build an existing ASW interface.

To export a variable list:


1 Open the Organizer.
2 Select the Model Variables view.
3 Select one or more variables from the list of variables.
4 Put the mouse over the variable grid (or click on the < Export Variables>
icon on the toolbar), and right-click to open the pop-up menu; select
Export Variables to File.
5 Specify the name and location of the text file to be exported.

To import a variable list:


1 Open the Organizer (active the simulation case containing the variables if
it is not already active).
2 Select the Model Variables view.
3 Put the mouse over the variable grid (or click on the < Import Variables>
icon on the toolbar), and right-click to open the pop-up menu; select
Import Variables from File.
4 Use the file browser to point to the text file which contains the exported
variable list, click the Open button to open this file into the ASW Data
Import wizard.
5 The Data Import wizard opens to the Select Data to Import form. Use
the fields in this form to select the variables and variable attributes to be
imported. By default, all attributes of all variables in the variable set file
will be imported. Use the General Preferences frame at the top of the
form to control the import behavior. Clear the Overwrite existing model

24 Section 1: Using Aspen Simulation Workbook


data checkbox if you want to retain variable values and units in the
existing simulation case. Clear the "Edit variable path/names upon import"
checkbox to directly import the variables unchanged (otherwise, you can
change the variable paths and names using the "Edit Variable
Paths/Names" dialogue box.)

6 If the Edit variable paths/names upon import box is checked, clicking


OK will open the Edit Variables Paths/Names form shown below. Enter
the text search and replace strings in the upper frame. Optionally specify
the search and replace options in the lower section of this frame.

Section 1: Using Aspen Simulation Workbook 25


7 Use the Replace and/or Replace All buttons in the Paths (Names)
frame to perform the text replacements. You can repeat this process
several times to perform multiple text replacement operations. The list of
variable paths in the Paths (Names) frame shows the current state of
the variables to be imported. The text boxes in the Current path/name
frame displays a preview of the results of the replace operation on the row
selected in the Paths (Names) frame. In the example below, you could
click the Replace All button to replace all instances of B1 with B2, or you
could click the Replace Current Path/Name button to replace text in
the selected row.
8 After completing this process, click OK at the bottom of the form to finish
the variable import process. Aspen Simulation Workbook will attempt to
add these variables to the organizer. If any of the modified variable paths
are invalid, ASW flags the error in a dialog box.

26 Section 1: Using Aspen Simulation Workbook


Using the Variable Browser and Query
Functions
Variable Browser
The ASW Variable Browser can be used to retrieve model variables from
attached simulation cases. This tool uses Aspen Simulation Interface to
display a hierarchical representation of the data contained within a model.
Model Authors can navigate through this browser to identify and select
variables to use in the interface.

Aspen Simulation Workbook also allows the Model Author to copy variables
directly from the native simulation forms and paste these variables into the
Organizer Model Variables grid.

Section 1: Using Aspen Simulation Workbook 27


Variable Query
The Query tab of the ASW Variable Browser can be used to define and launch
a query to identify groups of related variables. This provides another
mechanism to populate the organizer with model variables.

To perform a query:
1 Select an object in the tree to query. The query will be limited to this
object and its sub-objects.
2 Under Condition, specify one or more conditions for the variables
to match, and click Add. To specify multiple conditions, click the
Insert AND or Insert OR button to join conditions with an AND or
OR. You can nest ANDs and ORs to build up complex queries.
3 Click Run to run the query. The results appear in the bottom pane.
4 Select one or more variables from the results and click Add Selected to
add these variables to ASW.
The query shown above looks for all variables under Blocks with a status of
Specified.

Linking Excel to Model Variables


1 Enable Aspen Simulation Workbook

28 Section 1: Using Aspen Simulation Workbook


2 Attach the Excel sheet to one or more simulation cases
3 Activate the simulation and make it visible
4 Copy variables from the simulation case and paste them into the
Organizer

Setting Variable Properties


Model variables each have a number of properties as shown in the following
table. Most of the properties are set to default values when they are created.
Most variable properties are static (read-only), including the properties which
identify the address of the variable within the simulation model data
structure.
The Model Author or Model User can set several variable properties, including
the variable value and the upper and lower bounds of the variable, and others
(see table below).

Variable Property Read/Write Description

ACM_Inactive Read only True - Variable is


inactive; False - Variable
is active [e.g., Aspen
Custom Modeler
applications]
ACM Spec Read/Write Variable Specification
(Fixed, Free, Initial,
Estimated, etc.) [Aspen
Custom Modeler
applications]
Basis Read/Write Flow Basis (mass, mole,
volume) [Aspen Plus]
CondQuality Read only Conditioned quality (Not
Set, LL Exceeded, UL
Exceeded, LL Clamped,
UL Clamped, Good
CondValue Read only Conditioned Value - this
is the value sent back to
the simulation case after
applying upper and
lower clamping limits
and/;or verifying tag
quality
Container Read only Name of the container
(object) which contains
the variable. Examples
of containers: unit
operation models,
reaction models etc.)
Container Category Read only Category of the
container which owns
the variable, Examples:
Blocks, Streams, Unit
Ops, Reactions.
Container Type Read only Specific type of container

Section 1: Using Aspen Simulation Workbook 29


Variable Property Read/Write Description
within the container
category; for example:
Pump (Unit Operation),
Material (Stream), Free
Radical (Reactions)
Default Read only Default value (defined by
the simulation case)
Derivative Read only Variables time derivative
[Aspen Custom Modeler]
Description Read/Write User-defined descriptive
text
Display Name Read only Unique identifier for a
variable relative to its
parent (for example,
stage number in a
column profile)
Group Read/Write Optional user-defined
variable group ID. Use
this property as a aid to
group related variables
together for faster
navigation
History_Enabled Read/Write If True, variable history
is recorded. [Aspen
Custom Modeler] This
property is called
Record in the Aspen
Custom Modeler
applications.
ID Read only Unique number assigned
to each variable.
ID1 Read only Identifier 1 (See
Identifiers below.)
ID2 Read only Identifier 2 (See
Identifiers below.)
ID3 - ID9 Read only Additional Identifiers
Label Read only Default name given to
the object by the
simulator (usually the
same as DisplayName)
Lower Read/Write Variable lower bound
LowerClamp Read/Write Clamping on lower
bound (TRUE, FALSE)
Moniker Read/Write HYSYS moniker (variable
path) (HYSYS)
Name Read/Write Name assigned to a
variable. Aspen
Simulation Workbook
sets a name by default
when the variable is
pasted to the Organizer;
the user may override

30 Section 1: Using Aspen Simulation Workbook


Variable Property Read/Write Description
this name.
ObjectName Read/Write Name of the object
(container) containing
the variable
ObjectType Read/Write See Container Category
(above).
Path Read/Write ASI variable path (for
example, the path to the
variable in the ASW
variable browser).
Ranges Read/Write Excel ranges in ASW
tables containing this
variable
ReadOnly Read/Write Determines the
read/write status of the
value field. The default
state is determined by
the Status attribute, with
calculated variables set
to read only.
Simulation Read/Write Name of the simulation
file
Status Read/Write Variable status
{specified, calculated,
missing, defaulted etc.}
Type Read/Write Variable type {integer,
real, string}
Type_Display_Name Read/Write Variable of parameter
type in Aspen Custom
Modeler applications;
typically this is related to
the physical type of the
variable
Units Read/Write Units of measurement of
the variable
Uom_Options Read/Write A list of valid units of
measurement strings
Upper Read/Write Upper limit of the
variable
UpperClamp Read/Write Upper bound clamping
{TRUE / FALSE}
Value Read/Write Variable value
(read/write status is set
by the Read Only
attribute

ObjectType and ObjectName are retained for upward compatibility purposes;


the new “container” properties replace these within ASW.
Any number of model variables can be linked to an Excel sheet. Each model
variable is a complex named object consisting of several properties including:

Section 1: Using Aspen Simulation Workbook 31


type (integer, real, character, etc.), value, and units (where applicable). The
full set of variable properties is documented later in this guide.
Model variables can be input specifications, calculated results, or state
parameters (such as number of stages).
Any number of model variables can be linked to an Excel sheet. Each model
variable is a complex named object consisting of several properties including:
type (integer, real, character, etc.), value, and units (where applicable). The
full set of variable properties is documented later in this guide.
Model variables can be input specifications, calculated results, or state
parameters (such as number of stages).

Aspen Simulation Workbook and Aspen Remote


Simulation Service (ARSS)
To run files remotely, you must install Aspen Simulation Workbook on the
client (end user’s) computer; you must install the simulation applications and
the Aspen Remote Simulation Service on the server computer.
Aspen Simulation Workbook consumes a license while Excel is open and ASW
is enabled. Aspen Remote Simulation Service does not consume a license.
Aspen Simulation Workbook retains the state it was saved in. For example, if
the Excel workbook is saved with Aspen Simulation Workbook enabled, it will
open with the software enabled (provided a license key is found on startup).
An ASW Base license is checked out when an instance of Aspen Simulation
Workbook is opened.
For additional information on Aspen Remote Simulation Service, see Using
Remote Execution, and related information in the on-line help, as well as the
Aspen Engineering Suite Installation Guide.

Copying Variables from the Model to the


Organizer
Variables can be retrieved into the Organizer using two different mechanisms.
For most variables, using Copy/Paste is the best option for retrieving
variables since it allows the Model Author to navigate to the variable using the
native simulator user interface.
Some variables, however, may not be exposed through the interface in a
text-only format, making them inaccessible to the Copy/Paste mechanism.
The ASW Variable Browser can be used to retrieve all variables associated
with a simulation case. Users familiar with the variable explorer in Aspen Plus
may prefer navigating through this browser instead of using Copy/Paste.
Model variables can be entered directly into the values fields in ASW Tables
displayed in the open workbook. If the units field is displayed, alternate units
can be entered; Aspen Simulation Workbook will perform appropriate unit
conversions on the fly. If the specified variable value is outside of the bounds
and variable clamping is active, Aspen Simulation Workbook will reset the
variable value to the nearest bound. When variables are reset to their bounds
Excel will sound a warning beep and a message will be logged in the Aspen
Simulation Workbook log file.

32 Section 1: Using Aspen Simulation Workbook


Converting Units

Tips:
• Use the following procedure to change units or to view a list of valid unit
strings associated with a variable in an ASW Table:
• Select a row in an existing ASW Table in Excel and right-click to open a
pop-up menu
• Select Simulation Workbook Tables | Convert Units
• A list of valid unit strings will appear in the pop-up menu; select the
desired set of units from this list.

Warning: The units strings used in Aspen Simulation Workbook must be


consistent with the units used in the native simulation environment. If you
enter invalid units they will be ignored (the entered value will be replaced
with the original units string).

Note also that it is possible to make unit conversions only when the
simulation is active.

Section 1: Using Aspen Simulation Workbook 33


Navigating the Organizer Variable Grid
The Organizer Variable Grid displays variables as rows and variable attributes
as columns. By default, the Organizer displays a subset of the available
variable attributes. Use the Column Customization button to get a list of
available attributes.

Adding Columns
To add a new column to the variable grid, click and hold the column name
(variable attribute name) from the list of available attributes, drag the header
into the appropriate location of the variable grid and release.

Select colum
customization button
Select variable attribute, drag and
drop onto the variable organizer
grid in the appropriate location

Removing Columns
To remove a column from the grid, click and hold the column header and drag
it onto the column customization list.

Moving Columns
To move a column, select and drag the column header to a new location in
the grid.

Resizing Columns
Use the Best Fit button to automatically resize all columns in the variable
grid. The width of individual columns can be adjusted by dragging the edge of
the column left or right in the column header.

34 Section 1: Using Aspen Simulation Workbook


Sorting Variables
The Organizer can display the variables in a hierarchical form based on one or
more of the variable attributes. To sort by a particular attribute, drag the
column header up to the black space above the header row. Repeat this
action with additional attributes to sort by multiple categories.

Use the Collapse All Rows and Expand All Rows buttons to quickly
expand or collapse the variable grid view.
Variables can be quickly sorted by any category by clicking the appropriate
column header. Hold down the Shift key when clicking a category header to
perform a secondary sorting operation (for example, to sort by component ID
and stage number in a column profile).

Use the filtering control on the right side of each category header to
specify which variables are displayed in the variable grid. (This control pops
up a list of options to define the display filter).

Identifiers
Aspen Simulation Workbook supports several different simulation packages
through ASI (Aspen Simulation Interfaces) adapters. The ASI application
adapter assigns several identifiers to each variable to uniquely define the
source of the variable within the context of a simulation case:
The variable ID is a unique integer assigned to a variable by the Organizer.
By default, variables are sorted in ID order. Although the ID is stored mainly
for internal purposes, it can be convenient for sorting variable arrays into the
same order they are displayed in a form in the simulation package. For
example, when displaying composition or component flows the variables are
usually copied to ASW in the same order the components appear in the
simulator. This provides a way around alphabetical and numerical sorting
used by default in Aspen Simulation Workbook.

Section 1: Using Aspen Simulation Workbook 35


Each variable belongs to some type of container object; for example a
variable may belong to a specific instance of a unit operation model. Three
identifiers are required to fully characterize the container.
The Container Category identifies the class of objects that the container is a
member of. For example, in Aspen Plus the container types include Blocks,
Streams, Calculators, etc; in HYSYS the container types include UnitOps,
Streams, Workbooks, and so on. The obsolescent attribute ObjectType is
synonymous with Container Category.
The Container Type identifies the specific type of container within the given
container class. For example, “Pump” is a type of Unit Operation; “Material” is
a type of stream.
The Container attribute identifies which instance of an object owns the
variable. This attribute refers to the name of the stream, unit operation, etc.,
for example with unit operation PUMP P-101, the container is “P-101”.
Container is synonymous with the obsolete ObjectName attribute.
Many model variables are part of multi-dimensional arrays or collections. For
example, a variable may refer to the mole fraction of a particular component
in a specified phase in a given tray of a column. Each variable may have up to
nine Identifiers (ID1...ID9) to uniquely define its own location within these
arrays or collections. These identifiers are parsed from the variable path to
improve the usability of the path and to provide additional information which
you may wish to include in tables; they are not required to resolve the
variable (this is done uniquely by the path). When the variable structure is
too complicated to resolve within nine identifiers, the ninth identifier contains
the remainder of the variable path. This does not impact on the reliability of
the variable link – it is only cosmetic.
The specific use of these identifiers is context-sensitive, even within a
particular simulation application. Typically, these identifiers refer to elements
such as component identifiers, phase (or sub stream) identifiers, stage
numbers, points, or axial locations in profiles, or elements in distributions or
curves.
The variable label is a read-only attribute that identifies the unique identifier
of a variable within its context. For example, for a mole fraction variable, the
label is assigned to the component ID.

Model Variable Tables


Model variables can be grouped together in ASW Tables and inserted into the
Excel workbook. There are two mechanisms for generating tables. Select all
the variables to be included in the table:
1 Right-click any field in a variable row in the Organizer Variable Grid to
select the variable.
2 Press the Shift key to select a range of variables
3 Use the CTRL key to make multiple selections.
4 Use the Quick Tables button to use a table template or make new table
templates.
5 Click the ASW Table Wizard button to create your table

36 Section 1: Using Aspen Simulation Workbook


The orientation of variable tables can be changed, so variables appear as
columns and attributes as rows.

1 Click the button to create a variable table and the Create a Table
Wizard screen will appear
2 The first tab of the wizard has an additional check box (insert image here)
for changing the table's orientation
3 Select the desired options. The system updates the cell range and reflects
the change in table orientation
4 Click Finish. The table appears with the variables displayed as columns
and the attributes displayed as rows
For Changing an Existing Table's Orientation:
1 Select an existing variable table and select Simulation Workbook
Tables|Modify Table from the Context menu to modify a table. The
Modify a Table Wizard screen will appear
2 Again, the first tab of the wizard has an additional check box (insert image
here) for changing the table's orientation. (Note that if the table's
orientation has already been changed, the checkbox will be checked)
3 Set the orientation of the table via the Put data into columns instead
of rows checkbox. (The system updates the range preview to indicate the
orientation change
4 Click Finish. The table's orientation is changed and any formulas or
formatting applied to a cell will be preserved and transposed to the
desired location of the variable attribute.

Placing the Table into Excel


Use the Table Wizard button to follow a step-by-step process to format
and place the table into the Excel workbook. The Table Wizard brings up the
Table Location dialog box to set the table range. Point to a cell in the Excel
sheet to change the address. This address corresponds to the upper left
corner of the table. Click the OK button to continue.

Pulling Tags into the Organizer


Tags allow you to access information from other applications and link that
information directly into your ASW Model.

Linking Excel to Plant Data Tags


Plant Data Tags are named objects that define all aspects of a plant datum.
Typically plant tags are composed of several properties (such as value, units,
quality, and timestamp).
Plant tags must be retrieved from plant data servers (such as IP21, PhD, or
PI) using the plant data server’s native Excel Add-ins or OLE automation
features. Aspen Simulation Workbook includes a Map Tag Variables wizard
that can be used to associate an existing Excel table with tags. Each row in

Section 1: Using Aspen Simulation Workbook 37


the selected range is associated with a single tag; the columns in the selected
range are each mapped to tag attributes (such as value and units).
Aspen Simulation Workbook includes tools to link model variables and to map
tag quality states defined by the plant data server to states defined within
Aspen Simulation Workbook.

Mapping Tags to Model Variables


Any number of model variables can be linked to an Excel sheet. Each model
variable is a complex named object consisting of several properties including:
type (integer, real, character, etc.), value, and units (where applicable). The
full set of variable properties is documented later in this guide.
Model variables can be input specifications, calculated results, or state
parameters (such as number of stages).

Setting Tag Updates and Adding Tag Tables


Setting Tag Updates
Usually, plant data tags can be automatically updated at specified time
intervals using the Excel Add-In tools or OLE Automation tools delivered with
your plant information system software. Although this feature is not
incorporated into the Aspen Simulation Workbook as a standard tool, you can
use Visual Basic automation to link the appropriate macros to a timer as
described later in this chapter.
• Tags can be manually updated at any time using the Update Tags button
on the Aspen Simulation Workbook Run toolbar.
• Missing (null) tag values are never copied back to model variables. A
warning icon will appear next to each missing tag in the Organizer
Variable Mapping view.
• Tag updates behave slightly differently depending on which type of
simulation model is linked to the Aspen Simulation Workbook, as
described below.

Aspen Plus
When the user runs an Aspen Plus case through Aspen Simulation Workbook
three actions take place:
1 Model variables linked to plant tags (Tag to Model or Bidirectional) are
updated with the current conditioned value (CondValue) of the model
variable.
2 The model is run and the simulation results are retrieved.
3 Tags linked to model variables (Model to Tag or Bidirectional) are updated
with the conditioned value of the model variable.

Aspen HYSYS
When the user triggers a tag update using the Update Tags button, the
following actions occur:

38 Section 1: Using Aspen Simulation Workbook


1 Model variables linked to plant tags (Tag to Model or Bidirectional) are
updated with the current values stored in the Tags provided the tag
quality is “Good”.
2 The HYSYS model executes (provided the solver is active) and the model
variables are updated.
3 Tags linked to model variables (Model to Tag or Bidirectional) are updated
with the conditioned value of the simulation variables.

Aspen Custom Modeler or Aspen Plus Dynamics


When the user runs an Aspen Modeler case (for example, Aspen Custom
Modeler or Aspen Plus Dynamics etc) through Aspen Simulation Workbook
three actions take place:
1 Model variables linked to plant tags (Tag to Model or Bidirectional) are
updated with the current conditioned value (CondValue) of the model
variable.
2 The model is run and the simulation results are retrieved.
3 Tags linked to model variables (Model to Tag or Bidirectional) are updated
with the conditioned value of the model variable.

Adding Tag Tables


In ASW there are two ways to add tag tables: import tags directly from Excel
cells or by selecting tags in the Variable Organizer and using the Create Tag
Table command.

Adding Controls
Aspen Simulation Workbook includes a library of process equipment symbols
which can be inserted onto the worksheet to make the workbook interface
easier to use and more visually appealing. See Adding Graphics and Controls.
Automating models is accomplished through the use of Dynamic Profiles. See
Working with Dynamic Profiles.

Using the Standard Table


Wizards
Creating Tables
Each of the forms within the ASW Organizer allows the Model Author to create
ASW Tables from selected tags or variables. The ASW Table Wizard guides the
Model Author through the steps required to populate, format, and insert an
ASW Table inside an Excel worksheet.

Section 1: Using Aspen Simulation Workbook 39


Each ASW Table can contain one or more rows of data, with each row
corresponding to a particular variable or tag (or a mapping relationship
between tags and variables).
Each column in an ASW table corresponds to a property of the variable or tag
(for example, value, or units). ASW tables may optionally include titles,
column headers, empty rows, and empty columns. Once tables are placed
within an excel sheet, they can be reformatted using the standard formatting
functions within Excel.

Warning: Once tables are placed in an Excel sheet, do not insert or delete
columns or rows in them using Excel. You can move whole tables safely in
Excel. The ASW Table Wizard and the Table Manager both allow you to
otherwise rewrite tables without breaking the data links.

Creating Table Templates


While in Excel, click the “Apply Instant Table” toolbar button on the ASW
Design toolbar. (This button will be enabled only if there are quick table
templates available.) This will display the “Table Location” dialog box and you
may select the excel range to place the table.
After selecting the range, click “OK” to bring up the “Simulation Workbook
Table Wizard.”

40 Section 1: Using Aspen Simulation Workbook


Table Wizard Combo Boxes
Template Name The “Template Name” combo box will
display all available Quick table
templates. Combo box item names should
contain both the table icon along with the
template name. (The table icon is useful
for identifying standard table templates,
profile table templates and scenario table
templates.)
Table Range Settings The "Table Range Settings" combo box
lets you change the range/address of the
table.
Table Settings The "Table Settings" combo box lets you
define the title, look and style of the table
as well as showing or hiding column
headings and placing data into columns
instead of rows.

Note: Should you create a table with no title (i.e., the show title block is
unchecked) or no header information (i.e., the show column headings check
box is unchecked), then select and edit a table and apply "Autoformat," the
heading format may be applied to the first data row. (This would occur
because Excel's "autoformat" always assumes a header row.)
Click the “Apply” button and the system adds the clipboard variables to the
organizer and creates a table using the selected format. If you select an

Section 1: Using Aspen Simulation Workbook 41


enhanced table template, it will bring up the following “Variable Substitutions”
form.
The Variable Substitutions form contains "Make" and "Preview tabs."
• The "Make" tab displays substitution variables in the grid, with the
browser button attached to it. This will then bring up the "Variable
Substitution browser to allow you to select the variables.
• The "Preview" tab will then display all selected variables.
Click the “Finish” button to create a table with the selected variables. (If the
variables are not in the organizer, they need to be added.)

Creating Model Variable Tables


Model variables can be grouped together in Tables and inserted into the Excel
workbook. There are two mechanisms for generating tables. In both cases the
first step is to select all the variables to be included in the table. Right-click
any field in a variable row in the Organizer Variable Grid to select the
variable. Hold down the Shift key to select a range of variables. Use the CTRL
key to make multiple selections.

Table Wizard
Use the Table Wizard button to follow a step-by-step process to format
and place the table into the Excel workbook. The Table Wizard brings up the
Table Location dialog box to set the table range. Point to a cell in the Excel
sheet to change the address. This address corresponds to the upper left
corner of the table. Click the OK button to continue.

42 Section 1: Using Aspen Simulation Workbook


Click the Table tab to specify the table heading (title), to select borders
and/or use built-in Excel table formats, and to set other table options. This
sheet also allows you to recall or save a Table Template.

If the selected table range overlaps any other existing table a warning symbol
appears on the form. The user may resolve the overlap by changing the
location of the table or by changing the number of rows and columns in the
table. As a last resort, the user can select options to override the overlap
(ignore, shift rows, shift columns).
Several formatting options are available in the Table Settings frame. The
AutoFormat option can be used to apply a pre-defined table format included
in Excel. Use the Borders option to automatically draw a border around the
boundary of the table. Use the Inside Borders option to draw borders inside
the outer boundary of the Aspen Simulation Workbook table. You can also
select pre-defined cell styles for the table, title section, or headings. Use the
styles button to launch the Excel Styles wizard to define new cell styles
(see Creating Cell Styles, below).
By default, the table title will automatically merge across all columns in the
table title row. Uncheck the Merge and Center Title option to turn off this
feature.

Section 1: Using Aspen Simulation Workbook 43


Use the Columns tab sheet to select which variable properties to display in
the ASW Table. Each variable property corresponds to a column in the table.
Use the Properties pane to change the default column header or to apply a
cell style to the data cells for the selected column(s).

Use the Rows tab-sheet to specify the variable (row) order in the ASW Table.
This form also contains controls to add or remove variables. Each variable
corresponds to a horizontal row in the table.
The variables can be sorted in order by clicking the column headers. For
example, when the “Label” header is clicked the variables are sorted into
alphabetical order based on the label property.
The Sort By button can be used to automatically re-order the variable list
based on a variable property that is not displayed in the table.

Change
order of
selected
row(s)

Add: opens variable


Remove
selector, which lists
selected
all the variables in the
rows
Organizer

Insert
Opens a list of
empty
properties for sorting
row
the list of variables

Click the Finish button to exit the Table Wizard and insert the table into Excel.

44 Section 1: Using Aspen Simulation Workbook


Tips:
• Always use the Table Manager or Table Wizard to move or delete tables.
The Table Wizard can also be used to add/remove rows and/or columns
(including empty rows and columns) to tables and to auto-format the
tables.
• To edit an existing table, place the cursor over one of the cells in the
table, right-click, and select “Simulation Workbook Tables” from the pull-
down menu.
• To add variables to an existing table, open the Organizer to the Model
Variables view, select the variables of interest, right-click the mouse, and
select Add Selected Variables to Table. A form opens and displays a list of
existing tables; select the table to be modified; this adds the variable to
the last row of the selected table and then opens the Table Wizard form.
Use the Rows view of the Table Wizard form to change the row location.

Warning: Once tables are placed in an Excel sheet you cannot add or delete
rows or columns inside the table using standard Excel functions; otherwise
the table will get disconnected from its data source and will need to be
rebuilt. Use the Table Wizard to add rows or columns to existing tables or
move the table out of the way before adding rows or columns to a worksheet
that contains tables.

Quick Tables
Use the Quick Tables button to create or apply a Table Template. If pre-
defined templates are available, a list of available templates will appear. Click
the template name to generate a table containing the selected variables. If no
templates exist, the “<Manage Table Templates...>” box will appear. Click
this box to open the Manage Table Templates Dialog window.

Section 1: Using Aspen Simulation Workbook 45


To create a new template, click the <New> button and this will open the
Simulation Workbook Table Template Wizard.
The Table Template wizard allows you to pre-define all of the properties of a
table including which columns (variable properties) are included, and the
formats used in the table. You can select from pre-existing global table
formats or apply styles to cell columns, headers, or title (see Creating Styles
in Excel, below).
The table templates are saved by name and can be recalled later when
making new tables. Table templates can help make it easier to establish a
common look and feel to your model interface. Table templates can be
exported (as files) and re-used (imported) in other Aspen Simulation
Workbook cases.

46 Section 1: Using Aspen Simulation Workbook


Instant Table Template
The instant table feature allows you to create a table using variables already
selected in the simulation without having to first paste them into the Variable
Organizer. Simply:
1 Select and copy one or more variables from the simulator
2 Return to Excel and click the "Apply Instant Table" button on the ASW
Design bar,

This will display the Apply Instant Table Wizard

3 Select the template to use for the new table.


4 Select the location for the new table
5 Click the "Apply" button and a new table will be created using the
variables that you selected in the simulator.

Enhanced Table Template


An enhanced table template differs from a standard table template in that it
contains information about which variable data will be included within the
table.

Creating an Enhanced Table Template


To create an enhanced table template select a table in Excel, right click on it
and select Create Table Template from the context menu.

Note: You may also select a table in the organizer table list then select
Create Table Template from the context menu. Or you can click the New
button on the Manage Templates dialogue box which is accessed from the
Quick Table toolbar drop-down menu in the Model Variable Organizer.

Section 1: Using Aspen Simulation Workbook 47


This opens the Table Template Wizard. Table formatting and column
information are automatically filled-in from the source table.
By using the Variables Tab you define the variable data which will be in your
table. This variable data is defined by creating one or more variable patterns.
A variable pattern is a variable path that can include a Substitution
Variable and Wildcards.

Substitution Variables
A Substitution Variable is a placeholder for part of the variable path that will
be filled-in when the template is used. For example, a variable pattern may
include a substitution variable ("Block") which could be set to a particular
block name ("B1") when the template is used.

48 Section 1: Using Aspen Simulation Workbook


Use the variable tree to select a variable pattern. To create a substitution
variable, select the node in the variable tree and then click the Define
Substitution button. You will be prompted to enter a name for the
substitution variable. Enter a name and then click "ok." This will add the
substitution variable to the substitution variable pattern.

Wildcards
A variable pattern may also contain wildcards. Wildcards indicate that you
wish all "child nodes" on a particular level included in your data. For example,
"B1.Input.*" could include all child nodes below B1.Input, for example
B1.Input.TEMP or B1.Input.PRESS (as shown below).
To add a wildcard to your variable pattern, select the node in the variable tree
where you want the wildcard and then click the Define Wildcard button.
(See the following image.)

Section 1: Using Aspen Simulation Workbook 49


Patterns
All patterns that are included in the template are listed within the patterns list
box. The patterns will reflect any substitution variable and wildcards that you
have defined.
To remove any variable patterns from your template, select the pattern from
the pattern list box and click the Remove button.
To save the table template, click the OK button at the bottom of the dialogue
box.

50 Section 1: Using Aspen Simulation Workbook


Applying an Enhanced Table Template
To apply the Enhanced Table Template, return to the Organizer toolbar and click the
Apply Instant Table button.

Select the desired template (in this case Template1), and then click the Apply button.
This will open the Variable Substitution Window (as shown below). You will use the
Variable Substitution Window to choose a set of variables to include in your instant table.
The variables will be added to the Model Variable Organizer automatically.

Variable Substitution Window


The Variable Substitution Window displays the variable patterns included
in the Table Template. It allows you to set the substitution variable values
and displays all resulting model variables. It then lets you choose which of the
resulting model variables you want to include in your table.

Section 1: Using Aspen Simulation Workbook 51


The Variable Substitution Window contains three panes: The Substitution Variables
pane, the Pattern Expansions pane, and the Properties pane:

Substitutions Variables Pane


This pane lets you set substitution values. As shown in the image above, four columns of
data are displayed:

Displays the name of the substitution


Name variable you are defining.
Expansions Full expansions of variable paths
Status Describes whether the given variable path
is valid for the current simulation
Checkbox Lets you select whether you want the
variables associated with the given
expansion to be included in your table.

Patterns Expansion Pane


This pane lists all actual variables referenced in the Variables Substitution pane and
lets you individually select which ones you want to include in your table.

Full Path This is the full path of the model variable.

Checkbox This permits you to define a particular


variable in your table.

52 Section 1: Using Aspen Simulation Workbook


Properties Pane
This pane lists the variable properties for the variable selected in the Expansion pane.
These properties cannot be changed (read-only).

Using the Variable Substitution Window


There are two steps to choosing variables from the Variable Substitution
Window: First you must define all substitution variables and then you must
decide which of the resulting variables you want to include in your table.
To define a substitution variable, double click in the expansion column (as
shown below)

This will open the Substitution Variable Value Selection window. Select the node for
the variable you would like to select for your substitution variable. (See the following
image.)

Section 1: Using Aspen Simulation Workbook 53


In this case, click on B2 and then click the OK button. The value for the substitution
variable will then be set to B2.

The Patterns Expansion pane shows a list of all simulation variables that match the
patens listed in the Variable Substitution pane. The checkbox next to each variable
defines whether or not to include the variable in your table.

Note: Checking or un-checking an expansion in the Variable Substitution


pane will automatically check or uncheck all model variables in the Pattern
Expansion pane that match the given pattern.

Creating Styles in Excel


The Table Wizard uses the Styles feature in Excel to make it easier to develop
predefined table templates. The Styles wizard can be launched directly from
the ASW Table wizard or by selecting Format, Styles from the Excel pull-down
menus. The Styles wizard allows you to set the numerical format, font,
background color, cell protection, and other properties associated with a cell
or range of cells. Styles are saved by name and can be recalled in the Table
Wizard or Table Template wizard.

54 Section 1: Using Aspen Simulation Workbook


Warning: Excel Styles do not fully support borders because interior and
exterior border properties can only apply to a range containing more than one
cell. Use the Borders and Interior Borders options in the Aspen Simulation
Workbook template wizard to control border formatting for Aspen Simulation
Workbook tables.
Tip: For best results, uncheck the Border option in the Excel Style dialogue
when creating or changing a named cell style for Aspen Simulation Workbook.
This prevents the style’s border settings from interfering with the border
settings in Aspen Simulation Workbook table templates.

Modifying Tables
To make any modification to a table, right-click on the table and choose
Simulation Workbook Table|Modify Table.

Running Scenarios (using the


Scenario Wizard)
Scenarios can be defined in ASW using Scenario Tables. A scenario table
defines a set of input variables and a set of output variables for a set of
scenarios. Each row represents a scenario defined by the values of the input
variables.
To create a scenario table:
1 Open the ASW Organizer, and click the Model Variables view in the left
pane. Select at least one specified variable and at least one calculated
variable. Tip: hold down the shift key to select a range of variables or the
control (CTRL) key to select multiple variables.

2 Click the Create Scenario Table button or right-click in the right pane
and select Create Scenario Table.

Section 1: Using Aspen Simulation Workbook 55


3 When prompted, select the region for the table (which may expand below
and to the right of this region as needed) and click OK.
The Scenario Study Wizard window appears.
4 Use the Table tab to specify the format for the table, and whether to
include the title, column headings, and units. By default, the first row of
the table will include the current values of specified and calculated
variables. You can uncheck this option if desired. Specify the number of
cases (scenarios) to be included in the table. Click Next.
5 Use the Input Vars tab to specify the input variables. Click Add to add
previously defined model variables by highlighting them and then clicking
Select. Use the arrow buttons to order the variables. Click Next. Use
"Insert Blank" to include a blank column in the inputs.
6 Use the Output Vars tab to specify output variables in the same manner.
Use "Insert Blank" to include a blank column in the outputs. Click Finish.
The scenario table will be created in Excel. The first row will be populated with
the current values for the selected input and output variables to provide a
reference point when filling out data.
To run the scenarios:
1 In the Active column, enter * for each scenario (row) you want to run
and clear the cell for each scenario you do not want to run. In the columns
for the input variables, enter the values for each scenario. An empty input
cell means "use the same value as the previous case".
2 Right-click in the table and select Simulation Workbook Tables | Run
Scenario. In the RunScenarioDialog window, click Start Scenario
Run. This window displays the progress of the scenario run. Click OK
when finished. The scenario table in Excel will be updated with the results
from the scenarios that have been run.

Working with Dynamic Profiles


Dynamic models involve much higher levels of interactivity and information
flow compared to steady-state models. Model developers must take steps to
ensure good run-time performance under the ASW environment.
Use the following guidelines to maximize the performance of your models:
• Reduce simulation diagnostic levels before deploying Aspen Modeler
models to the end users. Diagnostic message traffic is a key source of
slow performance and high message levels lead to large file sizes in Excel
since ASW stores the simulation message history in hidden worksheets.
• Increase the simulation communication interval from the default value
(usually 0.01 hours) to a higher value. The ideal communication interval
depends on the characteristic times of the processes being simulated. The
interval needs to be low enough to capture important trends and events,
but it should not be set excessively low.
• Increase the ASW DynamicUpdateFrequency attribute (Simulation
References form). This parameter controls the frequency at which ASW
updates standard Model Variable tables and Dynamic Profiles tables. This
parameter is a multiple of the simulator communication interval. For

56 Section 1: Using Aspen Simulation Workbook


example, if DynamicUpdateFrequency is set to 10, then the ASW tables
will be updated only after ten simulation communication intervals.
Note: The simulation communication interval has a much bigger impact
on overall performance.
• Verify that the simulation model itself is well behaved. Run the model in
isolation to ensure it performs well under a wide range of input conditions.
Check the variable scaling and the form of the equations if you identify
problems. You can also adjust the model convergence parameters to
optimize performance. It is worth a bit of extra work up front to ensure
good performance.

Using the Profile Wizard


The Profile Wizard lets you create tables and strip charts of time-varying data
from dynamic simulations.

Note: Before you start, link Excel to all the relevant model variables in the
Dynamic variables you plan to use.

To create a profile table:


1 Open the ASW Organizer to the Model Variables view
2 Select some variables to put into the table
3 Right-click these variables and select Create Profile Table, or click the
button. The Profile Table Wizard appears.
4 Specify the number of rows for the table, and specify the time interval for
the table as a number and units.
5 Optionally set the table format and specify to include the headings, units
for headings, and/or relative time column. Click Next.
6 On the Profiles tab you can click Add to add additional model variables to
the table, and use the arrow buttons to order the variables. Click Finish.
When you run the dynamic model, the profiles will be filled. When the entire
table is filled, the data will scroll upwards (older data are removed from the
top row as new data are added to the bottom row of the table).

Making Strip Charts


To create strip charts of profile data:
1 Select the profiles to be plotted. (Do not select the time values.)

2 Click the Chart Wizard button in Excel. The Chart Wizard appears.
3 Select the Line chart type and any sub-type. Click Next.
4 In step 2 of the wizard, click the Series tab. Enter a name for the chart,
and in Category (X) axis labels, click and select the region
containing the time values. Click Next.
5 Specify titles and other formatting options. Click Next.
6 Specify where to place the chart. Click Finish.
The strip chart will scroll forward with time as the dynamic simulation
progresses.

Section 1: Using Aspen Simulation Workbook 57


Adding Graphics and Controls
Aspen Simulation Workbook Process
Graphics
Aspen Simulation Workbook Process Equipment Icon
Library
Aspen Simulation Workbook includes a library of process equipment symbols.
The process symbols are grouped into several categories based on the
equipment function. Use the Insert Process Icon button to retrieve a
process icon from the library. This tool opens the Insert Picture form. Select
one of the folders to preview the icons inside the folder. Browse to the desired
icon and click the insert button to drop the icon onto the active Excel
worksheet.
Once the process icon is inserted onto the Excel worksheet, it can be moved,
rotated, or resized using standard Excel drawing commands.
The Aspen Simulation Workbook process icons are saved as GIF (graphics
interchange format) files with transparent backgrounds. If desired, use the
Excel Fill Color button to put a solid color background behind the image
(this button is located on Excel’s Drawing toolbar). Use the Excel arrow
function to draw process streams between equipment icons.

Adding Process Icons to the Library


Users with administrative privileges can extend the Aspen Simulation
Workbook process equipment library with their own symbols. Simply add the
graphics files in any appropriate format (JPEG, GIF, WMF, EMF, etc.) into the
folder structure located under Program Files\AspenTech\Aspen Simulation
Workbook 2006\Process Icons. Users without administrative privileges can
add new icons into their own folder structures and browse to these files using
the standard Insert Picture function in Excel.

58 Section 1: Using Aspen Simulation Workbook


Inserting Complete Process Flow Diagrams
Aspen Plus, Aspen Custom Modeler, and Aspen Plus Dynamics all allow the
user to copy an image of the process flow diagram (process flow sheet) to the
paste buffer. Use the native user interface of the simulation tool to open the
Flow sheet view, use Edit/Select All (or CTRL+A) to select all items in the
process graphics, then use Edit/Copy (or CTRL+C) to copy the selected items
to the paste buffer. Return to Excel and select Edit/Paste (or CTRL+V) to
paste the selected image to Excel.
The current version of Aspen HYSYS does not support this feature. However,
third-party screen capture software, such as SnagIt©, can be used to copy an
image of the process flow diagram from HYSYS into Excel.

Adding equipment icons


1 Click the Insert Process Icon button located on the Designer Toolbar

2 Select a folder with the desired icon and open the folder (i.e., double click
the folder icon)

Section 1: Using Aspen Simulation Workbook 59


3 Select the desired icon (double-click)
4 The icon will drop onto the worksheet

Adding buttons and other types of controls


Aspen Simulation Workbook has built-in VBA macros; this feature makes your
model interfaces easier to use with buttons, combo boxes, and other standard
MS Excel Controls.

60 Section 1: Using Aspen Simulation Workbook


1 Select a button or control (in this case a button has been chosen).

2 Drop in a form control; cancel out of the Excel dialog

Section 1: Using Aspen Simulation Workbook 61


3 Select a macro from the list and click “OK”

Building a Model Interface


Developing a Model
It is important to invest some time and effort into the development of the
underlying simulation cases to ensure they are robust over a reasonably wide
range of conditions. The simulation case needs to be designed to use
appropriate specifications. This is especially important for Aspen HYSYS cases
and equation-oriented Aspen Plus or ACM cases which allow the user to
control fixed (specified) and free (calculated) variables.

Model Development Tips


The following steps are recommended:
1 Determine how the model should be specified; identify a list of
manipulated input variables (specifications) and results variables
(calculations); establish upper and lower bounds for each manipulated
variable.
2 Test the simulation case for robustness by running cases at the limits of
the manipulated variables. Verify the simulation converges without errors.
3 Leverage calculations in Excel; it may be possible to simplify your
simulation cases by moving calculations from the simulation case (e.g.,
calculator blocks in Aspen Plus) to the Excel sheet.

62 Section 1: Using Aspen Simulation Workbook


4 Strip unused hidden objects from the simulation; this can reduce the size
of the file and enhance performance.
In general, apply appropriate engineering judgment when setting up your
simulation cases. Avoid unnecessary details (such as trace components);
keep the model as simple as possible. The resulting models will run faster and
be more robust when deployed to casual users in the field.

Deploying Models
Within this guide we use the terms simulation case and model
interchangeably to refer to a single set of simulation files (for example a
single HYSYS case file or Aspen Plus backup file).

Using Multiple Cases


Aspen Simulation Workbook can link to one or more simulation cases,
however only one simulation case can be active at a given time. The model
user can activate and deactivate simulation cases at will.

Supported Case Types


Aspen Simulation Workbook supports Aspen Plus and Aspen HYSYS cases, as
well as the layered products based on these platforms (for example, Aspen
Polymers Plus and Aspen HYSYS Refining).
Aspen Simulation Workbook is also compatible with the Aspen HTFS Research
Network family of products, including Aspen Shell and Tube Exchanger, Aspen
Air Cooled Exchanger, Aspen Shell and Tube Mechanical, and Aspen Fired
Heater, etc.
Aspen Simulation Workbook is also compatible with the Aspen Modeler family
of products, including Aspen Custom Modeler (ACM), Aspen Plus Dynamics
(AD), Aspen Chromatography, Aspen Adsorption, and Aspen Model Runner
(AMR). The current version of Aspen Simulation Workbook supports all run
modes for these products. Initialization, steady-state, and dynamic runs are
fully supported. Although estimation and optimization run modes are
supported, the estimation data and results and optimization results variables
are not exposed in the current ACM adapter. We plan to extend the adapter in
the future to allow full access to all types of data within the ACM family of
products.
Aspen Simulation Workbook supports HYSYS models, including models based
on HYSYS Upstream and Aspen HYSYS Refining.

Caution: Aspen Simulation Workbook fully supports sequential-modular (SM)


variables in Aspen Plus. Equation-oriented (EO) models are supported
indirectly through the SM variables, which are synchronized with the EO
variables during simulation runs.

Section 1: Using Aspen Simulation Workbook 63


Connecting Models to Plant Data Tags
Plant DataTags
Plant Data Tags are named objects that define all aspects of a plant datum.
Typically plant tags are composed of several properties (such as value, units,
quality, and timestamp).
Plant tags must be retrieved from plant data servers (such as IP21, PhD, or
PI) using the plant data server’s native Excel Add-ins or OLE automation
features. Aspen Simulation Workbook includes a Map Tag Variables wizard
that can be used to associate an existing Excel table with tags. Each row in
the selected range is associated with a single tag; the columns in the selected
range are each mapped to tag attributes (such as value and units).
Aspen Simulation Workbook includes tools to link model variables and to map
tag quality states defined by the plant data server to states defined within
Aspen Simulation Workbook.

Retrieving Plant Tags into Organizer


Before tags can be associated with model variables, they must be part of the
Organizer data store.
Use the Excel add-in tools provided with your plant data server software
(such as Aspen IP.21) to create links between the Excel workbook and the
plant data tags. Ideally, the tags should be laid out in a table, with the
various tag attributes in the table columns and the rows of the table each
corresponding to a single tag (see the example below).
The tag table should include (as a minimum) the tag name, value, and units.
A tag description and tag quality (status) parameters may also be included.

Retrieving Tags into the Organizer


In Excel, highlight the range of cells containing the tag information. You may
include the table header and column headers in the selection range. Right-
click and select Simulation Workbook Tables, Map Tag Variables from the list
of options.

64 Section 1: Using Aspen Simulation Workbook


Alternately, you can click the Import Tags button on the Aspen Simulation
Workbook Design toolbar. This opens the Map Tag Attributes pop-up form.
Click the browse button on this form and then select the range of cells
containing the tag information in your Excel workbook.

The Map Tag Attributes pop-up form guides you through the steps to map the
tag data in your Excel sheet into the Organizer. The Map Tag Attributes form
will attempt to automatically map the attributes (columns) of the table to the
ASW plant data tag attributes based on the column headers (see list of tag
attributes in the next section).
The mapping between columns (Heading) and tag attributes (Attribute) is
displayed on the left-hand side of the Map Tag Attributes form. Use the
controls in the Attribute Mapping frame to change the mapping between the
selected column and the tag attributes. To skip a column in the table, select
the column header name from the list on the left and select the Do not import
(ignore) option in the Attribute Mapping frame on the lower right-hand side of
the form. Tag names and values must be included in the tag source table. A
warning indicator is displayed on the Map Tag Attributes if any of the
columns in the imported table are unmapped or if the tag values or names
are missing from the table.

Section 1: Using Aspen Simulation Workbook 65


Mapping Tags to Model Variables
Plant data tags can be mapped to model variables. This allows you to
automate workflows and leverage the power of process simulation in the plant
operations environment. You can:
• Map tags to model variables (e.g., populate model inputs with measured
data from the plant).
• Map model variables to tags (e.g., send model predictions back to the
plant data server through tags, which allows the model to act as a virtual
analyzer and/or provide predictions of unmeasured variables for operator
decision support applications).
• Create two-way flow of information between the model and plant data.
To map variables to tags:
1 Open the ASW Organizer and switch to the Variable Mapping view in the
left pane. This opens a grid in which each row displays a link between a
model variable and a plant tag. The first time the grid is opened, it will be
empty.
2 Right-click the variable grid pane to open the pop-up menu.
3 Select Add Unreferenced Tags to pull a list of tags into the variable
grid, or to update the list with recently added tags.
4 Aspen Simulation Workbook will automatically map tags and variables to
each other if the tag name and variable name are identical. If a matching
variable is not found for a tag, the 'null' symbol will show up in the Model
Variable column.
o To map a variable to an unreferenced tag, click the 'null'
symbol next to the tag name. This brings up a list of the
unmapped model variables.
o Scroll through the list to locate the desired model variable.
o Click on the variable name to map it to the tag.

Note: It is not necessary to map every plant tag to a model variable. Use the
Delete button to remove any tags that you do not want to map. Alternately,
you can remove all the unreferenced tags together by right-clicking in the
variable grid and selecting Remove Incomplete Tags from the pop-up
menu.

66 Section 1: Using Aspen Simulation Workbook


Mapping Tag Attributes

Uncheck these Browser allows


boxes if needed you to change the
selection range

Use these
controls to
change the
mapping or to
ignore the
column selected
on the left-hand
side of this form
This pane shows how
each column (Heading)
Warning symbol
is mapped to tag
indicates required
attributes
attribute (name or
value) is missing

After all of the columns are mapped to tag attributes click the OK button to
close the form and import the tags into the Organizer. This will also
automatically open the Organizer into the Variable Access / Tag Variables
view. This view shows the list of plant data tags in the Organizer variable
grid. You can modify and navigate through the tag list using the same
techniques described in Chapter 2 “Navigating the Organizer Variable Grid”.

Tip: Use the standard tag attribute names (see below) when making a table
of plant tags; for example use “Name” instead of “Tag” or “Tag ID” to identify
the tags. This saves time when you use the Map Tag Attributes form to import
the tags into the Organizer.

Section 1: Using Aspen Simulation Workbook 67


Tag Properties
Each plant data tag object consists of several properties including the tag
value, units of measurement, and other attributes. A full list of tag properties
is shown in the table below. The items in bold font can be specified or
changed by the user.

Property Read/Write Description


Description R/W User defined descriptive text.
Group R/W Optional user-defined variable group ID. Use
this property as an aid to group related tags
together for faster navigation.
ID Read only Unique identifier (integer).
Name R/W Name assigned to a tag.
Ranges Read only Excel ranges in ASW Tables containing this
tag, including the source location where the
tag was imported.
Quality R/W Tag quality [Good, Bad, etc.].
Units R/W Units of measurement of the variable.
Value R/W Value of the tag.

Grouping Tags
Each plant data tag can be assigned to a user-defined group. The group
attribute can be used as a tool for identifying relationships between tags in
the context of the model or plant. For example, the group identifier can be
used to identify a plant section (for example, “Reactor Train”), a data source
(for example, “DCS”) or as an additional field to help describe or sort the
tags.

Tip: Use the group property to group tags into sets for easier searching and
navigation. This is especially important when developing interfaces to large-
scale models.

Naming and Describing Tags


Each plant data tag can be assigned a name and a description. The tag name
is typically assigned to the name of the instrument that provides the data, for
example TI100 (temperature indicator 100).
Tag names and descriptions can be included in the tag tables generated by
Aspen Simulation Workbook.

Tip: If you plan to map plant data tags to model variables it is a good idea to
give the model variables and tags the same name. This saves time later when
mapping the plant tags to variables as described later in this section.

68 Section 1: Using Aspen Simulation Workbook


Preparing Models for Distribution
After preparing the simulation, you can optionally embed it in the ASW
workbook by setting the Embed Case property of the simulation to True.

Showing Simulation Status


Use the ASWGetSimulationAttribute workbook function with the argument
"status," to retrieve the current status of a simulation in Excel.

Changing the Path or Filename of a Linked


Model
Never change the path of a model while it is linked in Excel and ASW and
Excel are open.
When you open an ASW workbook after changing a simulation path or file
name, when you first connect to the simulation ASW will prompt you to
browse to the new simulation location.
Alternately, before activation you can change the file name property in ASW's
Managed Simulation Dialog to point to the new simulation location.

Publishing the Model and Locking Features


Publishing the Model
MS Excel allows the user to protect worksheets to prevent end-users from
damaging a worksheet by removing objects, rows or columns, deleting cells,
and etc. This feature can be combined with the Aspen Simulation Workbook
feature locking mechanism to fully protect all aspects of an Aspen Simulation
Workbook. See Excel Worksheet Protection.

Locking Features
Aspen Simulation Workbook allows you to embed simulation case files into
hidden worksheets in MS Excel. This makes it significantly easier to deploy
models to end users, to save files in standard document management
systems, and to run files remotely on a server Setting-up Aspen Simulation
Workbook and Microsoft Excel. (See Embedding Simulation Case Files in MS
Excel.)

Embedding Files
To link Excel worksheets to simulation cases you must (1) Enable the Aspen
Simulation Workbook; (2) Attach the Excel sheet to one or more simulation
cases; (3) activate the simulation and make it visible; and (4) copy variables
from the simulation case and paste them into the Organizer.

Section 1: Using Aspen Simulation Workbook 69


Writing Scripts for ASW
Aspen Simulation Workbook includes tools to help automate Excel sheets
using workbook functions and macros.

Aspen Simulation Workbook Functions


Aspen Simulation Workbook includes several Excel add-in functions. These
functions can be used to retrieve the properties of the attached simulation
cases, model variables, or process tags. The Aspen Simulation Workbook
functions can be used in any cell in the Excel workbook, in conditional
formatting statements, and in other objects that accept formulas.

Aspen Simulation Workbook Functions

Function( Arguments ) Description


ASWActiveSimulation() Returns the name of the active
simulation
ASWSimulationAttribute(Name, Attribute) Returns the give attribute of the named
simulation.
ASWSimulationLastSolveTime(Name) Returns the time of the last solve of the
named simulation (cell must have time
formatting)
ASWSimulationPath(Name) Returns the full path to the named
simulation case
ASWHYSYSDoSchedulerSequenceAction(the Controls HYSYS schedule sequences.
schedule number (an integer), sequence For example, calling
letter (a string - for example "A"), an ASWHysysDoSchedulerSequenceAction(1,
action to perform "A",
HysysEventSchedulerActions.StartSeq)
will start Sequence A of Schedule 1.
Note that the status of Sequence X of
Schedule N can be found at the following
path:
Top.appModel.Variables.Event
Schedule Manager.Event
Schedules.Schedule N.Event
Scheduler Sequence.Sequence
X.Sequence Status
ASWGetModelVariableAttribute(Variable, Returns the given attribute of the
Attribute) referenced model variable.
ASWGetTableVariableAttribute(Range, Returns the given attribute of the
Attribute) variable referenced by the specified Excel
range.

70 Section 1: Using Aspen Simulation Workbook


Aspen Simulation Workbook Function
Arguments

Argument Valid Values Description


Name (text) “” (null string) Use “” to specify name of current active
simulation.
Case name Use case name as text without extension.
Attribute (text) Active Returns the model active state (TRUE or FALSE).
Description Returns the description associated with the
model.
Filename Returns the simulation case file name.
FullPath Returns the full path to the simulation case.
LastSolveTime Returns the time of the last solve of the specified
simulation case.
Status Returns the status of the simulation case, as
returned by the specified simulation case.
Visible Returns the visible state of the specified
simulation case (TRUE or FALSE).

Aspen Simulation Workbook Macros


Aspen Simulation Workbook includes several macros to automate common
tasks. These macros can be associated with buttons placed on any sheet in
the Excel workbook.

Note: The active simulation case refers to the simulation case selected in the
combo box on the Aspen Simulation Workbook Run toolbar.

Macro Name Description


ASWActivateActiveSimulation Activates the active simulation case.
ASWCopyModelValuesToTags Copy model variable values into linked tags.
ASWCopyTagValuesToModel Copies tag values into linked model variables.
ASWDeactivateActiveSimulation Deactivates the active simulation case.

Section 1: Using Aspen Simulation Workbook 71


Macro Name Description
ASWEditSimulations Open the simulation list editor for Aspen
Simulation Workbook.
ASWHysysStartOptimizer Run a selected HYSYS Optimizer for the current
Aspen Simulation Workbook
ASWInitandRunActiveSimulation Initializes and runs the active simulation
ASWLoadSnapshot Loads a "snapshot" for the current simulation
ASWPauseActiveSimulation Attempts to pause a running simulation
ASWRestartActiveSimulation Restarts the active simulation from the beginning
[Aspen Plus].
ASWRunActiveSimulation Executes the active simulation [Aspen Plus] or
activates solver [HYSYS].
ASWRunAllActiveScenarios Opens the Run Scenarios dialogue box
ASWRunSelectedScenario Runs the currently selected scenario
ASWRunSyncActiveSimulation Runs the active simulation synchronously
ASWStopActiveSimulation Attempts to stop a running simulation [Aspen
Plus] or stop the solver [HYSYS].
ASWToggleActiveSimulationActive Toggles the activation status of the active
simulation.
ASWToggleActiveSimulationVisible Toggles the visible status of the active simulation.
ASWUpdateExcelFromModel Updates model variables in tables in Excel for the
active simulation case.
ASWUpdateModelFromExcel Updates the Model Variables from Excel for the
active Aspen Simulation Workbook.
ASWViewActiveSimulationLog Opens the log file for the active simulation case.

Using Buttons and Other Controls to Run


ASW Macros
Excel lets you insert buttons and other controls directly onto your worksheets.
Buttons and other controls can also link to macros, including the Aspen
Simulation Workbook macros summarized above. The available buttons and
controls are located in the standard Excel Forms toolbar.

Note: The instructions here only apply to buttons or other controls inserted
from the Excel Forms toolbar. These instructions do not apply to command
buttons inserted from the Excel Control Toolbox toolbar, which can be used
for Visual Basic automation.
To add a button or other control to your Excel workbook, left-click the desired
button or control on the standard Excel Forms toolbar. The cursor changes to
a crosshair; move the crosshair to the location on the excel sheet where you
want to place the button or control. Click and drag the crosshair to form the
image.
Move the cursor and the crosshair switches to an arrow. Place the arrow over
the desired image area. Click, and adjust the size of the button or control as
desired. (In the case of Button, the Assign Macro dialog box appears
immediately. Click the Cancel button or press the Escape key to close it.)

72 Section 1: Using Aspen Simulation Workbook


(3) Click Cancel

(1) Click on a button


or other control

(2) Move the crosshairs to the


desired position. Click and drag.
Adjust image using the arrows.

1 Right-click on the new button and select Assign Simulation Workbook


Macro.

2 Then select a macro from the list.

Section 1: Using Aspen Simulation Workbook 73


Important: If this file will be used on other computers which run under
different locales (language settings), some extra preparation is needed to
ensure macros will work properly.
• Rename the worksheets to use non-default names because the default
names can change in different locales.
• Rename the controls to use non-default names.
• Use only standard English characters in the names of worksheets,
controls, and macros, and in the macro code.

3 Button properties can be changed at any time. Right-click the button and
select Format Control from the pop-up menu. This opens a pop-up form

74 Section 1: Using Aspen Simulation Workbook


that allows you to change all of the properties of the button, including the
text, font, and so on.

Tip: Macros can also be associated with graphics or other controls inserted on
the Excel sheet; for example, you can cause the simulation model to run
when the user clicks a picture of the process.
To assign a macro to a graphic or other control: right-click the graphic or
other control and select Assign Simulation Workbook Macro from the pop-
up menu.

Running Simulation Cases


Using ASW
Workflow Overview
The basic steps for running simulation cases are outlined below. A specific
workflow varies depending on the application of the model and on the
underlying simulation engine.

Enter Input
Open Excel Sheet Retrieve Plant Activate Model Run Model
Data

Section 1: Using Aspen Simulation Workbook 75


For operator advisory, data reconciliation, and virtual sensor applications the
model user usually would start by updating the plant data tags used in the
model.
When using the models to run cases without plant data, the model user would
skip directly to the second or third steps shown above.

Entering Model Variables

Activating the Simulation Engine


The Model Author may optionally force automatic activation of a linked
simulation case when Excel is opened. In this case, the Activate/Deactivate
button will indicate that the model is active when the Excel Sheet is
opened.
By default, simulation files are not activated automatically when the Excel file
is opened. In this case, you must manually activate the simulation using the
Activate/Deactivate button on the Aspen Simulation Workbook Run
toolbar.
Although Aspen Simulation Workbook allows links to multiple simulation
cases, only one case can be activated concurrently.
When multiple simulation cases are linked to the Aspen Simulation Workbook,
the model user must select which simulation case is currently active.
Pause
Re-initialize Make the
Simulation Solver
Model Model Visible
Environment Restart
Step Solver Model
Manage the simulation Update
Tags

View Message
Activate or De-activate Logs
the Model Aspen Plus: Run
model
Run Mode Aspen HYSYS: Aspen Plus: Stop Model
(ACM/AD Activate Solver Aspen HYSYS: Stop Take a
“snapshot”

The selected simulation file is automatically activated when the model is run
(Aspen Plus) or the solver is activated (Aspen HYSYS).
The appropriate license key(s) required for the linked simulation cases are
checked out when the case is activated and remain checked out until the
simulation case is deactivated or Aspen Simulation Workbook is closed down.

76 Section 1: Using Aspen Simulation Workbook


Running the Active Simulation Case
The workflow for running, pausing and restarting models is somewhat
different for the various simulation engines supported by Aspen Simulation
Workbook.

Running Aspen Plus Cases


Aspen Plus uses a batch run paradigm. The user must launch a run to start
calculations.
Use the Run Simulation button to start the simulation run. While the
simulation is running you can view messages from Aspen Plus in the Logs
view of the Organizer or by clicking the view logs button on the Aspen
Organizer Run toolbar.
If problems occur during the simulation you can stop the calculations using
the Stop Simulation button . The simulation engine can be restarted using
the Initialize/Reinitialize Simulation button .

Running Aspen Plus EO

Tips:
• By default, the simulation strategy for Aspen Plus equation-oriented (EO)
simulations is set to the state in which the model was saved. The
simulation strategy, which can be “Sequential Modular”, “Mixed Mode”, or
“Equation Oriented”, is specified on the Aspen Plus control panel. This
variable can be copied into the Aspen Simulation Workbook Organizer and
exposed to the end-user in Excel as part of an ASW Table. However, this
variable is only accessible through the variable browser. To get this
variable into the Organizer, click the Variable Browser button on the
Organizer Toolbar and navigate through the following nodes in the tree
view: appModel.Setup.Sim-Options.Input.Paradigm (paradigm is the name
of the variable which stores the simulation strategy parameter). Valid
values of this variable are “SM”, “EO” and “MIXED”, which correspond to
the “Sequential Modular”, “Equation Oriented”, and “Mixed Mode” options
shown on the Aspen Plus control panel.
• The control panel EO Solution mode parameter can be copied from the
Run Mode field of the Solve Options form in the EO Configuration folder in
the Aspen Plus data browser, or from the appModel.EO
Configuration.Solve-Options.Input.Mode node in the ASW Variable
Browser. Valid values for this variable include “SIM” (simulation), “OPT”
(optimization), “EST” (parameter estimation) and “REC” (data
reconciliation).
• The optimization and/or reconciliation objective function name can be
copied from the Optimization and Reconciliation fields in the Selected
Objectives frame of the Solve Options folder. These variables can also be
found under the appModel.EO Configuration.Solve-Options.Input node of
the ASW Variable Browser (variable names “OPTOBJ” and “RECOBJ”).
These variables are assigned to a string corresponding to the name of the
selected objective function.

Section 1: Using Aspen Simulation Workbook 77


Running Aspen HYSYS Cases
Aspen HYSYS uses a “live solver” algorithm to update the simulation
calculations each time one of the model specifications is changed.
By default, the simulation solver is active when the simulation is activated.
You can use the Stop Simulation button to deactivate the solver at any
time. This may be convenient when changing several model inputs at once.
Use the Run Simulation button to restart the simulation solver.
You can view messages for the active simulation case in the Logs view of the
Organizer or by clicking the view logs button on the Aspen Organizer Run
toolbar.

Warning: The Run Simulation button on the Aspen Simulation Workbook


Run toolbar is identical to the Run Macro button on the standard Excel Visual
Basic toolbar. To avoid confusion, hide the Excel Visual Basic toolbar when
using or deploying an Aspen Simulation Workbook.

Running Aspen Custom Modeler and Aspen Plus Dynamics


Cases
Aspen Simulation Workbook supports all simulation run modes associated
with Aspen Custom Modeler and Aspen Plus Dynamics. Users can change the
run mode using the Run Mode combo box on the Aspen
Simulation Workbook Run toolbar. Alternately, the run mode can be set
using the Simulation References form in the ASW Organizer.
Use the Run Simulation button to start the simulation run. While the
simulation is running you can view messages from the simulation in the Logs
view of the Organizer or by clicking the View logs button on the Aspen
Organizer Run toolbar.

Use the Step button to take a single time step in a dynamic model.

Use the Pause Simulation button to temporarily pause dynamic


simulations. For example, you can pause the run while setting variable
values.
If problems occur during the simulation you can stop the calculations using
the Stop Simulation button . The simulation engine can be restarted
using the Initialize/Reinitialize Simulation button .

Tip: Aspen Simulation Workbook will run the active Aspen Modeler (ACM, AD,
etc) case using the run mode in which the case file was last saved. For
example, if the case was saved in “Estimation” mode, it will run in that mode
from Aspen Simulation Workbook.

Loading a Snapshot from the ASW Run Toolbar


1 Open a workbook connected to an Aspen Modeler case, such as ACM or
Aspen Plus Dynamics.
2 Activate the simulation

78 Section 1: Using Aspen Simulation Workbook


3 Select the load snapshot command from the ASW menu .
4 A dialog box displays a listing of the available snapshots and their
associated grid attributes
5 Select a snapshot and click the load snapshot button.
6 The system uses the Load action to load the snapshot and the values in
Excel and refreshes them to reflect the changes made by the snapshot.
7 Click the Create Snapshot button
8 The system uses the Create Snapshot action to create a new snapshot
and refresh any list of displayed snapshots

Viewing the Active Simulation Case


The active model can be viewed in its native simulation environment. This
feature allows expert users to view the full set of simulation results and inputs
in addition to the subset of results and inputs that may be exposed through
the Excel sheet.
The active simulation file can be made visible or invisible using the visibility
toggle button on the Aspen Simulation Workbook Run toolbar.

Viewing Simulation Log Files


Error, warning, and information messages generated by Aspen Simulation
Workbook and the underlying simulation case files are stored in log files and
can be opened from the Logs view of the Organizer.

View Aspen Simulation


Workbook messages
View messages for the
active simulation case

Alternatively, use the view logs button on the Aspen Organizer Run toolbar
to open the log file of the active simulation case.

Warning: Over time, the log messages can accumulate, causing the size of
the Excel file to increase. This can also cause substantially slower loading
times. To avoid this problem open the Organizer, go to the Configuration|
Simulations view, select the simulation case, and click the Configuration
button. This opens the Simulation References form. Scroll down to the
Runtime settings to verify that the parameter FlushSimulationMessagesLog is
set to True. This cause Aspen Simulation Workbook to flush the message
buffer each time a new run is launched. This parameter is True by default
except when the file was generated with older releases of Aspen Simulation
Workbook.

Section 1: Using Aspen Simulation Workbook 79


Saving the State of the Simulation Case
Aspen Simulation Workbook allows users to link Excel sheets to external
simulation case files or embed the simulation case files into Excel. (When
saving the Excel document, linked cases are not saved, while embedded
cases are.
Linked simulation cases retain their state between runs unless the user
explicitly saves the simulation case manually. Users can save the case file by
making the simulation visible and saving it using the native simulation
environment.
Embedded simulation cases are automatically updated when you save the
Excel sheet. This behavior is consistent with the behavior of embedded files in
most standard Windows applications.

Warning: When using embedded files be sure to save the model in an


appropriate state. For example, do not reinitialize the model and save Excel
without re-running the simulation (for Aspen Plus or Aspen Modeler). In the
case of dynamic simulations, rewind the model and run it in Initialization
mode before saving it to ensure a clean start for subsequent runs.

Using Visual Basic Automation to Launch


Simulation Cases
Aspen Simulation Workbook includes Excel functions and macros. These
macros can be launched using the Visual Basic automation features of Excel.
For example, the following program can be used to link the
ASWRunActiveSimulation macro to a command button. See Chapter 2, Aspen
Simulation Workbook Macros for a complete list of available macros.
Private Sub CommandButton1_Click()
Application.Run
("AspenSimulationWorkbook.xla!ASWRunActiveSimulation")
End Sub

Scheduling Simulation Runs


Some applications of Aspen Simulation Workbook in the plant operations
domain may require scheduling multiple simulations in series or may involve
updating plant tags and re-running the model at fixed time intervals. The
examples below show how to automate these types of workflows using Visual
Basic.

80 Section 1: Using Aspen Simulation Workbook


Scheduling Aspen Plus Runs
Plant data tags (and the variables linked to these tags) are updated each time
an Aspen Plus case is run from within Aspen Simulation Workbook. After the
simulation is complete, the tags mapped to model variables are updated with
calculation results from the simulation. All these actions can be linked to a
timer event as shown in the example below.
Private Sub
' The following must be called from a Module
Private bStopTimer As Boolean
Sub StartTimer()
Application.OnTime Now + TimeValue("00:00:05"),
"RoutineCalledPeriodically"
End Sub
Sub StopTimer()
bStopTimer = True
End Sub
Sub RoutineCalledPeriodically()
If (bStopTimer) Then Exit Sub
Application.Run
("AspenSimulationWorkbook.xla!OSERunActiveSimulation")
' Pseudo Recursively Call Self
Application.OnTime Now + TimeValue("00:00:15"),
"RoutineCalledPeriodically"
End Sub
End Sub

Scheduling HYSYS Runs


Aspen HYSYS uses an active solver to continuously update simulation results
each time the inputs are changed. Therefore, HYSYS will automatically run
each time the plant data tags are updated (provided the HYSYS case is active
and the solver is on). The tags mapped to model variables are updated with
calculation results when the HYSYS solver returns to “idle” mode after
completing calculations. Therefore, scheduling HYSYS updates is done
indirectly through the macro used to update tags, as shown below.
Private Sub
' The following must be called from a Module
Private bStopTimer As Boolean
Sub StartTimer()
Application.OnTime Now + TimeValue("00:00:05"),
"RoutineCalledPeriodically"
End Sub
Sub StopTimer()
bStopTimer = True
End Sub
Sub RoutineCalledPeriodically()
If (bStopTimer) Then Exit Sub
Application.Run
("AspenSimulationWorkbook.xla!ASWCopyTagValuesToModel")
' Pseudo Recursively Call Self
Application.OnTime Now + TimeValue("00:00:15"),
"RoutineCalledPeriodically"
End Sub
End Sub

Section 1: Using Aspen Simulation Workbook 81


Scheduling Aspen Custom Modeler or Aspen Plus
Dynamics Runs
Aspen Custom Modeler and/or Aspen Plus Dynamics simulations can be
scheduled using the subroutine shown above for scheduling Aspen Plus runs.

Running All Simulations


Sometimes it may be desirable to run all simulations sequentially. More
sophisticated automation is available but requires special references to work.
To enable these references, open the References Dialog from the Tools menu.
Check the entries: AspenSimulationWorkbookXLA and Aspen Simulation
Workbook V7.1.
Public Sub RunAllSimulations()
Dim wb As AspenSimulationWorkbook.ASWWorkbook
Dim sim As AspenSimulationWorkbook.IOSESimulation
Call AspenSimulationWorkbookXLA.GetASWActiveWorkbook(wb)
If wb Is Nothing Then Exit Sub
For Each sim In wb.Simulations
Set wb.ActiveSimulation = sim
sim.Active = True 'Load the case
If sim.ActiveMode = ActiveCalculationMode_Continuous Then
AspenSimulationWorkbookXLA.ASWCopyTagValuesToModel
Else
AspenSimulationWorkbookXLA.ASWRunActiveSimulation
End If
Next
End Sub

82 Section 1: Using Aspen Simulation Workbook


Running Simulations in a Specific Order
Sometimes it may be desirable to run simulations sequentially but in a
specific order. Like the running all simulations case, special references are
required for this to work. To enable these references open the References
Dialog from the Tools menu. Check the entries AspenSimulationWorkbookXLA
and Aspen Simulation Workbook V7.1.
Public Sub RunCases()
RunNamedSimulation "case1"
RunNamedSimulation "case2"
End Sub
Sub RunNamedSimulation(name As String)
On Error Resume Next 'Ignore invalid names
Dim wb As AspenSimulationWorkbook.ASWWorkbook
Dim sim As AspenSimulationWorkbook.IOSESimulation
Call AspenSimulationWorkbookXLA.GetOSEActiveWorkbook(wb)
If wb Is Nothing Then Exit Sub
If wb.Simulations.Count = 0 Then Exit Sub
Set sim = wb.Simulations(name)
If sim Is Nothing Then Exit Sub
sim.Active = True 'Load the case
If sim.ActiveMode = ActiveCalculationMode_Continuous Then
AspenSimulationWorkbookXLA.ASWCopyTagValuesToModel
Else
AspenSimulationWorkbookXLA.ASWRunActiveSimulation
End If
End Sub

Automatic Activation
The Model Author can set the default state of linked simulation case files. For
example, Aspen Simulation Workbook can automatically activate one of the
attached simulation cases each time the Excel workbook linked to the
simulation case is opened. This simplifies the work process of the model user,
since they can avoid the model activation step.
For Aspen Plus or ACM models, the Execute on Startup option can be used to
force the simulation to run once immediately after Excel is opened. This
option is convenient in applications where the user is required to run the
model to initialize some calculations in the Excel sheet.
The Model Author can also force the model to open (be visible) in the native
simulation environment each time the Excel workbook is opened. This feature
is useful for expert users who are developing the interface, but should be
deactivated when the model is published for use by the Model Users.
Use the Configuration view in the Organizer to change the default settings for
the attached simulation case, as shown below. Use the Configuration button
on the Configuration view of the Organizer to launch the Simulation
References form (see figure below).

Section 1: Using Aspen Simulation Workbook 83


Select linked
simulation case

Set
“ActivateOnStartup” to
“True” to force
automatic case
activation

Visible Toggle
Use the Make Visible button to make the active simulation case visible in
its native user interface environment. The simulation remains visible in a
separate window until you click the Make Visible button again.

Tip: Another method is available to quickly attach an Excel sheet to a


simulation case. Open the simulation case using its native user interface, copy
a variable, and paste it into the organizer. Aspen Simulation Workbook will
attach the simulation and make it active after getting user verification.

Refresh Excel from Simulation (Re-synchronizing Aspen


Simulation Workbook)
After editing the model in its native environment, some variables attributes in
the Excel sheet may be out of synch with the linked simulation model. Use
the Refresh Excel from Simulation button on the design toolbar to force
the variables on the Excel sheet and the Organizer to be in synch with the
variables in the active simulation case.

Using Remote Execution


Aspen Simulation Workbook allows you to run simulations remotely over a
network on a dedicated simulation server. Aspen Simulation Workbook must
be installed on the client (end-user) computers. Aspen Remote Simulation
Service and the simulation applications must be installed on the simulation
server computer.

84 Section 1: Using Aspen Simulation Workbook


Restricted user privileges on the client are sufficient to run simulation cases
remotely on the server; the files are run under the simulation services user
profile (the user account used to run this service is configured when Aspen
Remote Simulation Service is installed).
When running files remotely, Aspen Simulation Workbook creates a
temporary subdirectory under the simulation services user profile on the
server PC. The simulation case files referenced by the models are copied from
the client PC to the server PC into the temporary directory. Embedded files
are extracted from the MS Excel sheet into the temporary directory on the
server computer when the simulation is activated. The embedded files are
updated at the end of the run.
Some simulation models require library files (.APM for Aspen Plus, .ACML for
ACM, etc), OCX controls, user-defined DLL files or other files or controls which
must be installed or registered. To run these models remotely you must first
install the required files on the simulation server. Administrative privileges are
required to install these types of files on the server.

Note: Some layered products of Aspen HYSYS, including HYSYS Olgas and
HYSYS Olgas 3-Phase, cannot be run under the remote desktop option due to
contractual constraints.)
Follow the procedure below to configure ASW to run simulations on a remote
server:
1 Open the ASW Organizer; select the Configuration | Simulations view.
2 Select the simulation case intended for remote execution.
3 After selecting the desired simulation case (in this example:
testprob.bkp), click the Execute case on remote server check box and
then enter the remote host name and remote port (note that the default
port is "0".)

Warning: ASW remote execution cannot be used with Aspen Modeler files
which require APPDF files that cannot be embedded into the simulation case
file. This includes Aspen Plus Dynamics files that use RGIBBS, closed-form
Polymers Plus reaction models, or user reaction or property models written in
FORTRAN and compiled as DLL files. We expect to eliminate this restriction in
the future by introducing the compound file concept into the Aspen Modeler
family of products.

Section 1: Using Aspen Simulation Workbook 85


Installing Aspen Remote Simulation Server
(ARSS) on Windows Vista and Windows
2008 Server
Installing Aspen Remote Simulation Server on Windows Vista or Windows
2008 Server requires some specific settings:
1 Service Login -The ARSS service running on the server must be either
setup as a local service, or logged-in with a user account that has
administrative rights on that pc.
2 Firewall - The server firewall may be left on, but you must change the
advanced firewall settings to allow the ARSS executable file
AspenTech.AspenCxs.RemotingSvc.exe

to receive incoming connections. The default path to the file is:


C:\Program Files\AspenTech\Aspen Remote Simulation Server
V7.1\AspenTech.AspenCxs.RemotingSVC.exe
3 Registry/Heap memory fix - In order to run Aspen Custom Modeler or
Aspen Plus, you need to increase the size of the Window's heap memory
for non-interactive desktops. This can be done by changing the following
registry key:
HKEY_LOCALMACHINE\SYSTEM\Current Control Set\Control\Session
Manager\Subsystems\Windows
Change required:
Part of the Windows string value will be:
SharedSection=xxxx,yyyy,zzzz
where "zzzz" is the heap size for non-interactive desktops. Increase this
number to 3072 and reboot the server.

Running Aspen Remote Simulation Server


on Windows Vista
If ARSS isn't running properly, check the following:
1 ARSS Status Monitor - The ARSS status monitor is the best way to test
whether your ARSS client/server system is setup correctly. You can run
the ARSS Status Monitor Utility on your client PC to check the status of
the ARSS service running on the server. The name and/or address of the
ARSS server must be entered into the ARSS status monitor utility, then
click on the view->refresh now menu option.
If you get a warning that you cannot communicate with the server, then
you know your client/server systems are not setup correctly. You can also
run the ARSS status monitor utility on your server by entering localhost
as the server name in order to check the status of the ARSS service.
2 ARSS Windows Service - You can also check the status of the ARSS
service via the Windows Services dialog. You can access the Windows
Services dialog in Vista by clicking the start button and then right-

86 Section 1: Using Aspen Simulation Workbook


clicking on Computer and selecting Manage from the popup menu. You
then need to choose Services and Applications and then Services to
see a list of Windows services running on your computer. Aspen Remote
Simulation Service (version V7.1) should be listed there and the status
should be started. If the status is not started then you can right-click
on it and select the Start menu option to start the service.

Monitoring the Remote Simulation Server


Aspen Simulation Workbook includes a utility, Aspen Remote Simulation
Server Status Monitor that allows users to check the status of the remote
simulation server and the simulation jobs running on the remote server.
Users can start and stop the simulation service and view the CPU and
memory usage on the remote server(s). Users can also stop any runaway
simulation processes (if the simulator experiences an unexpected failure one
or more of the simulator processes may remain active, consuming memory
and/or CPU time).
To launch the Aspen Remote Simulation Service Status Monitor:
1 Click the Windows Start button, select All Programs | AspenTech |
Operations Support V7.1 | Aspen Simulation Workbook | Status
Monitor
or
Click the Windows Start button, select All Programs | AspenTech |
Process Modeling V7.1 | Aspen Simulation Workbook | Status
Monitor
2 Select the server ID from the list; or click Add to specify the name (or IP
address) and port for the server.
3 Use the Start Service and Stop Service buttons in the Service Status
frame to start and stop the remote simulation service. The current status
of the remote simulation service is shown above these buttons. The CPU
usage and free memory on the remote server are shown to the right of
these buttons.
4 Actively running simulation cases are listed in the Active cases on
server frame. To stop an active case, select the case by name and click
the Stop Case button.
When the Status Monitor window is not in use it will be minimized behind an
icon in the System Tray (normally located on the Windows taskbar).

Section 1: Using Aspen Simulation Workbook 87


Limiting End-User Access to
Simulation Case Files and Data
File embedding and remote execution can be used to prevent model end
users from viewing the contents of the linked simulation models. To prevent
end users from viewing the files or accessing the simulation case files you
must restrict user access to several features in Aspen Simulation Workbook.
First, embed the simulation case file and configure the simulation to run on a
remote server as described in the previous sections. Then:
1 Click the Restrict Access button to open the Restrict Access form and
clear the Export Simulation Case checkbox to prevent the user from
exporting the simulation case file. Alternatively, clear the View
Configuration checkbox to completely prevent the user from viewing the
file source name, server ID, and other configuration details.
2 Clear the Show/Hide Simulation checkbox to prevent the user from
viewing the case file using the native simulator.

88 Section 1: Using Aspen Simulation Workbook


3 Clear the View Variable Access checkbox to prevent the user from
viewing the simulation data structure using the variable browser inside the
organizer.
4 Enter a password to prevent the user from changing these options.

MS Excel Worksheet Protection


MS Excel allows the user to protect worksheets to prevent end-users from
damaging a worksheet by removing objects, rows or columns, deleting cells,
and etc. This feature can be combined with the Aspen Simulation Workbook
feature locking mechanism to fully protect all aspects of an Aspen Simulation
Workbook.
Select Tools | Protection | Protect Sheet from Excel’s pull-down menu to
activate the Protect Sheet dialogue. Use the check boxes on this form to
specify what actions the user is allowed to take in the protected areas of the
worksheet. This sheet is also used to specify an optional password to
unprotect the sheet.

By default, all cells in the worksheet are “locked” when the sheet is protected.
This prevents users from entering data into the cells. For Aspen Simulation
Workbook interfaces, be sure to unlock ranges where the model user needs to
enter data or units, as well as cells which contain calculated results (and their
units) written back to Excel from the simulation application. Note that cells
can only be unlocked while sheet protection is off. To unlock a range of cells,
select the range of cells, then select Format | Cells | Protection and uncheck
the Locked option.

Section 1: Using Aspen Simulation Workbook 89


Tips:
• Cell protection is one of the many format properties which can be included
in a cell style. Therefore the cell protection property can be included in
Aspen Simulation Workbook table templates. Since cells are locked by
default, be sure to make the protection unlocked in any styles you create
and use in ASW tables.
• For easy access to the sheet protection function, add the sheet protection
toggle button to one of the toolbars in Excel. To modify a toolbar, click
the control on the right-hand side of the toolbar, select Add or Remove
Buttons | Customize from the pop-up menu to open the Customize
dialogue. Move to the Commands tabsheet, select Tools in the Categories
frame and scroll down in the Commands frame to find the appropriate
button. Select the button and drag it into the appropriate toolbar location
using the mouse using drag-and-drop (for example, hold the mouse
button down to drag the object and release it to drop the object.

Using ASW to Automate Workflow


Retrieving Plant Tags
Before tags can be associated with model variables, they must be part of the
ASW Organizer data store:
1 Use the Excel add-in tools provided with your plant data server software
(such as Aspen IP.21) to generate a table of plant data tags and create
links between the Excel workbook and the plant data tags. Ideally, the
tags should be laid out in a table, with the various tag attributes in the
table columns and the rows of the table each corresponding to a single
tag.
The tag table should include:
• tag name (required)
• value (required)
• units (required)
• tag description and tag quality (status) parameters are optional.
2 In Excel, highlight the range of cells containing the tag information. You
may include the table header and column headers in the selection range.
3 Right-click and select ASW Tables | Map Tag Variables from the list of
options.
Alternately:

90 Section 1: Using Aspen Simulation Workbook


1 You can click the Import Tags button on the Aspen Simulation Workbook
Design toolbar. This opens the Map Tag Attributes pop-up form.
2 Click the Browse button on this form.
3 Select the range of cells containing the tag information in your Excel
workbook.
4 After all of the columns are mapped to tag attributes, click the OK button
to close the form and import the tags into the ASW Organizer. This will
also automatically open the ASW Organizer into the Variable Access/Tag
Variables view. This view shows the list of plant data tags in the ASW
Organizer variable grid.

Tip: Use the standard tag attribute names when making a table of plant tags;
for example use “Name” instead of “Tag” or “Tag ID” to identify the tags. This
saves time when you use the Map Tag Attributes form to import the tags into
the ASW Organizer.

Mapping Plant Tags to Model Variables


Plant data tags can be mapped to model variables. This allows you to
automate workflows and leverage the power of process simulation in the plant
operations environment. You can:
• Map tags to model variables (e.g., populate model inputs with measured
data from the plant).
• Map model variables to tags (e.g., send model predictions back to the
plant data server through tags, which allows the model to act as a virtual
analyzer and/or provide predictions of unmeasured variables for operator
decision support applications).
• Create two-way flow of information between the model and plant data.
To map variables to tags:
1 Open the ASW Organizer and switch to the Variable Mapping view in the
left pane. This opens a grid in which each row displays a link between a
model variable and a plant tag. The first time the grid is opened, it will be
empty.

2 Right-click the variable grid pane to open the pop-up menu.

Section 1: Using Aspen Simulation Workbook 91


3 Select Add Unreferenced Tags to pull a list of tags into the variable
grid, or to update the list with recently added tags.
• Aspen Simulation Workbook will automatically map tags and variables
to each other if the tag name and variable name are identical. If a
matching variable is not found for a tag, the 'null' symbol will
show up in the Model Variable column.
• To map a variable to an unreferenced tag, click the 'null' symbol
next to the tag name. This brings up a list of the unmapped model
variables.
• Scroll through the list to locate the desired model variable.
• Click on the variable name to map it to the tag.

Tags and variables with the same


name are automatically mapped
to each other

Unmapped tags are identified


with the null symbol in the model
variable column

Click here to bring up a list of


available model variables

Scroll through the variable list;


click on the name of the target
variable to complete the mapping

Note: It is not necessary to map every plant tag to a model variable. Use the
Delete button to remove any tags that you do not want to map.
Alternately, you can remove all the unreferenced tags together by right-
clicking in the variable grid and selecting Remove Incomplete Tags from
the pop-up menu.

Tag Quality Mapping


Process data systems usually qualify plant data tags with a quality or status
parameter that identifies the current state of the measured variable. The tag
quality parameter may reflect the state of an instrument (off-line or on-line),
the reliability of a measurement (in or out of bounds), the presence or
absence of data (available or missing), or may indicate if a variable is under
steady-state conditions.
These various quality states differ from one type of plant information software
to another. Further, the current version of Aspen Simulation Workbook only
recognizes two quality states: “Good” and “Bad”. Therefore the tag quality
definitions from the plant data server must be mapped to the valid states
used by Aspen Simulation Workbook.

92 Section 1: Using Aspen Simulation Workbook


Tag Mapping Properties
Several additional properties of the tags can be displayed in the variable grid
within the Variable Mapping view. These properties can be included in ASW
Tables generated from this view. The user can change the properties
identified with a bold font.

Property Read/Write Description


CondQuality Read only Conditioned quality {Good, UL Clamped, LL
Clamped, UL Exceeded, LL Exceeded,
Disabled}
CondValue Read only Conditioned value – this is the value sent back
to the simulation case after applying upper
and lower clamping limits and/or verifying tag
quality.
Difference Read only Numerical difference between model variable
and the tag value (MdlValue-Tag)
Enabled R/W Link between model variable and tag is active
{TRUE, FALSE}
Group R/W Optional user-defined variable group ID. Use
this property as an aid to group related
variables together for faster navigation.
Lower Read only Variable lower bound
LowerClamp Read only Clamping on lower bound {TRUE, FALSE}
MdlName Read only Model variable name
MdlUnits Read only Model variable units
MdlValue Read only Model variable value
MdlVarID R/W Model variable Identifier
Ranges Read only Excel ranges in ASW Tables containing this
tag/variable mapping row.
ReadOnly R/W Determines the read/write status of the value
field. Default state is determined by the
Status attribute, with calculated variables set
to read only.
Simulation Read only Name of the simulation file.
Ranges Read only Ranges in Excel where this mapping row
appears in a Tag Mapping table.
TagMult R/W Tag multiplier – see Tag Conditioning, below.
[1.0]
TagName Read only Name assigned to a variable. Aspen
Simulation Workbook sets a name by default
when the variable is pasted to the organizer;
user may override this name.
TagOffset R/W Tag offset – see Tag Conditioning, below.
[0.0]
TagUnits Read only Units of measurement of the variable.
TagValue Read only Tag value
TagVarID R/W Tag identifier
Type R/W Tag mapping type {Tag2Model, Model2Tag,
Bidirectional, Independent}

Section 1: Using Aspen Simulation Workbook 93


Upper Read only Model variable upper limit
UpperClamp Read only Upper bound clamping {TRUE, FALSE}

Tag Conditioning
Plant data measurements are never perfect. Aspen Simulation Workbook
allows you to apply a linear conversion formula to condition tags which are
linked to model variables. The TagMult and TagOffset properties are used to
carry out a simple linear conversion as shown below. When limit clamping is
active (TRUE), the conditioned value is further constrained by user-specified
upper and lower bounds.
Tag ⎯
⎯→ Model
ConditionedValue = MIN (MAX ((TagValue × TagMult + TagOffset ), Lower ), Upper )
ModelValue = ConditionedValue
When the system variable AlwaysCopyTagValues is TRUE, the model variable
is automatically set to the conditioned value. This variable is can be toggled
on and off using the Automatic Update button on the Aspen Simulation
Workbook Design toolbar indicates that automatic update is on and
indicates that automatic update is off.
The model variable is also updated when the CopyTag2Model function is
executed. This function is executed at the start of a run (Aspen Plus, ACM)
and when the user clicks the Copy Tag Values to Model button .

Model ⎯
⎯→ Tag
⎛ ⎛ ⎛ ModelConditionedValue − TagOffset ⎞ ⎞ ⎞
ConditionedValue = MIN ⎜ MAX ⎜⎜ ⎜⎜ ⎟⎟, Lower ⎟⎟, Upper ⎟
⎜ TagMult ⎟
⎝ ⎝⎝ ⎠ ⎠ ⎠
TagValue = ConditionedValue

When the system variable Simulation.AlwaysCopyTagValues is TRUE, the tag


variable is automatically set to the conditioned model variable value.
Otherwise, the tag is updated when the CopyModel2Tag function is executed
(this function is executed at the end of a simulation run (Aspen Plus, ACM) or
when the solver returns to idle mode (HYSYS).
In the equations above, the Upper and Lower properties refer to the upper
and lower limits specified in the Tag2Model form. These default to upper and
lower limits of the mapped model variables. The clamping properties also
default to the values specified for the corresponding model variables. The
Tag2Model clamps and limits can be overridden locally.
The linear conditioning formula can also be used to carry out unit conversions
to convert plant measurements in one set of units to model variables in
another set of units.
If more complex tag conditioning equations are required, use equations in
Excel to condition the raw tag values, and then link these conditioned values
to the model variables using another set of equations.

94 Section 1: Using Aspen Simulation Workbook


Mapping Tag Quality Definitions
Process data systems usually qualify plant data tags with a quality or status
parameter that identifies the current state of the measured variable. The tag
quality parameter may reflect the state of an instrument (offline or online),
the reliability of a measurement (in or out of bounds), the presence or
absence of data (available or missing), or may indicate if a variable is under
steady-state conditions.
These various quality states differ from one type of plant information software
to another. Further, the current version of Aspen Simulation Workbook only
recognizes two quality states: “Good” and “Bad”. Therefore the tag quality
definitions from the plant data server must be mapped to the valid states
used by Aspen Simulation Workbook.

Section 1: Using Aspen Simulation Workbook 95


Tag Quality Parameters
Variable and tag quality parameters are used to control the mapping of data
between linked model variables and plant tags. Likewise, if a model variable
is out of range, and variable clamping is active (checked), the quality of the
variable will be set to “UL Clamped” or “LL Clamped” and it will not be pushed
back to linked model variables.

Model Variable Linked to Tag, Type=Tag to Model or Bidirectional

Tag Value* Variable Variable Conditioned Conditioned


LL Clamping UL Clamping Variable Variable
Quality Value
Tag Value < Lower FALSE N/A LL Exceeded Value
Limit** TRUE N/A LL Clamped Lower Limit

Tag Value > Upper N/A FALSE UL Exceeded Value


Limit** N/A TRUE UL Clamped Upper Limit
LL < Tag Value < UL N/A N/A Good Tag Value
Tag quality is not N/A N/A Bad Last valid
“Good” value
Tag is unavailable or N/A N/A Not Set Last valid
Null value

* Tag value after linear conversion formula is applied, see Tag Conditioning,
above.
** Upper and Lower Limit attributes of the linked model variable

Tag is Linked to Model Variable, Type=Model to Tag or Bidirectional

Calculated Model Variable Variable Conditioned Conditioned


Variable Value LL Clamping UL Clamping Variable Variable
Quality Value and
Tag Value
Value*< Lower FALSE N/A LL Exceeded Value
Limit** TRUE N/A LL Clamped Lower Limit

Value* > Upper N/A FALSE UL Exceeded Value


Limit** N/A TRUE UL Clamped Upper Limit
LL < Value < UL N/A N/A Good Tag Value
Value is missing N/A N/A Not Set Last valid
value

* Model variable value after linear conversion formula is applied, see Tag
Conditioning, above.
**Upper and Lower Limit attributes of the linked model variable

96 Section 1: Using Aspen Simulation Workbook


Creating Tag Tables
Plant data tags can be grouped together in ASW Tables and inserted into the
Excel workbook. To create a tag table, select all the tags to be included in the
table. Right-click any field in a variable row in the Organizer Variable Grid to
select the tag. Hold down the Shift key to select a range of tags. Use the
CTRL key to make multiple selections. Use the ASW Table Wizard button
or the ASW Quick Tables button to open the appropriate forms to generate
a tag table. These forms are each described in detail in Chapter 2, “Creating
Model Variable Tables”.
Tag tables can be generated from the Tag Variables, Tag Quality Map, or
Variable Mapping views in the Organizer.

Tip: You can generate ASW Tables that display model variables and tags side-
by-side for easy comparison from the Variable Mapping view. Simply select
the tags of interest and use the table wizard to place the “Tag Value” and
“Model Value” in adjacent columns.

Getting the Most from MS Excel


This section covers several features of Microsoft Excel which are especially
convenient to use with Aspen Simulation Workbook. The objective of this
section is to raise awareness of these features and document the basic
functionality; refer to Microsoft’s documentation set or any of the widely
available third party Excel references for more detailed information.

Conditional Formatting
Excel includes a “conditional formatting” feature which can be used to change
the font, background color, and other formatting associated with a cell based
on the value of that cell or based on a user-specified formula. This feature can
be used to make your Aspen Simulation Workbook model interface more
visually appealing and easier to use.
To use conditional formatting, select a cell and then select Format |
Conditional Formatting from Excel’s pull-down menu. This will open the
Conditional Formatting dialogue:

Section 1: Using Aspen Simulation Workbook 97


Excel allows up to three conditions to be defined on this form. This allows you
to set up four sets of conditions and associated cell formats (one
corresponding to the original format of the cell). In this example, conditional
formatting is applied to a cell containing the Aspen Simulation Workbook
“Simulation Attribute” function which returns strings. The conditional
formatting gives the user an obvious visual cue that the state of the model
has changed, as shown below:

The next example demonstrates how to use conditional formatting to change


the color of the values column in an Aspen Simulation Workbook table based
on the specification state (status) of the variables. In this case, a formula is
used to control the value of each cell in the values column based on the
status attribute. The status attribute must be included in the Aspen
Simulation Workbook table, but of course this column can be hidden in the
worksheet.

98 Section 1: Using Aspen Simulation Workbook


The conditional formatting shown above is applied to cell N40. The user has
copied this format to the other cells using the Paste Special | Formats option
in Excel. Note the relative address ($P40) in the equation allows you to copy
this formula over a range of cells without having to reenter equations for each
cell. An absolute address ($P$40) would cause all the value cells to use the
same format based on cell $P$40.

MS Excel Form Controls


Excel allows you to add Windows-style controls directly to your worksheets.
These controls can be linked to cells in the worksheet, including cells linked to
process models using Aspen Simulation Workbook.
The basic form controls are included in the Excel Forms toolbar. Select View|
Toolbars and check the Forms item to make the toolbar visible:

To add any of the controls above to your Excel sheet, simply click on the
appropriate control. The mouse pointer will change from an arrow to a
crosshair (+). Point to a location on your worksheet and click to anchor one
corner of the control; hold down the button and drag the mouse to select the
desired area; release the button to anchor the opposite corner. Alternately,
you can point and click to drop the control onto the worksheet, and then use
the resizing handles to change the size and shape.

Tip: Hold the ALT key down while placing form controls to line the corners up
with the edges of cells. To specify an exact size, right-click the control and
select Format Control from the pop-up menu. Specify the control height and
width on the Size tabsheet.
Excel form controls are “locked” by default. To change this setting, select the
control, right-click to bring up a pop-up menu, select Format Control |
Protection, and uncheck the Locked attribute. This prevents the end user from
moving, resizing, or deleting the form control when the sheet is locked (see
Excel Worksheet Protection, below).
By default, the form controls will print out with the rest of the worksheet. To
prevent form controls from printing, select the control, right-click to bring up
the pop-up menu, select Format Control | Properties and uncheck the Print
control option. This tabsheet also contains settings which control how the
controls behave when the worksheet rows or columns are resized.
Excel controls are displayed in a “3D” mode by default. This gives the controls
the same look and feel as native Windows. Some users may prefer the

Section 1: Using Aspen Simulation Workbook 99


alternate (2D) style. To change styles, select the control, right click, select
Format Control | Control tabsheet and uncheck the 3D option.
The sections below describe several of the most commonly used controls and
functions available on the Excel Forms toolbar.

Spinner Controls and Scroll Bar Controls

The Spinner control and the Scroll Bar control allow the user to
quickly adjust the value of a cell using mouse clicks.
The Spinner control allows the user to increase or decrease the current value
of a cell within a specified range. The spinner control is very compact and it
can be placed very close to the linked cell as shown below:

Scroll Bars allow the user to increase or decrease the current value of a cell
within a specified range of values. The Scroll Bar control takes up a bit more
space than a spinner, but it offers some unique advantages. Unlike the
spinner, the scroll bar graphically displays the status of the value relative to
the upper and lower bounds:

Scroll bars also allow the user to make large changes to the value by
dragging the slider or by clicking the grey space on either side of the slider.
Both types of controls operate on whole numbers (integers). Thus these
controls are typically linked indirectly to Aspen Simulation Workbook tables
using an equation to convert the integer value returned by the control to a
real value required by the process simulation model.
The Scroll Bar control does not display numerical upper and lower bounds, but
your can add Label Controls under each end of the scroll bar to visually
document the numerical bounds.
Follow these steps to add a spinner or scroll bar to your worksheet:
1 Place a Spinner or Scroll Bar onto the worksheet as described in the
previous section.
2 Select the control; right-click to bring up a pop-up menu, and select
Format Control, click on the Control tabsheet.
3 Specify the Minimum value (lower bound), Maximum value (upper bound),
and Incremental change (this is the value change which will occur when
the user clicks the arrows on the control). For scroll bars, specify the page
change (this is the value change when the user clicks the grey space on
either side of the slider bar).
4 Click the browser button and point to a cell in your worksheet to link
this control to the specified cell. The linked cell does not need to be on the
same tabsheet as the control. It is good practice to hide the linked cell on
another sheet to avoid visual clutter in your Aspen Simulation Workbook
interface.

100 Section 1: Using Aspen Simulation Workbook


If the simulation variable is a real number which cannot be rounded to whole
number integers, or if it is a very large value, you will need to use equations
to convert the integer value in the control-linked cell to a cell in your Aspen
Simulation Workbook table, as shown below:

='Secret Formulae'!C4*0.01

In this example, the control cannot be


linked directly to the reflux ratio because
this control operates on whole numbers

These
When properties set the lower
the user manipulates theand upper
scroll bar,
values associated
the value with
in this cell willthe two ends of the
change.
scroll bar
Sets the step change which occurs when
the user slides the bar

When the user manipulates the scroll bar,


the value in this cell will change.

Grid Toggle
Use the Toggle Grid button on the Excel Forms toolbar to turn the
gridlines on or off on your worksheets. Controls and other graphics look
better when the Excel sheet has gridlines deactivated.

Buttons
You can insert a Button by selecting the button symbol on the Excel Forms
toolbar. Place the button directly onto your worksheet as described
previously.
Buttons can be linked to your own VBA macros or to predefined Aspen
Simulation Workbook Macros. See Using Buttons to Run Aspen Simulation
Workbook Macros for further details.

Label Control

The Label control allows you to insert a label box on your worksheet.
Text entered into the label box uses the same font and format as the text
associated with other format controls, which can give your application a
consistent look and feel. In addition, the label box is not anchored to a
particular cell, so it can be placed anywhere on the worksheet.
To add a label box to a worksheet, select the label control from the Forms
toolbar, and place it on the sheet as described above. Place the pointer over

the text; it will switch to move/resize mode . Click on the label box again
to switch to text insert mode . You can now enter or change the text in the
label box:

Section 1: Using Aspen Simulation Workbook 101


Group Box Control
The Group Box control is typically used to group Option Buttons
together as described in the next section. However, this control can also be
used to visually group a section of controls or subsection of the worksheet
together by drawing a frame around them.
The Group Box frame includes a text heading which can be used to give
instructions to the user. You must place the Group Box on your Excel sheet

and select it while the mouse is in move/resize mode . Click on the frame
header again to switch to text insert mode ; you can now enter new text.
The example below shows how the Group Box can be used to visually
identify a group of buttons (each of which are associated with Aspen
Simulation Workbook macros).

Option Button Control


Option buttons are used to present the user with two or more mutually
exclusive options. Option Buttons are always used together in a group. If
you intend to use more than one set of option buttons in a worksheet, you
must place each group of buttons inside a Group Box. At any time, only one
of the option buttons placed in a group box can be checked.

102 Section 1: Using Aspen Simulation Workbook


Follow these steps to add option buttons to your worksheet:
1 Place a Group Box onto the worksheet as described in the previous
section.
2 Place two or more Option Buttons inside the group box. The order in
which these buttons are placed will influence how the boxes communicate
with Excel. For example, the first box you place will be associated with the
integer “1”, the second box will be associated with integer “2” and so on.
3 To change the text associated with the option button, place the pointer

over the text; it will switch to move/resize mode . Click on the option
button control again to switch to text insert mode . You can now enter or
change the text.
4 Select any of the option buttons; right-click to bring up a pop-up menu,
and select Format Control, click on the Control tabsheet:

5 Click the browser button and point to a cell in your worksheet to link
these controls in Excel. The linked cell does not need to be on the same
tabsheet as the control. It is good practice to hide the linked cell on
another sheet to avoid visual clutter in your Aspen Simulation Workbook
interface. When you specify the cell link for one option button in a group,
all other buttons in that group are automatically linked to the same cell.
The linked cell will contain an integer value which indicates which option is
selected.
6 Use an equation to associate the linked cell with a cell in an Aspen
Simulation Workbook Table. Nested IF blocks are a convenient mechanism
to convert integer values to string values, as shown in this example:

Group
Box
Click here to point to a
Option cell in your sheet ,or type
Buttons it in the Cell Link box

Cell $N$9 displays which Range N10:O10 contains a simple OSE Table linked to the Aspen Plus
option is valid, the integers variable Sim-Options.Paradigm.
refer to the first, second, and This variable has two three possible string values:
third options above. Excel “SIM” (simulation); “EST” (estimation); and “OPT” (optimization).
assigns these integer values
automatically. Cell $O$10 contains: =IF(N9=1,"SIM",IF(N9=2,"EST","OPT"))

(returns SIM if option is 1, EST if option is 2, otherwise returns OPT)

Section 1: Using Aspen Simulation Workbook 103


Check Box Control
The Check Box control is convenient when the user must back a yes/no,
on/off, or true/false decision. This control returns a Boolean TRUE or FALSE
result (TRUE indicates the box is checked).
Follow these steps to use a check box in your worksheet:
1 Place a Check Box control on your excel sheet
2 To change the text associated with the check box, place the pointer over

the text; it will switch to move/resize mode . Click on the option button
control again to switch to text insert mode . You can now enter or
change the text.
3 Select the check box; right-click to bring up a pop-up menu, and select
Format Control, click on the Control tabsheet:

4 Click the browser button and point to a cell in your worksheet to link
these controls in Excel. The linked cell does not need to be on the same
tabsheet as the control. It is good practice to hide the linked cell on
another sheet to avoid visual clutter in your Aspen Simulation Workbook
interface.
5 If the model variable associated with this control accepts TRUE and FALSE
arguments, you can link the control directly to the appropriate location in
the Aspen Simulation Workbook table (link the checkbox to a cell in the
Value column of the Aspen Simulation Workbook table). Otherwise, use an
equation to convert the logical argument to a string, as shown in this
example:

Check Box control

Range $O$21:$P$21 contains an OSE table. Cell P21 is


linked to the Value attribute of the Aspen Plus
EO Configuration.Spec-Groups.Enabled variable.
This variable accepts strings YES or NO as input.
Cell $P$20 is set to Boolean
Cell $P$21 contains the formula =IF(P20,”YES”,”NO”) “TRUE” if the linked check
which converts the logical to an appropriate string. box is checked, and “FALSE”
if it is unchecked

Checkboxes are the preferred control for any sort of binary decision because
they occupy the minimum amount of space and are very easy to understand.

104 Section 1: Using Aspen Simulation Workbook


List Boxes and Combo Boxes
List Box controls, , and Combo Box controls, , allow the user to select
among a list of several mutually exclusive options. Both of these controls
offer the same functionality; they have a slightly different look and feel.
The List Box control shows the user multiple options simultaneously; the
user can simply click the list item to select it. The selected choice is identified
by highlighting as shown below.

The Combo Box control displays the currently selected item. The user must
click the right side of the control to pop up a list of available options, and click
again to select one of the options. The currently selected choice is displayed
after the user selects one of the options.

In general, Combo Boxes are preferred over List Boxes because they
occupy less space and the current selection is displayed in a more obvious
manner. Combo boxes are also a preferred over Option Boxes, especially
when the user must select between many options.
Follow these steps to add a List Box or Combo Box to your worksheet:
1 Select the control from the Excel Forms toolbar and place it on the
worksheet as described in the previous section.
2 For clarity, you may want to add a Label Control next to or above the list
box or combo box to provide the user with additional information.
3 Enter a list of options in a continuous range of cells on an Excel worksheet
in your workbook. The list does not need to be on the same tabsheet as
the control; in fact it is good practice to hide the list on another sheet to
avoid visual clutter in your Aspen Simulation Workbook interface.
4 Select the List Box or Combo Box; right-click to bring up a pop-up
menu, and select Format Control, click on the Control tabsheet:

5 Click the Input Range browser button, , and point to the range of cells
where previously you entered the list of options.

Section 1: Using Aspen Simulation Workbook 105


6 Click on the Cell Link browser button, , and point to a cell in your
worksheet. To avoid visual clutter, the linked cell can be placed in a
hidden row or column or on another tabsheet. The linked cell will contain
an integer value which indicates which option is selected; the first
selection option corresponds to a value of 1.
7 Use an equation to associate the linked cell with a cell in an Aspen
Simulation Workbook Table. The VLOOKUP function is convenient for this
purpose:

The Combo Box returns an


integer corresponding to the
user-selected value.

Use the VLOOKUP to convert


this integer back to a string
as shown here

Range N31:O31 is an OSE Table linked to the Aspen Plus variable Sim-Options.Paradigm.
This variable has three possible string values:
“SIM” (simulation); “EST” (estimation); and “OPT” (optimization).

Cell O31 uses the following function to convert the integer returned by the Combo Box into
an appropriate string value used in the simulation model:

=VLOOKUP(Q31,P28:R30,3) Note: (index, range, column in range)

106 Section 1: Using Aspen Simulation Workbook


Section 2: Working with
Specific Simulation Platforms

Using ASW with Esteco


ModeFrontier
Esteco Mode Frontier can be used with ASW to perform optimizations on your
Aspen simulations. To set this up, you should prepare an ASW workbook that
is linked to the simulation that you want to optimize with Mode Frontier, and
then create table(s) containing the variables that you want exposed.
When you set up Mode Frontier you will be specifying the cells containing the
input variable values that you want optimized and the cells containing the
output values that will be judged in your optimization.
One important point to remember is that you need to call the ASW macro
named ASWRunSynchActiveSimulation from Mode Frontier when you want
the simulation to solve: this will perform a synchronous solve, meaning that
Mode Frontier won’t read the simulation output values until the simulation has
finished running and ASW has placed the new output values back in the
workbook.
You should also set up your ASW workbook to automatically connect to the
simulation when opening (set the simulation property
activateOnStartup=True). This way, when Mode Frontier opens the
workbook, the simulation will be connected and ready to solve.

Using ASW with Oracle


CrystalBall
Oracle Crystal Ball can be used with ASW to perform Monte Carlo and other
analysis on your Aspen simulations. In order for ASW to work properly with
Crystal Ball, you need to add a small amount of VBA code to your workbook.
This VBA code triggers ASW to run the Aspen simulation during each Crystal
Ball trial run.

Section 2: Working with Specific Simulation Platforms 107


Using Oracle Crystal Ball to perform Monte
Carlo analysis with ASW Simulations
The following steps are needed to run ASW with Crystal Ball:

After ASW and Crystal Ball are installed, confirm that


both are installed correctly and are loading when
Excel starts. You should see both ASW and Crystal
1 Install Both Add-ins Ball custom menu options as part of Excel.
2 Setup ASW Workbook In Excel, enable ASW and link to the Aspen
Inputs & Output table(s) Simulation that you are interesting in using. Copy the
relevant input and output simulation variables into
the ASW Variable Organizer. After that, create tables
in the workbook containing those variables.
3 Setup Crystal Ball In Crystal Ball, you “define assumptions” by selecting
“Assumptions” (inputs) an input distribution type (e.g. Normal distribution
with a mean 25 and a sigma of 3) and associating
that distribution with a cell in Excel. For each of the
input values that you want to vary in your Monte
Carlo simulation, you should define a Crystal Ball
Input distribution and associate that distribution with
the corresponding ASW table cell that contains that
value.
4 Setup Crystal Ball In Crystal Ball, you “define forecasts” by a forecast
“Forecasts” (outputs) name and selecting the cell in Excel which will hold
its value. For each of the ASW simulation output
values that you are interested in tracking, you should
create a Crystal Ball Forecast and set the associate
Excel cell to the ASW table cell which contains the
output value.
5 Setup ASW Run Trigger When Crystal Ball performs a simulation, it does the
following during each trial run:
• Selects input values for each input
(“Assumption”) that you have setup
• Sets the newly selected input values into their
corresponding cells in Excel
• Forces Excel to recalculate all cells
(unfortunately, this does not also automatically
run the ASW simulation)
• Retrieves output values (“Forecasts”) from
corresponding Excel cells

Crystal Ball allows you to run a custom VBA macro during each Monte Carlo
simulation trial. This needs to be setup to force Aspen to do a simulation run
during each trial.
In order to set this up, you need to add a VBA macro to the workbook that
meets the following Crystal Ball requirements:

1 Name The macro must be named CBAfterRecalc

2 Arguments The macro must take exactly one argument and its
type must be ‘long’. The macro returns no value (i.e. it
is declared as a ‘sub’, not a ‘function’)

108 Section 2: Working with Specific Simulation Platforms


3 Location The macro must be in the same workbook as the
simulation and must be in a VBA model associated
with any of the worksheets or with the workbook. It
can NOT be placed in an added VBA module in the
workbook.

The macro only needs to contain one line of code. It needs to call the ASW
function to force a synchronous solve of the current simulation. The line of
code should be “ASW_SyncRun”.

The last step before running the Crystal Ball simulation


is to make sure that the ASW simulation is setup and
activated. It should be setup such that if you click the
4 Run Simulation ASW run button then the ASW simulation will solver.

Now run the Crystal Ball simulation. You should notice that the Aspen
Simulation runs once during each Crystal Ball trial. New values should be
transferred to the ASW output values table each time.
In order to test your setup, you can run a short Crystal Ball simulation (e.g. 4
or 5 trials) and confirm ASW is calculating and retrieving new results values
for each new set of input values.

Troubleshooting Tips

1 If the Crystal Ball Add-in doesn’t startup with Excel, then you should open
the Crystal Ball Application Manager and check ON the option to startup
Crystal Ball with Excel. If that still doesn’t work then you should try only
opening Excel indirectly via the Crystal Ball shortcut in the Crystal Ball
Program group (from the Windows Start button).
2 Sometimes opening an existing Excel / Crystal Ball / ASW workbook by
double clicking on it causes the Crystal Ball Add-in to not load in Excel. If
this happens, then try opening Excel via the Crystal Ball application
shortcut (e.g. Start->Programs->Crystal Ball->Crystal Ball). Once Excel
is open and you have confirmed that the Crystal Ball Add-in has loaded,
you can then open the workbook via the standard File->open Excel menu
option.
3 If the ASW Simulation isn’t solving then look at the following:
o Is the macro named correctly? The correct name must be “sub
CBAfterRecalc(aTrial as long)…”
o Is the macro in the same workbook as your simulation?
o Is the macro in a worksheet or the workbook VBA module? If
you added a new VBA code module to the VBA project of your
workbook and then added the code to that module then it won’t
work. You must add the macro code only to one of the existing
worksheet modules or the workbook module.

Section 2: Working with Specific Simulation Platforms 109


Using ASW within Aspen Plus
This section covers details pertaining to Aspen Plus, in particular it deals with
the development of Aspen Simulation Workbook interfaces for equation-
oriented (EO) simulation cases.

EO and SM Variables and Synchronization


Most Aspen Plus cases can be solved using a sequential-modular (SM)
strategy or an equation-oriented (EO) strategy. The sequential-modular
method has the advantage of being robust; the SM models use several
techniques to initialize and solve models even when good initial values are
unavailable. Equation-oriented models tend to solve much faster than SM
models, but they require reasonable initial guesses to converge reliably. The
design of Aspen Plus leverages the strengths of both methods; EO models can
be automatically initialized from a complete or partial SM solution.
The SM and EO representations of the problem are stored in two separate
sets of variables solved by two separate computational processes. Most
sequential-modular variables are exposed through the forms in the Aspen
User Interface forms (some intermediate and/or results variables are stored
internally and are only available by using the Aspen Variable Browser). These
variables are used to initialize corresponding EO variables the first time an EO
simulation is run, or after an EO simulation is reinitialized. This process is
called synchronization.

110 Section 2: Working with Specific Simulation Platforms


The initial values of the EO variables may also be specified using the EO
Configuration, EO Input forms. The EO Input forms are located at three levels
in the Data Browser menu tree:
• Within the individual block folders EO Configuration folder
• Within the hierarchy-level EO Configuration folder
• Within the top-level EO Configuration folder
• These forms provide a mechanism that allows Aspen Simulation Workbook
access to specified EO variables.
• After the simulation is solved using the EO strategy, a second
synchronization step occurs to copy EO results to SM results in order to
update the results variables shown in the Aspen Plus User Interface forms.

Developing Interfaces to EO Models


The dual SM/EO nature of Aspen Plus puts some constraints into the model
interface development process. When developing an Aspen Simulation
Workbook interface to an EO model, the Model Author must first identify
which variables are to be treated as input specifications. These specifications
variables must be copied from the EO Variable forms to the EO Input forms in
Aspen Plus. The variables can be copied from the EO Input forms to the
Organizer using the standard copy/paste mechanism described previously in
this guide. This technique can also be used to allow the model user to enter
initial values for other types of EO variables (Calculated, Measured,
Parameterized, Reconciled, or Independent variables).
To provide access to EO specifications (constant or independent variables) or
to allow the user to provide initial values for other types of EO variables:
Use the top-level, hierarchy-level, or block-level EO Inputs form to list these
variables. Variables can be added to EO Inputs using the browse button ( )
on the EO Inputs form Variable or Alias field or by using copy/paste from the
EO Variables form. This is described in detail in the Aspen Plus Getting
Started Using Equation Oriented Modeling documentation.

Tip – sort by Specification to find


variables quickly

(1) Select variables of interest on the EO


Configuration / EO Variables form
(2) Use CTRL+C to copy to buffer

Section 2: Working with Specific Simulation Platforms 111


Select the variables of interest by highlighting their values in the Value
column of the EO Inputs form. Use CTRL+C to copy the variables to the
clipboard. The lower and upper bounds for Optimized, Reconciled,
Independent, and Parameterized variables can be copied to Aspen Simulation
Workbook by selecting the appropriate fields in the EO Inputs form and using
CTRL+C to copy to the clipboard.

(3) Open EO Input form, go to Variable or alias field


(4) Use CTRL+V to paste

(5) Select cells in Value and/or LB, UB fields and


use CTRL+C to copy to clipboard
(6) Go to OSE Organizer and paste ( )

Return to Excel, open the Organizer to the Model Variables view, and click the
Paste Variables button, , to bring the variables into the Organizer. From
this point, you can make tables using the standard features described in
Chapter 2.

Tip: Variables copied from the top-level EO Configuration form are grouped
under the “EO Configuration” object in the Organizer. Use the block-level EO
Input form to force Aspen Simulation Workbook to group EO Variables in the
block object. The variable values show up as variable IVVALUE in the
Organizer.

Objective Function Variables


All of the variables in the EO Configuration Objective Setup forms are
accessible through Aspen Simulation Workbook. The Enabled checkbox shows
up as a YES/NO variable in the Organizer. The Cost variables show up as
specified variables. Use the normal copy/paste mechanism to copy these
fields from the Objective Setup form to the clipboard. These variables can be
exposed in an ASW Table to allow the model end user to change or specify
raw material costs and other parameters which influence the optimization
objective function, or to specify plant data for reconciliation runs.

112 Section 2: Working with Specific Simulation Platforms


Accessing Spec-Groups
Aspen EO Models allow the user to define any number of variable specification
groups (or Spec-Groups). The model end-user can activate or deactivate
Spec-Groups to change the nature of the problem being solved. For example,
the user could switch the operating mode of a distillation column to allow
fixed reflux ratio or fixed overhead composition.
In Aspen Plus, the Spec-Groups are activated and deactivated from the EO
Configuration Spec-Groups forms located at the top-, hierarchy-, and block-
levels in the Aspen Plus Data Browser tree, as shown below).
To enable this workflow in Aspen Simulation Workbook, select all the rows in
the Spec-Groups form, use CTRL+C to copy to the clipboard, and paste into
the Organizer (Model Variables view). The variables show up as YES/NO
variables in the Organizer (the Object Name is “Spec-Groups”, Object ID1 will
be set to the Spec-Group ID, the variable name is “Enabled”).

Section 2: Working with Specific Simulation Platforms 113


Accessing Connections
The enabled property of EO variable connections can also be copied into
Aspen Simulation Workbook. Open the EO Configuration Connection form,
select the rows of interest, and use CTRL+C to copy to the clipboard, and
paste into the Organizer (Model Variables view). This will copy the ENABLED
variable along with several others (BIAS, SCALE, etc). Alternately, navigate
through the ASW Variable Browser to the Connection node as shown below.

Troubleshooting EO Model Interfaces


The workflow for using Aspen Plus EO models is fairly complex and is
generally well understood only by fairly experienced modeling experts. If the
Model User enters inputs far from the initial conditions, or if the model moves
away from the SM conditions originally used to build the EO model, the model
may fail to converge. Once this occurs, it may be necessary to reinitialize the
model.
Apply these techniques to avoid convergence problems with EO models:
• Do not expose more variables than the end-user really needs
• Set upper and lower bounds on input variables in Aspen Simulation
Workbook
• Test all optimization and reconciliation functions exposed to the model
user
• Ensure all Specified variables in Aspen Simulation Workbook are linked
through the EO Input forms – SM input variables should not be linked
directly to Excel since these can cause the EO model to re-synchronize EO
variables to SM variables
• Echo all model inputs with calculated variables in the interface to allow the
end-user to confirm that the model is using the expected inputs.

114 Section 2: Working with Specific Simulation Platforms


• Note that design specification expressions such as Spec., Target, and
Tolerance within the data browser's SPEC folder, as well as the upper and
lower limits on the Vary folder, are special fields. These fields should not
be copied directly from the Aspen Plus User Interface as they contain
values or FORTRAN expressions: units for these fields are not supported.

Accessing Calculator Blocks and Design


Specifications
When you access a cell in a calculator block you are making a link to a cell
location - not the variable within the cell.
For example, if you make a format change in which the location of variables
in the calculator change, then the ASW reference may now link to a different
variable.

Using ASW within Aspen


Modeler Products
This section covers details pertaining to Aspen Custom Modeler and related
products, including Aspen Chromatography, Aspen Adsorption, and Aspen
Plus Dynamics. In this section, we use the term Aspen Modeler product to
refer to this family of products generically.

Selecting and Copying Variables from Grids


Variables may be copied from any grid-style form in any Aspen Modeler
product. To select variables from these forms, click the variable names in the
left-hand column of the table. You can use the shift key to select a range of
names or use the CTRL key to select multiple variables in different ranges.
When the variables are selected properly, the entire row of the table will be
highlighted, as shown below.

Next, right-click the mouse and select Copy from the pop-up menu
(alternately, use CTRL+C to copy the variables).

Section 2: Working with Specific Simulation Platforms 115


Return to Excel, Open the ASW Organizer, select the Model Variables view,
and click the paste button, , to add these variables to Aspen Simulation
Workbook

Warning: If you select cells from any of the columns on the right, such as
Spec, Value, etc, the paste buffer will contain only the data in the cells; it will
not contain the variable links required by Aspen Simulation Workbook. Thus,
you will not be able to paste the variables into the ASW Organizer.

Warning: You cannot copy variables directly from User-Defined Visual Basic
forms in ACM or from any of the graphical forms in Aspen Plus Dynamics or in
the other Aspen Modeler products. To copy variables from these applications,
open one of the grid forms (all models include the All Variables grid) or use
the Aspen Modeler Variable Finder form to select and copy the variables (see
next section). Alternately, find the variables using the Variable Browser or the
Variable Query forms in Aspen Simulation Workbook.

Selecting and Copying Variables Using the


Aspen Modeler Variable Finder
Variables may be copied directly from the Aspen Modeler Variable Finder
form. Open the variable finder from the simulation package using the Variable
Find button, , in the simulator toolbar.
Use the standard options on the Variable Find form to perform a search to
identify a list of variables, as shown below. Select one or more of the results
from the bottom pane of this form by clicking on the items. You can use the
CTRL and Shift keys to select multiple items or ranges of values from this
form.

116 Section 2: Working with Specific Simulation Platforms


After selecting the variables, select Edit, Copy from the simulator drop-down
menus. This adds the variables to the paste buffer.

Return to Excel, Open the ASW Organizer, select the Model Variables view,
and click the paste button, , to add these variables to Aspen Simulation
Workbook

Accessing Solver Options and Run Options


Solver Options and Run Options are stored in special nodes in the simulation
data tree under the Simulation Options node. You can add these variables to
your ASW interface and use them in model variable tables much like any
other type of variable.
To select and copy these variables into ASW, open the Organizer to the Model
Variables view and use the Browse for Variables button, , to open the
variable browser. Select the simulation case, and open the nodes as shown
below. Select the variables of interest, such as SimulationTime and click on
the Add Selected button to add these variables to the ASW Organizer.

Section 2: Working with Specific Simulation Platforms 117


Tip: When using simulation options such as RunMode in your ASW interface it
is good practice to link these model variables to an Excel Combo Box to show
the model user a list of valid options and to prevent invalid input. See Getting
the Most From MS Excel later in this chapter for further details.

Activating and Deactivating Tasks in ASW


Dynamic models usually include one or more Tasks which control the
sequence of events that occur during a dynamic simulation run. You can use
the ASW Variable Browser to access the Active and IsEventDriven attributes
of each task defined in an Aspen Modeler case file. These variables can be
exposed to the model end-users as TRUE/FALSE variables. Further, these
variables can be linked to MS Excel Check-Box controls to create a clean-
looking model interface.
To add Task Attributes to your ASW interface; open the ASW Organizer Model
Variables view and click the Browse for Variables button, , to open the
Variable Browser. Open the appModel and Flowsheet nodes as shown below.
Each Task is identified by name in a flowsheet-level node. Open the Task
node and select the Active or IsEventDriven variable. Click the Add Selected
button to add the selected variable to the organizer. Click Close to return to
the Organizer view.

118 Section 2: Working with Specific Simulation Platforms


The Task variables can be added to Model Variable tables using the standard
ASW Table Wizards described elsewhere in this Guide. These variables are
displayed in Boolean format; e.g. the user must set the Active variable to
“TRUE” to activate the task.
We recommend placing these tables in a hidden worksheet, and using an MS
Excel Check-Box control to set the value of the variable. Place the check box
on the input/output sheets to be viewed by the end user. Link this Check Box
to the value cell of the ASW Variable Table containing the TRUE/FALSE value
of the Task Active variable (see Getting the Most from MS Excel).

Maximizing Performance of Dynamic


Models Running Under ASW
Dynamic models involve much higher levels of interactivity and information
flow compared to steady-state models. Model developers must take steps to
ensure good run-time performance under the ASW environment.
Use the following guidelines to maximize the performance of your models:
• Reduce simulation diagnostic levels before deploying Aspen Modeler
models to the end users. Diagnostic message traffic is a key source of
slow performance and high message levels lead to large file sizes in Excel
since ASW stores the simulation message history in hidden worksheets.
• Increase the simulation communication interval from the default value
(usually 0.01 hours) to a higher value. The ideal communication interval
depends on the characteristic times of the processes being simulated. The
interval needs to be low enough to capture important trends and events,
but it should not be set excessively low.

Section 2: Working with Specific Simulation Platforms 119


• Increase the ASW DynamicUpdateFrequency attribute (Simulation
References form). This parameter controls the frequency at which ASW
updates standard Model Variable tables and Dynamic Profiles tables. This
parameter is a multiple of the simulator communication interval. For
example, if DynamicUpdateFrequency is set to 10, then the ASW tables
will be updated only after ten simulation communication intervals.
Note: The simulation communication interval has a much bigger impact
on overall performance.
• Verify that the simulation model itself is well behaved. Run the model in
isolation to ensure it performs well under a wide range of input conditions.
Check the variable scaling and the form of the equations if you identify
problems. You can also adjust the model convergence parameters to
optimize performance. It is worth a bit of extra work up front to ensure
good performance.

120 Section 2: Working with Specific Simulation Platforms


Section 3 Troubleshooting

This chapter provides information to help users resolve problems which are
preventing Aspen Simulation Workbook from running properly.

Required Software
The table below documents the operating system and MS Office requirements
for Aspen Simulation Workbook V7.1. In addition, ASW V7.1 requires
Microsoft .NET Framework 2.0. (This is standard with Windows XP).

Windows Vista (Business Edition) SP1


Windows Vista (Enterprise Edition) SP1
Operating System
Windows XP SP3 (Professional Edition)
Windows Server 2008
Microsoft Office 2007 SP1 (Vista and Windows
Server 2008 only)
Microsoft Office Compatibility 1 Microsoft Office 2003 SP3 (XP only - not
supported on Vista or Windows Server 2008)

Aspen Simulation Workbook can run files locally on the same desktop, or
remotely over a network using a server. When running files locally, two
products must be installed on your desktop computer: Aspen Simulation
Workbook and the appropriate process simulation software (Aspen HYSYS
and/or Aspen Plus). Additional products, such as Aspen Polymers Plus, may
also be required if the underlying models use these types of layered features.
All of the required software is delivered on the set of aspenONE DVDs.

1
Microsoft Office requirements also apply to Server Side as appropriate.

Section 3 Troubleshooting 121


Managing Multiple Versions of
ASW and Other MS Excel Add-
Ins
You may install more than one version of Aspen Simulation Workbook on a
particular computer, however only one version can be active at any particular
time. This is an inherent limitation of MS Excel (Excel does not support
concurrent add-in versions).
You can use the Aspen Simulation Workbook Add-In manager to activate a
particular version of ASW. Some users prefer to keep ASW inactive when
working with conventional MS Excel worksheets to avoid viewing the ASW
toolbars and to maximize the performance of Excel (ASW does make Excel
open a bit more slowly). The add-in manager can also be used to temporarily
deactivate third-party Excel add-ins which may interfere with Aspen
Simulation Workbook (for example, some versions of the Google Excel Add-In
are known to interfere with ASW for unknown reasons).
To open the ASW Add-in Manager click the Windows Start button, select All
Programs | AspenTech | Aspen Engineering Suite | Aspen Simulation
Workbook 2006 | Aspen Simulation Workbook Add-in Manager. Check
the option boxes to activate an add-in, uncheck the boxes to deactivate the
add-in. Only one version of Aspen Simulation Workbook (formerly Aspen OSE
Workbook) may be activated at a given time. Click OK to finish.

Troubleshooting Guide
Problem 1: After installing ASW, the ASW toolbars do not
appear in Excel and the Aspen menu does not appear in
the Excel menu structure
If only the toolbars do not appear, they may simply not be selected to be
displayed. In Excel, select View | Toolbars and ensure the two Aspen
Simulation Workbook toolbars are selected. If these toolbars are not found in
the list, see the resolution for problem 2, below.

122 Section 3 Troubleshooting


When both the toolbars and Aspen menu are missing, it is usually the result
of the workbook add-in not being registered correctly. This may occur when
Excel was open when ASW was installed. To resolve this problem, log in as a
user in the Administrators group, shut down all instances of Excel, open a
Command Prompt window, and enter this command:
regsvr32 "%CommonProgramFiles%\AspenTech Shared\Aspen Simulation
Workbook 2006\ASWXLAddinLoader.dll"

Problem 2: After installing ASW, the ASW toolbars are


grayed out, and the Aspen menu does not appear in the
Excel menu structure
The toolbars may be disabled by Excel. To check for this problem:
1 Open Excel.
2 Click Help | About Microsoft Excel.
3 Click Disabled Items. If Aspen Simulation Workbook appears in the list,
remove it.
To check for another way the add-in could be disabled:
1 Click Tools | Customize.
2 Click the Commands tab.
3 Under Categories, click Tools.
4 In the Commands list, select COM Add-Ins.
5 Click the Tools menu and drag the COM Add-Ins item to this menu, just
below the Add-Ins command. Then close the Customize dialog box.
6 Run the COM Add-Ins command you just added to the Tools menu.
7 Verify that Aspen Simulation Workbook is in the list. Verify that it is
checked (enabled). And verify that its path is ASWXLAddinLoader.dll in
the Aspen Simulation Workbook installation folder.

Problem 3: When opening Excel, a message appears


indicating that macros are disabled
To resolve this problem:
1 Run Tools | Macros | Security.
2 Either set the security level to Medium or Low, or check Trust all
installed addins. The Medium security level is preferred, because it
leaves the Excel security system in place. In this mode you will be
prompted to allow macros to run when you open a file.

Problem 4: The error message, Compile Error: Invalid


Character may result when using an ASW file created in
another locale
An ASW file created in one locale may contain macro names using local
characters which are invalid in another locale under a different character set.
In addition, when the default control or sheet names are used, Excel will
change these names when the file is moved to a new locale but the names in

Section 3 Troubleshooting 123


macro code which references these controls may not be updated. To resolve
this problem:
1 Right-click each control and select Properties.
2 Change the (Name) property of each control using only Standard English
characters (for example, A-Z, a-z, and/or numerals 1 through 9). Do not
allow default control names to be used because they can be locale-
dependent.
3 Verify that any macros you write are coded in standard English characters.
4 Rename any sheets containing such macros in the same manner. This will
ensure macros which reference the sheet will use the correct name. Any
macro code on other sheets which refers to the renamed sheets may need
to be updated to use the new name.

Problem 5: If Aspen Simulation Workbook v2006 and


v2006.5 are installed on a PC, and one of those versions is
uninstalled, the remaining version will stop working.
In this situation during the uninstall process, a dynamic link library file (i.e.,
CXSInteropCOM.dll) used by both versions of Aspen Simulation Workbook
becomes unregistered.
When this occurs, CXSInteropCOM.dll must be re-registered to enable the
remaining version to function properly.
1 Find the CXSInteropCOM.dll file. (In a typical installation it should be at
the following location: C:\Program Files\Common Files\Aspen Tech
Shared\Aspen CXS 2006.5 directory)
2 Open a command prompt window
(Start\Programs\Accessories\Command Prompt)
3 At the command prompt, type: regsvr32 "<full path to
CXSInteropCOM.dll>" and then hit the Enter Key.
4 In a typical installation, the <full path to CXSInteropCOM.dll> should
be replaced with the actual path to the component file. For example, the
full line will likely be: regsvr32 "C:\Program Files\Common
Files\Aspen Tech Shared\Aspen CXS 2006.5\CXSInteropCOM.dll"
(You need to include the quotation marks.) A message box
confirming that the component has been registered should then be
displayed.

124 Section 3 Troubleshooting


Section 3 Troubleshooting 125
Index
A M
Aspen Plus Suite, 110 Manage Simulations Page Toolbar
Aspen Simulation Workbook for Selections, 11
Aspen Modeler Products, 116 Model Authors, 2
AspenTech support, 3 Model User, 2
AspenTech Support Center, 3 Monitoring the Remote Simulation
Automation Server, 75
Functions, 57, 85 Multiple Cases
Macros, 86 using, 26, 62
B O
Bringing a Simulation Model into Open the Simulation References
ASW, 8 Window, 8
Organizer, 21
C
Navigation Pane, 22
Case Types, 26, 62 Variable Grid, 40
Changing links to a new simulation,
P
12
customer support, 3 Plant Tags, 63
grouping, 67
D
quality mapping, 82
Deleting a simulation which has quality parameters, 84
variables associated with it in retrieving, 63
the Variable Organizer, 12 tables, 85
documentation, 2
R
E
Running Aspen Remote Simulation
e-bulletins, 3 Server on Windows Vista, 74
Embedding Simulation Case Files in
S
MS Excel, 68
Embeding and exporting the Setting a Simulation to be
simulation, 13 Remotely Executed, 13
Exporting and Importing Variable Simulation Cases
Lists, 30 running, 90, 92
help desk, 3 viewing, 94
Visual Basic Automation, 95
I
Simulation Log Files, 94
Installing Aspen Remote Simulation Simulation Runs, 95
Server (ARSS) on Windows support, technical, 3
Vista, 73 T
Tables
L
Enhanced Table Template, 51
Limiting End-User Access to Instant Table Template, 51
Simulation Case Files and Plant Tags, 85
Data, 75 quick tables button, 49

126 Index
Table Wizard, 46 Using ASW with Oracle CrystalBall,
styles in Excel, 54 108
technical support, 3
V
Toolbars, 5
Design Toolbar, 5 Variable
Organizer, 35 Browser, 33
Run Toolbar, 6 Query, 34
Workbook Design, 5
W
Workbook Run, 6
web site, technical support, 3
U
Workflow
Using ASW with Esteco running simulation cases, 90
ModeFrontier, 107 Working with the Manage
Simulations Page, 10

Index 127