Aspen-Simulation Workbook User Guide

(1)

Aspen Simulation

Workbook

(2)

Version Number: V7.1

January 2009

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

(3)

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.

(8)

W

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

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

(10)

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

(11)

As

pen 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

(12)

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

(13)

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

(14)

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

(15)

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.

(16)

Working with the Manage Simulations Page

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

(17)

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.

(18)

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.

(19)

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

(20)

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

(21)

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

(22)

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.

(23)

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.

(24)

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

(25)

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

(26)

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.

(27)

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

(28)

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:

(29)

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.

(30)

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

(31)

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.

(32)

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.

(33)

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.

(34)

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

(35)

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.

(36)

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

(37)

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:

(38)

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.

(39)

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.

(40)

Navigating the Organizer Variable Grid

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

Adding Columns

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

Select colum customization 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.

(41)

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.

(42)

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.

(43)

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

(44)

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:

(45)

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.

(46)

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

(47)

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.

(48)

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.

(49)

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.

Aspen-Simulation Workbook User Guide