AspenSimulationWkbookV7 1 Usr

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

Section 1: Using Aspen Simulation Workbook iii

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

iv Section 1: Using Aspen Simulation Workbook

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

Section 1: Using Aspen Simulation Workbook v

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 1

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.

2 Section 1: Using Aspen Simulation Workbook

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 and Running a Process Model

Tutorials covering basic use of Aspen Plus. A prerequisite for the other Getting Started guides

Aspen Plus Getting Started Modeling Processes with Solids

Tutorials covering the Aspen plus features designed to handle solids

Aspen Plus Getting Started Modeling Processes with Electrolytes

Tutorials covering the Aspen plus features designed to handle electrolytes

Aspen Plus Getting Started Using Equation-Oriented Modeling

Tutorials covering the use of equation-oriented models in Aspen Plus

Aspen Plus Getting Started Customizing Unit Operation Models

Tutorials covering the development of

custom unit operation models in

Aspen Plus

Aspen Plus Getting Started Modeling Petroleum Processes

Tutorials covering the Aspen Plus features designed to handle petroleum

Aspen Plus User Guide Procedures for using Aspen Plus

Aspen Plus Unit Operation Models Reference Manual

Information related to specific unit operation models in Aspen Plus

Aspen Plus System Management Reference Manual

Information about customizing files provided with Aspen Plus


Aspen Plus Documentation

Title Content

APrSystem Physical Property Methods and Models Reference Manual

Information about property methods and property models

APrSystem Physical Property Data Reference Manual

Information about property databanks

Aspen Engineering Suite Installation Manual

Instructions for installing Aspen Plus and 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 Guide

This manual contains information on building and running HYSYS simulations in Dynamic mode. Dynamic theory, tools, dynamic functioning of the unit operations as well as controls theory are covered.

HYSYS OLI Interface Reference Guide

This manual contains information on applying HYSYS OLI 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 Guide

This manual contains all information relating to the available HYSYS Fluid Packages and components. This includes information on the Oil Manager, Hypotheticals, Reactions, as well as a thermodynamics reference section.

Tutorials & Applications Guide

This manual provides a range of step-by-step to advance instructions for building some industry-specific simulation examples.

Upstream Option Guide

This manual contains information on building and applying HYSYS Upstream unit operations.

Multiflash for Windows User Guide

This manual contains information on applying Multiflash GUI in Microsoft Windows.

HYSYS Refining Option Guide

This manual contains information on building and applying 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:


• 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.


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

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

Design Toolbar

Run Toolb

Design and Run Ribbon Bars


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


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


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 ....


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.


Working with the Manage Simulations Page

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


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.




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.



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


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


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).


Organizer Navigation Pane

Navigation Pane Select which task to perform

Organizer Toolbar Shortcuts to perform common tasks

Variable Properties Pane View all properties of selected variable - modify properties

Data Control See number of variables - navigate to a variable

Variable Grid Sort/View /Modify Variable Properties, Select variables for tables, add/delete tables


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.


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.


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).


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


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.


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."


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.


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.


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


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.


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.


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.


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


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



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



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:


type (integer, real, character, etc.), value, and units (where applicable). The full set of variable properties is documented later in this guide.


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.


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.


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.


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 columcustomization buttonSelect 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.


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.


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


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


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.


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:


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.


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.”


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

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.


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.


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.


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 selector, which lists all the variables in the Organizer

Remove selected rows

Insert empty row

Opens a list of properties for sorting the list of variables

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


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.


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.


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.


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.


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.)


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.


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.


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:

Name Displays the name of the substitution 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.


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.)


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.


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.


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


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.


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.


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)


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.


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


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.


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.


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.


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.


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.


Mapping Tag Attributes

Browser allows 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

Uncheck these boxes if needed

This pane shows how each column (Heading) is mapped to tag attributes

Warning symbolindicates required 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.


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.


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.


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 schedule number (an integer), sequence letter (a string - for example "A"), an action to perform

Controls HYSYS schedule sequences.

For example, calling ASWHysysDoSchedulerSequenceAction(1, "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, Attribute)

Returns the given attribute of the referenced model variable.

ASWGetTableVariableAttribute(Range, Attribute)

Returns the given attribute of the variable referenced by the specified Excel range.


Aspen Simulation Workbook Function Arguments Argument Valid Values Description

“” (null string) Use “” to specify name of current active simulation.

Name (text)

Case name Use case name as text without extension.

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.

Attribute (text)

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.

ASWDeactivateActiveSimulation Deactivates the active simulation case.

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.


ASWToggleActiveSimulationActive Toggles the activation status of the active simulation.

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.)

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].

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.


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

2 Then select a macro from the list.

(1) Click on a button or other control

(2) Move the crosshairs to the desired position. Click and drag. Adjust image using the arrows.

(3) Click Cancel


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


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.

Open Excel Sheet Activate ModelEnter Input

Retrieve PlantData

Run Model


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.

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.

Activate or De-activate the Model

Manage the simulation

Simulation Environment

Aspen Plus: Run model

Aspen HYSYS: Activate Solver

Step Solver

Aspen Plus: Stop Model Aspen HYSYS: Stop

Re-initialize Model

Restart Model

Make the Model Visible

View Message Logs

Update Tags

Take a “snapshot”

Run Mode (ACM/AD

Pause Solver


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.


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


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.

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.

View Aspen Simulation Workbook messagesView messages for the active simulation case


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.


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


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


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).


Select linked simulation case

Set “ActivateOnStartup” to

“True” to force automatic case

activation

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.


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.


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-


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).


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.


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.


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:


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.


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.


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}


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.

( )( )( )ValuedConditioneModelValue

UpperLowerTagOffsetTagMultTagValueMAXMINdValueConditione=

+×=⎯→⎯

,,ModelTag

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 .

dValueConditioneTagValue

UpperLowerTagMult

TagOffsetetionedValuModelCondiMAXMINdValueConditione

=

⎟⎟⎠

⎞⎜⎜⎝

⎛⎟⎟⎠

⎞⎜⎜⎝

⎛⎟⎟⎠

⎞⎜⎜⎝

⎛ −=

⎯→⎯

,,

TagModel

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.


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.


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 LL Clamping

Variable UL Clamping

Conditioned Variable Quality

Conditioned Variable Value

FALSE N/A LL Exceeded Value Tag Value < Lower Limit**

TRUE N/A LL Clamped Lower Limit

N/A FALSE UL Exceeded Value Tag Value > Upper Limit** N/A TRUE UL Clamped Upper Limit

LL < Tag Value < UL N/A N/A Good Tag Value

Tag quality is not “Good”

N/A N/A Bad Last valid value

Tag is unavailable or Null

N/A N/A Not Set Last valid 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 Value

Variable LL Clamping

Variable UL Clamping

Conditioned Variable Quality

Conditioned Variable Value and Tag Value

FALSE N/A LL Exceeded Value Value*< Lower Limit**

TRUE N/A LL Clamped Lower Limit

N/A FALSE UL Exceeded Value Value* > Upper 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


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:


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.


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


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.


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='Secret Formulae'!C4*0.01

When the user manipulates the scroll bar, the value in this cell will change.

When the user manipulates the scroll bar, the value in this cell will change.These properties set the lower and upper values associated with the two ends of the scroll bar

When the user manipulates the scroll bar, the value in this cell will change.These properties set the lower and upper values associated with the two ends of the scroll bar

Sets the step change which occurs when the user slides the bar

In this example, the control cannot be linked directly to the reflux ratio because this control operates on whole numbers

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:


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.


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 cell in your sheet ,or type it in the Cell Link box

Cell $N$9 displays which option is valid, the integers refer to the first, second, and third options above. Excel assigns these integer values automatically.

Range N10:O10 contains a simple OSE Table linked to the Aspen Plus variable Sim-Options.Paradigm.This variable has two three possible string values: “SIM” (simulation); “EST” (estimation); and “OPT” (optimization).

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)

Option Buttons

Group Box

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

Cell $N$9 displays which option is valid, the integers refer to the first, second, and third options above. Excel assigns these integer values automatically.

Range N10:O10 contains a simple OSE Table linked to the Aspen Plus variable Sim-Options.Paradigm.This variable has two three possible string values: “SIM” (simulation); “EST” (estimation); and “OPT” (optimization).

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)

Option Buttons


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

Cell $P$20 is set to Boolean “TRUE” if the linked check box is checked, and “FALSE”if it is unchecked

Range $O$21:$P$21 contains an OSE table. Cell P21 is linked to the Value attribute of the Aspen PlusEO Configuration.Spec-Groups.Enabled variable.This variable accepts strings YES or NO as input.

Cell $P$21 contains the formula =IF(P20,”YES”,”NO”) which converts the logical to an appropriate string.

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.


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.


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:

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 intoan appropriate string value used in the simulation model:

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

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

Section 2: Working with Specific Simulation Platforms 107

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.

108 Section 2: Working with Specific Simulation Platforms

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

1 Install Both Add-ins

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 Ball custom menu options as part of Excel.

2 Setup ASW Workbook Inputs & Output table(s)

In Excel, enable ASW and link to the Aspen 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 “Assumptions” (inputs)

In Crystal Ball, you “define assumptions” by selecting 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 “Forecasts” (outputs)

In Crystal Ball, you “define forecasts” by a forecast 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’)


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”.

4 Run Simulation

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 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.


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.


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.

(1) Select variables of interest on the EO Configuration / EO Variables form(2) Use CTRL+C to copy to buffer

Tip – sort by Specification to find variables quickly


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 ( )

(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.


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”).


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.


• 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).


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.


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.


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.


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.


• 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.

Section 3 Troubleshooting 121

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

Windows XP SP3 (Professional Edition) Operating System

Windows Server 2008

Microsoft Office 2007 SP1 (Vista and Windows Server 2008 only)

Microsoft Office Compatibility1 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.

122 Section 3 Troubleshooting

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.


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

124 Section 3 Troubleshooting

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.


126 Index

Index

A

Aspen Plus Suite, 110 Aspen Simulation Workbook for

Aspen Modeler Products, 116 AspenTech support, 3 AspenTech Support Center, 3 Automation

Functions, 57, 85 Macros, 86

B

Bringing a Simulation Model into ASW, 8

C

Case Types, 26, 62 Changing links to a new simulation,

12 customer support, 3

D

Deleting a simulation which has variables associated with it in the Variable Organizer, 12

documentation, 2

E

e-bulletins, 3 Embedding Simulation Case Files in

MS Excel, 68 Embeding and exporting the

simulation, 13 Exporting and Importing Variable

Lists, 30 help desk, 3

I

Installing Aspen Remote Simulation Server (ARSS) on Windows Vista, 73

L

Limiting End-User Access to Simulation Case Files and Data, 75

M

Manage Simulations Page Toolbar Selections, 11

Model Authors, 2 Model User, 2 Monitoring the Remote Simulation

Server, 75 Multiple Cases

using, 26, 62

O

Open the Simulation References Window, 8

Organizer, 21 Navigation Pane, 22 Variable Grid, 40

P

Plant Tags, 63 grouping, 67 quality mapping, 82 quality parameters, 84 retrieving, 63 tables, 85

R

Running Aspen Remote Simulation Server on Windows Vista, 74

S

Setting a Simulation to be Remotely Executed, 13

Simulation Cases running, 90, 92 viewing, 94 Visual Basic Automation, 95

Simulation Log Files, 94 Simulation Runs, 95 support, technical, 3 T Tables

Enhanced Table Template, 51 Instant Table Template, 51 Plant Tags, 85 quick tables button, 49

Index 127

Table Wizard, 46 styles in Excel, 54

technical support, 3 Toolbars, 5

Design Toolbar, 5 Organizer, 35 Run Toolbar, 6 Workbook Design, 5 Workbook Run, 6

U

Using ASW with Esteco ModeFrontier, 107

Using ASW with Oracle CrystalBall, 108

V

Variable Browser, 33 Query, 34

W

web site, technical support, 3 Workflow

running simulation cases, 90 Working with the Manage

Simulations Page, 10

Documents

AspenSimulationWkbookV7 1 Usr