ACM Aspen Modeler Reference

Aspen Custom Modeler 2004.1

Aspen Modeler Reference Guide

Who Should Read this Guide 2

Who Should Read this Guide

This guide contains information on using automation, solver options, physical properties, the Control Design Interface (CDI), Simulation Access eXtensions, online links, and using external nonlinear algebraic solvers.

Contents 3

Contents

INTRODUCING ASPEN CUSTOM MODELER..................................................... 14

1 USING AUTOMATION AND VISUAL BASIC ................................................. 15 Automatically Run Script Events............................................................................... 15 Handling Errors...................................................................................................... 16 Working with Sets .................................................................................................. 17

2 CONTROLLING SIMULATIONS WITH SCRIPTS........................................... 20 Syntax for Scripts .................................................................................................. 21 Examples of Scripts................................................................................................ 22

Example of Setting Up Initial Conditions for a Flash System .................................... 22 Example of Initializing an Array Variable, Changing the Upper Bound of a Variable, and Setting the Run Mode to Dynamic........................................................................ 23

Calling External Applications .................................................................................... 23 Improving the Speed of Visual Basic Scripts............................................................... 24

DisableIncrementalUpdate Command................................................................... 24 EnableIncrementalUpdate Command.................................................................... 25

Passing Inputs to Scripts and Getting Outputs from Scripts .......................................... 26 Automatically Run Event Scripts............................................................................... 27

3 CONTROLLING SIMULATIONS WITH EXTERNAL VISUAL BASIC................. 29 Creating an Instance of an Application Object ............................................................ 30

Example of Creating an Instance of an Application Object ....................................... 30 Creating an Instance of an Application Object for a Specified Product Version ............ 30

Accessing Simulation and Document Objects.............................................................. 31 Example of Accessing Objects ............................................................................. 32

Using a Simulation Variable to Run a Simulation......................................................... 32 Example of Using a Simulation Variable to Run a Simulation.................................... 33

Checking the Simulation ......................................................................................... 33 Saving Changes and Closing the Application............................................................... 33 Example of Using External Visual Basic...................................................................... 33 Running Multiple Simulations ................................................................................... 34

Example of Running Multiple Simulations.............................................................. 34

Contents 4

Using the GetObject Method .................................................................................... 35 Example of Using GetObject ............................................................................... 36

4 AUTOMATION METHODS AND PROPERTIES............................................... 37 List of Properties that Return Objects................................................................... 38 Accessing Items Within the Flowsheet .................................................................. 40 Table of Key Automation Objects......................................................................... 41

Application Object .................................................................................................. 42 Application Properties ........................................................................................ 42 Application Methods .......................................................................................... 46 Application Events............................................................................................. 50

ActiveDocument Object........................................................................................... 51 ActiveDocument Properties................................................................................. 51 ActiveDocument Methods ................................................................................... 53

Form Object .......................................................................................................... 56 VariablesPaths .................................................................................................. 57

Simulation Object .................................................................................................. 57 Simulation Properties......................................................................................... 57 Simulation Methods........................................................................................... 72

Properties Object ................................................................................................... 79 Properties of the Properties Object....................................................................... 79 Properties Methods............................................................................................ 80

ComponentList Object............................................................................................. 81 ComponentList Properties................................................................................... 81

OutputLogger Object .............................................................................................. 84 OutputLogger Properties .................................................................................... 84 OutputLogger Methods....................................................................................... 87

Results Object ....................................................................................................... 88 Results Properties ............................................................................................. 88

Results Methods..................................................................................................... 89 UOM Object........................................................................................................... 95 Block, Stream, Structure and Flowsheet Objects......................................................... 95

Methods Common to Block, Stream, Structure and Flowsheet Objects ...................... 96 Flowsheet-Specific Methods ...............................................................................110 Stream-Specific Methods...................................................................................113

Port Object ..........................................................................................................116 Name and GetPath Methods for Ports ..................................................................116 Testing Whether a Port is Connected...................................................................117 Testing Whether a Port is Connected to Hierarchy Connector or Is Linked.................117

Variable Object .....................................................................................................118

Contents 5

Units of Measurement.......................................................................................118 Working with Set Attributes ...............................................................................119 About the History Method..................................................................................120 History Properties and Methods ..........................................................................121 Exploring Variable Time History..........................................................................124 Other Custom Methods .....................................................................................127 RealVariables Methods ......................................................................................133

Task Object..........................................................................................................134 Active Property ................................................................................................134 LanguageText Property .....................................................................................135

Homotopy Object ..................................................................................................135 Homotopy Properties ........................................................................................135 Homotopy Methods ..........................................................................................136

Optimization Object...............................................................................................137 Optimization Properties.....................................................................................137 Optimization Methods .......................................................................................139

OnLineLinks Object ...............................................................................................143 OnlineLinks Properties ......................................................................................143 OnLineLinks Methods ........................................................................................146

OLL Variable Object...............................................................................................148 OLL Variable Object Properties ...........................................................................148 OLL Variable Object Methods .............................................................................150

CDI Object ...........................................................................................................150 CDI Properties .................................................................................................150 CDI Methods ...................................................................................................153

StructureContainer Object ......................................................................................157 StructureContainer Methods ..............................................................................157

Defining an Estimation Simulation ...........................................................................158 Defining Estimated Variables .............................................................................158 Defining Steady-State Estimation Experiments .....................................................159 Defining Dynamic Estimation Experiments ...........................................................161 Resetting Estimation Experiments.......................................................................163

Accessing Results of Estimation Simulations..............................................................164 Accessing Estimated Variables' Values.................................................................164 Accessing Standard Errors .................................................................................165 Testing for Standard Error Results ......................................................................165 Accessing Individual Correlation Results ..............................................................166 Accessing the Correlation Matrix.........................................................................166 Testing for the Correlation Matrix .......................................................................167

5 SYNCHRONOUS AND ASYNCHRONOUS SIMULATION RUNS ......................169

Contents 6

Using Synchronous Runs........................................................................................169 Synchronous Run Example ................................................................................169

Using Asynchronous Runs ......................................................................................170 Asynchronous Run Example...............................................................................171

6 USING THE ASPEN MODELER TYPE LIBRARIES.........................................173 Referencing a Type Library from a Microsoft Visual Basic Project ..................................173 Using the Object Type Names in Your Code...............................................................173

7 SOLVER PROPERTIES DIALOG BOX............................................................175 Diagnostics Tab ....................................................................................................175 Tearing Tab..........................................................................................................178 Tolerances Tab .....................................................................................................182 Integrator Tab ......................................................................................................187

Migrating from 11.1 Integrators to 12.1 Integrators ..............................................188 Integrator Tab: Explicit Euler .............................................................................190 Integrator Tab:Runge Kutta 4 ............................................................................191 Integrator Tab: ImpEuler (11.1).........................................................................191 Integrator Tab: Implicit Euler.............................................................................192 Integrator Tab: VSIE (11.1)...............................................................................193 Integrator Tab: Gear(11.1)................................................................................196 Integrator Tab: Gear ........................................................................................200 Integrator Solver Options ..................................................................................200 Event Handling ................................................................................................203 Diagnostics .....................................................................................................204

Linear Solver Tab..................................................................................................205 Linear Solver Tab: MA48 ...................................................................................205 Linear Solve Tab: MA38 ....................................................................................207 Linear Solver Tab: MA28 ...................................................................................212

Non-Linear Solver Tab ...........................................................................................212 Non-Linear Solver Tab: General .........................................................................213 Non-Linear Solver Tab: Diagnostics ....................................................................215 Non-Linear Solver Tab: Tolerances .....................................................................216 Non-Linear Solver Tab: Open NLA Solver.............................................................218

Optimizer Tab.......................................................................................................219 Optimizer Tab Reporting Level ...........................................................................219

Homotopy Tab......................................................................................................219 Homotopy Options ...........................................................................................220

Estimator Tab.......................................................................................................221 Estimator Tab: Least Squares ............................................................................221

Contents 7

Estimator Tab: Maximum Log Likelihood..............................................................224 Solvers for Optimization and Estimation ...................................................................224

FEASOPT ........................................................................................................225 Nelder-Mead....................................................................................................227 SRQP .............................................................................................................228 NL2SOL ..........................................................................................................230 Open NLP - reduced space.................................................................................230 Open NLP - full space .......................................................................................230 DMO ..............................................................................................................230

8 USING CALCULATION OPTIONS FOR PROPERTIES PLUS ..........................253 OPSET Option.......................................................................................................254 FREE-WATER Option..............................................................................................254 CHEMISTRY Option................................................................................................254 TRUE-COMP Option ...............................................................................................255 HENRY-COMPS Option ...........................................................................................255 SOLU-WATER Option .............................................................................................256 KBASE Option.......................................................................................................257 MAXIT Option .......................................................................................................257 TOLERANCE Option ...............................................................................................257 RETENTION Option................................................................................................258

9 INTERFACING YOUR OWN PHYSICAL PROPERTIES ..................................259 How the Interface Communicates with Properties Plus ................................................259 Phase specific Variable Types and Property Procedures ...............................................260 Generalized Physical Properties Interface Routines.....................................................261

GPP_SETUP.....................................................................................................262 GPP_INI..........................................................................................................262 GPP_QUERY ....................................................................................................263 GPP_LOAD ......................................................................................................264 GPP_UNLOAD ..................................................................................................265 GPP_END........................................................................................................265 GPP_OPTIONS .................................................................................................265

Entry Point Routines ..............................................................................................266 Example of Procedure Declaration with Analytic Derivatives....................................269 Example of Entry Point Routine that returns Analytic Derivatives.............................269 Example of Procedure Declaration without Analytic Derivatives ...............................272 Example of Entry Point Routine that Does Not Return Analytic Derivatives................272

Linking Property Procedure Types to Subroutines.......................................................274

Contents 8

Property Procedures with Analytic Derivatives ......................................................274 Property Procedures Without Analytic Derivatives .................................................275

Definition of GPPI Entry Points ................................................................................276 pAct_Coeff_Liq ................................................................................................276 pBubt .............................................................................................................277 pCond_Liq.......................................................................................................277 pCond_Vap .....................................................................................................278 pCp_Mol_Liq....................................................................................................278 pCp_Mol_Vap ..................................................................................................279 pCv_Mol_Liq....................................................................................................280 pCv_Mol_Vap ..................................................................................................281 pDens_Mass_Liq ..............................................................................................281 pDens_Mass_Sol ..............................................................................................282 pDens_Mass_Vap .............................................................................................282 pDens_Mol_Liq ................................................................................................283 pDens_Mol_Sol ................................................................................................284 pDens_Mol_Vap ...............................................................................................284 pDewt ............................................................................................................285 pDiffus_Liq......................................................................................................286 pDiffus_Vap ....................................................................................................286 pEnth_Mol.......................................................................................................287 pEnth_Mol_Liq .................................................................................................287 pEnth_Mol_Sol.................................................................................................288 pEnth_Mol_Vap................................................................................................289 pEntr_Mol .......................................................................................................289 pEntr_Mol_Liq .................................................................................................290 pEntr_Mol_Sol .................................................................................................291 pEntr_Mol_Vap ................................................................................................291 pFlash ............................................................................................................292 pFlashPH ........................................................................................................293 pFlashPV.........................................................................................................293 pFlashTH ........................................................................................................294 pFlashTV.........................................................................................................295 pFlash3 ..........................................................................................................296 pFlash3PH.......................................................................................................297 pFlash3PV.......................................................................................................298 pFlash3TH.......................................................................................................299 pFlash3TV.......................................................................................................300 pFuga_Liq .......................................................................................................301 pFuga_Sol.......................................................................................................302 pFuga_Vap......................................................................................................302 pGibbs_Mol_IDLGAS.........................................................................................303

Contents 9

pGibbs_Mol_Liq ...............................................................................................303 pGibbs_Mol_Sol ...............................................................................................304 pGibbs_Mol_Vap ..............................................................................................305 pKllValues.......................................................................................................305 pKValues ........................................................................................................306 pMolweight .....................................................................................................307 pMolweights ....................................................................................................307 pSurf_Tens .....................................................................................................308 pSurf_TensY....................................................................................................308 pTrueComp .....................................................................................................309 pTrueCmp2 .....................................................................................................310 pTrueCmpVLS..................................................................................................310 pVap_Pressures ...............................................................................................311 pVisc_Liq ........................................................................................................311 pVisc_Vap.......................................................................................................312

Fortran Programmer's Checklist ..............................................................................312 Installing the Physical Properties Interface................................................................313

10 USING THE CONTROL DESIGN INTERFACE (CDI)....................................314 How CDI Works ....................................................................................................314

About DAE Models ............................................................................................315 About Linear Models .........................................................................................315 How CDI Produces Linearized Models ..................................................................316 Relative Gain Array (RGA) .................................................................................316 Niederlinski Index (NI)......................................................................................317 Morari Resiliency Index (MRI) ............................................................................317 State Transition Matrix (STM) ............................................................................317

Creating CDI Automation Scripts .............................................................................318 Syntax for CDI Automation Scripts .....................................................................319 Example of Creating a CDI Script .......................................................................319

CDI Output Files ...................................................................................................320 ASCII DAT Format............................................................................................320 About the CDI .lis File .......................................................................................321

11 ESTIMATION ..........................................................................................328 Mathematical Statement of Flowsheet Equations........................................................328 About Experimental Data .......................................................................................329 About Parameter Estimation Methods.......................................................................329 About Least Squares Parameter Estimation...............................................................330

About Log Likelihood Estimation .........................................................................330

Contents 10

12 USING THE SIMULATION ACCESS EXTENSIONS .....................................332 Writing a DLL Function for the Simulation Access eXtension ........................................333

Using Variable Accessing Functions .....................................................................333 Using Return Codes ..........................................................................................334 Events in Simulation Access eXtensions...............................................................335

Controlling the Simulation Access eXtensions ............................................................337 Specifying the Simulation Access eXtensions Input and Output Variables..................337 Specifying the DLL and Function Name for the Simulation Access eXtensions ............338

Additional Simulation Access eXtensions Functions.....................................................338 Simulation Access eXtensions Attribute Tokens.....................................................341

13 USING ONLINE LINKS (OLL) ..................................................................343 Installing the Data Server for OLL ...........................................................................343 Specifying the Data Server Configuration for OLL.......................................................344 Specifying the Links between the Simulator and the OLL Data Server ...........................346

Adding New Links for OLL..................................................................................348 Removing OLL Links .........................................................................................349 Changing the Simulation Variable in an OLL Link...................................................349 Browsing for OLL Tags ......................................................................................349

14 USING EXTERNAL SOLVERS....................................................................351

15 EXPORTING FLOWSHEETS TO ASPEN PLUS ............................................352 Software and Hardware Requirements .....................................................................352

16 PREPARING AN ASPEN MODELER FLOWSHEET FOR EXPORT .................353 Preparing a Flowsheet for Export .............................................................................353

Making the Flowsheet Square.............................................................................354 Ensuring the Flowsheet has a Rating Specification.................................................354 Defining Ports for Connecting to Aspen Plus Material Streams.................................355 Ensuring the Flowsheet Solves in Steady-State Mode ............................................357

Preparing a Flowsheet That Uses Custom Models .......................................................358 Adding Custom Feed and Product Blocks..............................................................358 Adapting the Example Models ............................................................................358

Preparing an Aspen Dynamics Flowsheet for Export....................................................359 Exporting an Aspen Modeler Flowsheet.....................................................................361

17 USING AN EXPORTED FLOWSHEET IN ASPEN PLUS................................364 Using an Aspen Modeler Flowsheet in Aspen Plus .......................................................364

Contents 11

Modifying an Exported Flowsheet.............................................................................364 Licensing of Exported Flowsheets ............................................................................365 Distributing the Exported Flowsheet to Aspen Plus Users.............................................365

18 USING MODELS IN OTHER APPLICATIONS .............................................367 Building Custom Unit Operation Models for Aspen Plus and HYSYS ...............................367

Software and Hardware Requirements.................................................................368 Creating a Unit Operation Model for Aspen Plus and HYSYS .........................................368

Creating the Model ...........................................................................................369 Exporting the Model .........................................................................................375 Installing the Model using Windows Explorer ........................................................376

Using an Aspen Modeler Unit Operation Model in Aspen Plus or HYSYS..........................377 Using an Aspen Modeler Model in Aspen Plus........................................................377 Using an Aspen Modeler Model in HYSYS .............................................................377 Configuring an Aspen Modeler Unit Operation Block In Aspen Plus...........................378 Configuring an Aspen Modeler Unit Operation Block In HYSYS.................................379 Licensing Exported Models Running in Aspen Plus .................................................380 Licensing Exported Models Running in HYSYS.......................................................380 Distributing an Exported Model To Aspen Plus Users..............................................380 Distributing an Exported Model To HYSYS Users ...................................................380 Using the MyPipe Model in HYSYS.......................................................................381

19 ASPEN CUSTOM MODELER LANGUAGE FILE ............................................382 Version...........................................................................................................383 Libraries .........................................................................................................383 <Global Definitions> ........................................................................................383 <Type Definitions> ..........................................................................................383 <Plot and History Table Definitions>...................................................................384

Flowsheet ............................................................................................................384 StructureContainer...........................................................................................384 <Blocks, Stream and Connection Statements>.....................................................385 CONSTRAINTS.................................................................................................385 Task <name>..................................................................................................385 ActiveTasks.....................................................................................................386 <Flowsheet Assignments> ................................................................................386 Graphics .........................................................................................................386 HIERARCHY <name>........................................................................................386 Properties .......................................................................................................387 Options...........................................................................................................388 Optimization....................................................................................................393 Estimation.......................................................................................................394

Contents 12

Homotopy .......................................................................................................394 SimulationAccessExtensions ..............................................................................395 Snapshot <name> ...........................................................................................395

GENERAL INFORMATION..............................................................................397 Copyright.............................................................................................................397 Related Documentation..........................................................................................399

TECHNICAL SUPPORT...................................................................................400 Online Technical Support Center .............................................................................400 Phone and E-mail..................................................................................................401

INDEX ..........................................................................................................402

Contents 13

Introducing Aspen Custom Modeler 14

Introducing Aspen Custom Modeler

Aspen Custom Modeler (ACM) is an easy-to-use tool for creating, editing and re-using models of process units. You build simulation applications by combining these models on a graphical flowsheet. Models can use inheritance and hierarchy and can be re-used directly or built into libraries for distribution and use. Dynamic, steady-state, parameter estimation and optimization simulations are solved in an equation-based manner which provides flexibility and power.

ACM uses an object-oriented modeling language, editors for icons and tasks, and Microsoft Visual Basic for scripts. ACM is customizable and has extensive automation features, making it simple to combine with other products such as Microsoft Excel and Visual Basic. This allows you to build complete applications for non-experts to use.

1 Using Automation and Visual Basic 15

1 Using Automation and Visual Basic

You can use Microsoft Visual Basic (VB) and automation to control and define a simulation either from:

• Scripts that use Microsoft® Visual Basic® scripting

• External Microsoft® Visual Basic® applications, such as Microsoft® Visual Basic® 5.0 Control Creation Edition (CCE), Microsoft® Visual Basic® 5.0 or 6.0 Professional or Enterprise editions, or Microsoft® Visual Basic® for Applications (VBA) as supplied with Microsoft® Office applications, such as Microsoft® Excel and Microsoft® Word.

In both cases, you use automation methods and properties to control the simulation.

You can also choose whether control returns to Microsoft® Visual Basic® only when the simulation run finishes, or immediately.

Note: Microsoft and Visual Basic are registered trademarks of Microsoft Corporation.

Automatically Run Script Events When certain events occur in the application an automation script will be run. These scripts should be contained in files located in the installation directory for the application.

By default this is in:

C:\ProgramFiles\AspenTech\Aspen Custom Modeler 12.1\bin

The scripts should be placed in files will specific names so the application can find them.

These are:

• OnNewDocumentScript.vb

• OnPreOpenDocumentScript.vb

• OnPostOpenDocumentScript.vb


• OnSaveDocumentScript.vb

• OnCloseDocumentScript.vb

The scripts in these files will be called when opening closing and saving documents.

New

When you start up the application or select to create a New document in the GUI the script files OnNewDocumentScript.vb and OnPostOpenDocumentScript.vb are called.

Open

When you open up the application by double clicking on an .acmf file or select to open a document in the GUI the script files OnNewDocumentScript.vb, OnPreOpenDocumentScript.vb and OnPostOpenDocumentScript.vb are called.

Save As

The script OnSaveDocumentScript.vb is called when you select Save As in the GUI.

Close

The script OnCloseDocumentScript.vb is called when a document is closed either by leaving the application or by opening or creating a different document.

Handling Errors When an ACM method or property fails a Visual Basic error is raised. This can be handled using the Visual Basic �On Error� command. If no On Error command is given the Visual Basic program will terminate. When an error is raised the Visual Basic Err object can be used to obtain information about the error. Note that for scripts in ACM the statement On Error Resume Next must be used, On Error Goto cannot be used.

Example in Visual Basic

Sub RunTestSimulation()

Dim ACMobj As AspenModelerSimulation ' Available in the ACM type library

Set ACMobj = GetObject("d:\test.acmf")

ACMobj.Application.Visible = True

On Error Resume Next

ACMobj.Run (True)

If Err.Number <> 0 Then

' got an error

MsgBox "Error " & Err.Number & " : " & Err.Description


Err.Clear

End If

On Error GoTo errorhandler

If ACMobj.Successful Then

MsgBox "last run was successful."

Else

MsgBox "last run was not successful."

End If

Exit Sub

errorhandler:

MsgBox "default error handler."

End Sub

In this example if an error is raised by the Run command On Error Resume Next will cause the next statement to be executed. An Err.Number value other than 0 indicates an error has occurred. Note that an On Error GoTo statement could have been used to handle the error in the Run command.

Refer to the Visual Basic help for more information.

Working with Sets ACM gives access to some data via sets of objects.

Examples of these are:

• Components in a component list are accessed as a set of strings

• Sets of variables can be accessed

• The value of some variables can be sets of strings, reals or integers

Sets can be retrieved via methods on their owning objects:

e.g.:

Set MyVars = B1.FindMatchingVariables(�~�)

will retrieve all variable objects from the block B1.

Set MyComponentList =

Application.Simulation.Properties. ComponentList("CompList").Components

retrieves the components in a component set.

Alternatively new sets can be created in a script using the following methods:

• NewVariableSet


• NewStringSet

• NewIntegerSet

e.g.:

Set MyVarSet = B1.NewVariableSet

This creates an empty variable set.

Once a set has been obtained the following methods can be used to manipulate the contents:

AddValues item1, item2,�

This can be used to add values to the set. The arguments can be single values or sets of the correct type:

e.g.:

MyVarSet.AddValues Varset1, Varset2, B1.Temp

This adds the contents of the set Varset1 and Varset2 as well as the variable B1.Temp to the set MyVarSet.

RemoveValues item1, item2,�

This can be used to remove values from the set. Not available for variable sets:

e.g.:

MyComponentList.RemoveValues �H2O�

Note that manipulating the set will have no affect until the set is used:

e.g.:

Set Application.Simulation.Properties. ComponentList("CompList").Components =

MyComponentList

This replaces the existing component list with the contents of the set MyComponentList:

e.g. UpdateVariables MyVarSet

This updates values in the ACM client for all variable in the set. It improves performance when values are accessed for these variables.

Elements of a set can be accessed using the For Each Syntax

e.g.:

For Each Var in MyVarSet

Application.msg Var.Name


Next

This prints out the names of each variable in the set.

Refer also to Working with Set Attributes and ComponentList.Components.

2 Controlling Simulations with Scripts 20

2 Controlling Simulations with Scripts

A script is a set of instructions written in Microsoft® Visual Basic® Scripting Edition (VBScript) that automates the setup and control of a simulation. You can write your own scripts or generate them from the Status window or from Variable Find.

You can use scripts to:

• Automate and record actions on models and flowsheets, which enables you to automate specification and initialization.

• Control sequences of simulation runs using automation methods and properties. For example, you can use scripts to run scripts from within scripts, apply snapshots to a simulation, set the run mode, launch forms, and set solver options for a simulation.

• Define estimation simulations.

• Define units of measurement sets and conversions.

• Obtain inputs and outputs.

• Call external applications.

Microsoft® Visual Basic® Scripting Edition (VBScript) is supplied automatically with your installation.

Important Note: Do not confuse scripts with tasks. Scripts are used to set up a simulation. In contrast, tasks are used to define a sequence of actions that take place during a dynamic simulation. For more information on tasks, see the Modeling Language Reference, Defining Tasks.

From scripts, the top level of the object path can be one of:

• Application

• Flowsheet

• ActiveDocument

Note the following Microsoft® Visual Basic® conventions:

Convention Meaning

' Comment marker

_ Continuation marker


This chapter includes:

• Syntax for variable assignments in scripts.

• Examples of variable assignments in scripts.

• Tips on making faster scripts.

• Information on passing inputs to scripts and getting outputs from scripts.

Note: If you receive an unhandled exception message while a script is running, you may need to quit your Aspen Modeler product and start it again. This is because the Microsoft® Visual Basic® engine can become unusable after an unhandled exception. The only way to resolve this situation is to restart the Visual Basic engine by restarting the Aspen Technology user interface.

Examples of Object Paths

Application for run time settings:

Application.Simulation.RunMode = "Dynamic"

Flowsheet for the variable assignment:

Flowsheet.Tank1.Flowin.Flow.Spec = "Fixed"

In the following example, Application.Simulation is used to set the run mode:

Application.Simulation.RunMode = "Initialization"

The preceding example is equivalent to:

ActiveDocument.RunMode = "Initialization"

The path ActiveDocument is equivalent to the path Application.Simulation.

About Microsoft Visual Basic Scripting Edition

For basic applications such as automating specification for defining parameter and variable properties, that is, spec, value, upper and lower limits, you do not need to learn VBScript. However, learning VBScript gives you access to powerful features such as calling scripts within scripts and launching an external Windows application such as a Microsoft® Excel spreadsheet or Microsoft® Visual Basic® application.

You can obtain documentation on the more powerful features of VBScript from the Microsoft® web site.

Note: Microsoft®, and Visual Basic® are registered trademarks of Microsoft Corporation.

Syntax for Scripts The syntax for variable assignments in a flowsheet is:


BlockName.VariableName.Property = value

The syntax for variable assignments in a model is:

VariableName.Property = value

For properties whose values are strings, place the strings within quote marks.

Examples of Scripts The following two example scripts show how to:

• Set up initial conditions for a flash system.

• Initialize an array variable, change the upper bound of a variable, and set run mode to dynamic.

Example of Setting Up Initial Conditions for a Flash System The following script shows how to set up the initial conditions for a flash system:

'Initial conditions - state variables initialized

FLASH1.E.Spec="Initial"

FLASH1.E.Value=0.964186

FLASH1.Mc("BENZENE").Spec="Initial"

FLASH1.Mc("BENZENE").Value=8.41653

FLASH1.Mc("OXYLENE").Spec="Initial"

FLASH1.Mc("OXYLENE").Value=12.2439

FLASH2.E.Spec="Initial"

FLASH2.E.Value=0.231459

FLASH2.Mc("BENZENE").Spec="Initial"

FLASH2.Mc("BENZENE").Value=1.31776

FLASH2.Mc("OXYLENE").Spec="Initial"

FLASH2.Mc("OXYLENE").Value=6.06461

'Variables fixed and free to provide consistent specifications

FLASH1.M.Spec="Free"

FLASH1.M.Value=30.

FLASH1.P_drop.Spec="Free"

FLASH1.P_drop.Value=0.1

FLASH2.M.Spec="Free"

FLASH2.M.Value=10.


FLASH2.P_drop.Spec="Free"

FLASH2.P_drop.Value=0.1

Example of Initializing an Array Variable, Changing the Upper Bound of a Variable, and Setting the Run Mode to Dynamic The following example shows how to initialize an array variable, change the upper bound of a variable, and set run mode to dynamic:


Bed.TempIn.Upper = 800

dim i

for i = 1 to 20

Bed.Tg(I).spec = "initial"

Bed.Tg(I).value = 600

Bed.Ts(I).spec = "initial"

Bed.Ts(I).value = 600

next

Note: To define the run mode, you could use ActiveDocument instead of Application.Simulation.

Calling External Applications You can call external applications from scripts.

Examples of Calling an External Application

The following example shows opening a Microsoft® Excel spreadsheet from a script:

Dim xlObj

Set xlObj = GetObject("\directory\sheet.xls", "Excel.Sheet")

xlObj.Application.Visible = True

' Makes windows visible

xlObj.Application.Windows("sheet.xls").Activate

' Makes the new worksheet visible


Improving the Speed of Visual Basic Scripts When you run a Microsoft® Visual Basic® script within the user interface, each statement is acted upon on a line-by-line basis. This means that any structural changes you make in a script that alters a flowsheet block parameter causes the simulation to be re-evaluated each time a statement is made.

Quite often for a large flowsheet, you need to alter block parameters for several independent blocks. Each time you make a change to one block, the whole simulation is re-evaluated.

To make scripts in which you change several parameters run faster, you need to change the way script statements are interpreted. You can force the script to batch process structural changes so that all the changes to the simulation equations are made at one time.

The following commands enable you to affect the way scripts are interpreted:

• DisableIncrementalUpdate

• EnableIncrementalUpdate

DisableIncrementalUpdate and EnableIncrementalUpdate operate on a lock counter which is incremented by DisableIncrementalUpdate and decremented by EnableIncrementalUpdate. This allows scripts called within scripts to use Disable or EnableIncrementalUpdate without overriding the lock on incremental updating that may have been established in the calling script.

For scripts that run The lock count is controlled by

Within an Aspen Modeler product

Automatically checking that the lock count is restored to its initial condition, when the script completes.

From external Visual Basic Ensuring that the number of calls to DisableIncrementalUpdate are matched by an equal number of calls to EnableIncrementalUpdate.

DisableIncrementalUpdate Command The incremental update command is enabled by default, which means that each line of a script in acted upon as it is interpreted. By entering the automation method command DisableIncrementalUpdate, you change the way script commands are acted upon.

After you enter the command DisableIncrementalUpdate, all parameter changes are stored and applied either when the script finishes, or when the command EnableIncrementalUpdate is encountered. In general, it is better to pair DisableIncrementalUpdate and EnableIncrementalUpdate commands, rather than relying on the end of a script to re-enable the default setting.


Example of DisableIncrementalUpdate

The following script uses DisableIncrementalUpdate to store all the changes made to all the blocks on the flowsheet until the EnableIncrementalUpdate command:

'Change the specifications of a series of columns

DisableIncrementalUpdate

C1.Ntrays = 21

C2.Ntrays = 48

C3.Ntrays = 16

C4.Ntrays = 17

EnableIncrementalUpdate

'End of script

If you do not disable incremental updates, the simulation equations are re-evaluated four times. When you use DisableIncrementalUpdate, the equations are re-evaluated once.

EnableIncrementalUpdate Command The EnableIncrementalUpdate command is used to re-enable the default action of the scripts, where each line is acted upon as it is interpreted. Usually the EnableIncrementalUpdate command is made after the DisableIncrementalUpdate command and several structural statements.

You can use EnableIncrementalUpdate to force the changes to be made since the previous DisableIncrementalUpdate command during a script.

Example of EnableIncrementalUpdate

The following example script uses EnableIncrementalUpdate to force the changes made in the previous line to be acted upon at that point. Thereafter, all lines are acted on as they are interpreted:

'Change the specifications of a series of columns

'Then initialize the simulation


C1.Ntrays = 21

C2.Ntrays = 48

C3.Ntrays = 16

C4.Ntrays = 17


FeedStream.F = 10.0

Application.Simulation.RunMode = "Steady State"

Application.Simulation.Run(True)



Application.Simulation.Run(False)

' End of script

If you do not enable incremental updates, both runs do not use the updated values of the number of trays in the column. This is because, if you do not use the EnableIncrementalUpdate command, the changes to the structure of the simulation are made when the script finishes, which is after the two simulation runs made by the script. In this example, if you do not use EnableIncrementalUpdate, you do not converge the simulation with the specification you have defined.

Passing Inputs to Scripts and Getting Outputs from Scripts If a script is invoked with arguments, these will be exposed in the called script as a collection of variants called Inputs. This is a conventional collection supporting a Count & item and iteration using the For Each syntax.

For example, a script called "CallableScript" is written, with the following text:

application.msg " Input count = " & Inputs.count

for each arg in inputs

application.msg " " & arg

next

It can then be passed arguments like a conventional method, for example:

call CallableScript("arg1", 10.5)

This would print the following in the Simulation Messages window:

Input count = 2

arg1

10.5

A script can also return outputs, using a second variant collection called Outputs. This is the same type of object as the inputs collection. When a script is invoked, the Outputs collection is initially empty. To size it, you assign a value to the Count property.

The following script, called SumInputs, sums its inputs and returns the result in the output collection:

outputs.count=1

outputs(1) = 0

for each arg in Inputs

outputs(1) = outputs(1) + arg


next

The outputs collection will be returned as the result of the script, so an invocation of the script looks like this:

set results = SumInputs(1,2,3.5)

application.msg "Sum of inputs = " & results(1)

Automatically Run Event Scripts When certain events occur in the application an automation script will be run. These scripts should be contained in files located in the installation folder for the application.

By default this is in:

C:\ProgramFiles\AspenTech\AMSystem 12.1\bin

The scripts should be placed in files will specific names so the application can find them.

These are:

• OnNewDocumentScript.vb

• OnPreOpenDocumentScript.vb

• OnPostOpenDocumentScript.vb

• OnSaveDocumentScript.vb

• OnCloseDocumentScript.vb

The scripts in these files will be called when opening closing and saving documents.

New

When you start up the application or select to create a New document in the GUI the script files OnNewDocumentScript.vb and OnPostOpenDocumentScript.vb are called.

Open

When you open up the application by double clicking on an .acmf file or select to open a document in the GUI the script files OnNewDocumentScript.vb, OnPreOpenDocumentScript.vb and OnPostOpenDocumentScript.vb are called.

In addition the Open Document event will run a script called OnLoadSimulation located under the Flowsheet in the simulation being loaded. This allows you to make changes that are specific to the simulation being loaded e.g. simulation specific units of measurements and screen layouts. This script is run after the OnPostOpenDocumentScript.vb script.

Save As

The script OnSaveDocumentScript.vb is called when you select Save As in the GUI.

Close


The script OnCloseDocumentScript.vb is called when a document is closed either by leaving the application or by opening or creating a different document.

3 Controlling Simulations with External Visual Basic 29

3 Controlling Simulations with External Visual Basic

You need to define a variable to refer to the simulation document, that is, the file created by your Aspen Modeler product, (for example, Aspen Custom Modeler® or Aspen Dynamics�), so that you can access the automation methods from your external Microsoft® Visual Basic®.

Aspen Modeler type libraries are available for use in external Microsoft® Visual Basic® applications. Using these type libraries will improve the efficiency of your code and provide helpful prompts, giving available method and property names. For more information see Chapter 6.

This chapter describes how to:

• Create an instance of the application.

• Obtain access to objects.

• Use a simulation variable to run a simulation.

• Check whether the simulation completed successfully.

• Save and exit the application.

• Run multiple simulations.

• Use the GetObject method.

Note: Previous versions of the Automation documentation advocated the use of the GetObject() routine to obtain access to simulation documents. Although GetObject() is still supported, the use of the Application methods described in this section is now the preferred approach, in that the methods provide additional functionality and are more compliant with recent developments in.

Automation architecture. Consequently you should use GetObject only for accessing a simulation that is already running, as described in the GetObject section.


Creating an Instance of an Application Object To create an instance of an application object, use the following syntax:

Dim AppName as Object Set AppName = CreateObject("Application") AppName.Visible=Value

AppName Name you give to the object variable, for example,

ACMApp, ADApp, ADSApp, ChmApp.

Application Can be one of:

ACM Application Aspen Custom Modeler AD Application Aspen Dynamics ADS Application Aspen Adsim Chm Application Aspen Chromatography

AppName.Visible

Determines whether or not the application is visible

Value Can be one of:

FALSE Object is invisible (default) TRUE Object is visible

Example of Creating an Instance of an Application Object The following example defines the necessary Aspen Custom Modeler® objects, and makes it visible:

Dim ACMApp As Object

Dim ACMDocument As Object

Dim ACMSimulation As Object

Set ACMApp = CreateObject("ACM Application")

ACMApp.Visible = True

Creating an Instance of an Application Object for a Specified Product Version When more than one version of the product is installed on your machine simultaneously, you may want to specify which version is invoked under automation.

The general syntax for this is:

Dim AppName as Object Set AppName = CreateObject("Application") AppName.Visible=Value

"Application" The product name and a version number. The version


number consists of the major version and minor version numbers run together to make a four digit number.

Example of Creating an Instance of an Application Object for a Specified Product Version

The following is an example of creating an instance of an application object for a specified product version:

' launch version 12.1 of ACM

Set AppName = CreateObject("ACM Application 1210")

Note: Product versions 10.0 and earlier cannot be started using this syntax.

Accessing Simulation and Document Objects To handle simulation documents, the application object can use the following methods:

• NewDocument

• OpenDocument

• CloseDocument

• SaveDocument

• SaveDocumentAs

An application can have zero or one documents open at any given time (initially zero) and each document corresponds to one simulation flowsheet.

After you obtain an application variable, you would typically open an existing simulation document using the OpenDocument method:

Dim ATDocument as Object Set ATDocument=AppName.OpenDocument("path")

path Full path name and file name of the existing simulation

document you want to open, for example: d:\acm_simulations\tower.acmf

After a simulation document has been opened, you can ask the application for access to the simulation it represents:

Dim ATSimulation as Object Set ATSimulation=AppName.Simulation

Important Note: You ask the application, not the document, for the simulation. Because there is never more than a single simulation open at once within a single executable session, the


application knows which document contains the simulation.

The simulation object has properties and methods pertaining to the simulation, including:

• RunMode

• Time

• Run

• Step

• Reset

• Restart

Example of Accessing Objects The following example shows how to obtain access to objects by opening an Aspen Custom Modeler® simulation document, specifying the path to the document, and getting a variable which points to the simulation:

Set ACMDocument = ACMApp.OpenDocument("d:\acm simulations\tower.acmf")

Set ACMSimulation = ACMApp.Simulation

Using a Simulation Variable to Run a Simulation You can use the simulation variable to run the simulation:

ATSimulation.RunMode="Mode" ATSimulation.Run(value)

value Can be one of:

True Control returns to Visual Basic after the simulation has completed False Control returns to Visual Basic immediately

For more information, see Chapter 5.

Mode Can be one of:

Steady State Optimization Estimation Dynamic Initialization

As is normal in Visual Basic, you do not need to explicitly create a variable for the simulation, and could instead have written:

AppName.Simulation.RunMode="Mode" AppName.Simulation.Run(value)


Example of Using a Simulation Variable to Run a Simulation The following Aspen Custom Modeler® example sets the run mode to steady state, runs the simulation and waits for it to complete:

ACMSimulation.RunMode = "Steady State"

ACMSimulation.Run (True)

Checking the Simulation After the simulation has completed, you can check whether it completed successfully and take action accordingly:

if ATSimulation.Successful then msgBox "Simulation Complete" else msgBox "Simulation Failed" endif

Saving Changes and Closing the Application After a simulation has completed and you have checked whether it was successful, you can save any changes to disk and close down the application:

AppName.SaveDocument() AppName.quit()

AppName.SaveDocument() Save the changes to disk

AppName.quit() Exit the application

Example of Using External Visual Basic The following example shows the complete code for using external Visual Basic® to load and run an Aspen Custom Modeler® simulation:





' Use "ACM Application" for aspen custom modeler,


' Use "AD Application" for Aspen Dynamics


' Now that we have access to the app we can obtain

' other useful objects. First open a simulation document


' Substitute the path with one that exists on your machine.

' Get a variable which points to the simulation


' Set the run mode to steady state

ACMSimulation.RunMode = "Steady State"

' Run the simulation and wait for it to complete


' Check whether it worked

If ACMSimulation.Successful Then

MsgBox "Simulation Complete"

Else

MsgBox "Simulation Failed"

End If

' Save the changes

' and shut down the ACM application

ACMApp.SaveDocument()

ACMApp.quit

Running Multiple Simulations You can use a single invocation of the Aspen Modeler server to run many different simulations.

Example of Running Multiple Simulations The following code could be used to run six Aspen Custom Modeler® simulations, assuming the folder "d:\acm simulations" contains six simulation files: test1.acmf, test2.acmf, to test6.acmf :

Option Explicit

Public Sub RunSimuls()




Dim nFileNumber As Integer

Dim sFileName As String

nFileNumber = 0

On Error GoTo ErrorHandler



For nFileNumber = 1 To 6

sFileName = "d:\acm simulations\test" & CStr(nFileNumber) & ".acmf"

ACMApp.OpenDocument (sFileName)


' set the run mode to Initialization

ACMSimulation.RunMode = "Initialization"

' and run the simulation, waiting for it to complete


ACMApp.CloseDocument (True) ' save changes

Next nFileNumber


ACMApp.quit

Exit Sub

'

'

ErrorHandler:

' Error handling might normally be more sophisticated than this

MsgBox "Error at simulation " & nFileNumber & " " & Err.Description

Exit Sub

End Sub

Using the GetObject Method Normally, you use the OpenDocument method of the Application automation object to gain access to a simulation in stored file form (for example, an .acmf,.acmd,.dynf or .dynd file).


However, sometimes it is more convenient to use the Visual Basic® GetObject method, for example, when you want to connect to a simulation that is already running. The syntax for defining an object name for an Aspen Modeler product is:

Set MyObject = GetObject("Filename.extension" , "Class")

MyObject An object variable name that you define using a DIM

statement

Filename.extension

Either the name of an existing Aspen Modeler product file or an empty string, in which case the class is Compulsory.

Class Name describing the type of object. Optional if you have included an existing file name, compulsory if you have not included an existing file name

The following classes are available to GetObject:

File extension Class name

.acmf Aspen Custom Modeler Language

.acmd Aspen Custom Modeler Document

.dynf Aspen Dynamics Language

.dynd Aspen Dynamics Document

.ada Aspen Adsim Language

.adb Aspen Adsim Document

.cra Aspen Chromatography Language

.crb Aspen Chromatography Document

.bspf Aspen BatchSep Language

.bspd Aspen BatchSep Document

.auf Aspen Utilities Language

.aud Aspen Utilities Document

.awf Aspen Water Language

.awd Aspen Water Document

Example of Using GetObject The following line of VBA shows an example of running GetObject as a Microsoft® Excel macro:

Set Mysim = GetObject("C:\Program Files\AspenTech\Aspen Custom Modeler 12.1\Examples\5Tank\fivetank.acmf")

Mysim.Application.Visible = True

Mysim.Run True

If Aspen Custom Modeler® is already running the simulation, a link to the running instance will be returned. If it is not already running, Aspen Custom Modeler will be started and the simulation loaded. In either case, the simulation is then run.

4 Automation Methods and Properties 37

4 Automation Methods and Properties

Methods are commands that you can use to control the simulation. Properties contain values that you can read and/or write.

This chapter contains information on automation methods and properties.

The following diagram shows the relationship between the objects and collections within Aspen Modeler products:


List of Properties that Return Objects The following properties all return references to objects: Property Returns

Application The one and only Application object

Application.Simulation The one and only Simulation object

Application.ActiveDocument The one and only ActiveDocument object

Application.Simulation. The one and only Flowsheet object


Flowsheet

Application.Simulation. Flowsheet.Blocks

Collection of blocks within the flowsheet

Application.Simulation. Flowsheet.Streams

Collection of streams within the flowsheet

Application.Simulation. Flowsheet.Resolve

Returns a specified object

Application.Simulation. Flowsheet.Global

Collection of global variables

Application.Simulation.CDI The one and only CDI object

Application.Simulation. Homotopy

Provides access to the Homotopy facility for automation

Application.Simulation. OnLineLinks

Provides access to the OnLine Links facility for automation

Application.Simulation. Options

Provides access to the various run options of the simulation

Application.Simulation. Optimization

Provides access to the optimization facility for automation

Application.Simulation. OutputLogger

Provides access to methods & properties which determine how run-time output is handled

Application.Simulation. Properties

Contains physical properties information

Application.Simulation. Results

Manages snapshots and results

Application.Simulation.UOM Provides the ability to manipulate Unit of Measurement sets

Application.Simulation. Flowsheet <Taskname>

An event-driven task

For a given block, for example, b1, the following are returned:

Property Returns

b1.Blocks Collection of blocks within block b1; equivalent to Application.Simulation.Flowsheet.Blocks("b1").blocks

b1.Streams Collection of streams connected to block b1; equivalent to Application.Simulation.Flowsheet.Streams("b1").streams

b1.Ports Collection of Ports within this block

b1.ControlPorts Collection of ControlPorts within this block

b1.Resolve A specified object

For a given stream, for example, s1, the following are returned:

Property Returns

s1.Blocks Collection of blocks connected to stream s1; equivalent to Application.Simulation.Flowsheet.Blocks

s1.Streams Collection of streams within stream

s1.Ports Collection of Ports within this stream

s1.ControlPorts Collection of ControlPorts within this stream

s1.Resolve A specified object

s1.InputPort A specified object

s1.InputBlockPort A specified object

s1.OutputPort A specified object


s1.OutputBlockPort A specified object

For a given port, for example, p1, the following is returned::

Property Returns

p1.Resolve A specified object

Accessing Items Within the Flowsheet The Resolve method converts a string to a reference to an object.

If the string is constant, you do not need to use it explicitly. For example, in a flowsheet flow containing a block b1, the following all return the same object:

From a script within Aspen Custom Modeler®:

Simulation.Flowsheet.Resolve("b1")

Simulation.Flowsheet.b1

Furthermore, the Flowsheet.blocks collection can be used to return a reference to this object, too:

Simulation.Flowsheet.Blocks.Item("b1")

Lastly, note that the Item keyword is optional in Visual Basic® so this expression is equivalent to:

Simulation.Flowsheet.Blocks("b1")

Using Scope in Scripts

Scripts have scope, so for example, for a script within a block b1, there is no need to specify the full path in a script at the flowsheet level:

ports

is equivalent to:

b1.ports

To refer to this b1.ports collection from a script in another block b2, use the following syntax:

Application.Simulation.Flowsheet.b1.ports

Accessing Variables Using the Resolve Method

The Resolve method takes a string argument and returns a reference to an object. It can be used to access variables in any given block, stream, or the flowsheet itself from a script anywhere in the simulation.

For example, given a simulation with two blocks, b1 and b2, from a script in b1, you can access the variable b2.x like this:

resolve("Application.Simulation.Flowsheet.b2.x")


Note: Global variables are not accessed with the Resolve method. Instead, the syntax is, for example:

Simulation.Global.vrbname

where vrbname is the name of the required variables.

For more information on Resolve, see Resolve Method.

Table of Key Automation Objects The following table lists the key automation objects, and their relationship (path) from the Application object.

Name Path Relative to

Application Description

Application Application The application object.

For example, for Aspen Custom Modeler®:

In external Microsoft® Visual Basic®, obtained by: Dim ACMApp as objectSet ACMApp =createobject("ACM Application")

In a script, available as: "Application":Set ACMApp=Application

Active Document

Application. ActiveDocument

Represents the currently open simulation document (, that is, the file created by your Aspen Modeler product) and supports methods such as Save, Save As, and others, found on the File menu.

Is the object returned when a GetObject("file.acmf") call is made from external Microsoft® Visual Basic®. Is the same object as the simulation object

Simulation Application.Simulation The current simulation, contains the flowsheet object and has methods to perform runs.

Flowsheet Application.Simulation. Flowsheet

Contains the blocks, streams, variables, etc., of the currently open simulation, and gives access to them to allow variables to be set or retrieved.

Block Application.Simulation. Flowsheet.BlockName

A block in the flowsheet

Stream Application.Simulation. Flowsheet.StreamName

A stream in the flowsheet

Port Application.Simulation. Flowsheet.BlockName. PortName

A port in a block

Variable Application.Simulation. Flowsheet.BlockName. VarName

A variable in a block

Properties Application.Simulation. Properties

Contains physical properties information

Component List

Application.Simulation. Properties. ComponentList(name)

Contains information about a particular named list of components

OutputLogger Application.Simulation. OutputLogger

Controls the behavior of the Simulation Messages window and the logging file. Provides access to the same functionality as the right mouse button does in the Simulation Messages window.

Results Application.Simulation. Results

Provides the ability to use results from a snapshot file to initialize a run, that is, the same functionality provided


by the menu item Use on the Tools menu.

UOM Application.Simulation. Uom

Provides the ability to manipulate the Unit of Measurement sets in use by your Aspen Modeler product. See the Modeling Language Reference, Chapter 2.

Task Application.Simulation. Flowsheet.TaskName

An event-driven task

Homotopy Application.Simulation. Homotopy

Controls Homotopy behavior

Optimization Application.Simulation. Optimization

Accesses optimization functions for the current simulation

OnlineLinks Application.Simulation. OnlineLinks

Provides access to the Online Links facility, which controls the exchange of data between the simulation and an on-line data server.

CDI Application.Simulation.CDI Returns a reference to the CDI object.

Note: If a method or property is used incorrectly, it generates an error. In Microsoft Visual Basic, you can inspect the Err object (particularly Err.Description, which is a string describing the error) to find the nature of the error.

Application Object Properties, methods and events are available for the Application object.

Application Properties The following properties are available for the Application object.

• Application.ActiveDocument

• Application.Caption

• Application.DefaultFilePath

• Application.FullName

• Application.Height

• Application.Interactive

• Application.Left

• Application.Name

• Application.Path

• Application.ProcessID

• Application.Simulation

• Application.StatusBar

• Application.Top

• Application.Version

• Application.Visible

• Application.Width

• WorkingFolder


Application.ActiveDocument

Returns the currently open document (if any).

Example

Running external Microsoft® Visual Basic®:

Dim doc as object

Set doc=ACMApp.ActiveDocument

Application.Caption

Returns or sets the caption on the main GUI window.

Example

Running a script from Flowsheet or Model:

Application.Caption = "My own GUI title"


label1.caption = ACMApp.Caption

Application.DefaultFilePath

Returns the file path name that is initially available on a File / Open... operation.

Example


Dim OpenPath

OpenPath = Application.DefaultFilePath

'sets the path

Application.DefaultFilePath="c:\project\"

Application.FullName

Returns the full path and file name of the current executable.

Example


Dim CurrentExec

CurrentExec = Application.FullName

Application.Height

Returns or sets the height in points (there are approximately 72 points in an inch) of the GUI window.

Example


Application.Height = 400



Label1.Caption = ACMApp.Height

Application.Interactive

Sets whether the user can interact with the GUI. Takes a logical value of True and False.

Example


Application.Interactive = False

Application.Left

Returns or sets the position in points (there are approximately 72 points in an inch) of the left edge of the GUI window.

Example


Application.Left = 30


Label1.Caption = ACMApp.Left

Application.Name

Returns the current name of the application.

Example


Dim CurrentName

CurrentName = Application.Name

Application.Path

Returns the path to the current application.

Example


Dim CurrentPath

CurrentPath = Application.Path

Application.ProcessID

Returns the process ID of the ACM client process.

Example

From external Microsoft Visual Basic:

Dim ProcID

ProcID = ACMApp. ProcessID


Application.StatusBar

You can read the value of the text in the status bar of the GUI.

Example


Label1.Caption = ACMApp.StatusBar


Application.StatusBar = "Definitions in progress"

Application.Top

Returns or sets the position in points (there are approximately 72 points in an inch) of the top edge of the GUI window.

Example


Application.Top = 10


Label1.Caption = ACMApp.Top

Application.Version

Returns the version of the application. Read-only string.

Example


Label1.Caption = ACMApp.Version

Application.Visible

You can make the GUI visible or invisible. Can be either True or False.

Example


If Check1.Value = 0 Then ACMApp.Visible = True

Application.Width

Returns or sets the width in points (there are approximately 72 points in an inch) of the GUI window.

Example


Application.Width = 600


Label1.Caption = ACMApp.Width


WorkingFolder

Returns or sets the working folder for the simulation server. Note that the working folder can not be changed if a simulation is already opened.

Example:

in a script:

display the current working folder

Application.Msg "Current working folder is " & Application.WorkingFolder

Example:

with external visual basic

(This example shows how to set the working folder before opening the simulation.)

Private Sub CommandButton1_Click()

Dim acm As Object

Dim acmsim As Object

Set acm = CreateObject("ACM Application")

acm.Application.Visible = True

acm.Application.WorkingFolder = "d:\tmp1"

Set acmsim = acm.Application.OpenDocument("d:\tmp\test1.acmf")

End Sub

Application Methods The following methods are available for the Application object.

• Application.Activate()

• Application.CloseDocument()

• Application.Maximize()

• Application.Minimize()

• Application.Msg()

• Application.NewDocument()

• Application.OpenDocument()

• Application.ProcessIDs

• Application.Quit()

• Application.Restore()

• Application.SaveDocument()


• Application.SaveDocumentAs()

Application.Activate()

Brings the application's main window to the front and gives it keyboard focus.

Example


ACMApp.Activate

Application.CloseDocument()

Closes the currently open document. The Boolean parameter is true if any changes to the document should be saved back to disk.

Caution: Do not execute this command from a script because the script will be abruptly terminated. This is because the running script is owned by the document being closed.

Example


ACMApp.CloseDocument(True)

Application.Maximize()

Makes the application's main window occupy the full screen.

Example


ACMApp.Maximize

Application.Minimize()

Iconizes the application's window.

Example


ACMApp.Minimize

Application.Msg()

You can print text to the Simulation Messages window.

The & character enables you to concatenate strings of text.

If you find that you cannot print some values to the message window, try using the CStr() function, which converts parameters to strings of text.

Caution: When running from external Microsoft® Visual Basic®, the Simulation Messages window only exists when a simulation document is open. If there is no open document, the text sent through this method will be lost.


Examples


Application.Msg "Hello World"

Application.Msg Application.Simulation.RunMode

Application.Msg "Run Mode is " & Application.Simulation.RunMode

Application.Msg "Run complete at time" & Time

Application.NewDocument()

Closes any currently open document, and creates a new document.

If a document is already open at the time the call is made then it will be automatically closed if it is not modified.

If it is modified then the system will prompt you to save changes. Consequently it is usually best to close any existing document explicitly using the CloseDocument method before using this method. For details, see Application.CloseDocument().

Caution: Do not execute this command from a script because the script will be abruptly terminated. This is because the running script is owned by the document being closed.

Example


Dim ACMDocument as object

Set ACMDocument=ACMApp.NewDocument

Application.OpenDocument()

Opens an existing document. Takes a string argument which is the path to the file, and returns a document.

If a document is already open at the time the call is made then it will be automatically closed if it is not modified.

If it is modified then the system will prompt you to save changes. Consequently it is usually best to close any existing document explicitly using the CloseDocument method before using this method. For details, see Application.CloseDocument().

Caution: If you execute the command from within a script, it will be abruptly terminated. This is because the running script is owned by the document being closed.


Example


Dim ACMDocument as object

Set ACMDocument=ACMApp.OpenDocument("d:\simulations\towersim.acmf")

Application.ProcessIDs

Returns an array of 3 integers. These are the process IDs of the 3 ACM processes, ACM client, server and task server in that order.

Example


Dim ProcIDs

ProcIDs = ACMApp. ProcessIDs

Application.Quit()

Quits the current session.

Example


MsgBox("Do you want to close the application?", vbYesNoCancel, "Quit Application")

If Response = "yes" Then ACMApp.Quit

Application.Restore()

Restores the application's main window to its normal size. Normally called after the window has been minimized or maximized.

Example


ACMApp.Restore

Application.SaveDocument()

Saves the currently open simulation document under its existing name.

Example


Dim ACMApp as Object

Set ACMApp= CreateObject("ACM Application")

ACMApp.visible=true

ACMApp.OpenDocument("d:\test\simulation01.acmf")

' other work occurs here�


' save results

ACMApp.SaveDocument

ACMApp.Quit

Application.SaveDocumentAs()

Saves the currently open simulation document under a new name.

Takes the new path as the first argument, and a Boolean variable as the second. If the second argument is true then any existing file with the name will be overwritten.

Note: After the document has been saved using this function, the new path becomes the default path for future calls to the SaveDocument method.

Example




ACMApp.visible=true

ACMApp.OpenDocument("d:\test\simulation01.acmf")


' save results, overwriting file if it exists

ACMApp.SaveDocumentAs "d:\test\simulation02.acmf",True

ACMApp.Quit

Application Events Aspen Modeler products expose a number of automation events which can be handled in a Visual Basic form. These events are:

Event Occurs whenever

void OnRunStarted(); A run is started in ACM

void OnRunPaused(); A run is paused in ACM

void OnHasQuit(); The ACM application terminates

void OnHasSaved(); The current simulation is saved

void OnSavedAs(VARIANT sPath); The current simulation is saved to a new filename. sPath gives the new path and filename.

void OnOpened(VARIANT sPath); A simulation is opened. sPath gives the path and filename of that simulation.

void OnNew(); A new, blank simulation is created

void OnRunModeChanged(VARIANT sRunMode); The run mode is changed, for


example, from steady-state to dynamic. sRunMode gives the new run mode.

void OnNewBlock(VARIANT sBlockName); A new block is added to the flowsheet. sBlockName gives the name of that block.

void OnNewStream(VARIANT sStreamName); A new stream is added to the flowsheet. sStreamName gives the name of that stream.

void OnDeletedBlock(VARIANT sBlockName); A block is deleted from the flowsheet. sBlockName gives the name of that block.

void OnDeletedStream(VARIANT sStreamName); A stream is deleted from the flowsheet. sStreamName gives the name of that stream.

void OnUomSetChanged(VARIANT sUomSetName); The units of measurement set changes.

void OnStreamConnected(VARIANT sStreamName); A stream is connected. sStreamName gives the name of that stream.

void OnUserChangedVariable (VARIANT sVariableName);

The value or other properties of a variable are changed by the user.

void OnStreamDisconnected(VARIANT sStreamName); A stream is disconnected. sStreamName gives the name of that stream.

void OnStepComplete(); A solution step is completed.

For an example of using Visual Basic 6 to handle events, see Aspen Custom Modeler Examples, Handling Events in a Visual Basic Form.

ActiveDocument Object Properties and methods are available for the ActiveDocument object.

ActiveDocument Properties The following properties are available for the ActiveDocument object.

• ActiveDocument.Application

• ActiveDocument.FullName

• ActiveDocument.Name

• ActiveDocument.Parent

• ActiveDocument.Saved

• ActiveDocument.FlowsheetWallpaperMode

ActiveDocument.Application

This read-only string property returns the application.

Example


Dim ACMApp

Set ACMApp= ActiveDocument.Application


ACMapp.msg "using the application"

ActiveDocument.FullName

This read-only string property returns the full path of the document. If the document has not yet been loaded from or saved to disk then the string may be empty.

Example


Dim ACMName

' Get full path to document

ACMName = ActiveDocument.FullName

' write path to Simulation Message Window

ACMapp.msg ACMName

ActiveDocument.Name

This read-only string property returns the name of the document. For a document which not been associated with a disk file this is normally "Untitled". If the document was opened from the file "d:\simulations\sim01.acmf" then the Name would be "sim01.acmf".

Example


Dim ACMName

' Get name of the document

ACMName = ActiveDocument.Name

'write name to Simulation Message Window

ACMapp.msg ACMName

ActiveDocument.Parent

This read-only property returns the parent automation object of the document, that is, the application.

Example


Dim ACMApp

' Get parent of the document

Set ACMApp = ActiveDocument.parent

' Use one of the application�s methods to show

' we really have hold of the application

ACMApp.msg "using the msg method of the application"


ActiveDocument.Saved

This read-only Boolean property returns True if any modifications made to the document have been saved to disk. If the document has been changed in memory since it was last written to disk, it returns False.

Example


Dim bSaved

' Get document modification state

bSaved = ActiveDocument.Saved

' write status to Simulation Message Window

if bSaved Then

activedocument.application.msg "Document secure on disk"

else

activedocument.application.msg "Document modified in memory"

end if

ActiveDocument.FlowsheetWallpaperMode

This Boolean property controls if the flowsheet will be set as the wallpaper background of the application or as a floating window.

Example


Application.ActiveDocument.FlowsheetWallpaperMode = true

ActiveDocument Methods The following methods are available for the ActiveDocument object.

• ActiveDocument.CloseAllForms()

• ActiveDocument.CreateLibrary()

• ActiveDocument.SaveDocument()

• ActiveDocument.SaveDocumentAs()

• ActiveDocument.CloseExplorerWindows

• ActiveDocument.CloseEditorWindows

• ActiveDocument.LaunchExplorer

• ActiveDocument.ShowFlowsheetWindow

• ActiveDocument.ShowEditorWindow

• ActiveDocument.ShowMessagesWindow

ActiveDocument.CloseAllForms()

Closes all of the currently open forms (plots and tables).

Example


Running from a script within Aspen Custom Modeler®:

ActiveDocument.CloseAllForms

ActiveDocument.CreateLibrary()

Creates a library with the path supplied by its one string argument. The file name must end with the extension .acml.

Example



Dim ACMDoc as Object


ACMApp.visible=true

ACMDoc=ACMApp.OpenDocument("d:\test\simulation01.acmf")

' save as a library

ACMDoc.CreateLibrary("d:\test\simulation01.acml")

' save results

ACMApp.Quit

ActiveDocument.SaveDocument()

Saves the currently open simulation document under its current name.

Example





ACMApp.visible=true

Set ACMDoc=ACMApp.OpenDocument("d:\test\simulation01.acmf")


' save results

ACMDoc.SaveDocument

ACMApp.Quit

ActiveDocument.SaveDocumentAs()

Saves the currently open simulation document under a new name.

Takes the new path as the first argument, and a Boolean variable as the second. If the second argument is True then any existing file with the name will be overwritten.


Notes:

• After the document has been saved using this function the new path becomes the default path for future calls to the SaveDocument method.

• The path must specify a directory that already exists.

Example





ACMApp.visible=true

Set ACMDoc=ACMApp.OpenDocument("d:\test\simulation01.acmf")


' save results

ACMDoc.SaveDocumentAs "d:\test\simulation02.acmf",TRUE

ACMApp.Quit

ActiveDocument.CloseExplorerWindows

Closes all of the currently open explorer windows.

Example

Running from a script within Aspen Custom Modeler:

Application.ActiveDocument.CloseExplorerWindows

ActiveDocument.CloseEditorWindows

Closes all of the currently open editor windows.

Example

Running from a script within Aspen Custom Modeler:

Application.ActiveDocument.CloseEditorWindows

ActiveDocument.LaunchExplorer

Launches an explorer window. Optional arguments can be used to give the window position and size.

LaunchExplorer x position, y position, width, depth

Example


Application.ActiveDocument.LaunchExplorer 100,0,180,600


ActiveDocument.ShowFlowsheetWindow

Show the flowsheet window. Optional arguments can be used to give the window position and size.

ShowFlowsheetWindow x position, y position, width, depth

Example


Application.ActiveDocument.ShowFlowsheetWindow 100,0,180,600

ActiveDocument.ShowEditorWindow

Shows an editor window. There can be up to 8 arguments. Arguments 1 and 2 are mandatory and are the location and name of the item to be edited.

The location can be "Flowsheet", �Custom� or a library name which must be a full path to an attached library.

The name is the name of the type in the case of a library or Custom modeling or the path to the item in the case of the Flowsheet.

Argument 3 is a read only flag, 0 for read only, 1 for write. All libraries must be accessed read only.

Argument 4 to 7 are the x position, y position, width and depth of the editor window.

Argument 8 is the line number to be made current.

Example


ActiveDocument.ShowEditorWindow "Custom","Tank",0,581,387,351,160,1

ActiveDocument.ShowEditorWindow

"E:\Program Files\AspenTech\AMSystem 2004\lib\Modeler.acml","APlusProduct", 0,182,184,603,218

ActiveDocument.ShowMessagesWindow

Shows the simulation messages window. Optional arguments can be used to give the window position and size.

ShowMessagesWindow x position, y position, width, depth

Example


Application.ActiveDocument.ShowMessagesWindow 180,497,840,124

Form Object The following properties are available for the Form object:


Name

The name of the object relative to its parent model (read only).

VariablesPaths

Collection of variable paths the form displays (read only).

VariablesPaths VariablesPaths is the collection of strings which contains the names of the variables selected on a form.

Example:

The following script prints the variables selected on table "Results" from block B1.

for each s in B1.Forms("Results").VariablesPaths

set v = B1.Resolve(s)

application.msg s & " = " & v.value

next

Simulation Object Properties and methods are available for the Simulation object.

Simulation Properties The following properties are available for the Simulation object.

• Simulation.CDI

• Simulation.CommunicationInterval

• Simulation.Correlation

• Simulation.CorrelationMatrix

• Simulation.CorrelationMatrixPresent

• Simulation.Covariance

• Simulation.CovarianceMatrix

• Simulation.CovarianceMatrixPresent

• Simulation.Degrees

• Simulation.Deviation

• Simulation.DeviationArrayPresent

• Simulation.DisplayTime

• Simulation.EndStepCount

• Simulation.EndTime

• Simulation.Equations

• Simulation.EstimatedValue


• Simulation.EstimationRunState

• Simulation.Flowsheet

• Simulation.FullName

• Simulation.LeastSquaresObjective

• Simulation.Name

• Simulation.Options...

• Simulation.Properties

• Simulation.Results

• Simulation.RunMode

• Simulation.RunNumber

• Simulation.Saved

• Simulation.ScriptIsRunning

• Simulation.SpecState

• Simulation.State

• Simulation.Successful

• Simulation.Termination

• Simulation.Time

• Simulation.Variables

Simulation.CDI

Returns a reference to the CDI object. For more information, see CDI Object.

Simulation.CommunicationInterval

This Read/Write property gives access to the Communication Interval. This is the interval in simulation time at which results are returned from the simulation engine to the GUI.

Example

Running a script from Flowsheet:

Simulation.CommunicationInterval=0.02

Application.msg "Com Time: " & Simulation.CommunicationInterval

Simulation.Correlation

This read-only property accepts the names of two of the estimated variables and returns the correlation of the variables (that is, one element of the correlation matrix).

For an example, see the Modeling Language Reference, Chapter 2, Accessing Individual Correlation Results.

Simulation.CorrelationMatrix

This read-only property returns the 2D correlation matrix of floating point numbers. The array subscripts both range from 0..number_estimated_variables-1, where 0 corresponds to the first variable added by AddEsstimateVariable(), 1 to the second, and so on. The array is


symmetric about the lead diagonal. For an example, see the Modeling Language Reference, Chapter 2, Testing for the Correlation Matrix.

Note: Use after an Estimation run only.

Simulation.CorrelationMatrixPresent

This read-only property returns true if the correlation matrix is present. For an example, see the Modeling Language Reference, Chapter 2, Testing for the Correlation Matrix.

Simulation.Covariance

This read-only property is used as follows:

Covariance("estimated var1", "estimated var2")

It returns the covariance of the variables (that is, one element of the covariance matrix).

Note: Use after an Estimation run only.

Simulation.CovarianceMatrix

This read-only property returns the 2D covariance matrix of floating point numbers. The array subscripts both range from 0..number_estimated_variable-1, where 0 corresponds to the first variable added by AddEstimateVariable(), 1 to the second, and so on. The array is symmetric about the lead diagonal.

Simulation.CovarianceMatrixPresent

This read-only property returns true if the covariance matrix is present, and false if it is not.

Simulation.Degrees

Returns the number of degrees of freedom of the simulation. Returns 0 for a complete simulation, a positive value for an under-specified simulation, and a negative number for an over-specified simulation.

Example


Label1.Caption = ACMApp.Simulation.Degrees


IF Application.Simulation.Degrees < 0 THEN

B1.Input1.Flow.Spec = "Fixed"

ENDIF


Simulation.Deviation

See the Modeling Language Reference, Chapter 2, Defining an Estimation Simulation..

Simulation.DeviationArrayPresent

See the Modeling Language Reference, Chapter 2, Defining an Estimation Simulation..

Simulation.DisplayTime

This read-write property allows you to access and modify the current simulation time in the current display units. See also Simulation.Time.

Example


Label1.Caption = ACMApp.Simulation.DisplayTime

Simulation.EndStepCount

Returns or sets the number of steps before a dynamic run pauses.

Notes • This option has no effect if the Application.Simulation.Termination

property is subsequently set to Never.

• Depending on the previous value of Termination, setting Simulation.EndStepCount changes that value:

If Termination was previously set to

Setting EndStepCount changes the value of Termination to

"Never" "OnIterations"

"AtTime" "TimeOrIterations"

Example


Application.Simulation.EndStepCount = 50

Application.Simulation.Termination = "AtTime"


Label1.Caption = ACMApp.Simulation.EndStepCount

Simulation.EndTime

Returns or sets the end time of a dynamic run.

Notes • This option has no effect if the Application.Simulation.Termination

property is set to Never.

• Depending on the previous value of Termination, setting Simulation.EndStepCount changes that value:


If Termination was previously set to

Setting EndTime changes the value of Termination to

"Never" "AtTime"

"OnIterations" "TimeOrIterations"

Example


Application.Simulation.EndTime = 100.0

Application.Simulation.Termination = "AtTime"


Label1.Caption = ACMApp.Simulation.EndTime

Simulation.Equations

Returns the total number of equations in the simulation.

Example


Label1.Caption = ACMApp.Simulation.Equations

Simulation.EstimatedValue

See the Modeling Language Reference, Chapter 2, Defining an Estimation Simulation.

Simulation.EstimationRunState

A read-only property that may be inspected after an Estimation run to determine if it succeeded. Possible values are:

Value Meaning

0 Still running

1 Solution Convergence

2 Relative Function Convergence

3 Solution and Relative Function Convergence

4 Absolute Function Convergence

5 Singular Convergence

6 False Convergence

7 Exceeded maximum number of iterations

8 Non specific error condition (see Simulation Messages window)

255 Not run

Simulation.Flowsheet

Returns the Flowsheet object. The Flowsheet object is used to access blocks and stream on the flowsheet. For more information, see Block, Stream, and Flowsheet Objects.

Example



Dim ACMFlowsheet as Object

Set ACMFlowsheet = ACMApp.Simulation.Flowsheet

Simulation.FullName

Returns the full path name of the current simulation, for example: D:\simulations\simulation01.acmf.

Note: If the simulation document has not yet been loaded from, or saved to disk, then the string may be empty.

Example

Running external Microsoft Visual Basic:

Label1.Caption = ACMApp.Simulation.FullName

Simulation. LeastSquaresObjective

This read only property allows you to access the result of an estimation run giving the final value of the least squares objective function.

Example


Labell.Caption = ACMApp.Simulation. LeastSquaresObjective

Simulation.Name

This read-only property returns the name of the current simulation as a string. For example, if the open simulation document is D:\simulations\simulation01.acmf, the value returned is simulation01.acmf.

Example


Label1.Caption = ACMApp.Simulation.Name

Simulation.Options...

The Options properties correspond to the options available on the Solver Options dialog. Each solver property is defined by Application.Simulation.Options, followed by the solver option property name OptionProperty. Running a script from Flowsheet or Model, the syntax is:

Application.Simulation.Options.OptionProperty

For the valid values of numerical solver options, see Solver Properties Dialog Box Chapter 6.

General Properties

The available General properties are:

Property Explanation


AbsPerturb Numerical derivative absolute perturbation

AbsTearTol Absolute tear tolerance

AbsTol Absolute variable tolerance

ChangeTol SAX tolerance

CheckProcDerivs Check procedure derivatives. Argument is an integer or string. Valid values are: 0 = "Off", 1 = "Active derivatives". Returns as a string.

Compression Eliminates equivalence equations: Boolean

DerivAbsTol Absolute checking tolerance

DerivRelTol Relative checking tolerance

EqnTol Absolute equation tolerance

MaxTearIter Maximum tear iteration

PrintLevel Print level. Argument is an integer from 0 to 5 0 � None 1 - Low 2 � Medium 3 - High 4 - Very High 5 - Maximum

PropInfo Properties print level. Argument is an integer from -1 to 3 -1 � None 0 - Minimal 1 � Low 2 - High 3 - Maximum

RelPerturb Numerical derivative relative perturbation

RelTearTol Relative tear tolerance

RelTol Relative variable tolerance

Scaling Solver scaling. Argument is a Boolean: True or False

SyncSteps Takes an integer or string argument: 0 = "Full", 1 = "Low", 2 = "Medium", 3 = "High"

Tearing Argument is an integer or string. Valid values are: 0 = "none", 1 = "update", 2 = "start", 3 = "complete". Returns as a string.

TearUpdate Takes an integer or string argument: 0 = "Wegstein", 1 = "Direct". Returns as a string.

WatchGroup Watch group. Argument is an integer from 1 to the number of equation groups in the simulation

WatchSubgroup Watch Subgroup of torn group

Wegstein.MaxAcceleration

Wegstein maximum Acceleration

Wegstein.MinAcceleration Wegstein minimum Acceleration

Integrator Properties

To display the relevant Solver Options Reference information, refer to the property name in the left column of the table.

Integrator:

Explicit Euler, Runge Kutta 4, Implicit Euler, ImpEuler (11.1), Gear, VSIE (11.1), Gear (11.1).

Example:

Application.Simulation.Options.Integrator = "Gear"

Label1.Caption = Application.Simulation.Options.Integrator.


Returns a string. Property Explanation

Unified integrator options

Where appropriate these options will be applied when any of the following integration methods is selected: Explicit Euler, Runge Kutta 4, Implicit Euler, Gear.

Integration..AbsErrorTol Absolute integration error tolerance

Integration..AbsTearTol Absolute integration tear error tolerance

Integration..RelErrorTol Relative integration error tolerance

Integration..RelTearTol Relative integration tear error tolerance

Integration..IncSensErrors Include sensitivity errors

Integration..RcvTornVars Reconverge torn variables

Integration.TestSAndAVars Integration error test includes State and Algebraic variables

Integration.StepSizeType Step size type - Fixed or Variable

Integration.StepSize Step size

Integration.InitStepSize Initial step size

Integration.MinStepSize Minimum step size

Integration.MaxStepSize Maximum step size

Integration.StepRedFact Step reduction factor

Integration.EnforceMinStep Always enforce minimum step

Integration.ItplToComTime Interpolate communication time

Integration.LocateIEvents Locate model discontinuities

Integration.ReInitAfterIE Re-initialize after model discontinuities

Integration.DiscontinuityEventTol

Discontinuity event tolerance [was ImplicitEventTolerance]

Integration.ReInitAfterEE Re-initialize after Variable Step Change

Integration.UsePrevAfterEE Step size after Variable Step Change

Integration.ShowHIErrors Highest integration errors

Integration.ShowHTIErrors Highest tear integration errors

Integration.MaxOrder Maximum order for Gear method

ImpEuler(11.1) options

ImpEuler.Step Integration step

VSIE (11.1) options

VSIE.InitialStep Initial integration step

VSIE.MinimumStep Minimum integration step

VSIE.MaximumStep Maximum integration step

VSIE.StepRedFact Step reduction factor

VSIE.MaxIncFact Maximum step increment factor

VSIE.HighestErrors Highest errors

VSIE.MaxCorIter Maximum corrector iterations

VSIE.AbsErrTol Absolute error tolerance

VSIE.TearErrTol Tear error tolerance

VSIE.Interpolation VSIE interpolation Takes a Boolean argument

VSIE.ReconvergeTorn VSIE reconverge torn variables Takes a Boolean argument

Gear (11.1) options

Gear.HighestErrors Gear highest integration errors


Gear.InitialStep Gear initial integration step

Gear.MinimumStep Gear minimum integration step

Gear.MaximumStep Gear maximum integration step

Gear.Reinit Gear re-initialization method Takes an integer or string argument, returns as a string Valid Values are 0 = "Normal", 1 = "Fast", 2 = "Save"

Gear.BoundCheck Gear keep solution within bounds Takes an integer or string argument, returns as a string 0 = "Off", 1 = "Track", 2 = "Clip"

Gear.EventTol Gear event tolerance

Gear.JacUpdate Gear Jacobian update policy

Gear.MaxCorSteps Show Gear maximum corrector step sizes

Gear.MaxCorIter Gear Maximum corrector iterations

Linear Solver Properties

The available Linear Solver properties are:


LinearSolver Linear solver. Takes an integer or string argument. Valid values are: 1 = "MA28" 4 = "MA48"

MA28.DropTol MA28 drop tolerance

MA48.DropTol MA48 drop tolerance

MA48.PivotTol MA48 pivot tolerance

MA48.ReanalyzeThreshold MA48 reanalyze threshold

MA48.ReanalyzeWindow MA48 reanalyze FLOPS window size

MA48.Repivot MA48 repivot every n factorizations

MA48.PivotSearch MA48 solver searches n columns for pivots

Non-Linear Solver Properties

The available Non-Linear Solver properties are:


Nonlinear.Method Non-linear solver method. Takes an integer or string argument: 0 = "Hybrid" 1 = "Newton" 2 = "Fast Newton"

OpenNLASolver The name of the DLL for the Open Nonlinear Algebraic solver

OpenNLASolverParameters.Item("Param") Set or get this property to read/write to the OpenNlaSolver parameter "param", for example: OpenNLASolverParameters.Item("PrintLevel") = 1 'Set printlevel parameter to one

OpenNLASolverParameters.Count Returns the number of OpenNLASolver parameters

OpenNLASolverParameters.ParamName(i) Returns the name of parameter i in the OpenNLASolverParameters collection


Nonlinear.MaxIter Non-linear solver maximum iterations

Nonlinear.MaxDivSteps Non-linear solver maximum divergent steps

Nonlinear.MaxStepRed Non-linear solver maximum step reductions

Nonlinear.MaxFastNewtonSteps Non-linear solver maximum Fast Newton steps

Nonlinear.ConvCrit Non-linear solver convergence criterion. Takes an integer or string argument: 0 = "Residual" 1 = "Variable" 2 = "Residual and Variable" 3 = "Residual or Variable"

Nonlinear.Dogleg Non-linear solver dogleg method. Takes a Boolean argument, True or False

Nonlinear.HiVarSteps Non-linear solver highest variable steps

Nonlinear.HiResidual Non-linear solver highest residuals

Nonlinear.MathsPrint Non-linear solver print linear algebra for groups of size greater than or equal to n.

Nonlinear.Boundfrac Non-linear solver maximum approach to bound

Nonlinear.RangeFrac Non-linear solver maximum range fraction

Nonlinear.BoundClip Non-linear solver approach to bound

Nonlinear.AbsPert Non-linear solver absolute perturbation

Nonlinear.SingPert Non-linear solver singularity perturbation

Nonlinear.MaxVarStep Non-linear solver maximum variable step

Estimation Solver Properties

Estimation solver property options are listed below. To display the relevant Solver Options Reference information, click the name in the property column.


NL2Sol.AbsFuncTol Estimation Absolute Function Tolerance

NL2Sol.FalseConvTol Estimation False Convergence Tolerance

NL2Sol.MaxIter Estimation Maximum Iterations

NL2Sol.RelFuncTol Estimation Relative Function Tolerance

NL2Sol.SolTol Estimation Solution Tolerance

Estimator Estimation method. Valid values are: 1 = Least squares; 2 = Maximum log likelihood

EstimationSolver Estimation solver to be used. Takes an integer argument. Valid values are: 1 = FEASOPT (Maximum log likelihood estimator only); 2 = NL2SOL; 3 = Nelder-Mead; 6 = Open NLP (reduced space)

EstimationPrintLevel Reporting level for estimator diagnostic output. Takes an integer or string argument but returns a string. Valid values are: 0 = "None"; 1 = "Low"; 2 = "Medium"; 3 = "High"; 4 = "Very High"

OpenESTSolver The name of the DLL for the Open estimator Algebraic solver

OpenNLPEstSolverParameters.Item("Param")

Set or get this property to read/write to the OpenNLPEstSolver parameter "param".For example:OpenNLPEstSolverParameters.Item("PrintLevel") = 1 'Set


printlevel parameter to oneOpenNLPEstSolverParameters.Count � Returns the number of OpenNLPEstSolver parametersOpenNLPSolverParameters ParamName(i) � Returns the name of parameter i in the OpenNLPEstSolverParameters collection

Timesettings Properties Property Explanation

TimeSettings. CommunicationInterval

Specifies the communication interval at which data is available for plotting and snapshots

TimeSettings.DisplayUpdateInterval

Specifies the interval at which data is updated on screen in real time

TimeSettings.EnablePauseAt Boolean; pauses the simulation at the time specified in TimeSettings.PauseAt

TimeSettings.PauseAt Pauses the simulation at the specified time in conjunction with TimeSettings.EnablePauseAt = TRUE

TimeSettings.EnableStepFor: False Boolean; pauses the simulation after the number of steps specified in TimeSettings.StepFor

TimeSettings.StepFor Pauses the simulation after the specified number of steps in conjunction with TimeSettings.EnableStepFor = TRUE

TimeSettings.RealTimeSyncFactor Determines the relationship between real time and simulation time. Set to 0 for the simulation to run as fast as possible; set to 1 to run the simulation in real time, if possible. Any other positive real number acts as a multiplier of real time

TimeSettings.RecordHistory Boolean; set to TRUE to record a time history for all variables in the simulation regardless of each variable's Record attribute

TimeSettings.CommunicationUnits Specifies the simulation time units. Valid units are: "seconds", "minutes", "hours", "days", "weeks", "months", "years"

TimeSettings.TimeDisplayUnits Sets or retrieves the unit in which time is displayed in the GUI. Valid units are: "seconds", "minutes", "hours", "days", "weeks", "months", "years"

Examples of Using Estimation Solver Properties


Application.Simulation.Options.NL2Sol.AbsFuncTol = 1e-20 ' absolute function tolerance

Application.Simulation.Options.NL2Sol.RelFuncTol = 1e-4 ' relative function tolerance

Application.Simulation.Options.NL2Sol.SolTol = 1e-4 ' solution tolerance

Application.Simulation.Options.NL2Sol.PrintLevel = 2 ' print level

Application.Simulation.Options.NL2Sol.FalseConvTol = 0 ' false convergence tolerance

Application.Simulation.Options.NL2Sol.MaxIter = 50 ' maximum iterations



Dim objApplication as Object

Set objApplication = GetObject(filename)

objApplication.Application.Simulation.Options.NL2Sol.AbsFuncTol = 1e-20 ' absolute function tolerance

objApplication.Application.Simulation.Options.NL2Sol.RelFuncTol = 1e-4 ' relative function tolerance

objApplication.Application.Simulation.Options.NL2Sol.SolTol = 1e-4 ' solution tolerance

objApplication.Application.Simulation.Options.NL2Sol.PrintLevel = 2 ' print level

objApplication.Application.Simulation.Options.NL2Sol.FalseConvTol = 0 ' false convergence tolerance

objApplication.Application.Simulation.Options.NL2Sol.MaxIter = 50 ' maximum iterations

Simulation.Properties

This read-only property contains the physical properties object. For information on its uses, see Properties Object.

Example

The following is an example of retrieval at the Flowsheet level:

Set physprops=properties

Simulation.Results

Returns a reference to the Results object.

For more information, see Results Object.

Simulation.RunMode

This Read/write property gives access to the run mode for the next simulation run.

Valid options are "Steady State", "Initialization", "Dynamic", "Estimation", "Optimization".

Example




Label1.Caption = ACMApp.Simulation.RunMode

Simulation.RunNumber

This read-only property returns the run number of the current simulation.

Example



Dim iRun

iRun = Application.Simulation.RunNumber

Application.Msg "The run number is " & Cstr(iRun)

Simulation.Saved

This read-only Boolean property returns True if any modifications made to the simulation document have been saved to disk. If the document has been changed in memory since it was last written to disk, it returns False.

Example


Dim bSaved

' Get document modification state

bSaved = Application.Simulation.Saved

' write status to Simulation Message Window

if bSaved Then

application.msg "Document secure on disk"

else

application.msg "Document modified in memory"

end if

Simulation.ScriptIsRunning

Read only property which returns true if a script is currently being run.

Example


If ACMApp.Simulation ScriptIsRunning then

Simulation.SpecState

This read-only property returns the specification status of the current simulation. Can return the string values "Complete", "UnderFixed", "OverFixed", "UnderInitial", "OverInitial".

Example


Label1.Caption = ACMApp.Simulation.SpecState

Simulation.State

This read-only object returns the current run state. Valid run states are "Paused", "Running", "Stepping" and "Ready".

Example



Label1.Caption = ACMApp.Simulation.State

Simulation.Successful

Returns whether the previous simulation run or step is successfully converged. Returns a logical value, True or False.

Note: The value of the property is undefined if no run has taken place.

Example



Dim ACMobj As Object




ACMobj.Application.simulation.Run (True)


' got an error


Err.Clear

End If


If ACMobj.Application.simulation.successful Then


Else


End If

Exit Sub

errorhandler:


End Sub


Simulation.Termination

This read-write property determines how a dynamic run terminates in the current simulation. It can return the string values "AtTime", "OnIterations", "TimeOrIterations", or "Never". See also Simulation.EndTime and Simulation.EndStepCount.

• AtTime is equivalent to checking the checkbox in the Run, Run Options, "Pause At" time. This means the simulation pauses automatically at the Simulation.EndTime.

• OnIterations is equivalent to the Run, Run Options, "Pause After" checkbox. This means the simulation pauses after the specified number of communication intervals, which is specified via Simulation.EndStepCount.

• TimeOrIterations means that it pauses whenever one of the criteria is satisfied, ie both checkboxes enabled.

• Never means that it ignores the settings, ie clears both checkboxes.

Examples

Stop at a time 0.3:-

application.simulation.endtime = 0.3

application.simulation.termination = "AtTime"

Step for 10 time intervals from current time then stop:-

application.simulation.endstepcount = 10

application.simulation.termination = "OnIterations"

Stop at a time 0.5 or after 4 time intervals whichever is sooner:-

application.simulation.endstepcount = 4

application.simulation.endtime = 0.5

application.simulation.termination = "TimeOrIterations"

Simulation.Time

This read-only property returns the current simulation time in communication units. See also Simulation.DisplayTime.

Example


label1.caption = ACMApp.Simulation.Time

Simulation.Variables

This read-only property returns the total number of active variables in the simulation.

Note: An active variable is a variable that occurs in an equation in the current simulation.


Example


Label1.Caption = ACMApp.Simulation.Variables

Simulation Methods The following methods are available for the Simulation object.

• Simulation.AddEstimateVariable()

• Simulation.AddExperiment()

• Simulation.AddSensitivityParameter()

• Simulation.AddSensitivityVariable()

• Simulation.ClearSensitivities() • Simulation.CloseAllForms • Simulation.CloseFormView(�FormName�) • Simulation.CompileType

• Simulation.CreateFolder

• Simulation.CreateLibrary()

• Simulation.CreateStructure

• Simulation.CreateType

• Simulation.DisableSensitivities()

• Simulation.EnableSensitivities()

• Simulation.GetEstimationPredictedValues

• Simulation.GetSensitivityValue ( "Variable","Parameter" )

• Simulation.GetTypeText

• Simulation.Interrupt()

• Simulation.LaunchFormView("FormName")

• Simulation.NewExperiment()

• Simulation.Pause()

• Simulation.RemoveFolder

• Simulation.RemoveType

• Simulation.Reset()

• Simulation.ResetEstimation()

• Simulation.Restart()

• Simulation.Run()

• Simulation.SetTypeText

• Simulation.Step()

Simulation.AddEstimateVariable()



Simulation.AddExperiment()


Simulation.AddSensitivityParameter()

You need to add the names of the known variables you use to get sensitivity data. Known or Fixed variables are applied with the AddSensitivityParameter method.

Note: You cannot apply parameters for use in calculating sensitivities. If you call AddSensitivityParameter or AddSensitivityVariable you must perform either an initialization or steady simulation or dynamic step and ensure the sensitivities are enabled BEFORE making a GetSensitivityValue call.

Example

From external Microsoft® Visual Basic®:

ACMApp.Simulation.AddSensitivityParameter "B1.In1.Flow"

Simulation.AddSensitivityVariable()

You need to add the names of the calculated variables you use to get sensitivity data. Calculated or Free variables are applied with the AddSensitivityVariable method.

Note: If you call AddSensitivityParameter or AddSensitivityVariable you must perform either an initialization or steady simulation or dynamic step and ensure the sensitivities are enabled BEFORE making a GetSensitivityValue call.

Example


ACMApp.Simulation.AddSensitivityVariable "B1.Out1.Temp"

Simulation.ClearSensitivities()

You can delete all the calculated variables and known variables that have been previously applied to the current simulation.

Example


ACMApp.Simulation.ClearSensitivities

Simulation.CloseFormView(�FormName�)

You can close a named form, such as a plot or a table. The argument is the name of the form, including the block name if required. If the form is opened more than once all instances will be closed.


Example


Application.Simulation.CloseFormView("Plot1") Application.Simulation.CloseFormView("B1.FeederTable")

Simulation.CloseAllForms

You can close all forms open in the application

Example


Application.Simulation.CloseAllForms

Simulation.CompileType (alternative CompileModel)

CompileType "TypeName"

This automation method will compile the given type. The method fails if the type fails to compile.

Simulation.CreateFolder

CreateFolder "Folder path"

This automation method create a hierarchy of folders given by the folder path argument. The folder names should be separated by �.� characters. E.g. Reactions.Methanol will create a new folder Methanol in the folder Reactions. The folder Reactions will be created if necessary.

Simulation.CreateLibrary()

Creates a library from the current simulation, with the specified name.

Example


Application.Simulation.CreateLibrary("C:\project2\heaters.acml")

Simulation.CreateStructure

CreateStructure "Structure Type", "Structure Name"

This automation method creates an instance of the given structure type. The type can be in any folder but the instance will be created in a folder under the flowsheet Explore node with the same name as the folder containing the type.

Simulation.CreateType

CreateType "TypeName","Language Text","Folder" - "Folder" is optional (alternative CreateModel)

This automation method will create a new type with the given name in the Custom Modeling folder. The language text given should start with the keyword for the type required e.g. Model followed by the given name and the


language statements. It should terminate with End. You can provide the name of a folder.

Simulation.DisableSensitivities()

You can temporarily hide the variables you have applied to the current simulation. Later, you can re-activate the variables you previously applied to the simulation.

Example


ACMApp.Simulation.DisableSensitivities

Simulation.EnableSensitivities()

You can re-activate the variables you previously de-activated in the current simulation.

Example


ACMApp.Simulation.EnableSensitivities

Simulation.GetEstimationPredictedValues

This method returns the predicted values for the measured variables in the given estimation experiment. If the experiment is steady state a single value is returned. For dynamic experiments an array of values is returned, one value for each time point in the experiment

GetEstimationPredictedValues(�Experiment 1�, �Variable 1�)

Note. Use after an Estimation run only.

Simulation.GetSensitivityValue ("Variable","Parameter")

Returns the sensitivity of an unknown variable with respect to a known variable in a simulation.

Sensitivities are the values of partial derivatives of calculated variables with respect to known variables.

Sensitivity information is available in the following run modes:

• Steady state

• Initialization

• Dynamic

Note: To get sensitivity information, you must not have activated the ImpEuler (11.1) Integrator. VSIE

You must perform either an initialization or steady simulation or dynamic step between defining your sensitivity parameters and variables and enabling them and BEFORE making a GetSensitivityValue call.


Example


Dim Sens1

Sens1 = ACMApp.Simulation.GetSensitivityValue ( "B1.Out1.Temp","B1.In1.Flow" )

Simulation.GetTypeText (alternative GetModelText)

"Language Text" = GetTypeText "TypeName"

This automation method will get the defining text for a given type.

Simulation.Interrupt()

You can use the Simulation.Interrupt method to interrupt a running or stepping simulation. If the simulation is not running or stepping then the call is ignored. The parameter determines whether method should wait for the simulation to stop (bWait is True) or return immediately (bWait is False). It can take some seconds for a simulation to be interrupted. When using the parameter as False, you can check when the interrupt has completed by looking for a Simulation.State of �paused�.

Example


AcmApp.Simulation.Run False

'other code here

ACMApp.Simulation.Interrupt true

Simulation.LaunchFormView("FormName")

You can open a named form, such as a plot or a table. The argument is the name of the form, including the block name if required.

Example


Application.Simulation.LaunchFormView("Plot1")

Application.Simulation.LaunchFormView("B1.FeederTable")

Simulation.NewExperiment()


Simulation.Pause()

You can pause a simulation.

Example


Application.Simulation.Pause


Simulation.RemoveFolder

RemoveFolder "Folder path"

This automation method removes a hierarchy of folders given by the folder path argument. The folder names should be separated by �.� characters. E.g. Reactions.Methanol will delete the folder Methanol in the folder Reactions. The method will fail if the folder is not empty except when it contains empty folders itself.

Simulation.RemoveType (alternative RemoveModel)

RemoveType "TypeName"

This automation method will remove the given type from the simulation. The method will fail if the type is in use on the flowsheet or in any other types.

Simulation.Reset()

You can return the current simulation to the default values of all the variables. Optional logical argument specifies what will be reset.

Reset(True) resets everything

Reset(False) resets only free variables.

If the argument is omitted, it resets only free variables.

Example


Application.Simulation.Reset

Simulation.ResetEstimation()

Clears all estimated results, variables, and parameters.

Simulation.Restart()

You can return the current dynamic simulation to the state of the simulation at time zero of the current simulation.

Example


Application.Simulation.Restart

Simulation.Run()

You can start a simulation run. An argument is required. Valid values are True and False.

Use False to start the simulation and pass control on to the next line of Microsoft Visual Basic.

Use True to start the simulation and only pass control on to the next line of Microsoft Visual Basic when the run is complete. Note that in this case if the run is unsuccessful an error will be raised which must be handled with Visual Basic error statements or the Visual Basic program will terminate. When an


error is raised the Visual Basic Err object can be used to obtain information about the error. Note that for scripts in ACM the statement On Error Resume Next must be used, On Error Goto cannot be used.

Example in Visual Basic


Dim ACMobj As AspenModelerSimulation ' Available in the ACM type library



ACMobj. RunMode = "Steady State"


ACMobj.Run (True)


' got an error


Err.Clear

End If


If ACMobj.Successful Then


Else


End If

Exit Sub

errorhandler:


End Sub

Simulation.SetTypeText (alternative SetModelText)

SetTypeText "TypeName","Language Text" (alternative SetModelText)

This automation method sets the defining text for a given type. The language text given should start with the keyword for the type required e.g. Model followed by the given name and the language statements. It should terminate with End. This method does not compile the type.


Simulation.Step()

You can step a dynamic simulation by one communication interval. An argument is required. Valid values are True and False.

Use False to step the simulation and pass control on to the next line of Microsoft® Visual Basic®.

Use True to step the simulation and only pass control on to the next line of Microsoft Visual Basic when the step is complete.

Example


Application.Simulation.Step(False)

Properties Object Properties and methods are available for the Properties object.

Properties of the Properties Object The following properties are available for the Properties object:

• Properties.ComponentList

• Properties.ComponentListNames

Properties.ComponentList

This property returns a componentlist object specified by name.

Example


Set objPhysProps=ACMApp.Simulation.Properties

'get component list whose name is in text box txtCompListname

Set objCompList= objPhysProps.ComponentList(txtCompListName.Text)

Properties.ComponentListNames

This read-only property returns a collection containing the names of all the component lists in the simulation.

Example


Dim objPhysProps

Set objPhysProps= ACMApp.simulation.Properties

' populate list box with names of componentlists

Dim Components


lstNames.Clear

Set Components = objPhysProps.ComponentListNames

Dim sCurrentComp

For Each sCurrentComp In Components

lstNames.AddItem sCurrentComp

Next

Properties Methods The following methods are available for the Properties object:

• Properties.AddComponentList()

• Properties.LoadPropertiesFile()

• Properties.RemoveComponentList()

Properties.AddComponentList()

This method creates a new component list with the specified name. It takes one mandatory string argument, which is the name of the component set, and one optional Boolean parameter, which, if true, causes the list to be created as a component set. If the second argument is false or omitted, the component list is created with the reference to the physical properties (which do not have to be initialized beforehand).

Example


Private Sub btnAddComponentList_Click()

Dim sCompname As String

sCompname = txtComponentListName.Text 'get name from text box

If 1 = chkIsSet Then 'look at check box' Component set

ACMApp.Simulation.Properties.addcomponentlist sCompname, True

Else

ACMApp.Simulation.Properties.addcomponentlist sCompname

End If

End Sub

Properties.LoadPropertiesFile()

This method loads a physical properties file (.appdf or .aprpdf file) with the specified name. It takes one mandatory string argument, which is the name of file.

Example



ACMApp.simulation.Properties.LoadPropertiesFile "props1.appdf"

Properties.RemoveComponentList()

This method destroys the component list with the specified name. It takes one string argument, which is the name of the component list to be deleted.

Example


ACMApp.Simulation.Properties.removecomponentlist "List1"

ComponentList Object Properties only are currently available for the ComponentList object.

ComponentList Properties The following properties are available for the ComponentList object.

• ComponentList.Components

• ComponentList.IsComponentSet

• ComponentList.Name

• ComponentList.Option

• ComponentList.OptionNames

ComponentList.Components

This read/write property is a string collection of the names of the components in the component list.

Example


Private Sub btnGetComponentNames_Click()

' populate list box lstNames with list of components in component

' list "complist"

Dim objPhysProps

Set objPhysProps=ACMApp.simulation.Flowsheet.Properties

Set objComponentList = objPhysProps.ComponentList("CompList")

Dim comps

lstNames.Clear

Set comps = objComponentList.Components

Dim sCurrentComp


For Each sCurrentComp In Components

lstNames.AddItem sCurrentComp

Next

End Sub

Note: You cannot edit the components object in situ�you must first copy them to another collection, for example:

Set comps=objComponentList.Components

comps.RemoveValues("CH4")

comps.AddValues("CO2")

objComponentList.Components=comps

You cannot use the following:

objComponentList.Components.RemoveValues("CH4")

ComponentList.IsComponentSet

This read/write Boolean property determines whether the component list is a component set or not.

Example


'Set whether component set based on checkbox

If 1 = chkIsComponentSet.Value Then

objComponentList.IsComponentSet = True

Else

objComponentList.IsComponentSet = False

End If

ComponentList.Name

This read-only string contains the name of the component list.

Example


Dim objPhysProps

Set objPhysProps= ACMApp.simulation.Properties

Set objComponentList = objPhysProps.ComponentList("CompList")

MsgBox "Name: " & objComponentList.Name


ComponentList.Option

This read/write property is a string collection of the names of the values for the particular named option.

Example


Private Sub btnGetOption_Click()

' populate a list box with the allowed values for the option

' whose name is in text box txtOptionName

Dim colOptionValues

Set colOptionValues = objComponentList.Option(txtOptionName.Text)

Dim sOptionValue

For Each sOptionValue In colOptionValues

lstNames.AddItem sOptionValue

Next

End Sub

Note: You cannot edit the option object in situ, but must first copy it to another collection, for example:

Set values1=objComponentList.Option("G1")

values1.remove("Full")

objComponentList.Option("G1")= values1

You cannot use the following:

objComponentList.Option.Remove("Full")

ComponentList.OptionNames

This read-only property is a string collection of allowed option names.

Example


Private Sub btnOptionNames_Click()

' load list box lstNames with option names for component

' list "ACompList"

Dim objPhysProps

Set objPhysProps=ACMApp.Simulation.Properties

Set objComponentList = objPhysProps.ComponentList("ACompList")


Dim colOptions

Set colOptions = objComponentList.optionnames

lstNames.Clear

Dim sCol

For Each sCol In colOptions

lstNames.AddItem sCol

Next

End Sub

OutputLogger Object Properties and methods are available for the OutputLogger object.

OutputLogger Properties The following properties are available for the OutputLogger object:

• OutputLogger.FileOutput

• OutputLogger.Height

• OutputLogger.Left

• OutputLogger.MessageCount

• OutputLogger.Messages

• OutputLogger.MessageText

• OutputLogger.Path

• OutputLogger.ScreenOutput

• OutputLogger.Top

• OutputLogger.Width

Note: These methods will fail if the messages window is not currently being displayed. You can ensure that it is by using the ActiveDocument.ShowMessagesWindow method.

OutputLogger.FileOutput

Returns or sets whether run-time output is sent to file.

Example


IF Application.Simulation.OutputLogger.FileOutput = False THEN

Application.Simulation.OutputLogger.FileOutput = True

ENDIF


OutputLogger.Height

Sets the height in points (there are approximately 72 points in an inch) of the Simulation Messages window.

Example


Application.Simulation.OutputLogger.Height = 10

OutputLogger.Left

Sets the horizontal coordinate of the Simulation Messages window.

Example


Application.Simulation.OutputLogger.Left = 20

OutputLogger.MessageCount

Returns the number of lines of messages currently in the Simulation Messages window. Note that this number can change rapidly as more output is generated.

Example


MsgBox "Messages:" & Application.Simulation.OutputLogger.MessageCount

OutputLogger.Messages

This read-only property is a collection of all the messages in the Simulation Messages window.

Example


dim op

dim mescoll

dim acmapp

dim curmsg

set acmapp=application

set op=acmapp.outputlogger

set mescoll=op.messages

msgbox "number of lines in message window" & mescoll.count

for each curmsg in mescoll

msgbox curmsg

next


OutputLogger.MessageText

This read/only property contains a single string which is all the lines present in the Simulation Messages window returned as a single string, with each end of line marked by a carriage return or line feed pair of characters.

OutputLogger.MessageText has two parameters:

• The first line to be returned (0�MessageCount-1)

• The last line to be returned (0..MessageCount-1)

If the second parameter is less than the first, or the first parameters is less than zero, an error will be raised. If the second parameter is greater than the upper limit then no error will be raised and as many lines as available will be returned.

Example


MsgBox Application.Simulation.OutputLogger.MessageText(0,9)

OutputLogger.Path

Sets the path name for the logging file.

Example


Application.Simulation.OutputLogger.Path = "C:\My Simulations\Output.txt"

OutputLogger.ScreenOutput

Sets whether messages are sent to the Simulation Messages window. Takes the logical arguments True and False.

Example


Application.Simulation.OutputLogger.ScreenOutput = True

OutputLogger.Top

Sets the vertical coordinate of the Simulation Messages window.

Example


Application.Simulation.OutputLogger.Top = 45

OutputLogger.Width

Sets the width of the Simulation Messages window.

Example


Application.Simulation.OutputLogger.Width = 150


OutputLogger Methods The following methods are available for the OutputLogger object.

• OutputLogger.ClearWindow()

• OutputLogger.Print()

• OutputLogger.WriteFileHeader()

OutputLogger.ClearWindow()

You can clear the text from the Simulation Messages window.

Example


Application.Simulation.OutputLogger.ClearWindow

OutputLogger.Print()

You can send the contents of the Simulation Messages window to your default printer.

Example


Application.Simulation.Run(True)

Application.Simulation.OutputLogger.Print

OutputLogger.WriteFileHeader()

When you set OutputLogger.FileOutput to true, a log file is opened to contain the output logger messages. At the top of the file, there is normally a line that specifies the user who opened the log file and when the file was opened. The OutputLogger.WriteFileHeader method controls whether this header line is written:

If WriteFileHeader is

Then

True (default) The header line is written

False The header line is not written

If you set the value of the WriteFileHeader method to False, you can compare logger files generated at different times without the difference in the first line appearing.

Example

Running a script from Flowsheet or Model which opens a log file without the header line.

set logger=application.outputlogger

logger.writefileheader=false

logger.path="d:\temp\unittest.txt"

logger.fileoutput=true.


Note: The state of WriteFileHeader is set before the path or fileoutput properties because the line is written as the file is opened.

Results Object Properties and methods are available for the Results object.

Before using the Results object, you must call Results.Refresh() to ensure access to all currently available snapshots and results.

Results Properties The following properties are available for the Results object.

• Results.Interval

• Results.Limit

• Results.RegularSnapshot

• Results.ResultCount

• Results.SnapshotCount

• Results AutoSnapshot

Results.Interval

You can retrieve or set the simulation time interval at which snapshots are taken.

Example


Application.Simulation.Results.Interval = 2.0


Label1.Caption = ACMApp.Simulation.Results.Interval

Results.Limit

Returns or sets the maximum number of snapshots that can exist for the current simulation. When this number of snapshots is reached, the oldest automatically taken snapshot is deleted before a new snapshot is taken.

Example


Application.Simulation.Results.Limit = 20


Label1.Caption = ACMApp.Simulation.Results.Limit


Results.RegularSnapshot

Returns or sets whether regular snapshots are taken during a dynamic run. Read/write Boolean.

Example


Application.Simulation.Results.RegularSnapshot = True

Results.ResultCount

Returns the number of results that are available for the current simulation. This includes all kept results and results contained in result files.

Example


Label1.Caption = ACMApp.Simulation.Results.ResultCount

Results.SnapshotCount

Returns the number of snapshots that are available for the current simulation.

Example


Label1.Caption = ACMApp.Simulation.Results.SnapshotCount

Results.AutoSnapshot

Returns or sets whether snapshots are taken automatically when a simulation is run in any run mode. Read/write Boolean.

Example


Application.Simulation.Results.AutoSnapshot = True

Results Methods The following methods are available for the Results object.

• Results.Compress()

• Results.CopyValues()

• Results.Delete()

• Results.FindResult()

• Results.FindSnapshot()

• Results.GetResult()

• Results.GetSnapshot()

• Results.GetSnapshot().Converged

• Results.GetSnapshot().DateTime

• Results.GetSnapshot().Description

• Results.GetSnapshot().Export


• Results.GetSnapshot().ExportasBinary

• Results.GetSnapshot().RunNumber

• Results.GetSnapshot().SimulationTime

• Results.Import()

• Results.Refresh()

• Results.Rewind()

• Results.TakeSnapshot()

Results.Compress() You can reduce the size of the snapshot files in the working folder for the current problem by using this method. If snapshots or results have been deleted, compress will reclaim the space in the file.

Example


Application.Simulation.Results.Compress()

Results.CopyValues

You can take a snapshot or result and copy the values to the current simulation. This has the same function as the CopyValues button on the Advanced Copy dialog available from the Snapshot Management dialog box.

Application.Simulation.Results.CopyValues has two forms:

CopyValues aResult

This copies the values of all the variables in the same way as the CopyValues button on the Snapshot Management dialog, and is the same as:

CopyValues aResult, True, True, True, True, True, True, "", "~", False, False

The second form takes the following arguments:

Argument Type Example

Result Variant Typically, a variant equated to the value returned by the GetSnapshot or GetResult methods

SourceFixed Boolean False

SourceFree Boolean True

SourceInitial Boolean True

DestinationFixed Boolean False

DestinationFree Boolean True

DestinationInitial Boolean True

SourcePath Text String "B1"

DestinationPattern Text String "~.Temp"

SourceStructural Boolean False

DestinationStructural Boolean False


Note: The last two arguments are optional, and only have meaning for results containing structural parameters that cause structural changes. If both arguments are TRUE, then structural changes will be applied.

To copy the values of all the variables in the same way as the CopyValues button on the Snapshot Management dialog, use:

CopyValues aResult, True, True, True, True, True, True, " ", "~"

Example


Dim aResult

Set aResult = Application.Simulation.Results.GetResult(1)

Application.Simulation.Results.CopyValues aResult, False, True, True, False, True, True, "Reactor", "~.*Tray.Temp"

Dim aSnapshot

Set aSnapshot = Application.Simulation.Results.GetSnapshot(2)

Application.Simulation.Results.CopyValues aSnapshot

Results.Delete()

You can delete an existing snapshot or result. The single argument is a snapshot or result object returned by either GetSnapshot or GetResult.

Example

Running a script from Flowsheet or Model, this example deletes all snapshots with the description "example":

Dim aSnapshot

Dim iCount

Application.Simulation.Results.Refresh

For iCount = 0 To Application.Simulation.Results.SnapshotCount-1

Set aSnapshot = Application.Simulation.Results.GetSnapshot(iCount)

If (aSnapshot.Description = "example") Then

Application.Simulation.Results.Delete (aSnapshot)

End If

Next


Results.FindResult()

You can find a result from the description. As result descriptions are not necessarily unique, this will find the first result with the given description. A result object is returned.

Example


Set aResult = Application.Simulation.Results.FindResult("Steady State")

Results.FindSnapshot()

You can find a snapshot from the description. As snapshot descriptions are not necessarily unique, this will find the first snapshot or result with the given description. A snapshot object is returned.

Example


Set aSnapshot = Application.Simulation.Results.FindSnapshot("Steady State")

Results.GetResult()

You can select a result from a numbered list. The first result in the list is numbered 0.The last item is numbered Results.ResultCount ( ) �1. Note that all the properties available for GetSnapshot are also available for GetResult.

Example


Dim aResult

Set aResult = Application.Simulation.Results.GetResult(4)

Results.GetSnapshot()

You can select a snapshot from a numbered list. The first snapshot in the list is numbered 0. The last item is numbered Results.SnapshotCount ( ) �1. Note that all the properties available for GetResult are also available for GetSnapshot.

Example


Dim aSnapshot

Set aSnapshot = Application.Simulation.Results.GetSnapshot(4)

Results.GetSnapshot().Converged

Returns whether a selected snapshot (or result, if GetResult is used) was converged (1 = converged, 0 = not converged). Integer, read-only.

Example



Dim aSnapshot

Dim iCount


For iCount = 0 To Application.Simulation.Results.SnapshotCount-1

Set aSnapshot = Application.Simulation.Results.GetSnapshot(iCount)

If (aSnapshot.converged = 1) Then

application.msg asnapshot.description & "is converged"

End If

Next

Results.GetSnapshot().DateTime

Returns at what date and time a selected snapshot (or result, if GetResult is used) was taken.

Example


Label1.Caption = ACMApp.Simulation.Results.GetSnapshot(4).DateTime

Results.GetSnapshot().Description

Sets or returns the description name of a selected snapshot (or result, if GetResult is used). String, read-write.

Example


Label1.Caption = ACMApp.Simulation.Results.GetSnapshot(4). Description

Results.GetSnapshot().Export

Exports a snapshot to an ASCII result file with an extension of .asnp. You can then import the file into any simulation using the Results.Import method.

This command also works for GetResults.

Example

The following example will export the contents of snapshot number 4 to the given file:

Application.Simulation.Results.GetSnapshot(4). Export "\aspen\result1.asnp"


Results.GetSnapshot().ExportasBinary

Exports a snapshot (but not results) to a binary file with extension .snp. You can export a snapshot directly to the working directory of another simulation, where it is picked up automatically by that simulation as a result.

Example

The following example exports the contents of snapshot number 4 to the given binary file:

Application.Simulation.Results.GetSnapshot(4). ExportasBinary "..\mysimulation\result1.snp"

Results.GetSnapshot().RunNumber

Returns the run number for the selected snapshot (or result, if GetResult is used).

Example


Label1.Caption = Application.Simulation.Results.GetSnapshot(4). RunNumber

Results.GetSnapshot().SimulationTime

Returns at what simulation time a selected snapshot (or result, if GetResult is used) was taken.

Example


Label1.Caption = ACMApp.Simulation.Results.GetSnapshot(4). SimulationTime

Results.Import()

You can import a result from an ASCII result file into the current simulation. It will be added as a kept result and will be included on saving changes to your input file. The default file extension for ASCII result files is .asnp.

Example


Application.Simulation.Results.Import "\aspen\result1.asnp"

Results.Refresh()

Before using any of the Automation methods and properties, you need to issue a Refresh command. This command ensures that automation has access to all the currently available snapshots and results in the simulation.

If you do not issue a Refresh command, you may find that the snapshots and results to which you have access do not match the snapshots and results in the current simulation.

Example





ACMApp.Simulation.Results.Refresh

Results.Rewind()

You can rewind to a snapshot. This causes the values of all variables in the simulation to be set to the values stored in the snapshot. This has the same effect as Rewind from the Snapshot Management dialog box.

Note: You cannot rewind a result.

Example


Application.Simulation.Results.Rewind aSnapshot

Results.TakeSnapshot()

You can take a snapshot of the current simulation results. Takes a string of text as an argument for the snapshot name.

Example


Application.Simulation.Results.TakeSnapshot("test1")

UOM Object The following methods are available for the UOM object. For more information, see the Modeling Language Reference, Chapter 2, Using Units of Measurement.

• Uom.AddUOMSet

• Uom.AddPhysicalQuantity

• Uom.DefineConversion

• Uom.SelectUOMSet

• Uom.ConvertToBaseUOM

• Uom.ConvertFromBaseUOM

Block, Stream, Structure and Flowsheet Objects All the properties of blocks and streams in the modeling language are exposed as properties of the corresponding Microsoft Visual Basic objects.


For example, to access the feed port object of a mixer M1 in the flowsheet, you write the following:

Mixer = Simulation.Flowsheet.M1.feed

To access stem position variable in a valve block called V1:

Set VarInput = V1.ValveStemPosition

You can also use a number of additional properties and methods, which are common to block, stream, and flowsheet objects. This section describes these methods.

Each of these object types also has certain special methods that are unique to each object type.

Methods Common to Block, Stream, Structure and Flowsheet Objects The following methods are common to block, stream, and flowsheet objects:

Method Description

Name() The name of the object relative to its parent model

GetPath() The full path to an object from the flowsheet

TypeName() The name of an objects type

BaseTypeName The BaseTypeName method returns the name of the base type of an object that is the base of the derivation tree if any. If the model is not derived it will return the same as the TypeName method.

Resolve() Convert a string path to an object

Blocks() Collection of block objects

Block.IsKindOf Collection of block objects

Streams() Collection of stream objects

Ports() Collection of port objects

ControlPorts() Collection of control port objects

Forms() Collection of Form Objects

FindMatchingVariables() Collection of variables matching a given pattern

GetVariableValues() Collection of many values in one call (fast method)

UpdateVariables() Update the object variables with the values from the server

Global() Property through which to access global variables

DisableIncrementalUpdate() Suspend incremental updates

EnableIncrementalUpdate() Resume incremental updates

BeginLongOperation() Disable server busy dialog boxes

EndLongOperation() Enable server busy dialog boxes

Invoke() Runs a named script

InvokeLibraryScript Runs a named library script

LaunchFormView() Display a model form

LaunchCustomFormView() Displays a form based upon a specified cusom ocx control


Name and GetPath Methods

All blocks and streams have a Name method and a GetPath method:

This method Returns a string which is

Name() The path to the object relative to its parent model

GetPath() The full path to an object

Example

The following examples show the use of GetPath and Name:

Str = B1.stage(1).GetPath 'result is "B1.stage(1)"

Str = B1.stage(1).Name 'result is "stage(1)"

In the case of a flowsheet block or stream that has a quoted name in the language input file (for example, Streams("1") as MaterialStream;), the Name method will also remove the Streams("") part of the path, as illustrated in the next example:

Str = Streams("1").GetPath 'result is "Streams(1)"

Str = Streams("1").Name 'result is "1"

TypeName Method

The TypeName method returns the name of the type of an object.

Example

The following example shows the use of the TypeName method:

Str = Streams("1").TypeName 'result is "MaterialStream"

Resolve Method

In some situations, you may need to be able to convert a string that represents the path to an object, to the object itself. To do this for block, stream, and flowsheet objects, you can use the Resolve method, which takes a string argument and returns an object.

Example

At the Flowsheet level:

' Resolve the block "Flash1"

dim b1

set b1 = resolve("Flash1")

application.msg "Resolve Flash1 gave us " & b1.getpath

'Resolve the stream "Stream1"

dim s1

set s1 = resolve("Stream1")

application.msg "Resolve Stream1 gave us " & s1.getpath


' Get variable "MassHoldUp" from b1

dim var1

set var1 = b1.resolve("MassHoldUp")

application.msg "b1.Resolve MassHoldUp gave us " & var1.getpath

' Get variable "TotalVolume" directly

dim var2

set var2 = resolve("Flash1.TotalVolume")

application.msg "Resolve Flash1.TotalVolume gave us " & var2.getpath


Example

The following automation example shows how to read the name of a variable from an Excel sheet and write the value in the next cell.

Private Sub CommandButton1_Click()

Dim var As Object

Set acmObj = GetObject("d:\FiveTanks.acmf")

acmObj.Application.Visible = True

Set oFlowsheet = acmObj.Application.Simulation.Flowsheet


For i = 1 To 10

Set var = oFlowsheet.Resolve(Sheet1.Cells(i + 1, 1).Value)


Err.Clear clear error

Sheet1.Cells(i + 1, 2).Value = "N/A"

Else

Sheet1.Cells(i + 1, 2).Value = var.Value

End If

Next

End Sub

ShowFlowsheetWindow

Show the flowsheet window associated with the hierarchy block. This method will fail is the current items is not a hierarchy.

Optional arguments can be used to give the window position and size.

ShowFlowsheetWindow x position, y position, width, depth

Running a script in a hierarchy block:

ShowFlowsheetWindow 100,0,180,600

Blocks Collection Properties and Methods

You can access information about all the blocks on your flowsheet or in other blocks or streams. Note that structures cannot contain blocks or streams. The information about the blocks is returned as a collection. You can use the standard collection properties and methods:


Method or Property

Description

Count Integer, the number of block objects in the collection

Item([integer] Index) Gets the block object at position Index in the collection. The first item is at position 1, and the last at position Count.

Item([string] Name) Returns the block object whose name matched Name

You can use the information to read the names of the blocks on your flowsheet and determine the models used by the blocks, and you can also use the information in For loops.

Example

Using external Microsoft® Visual Basic®:

Dim BlockCollctn

Set BlockCollctn = ACMApp.ActiveDocument.Flowsheet.Blocks

ACMApp.Msg "Number of blocks on Flowsheet is " & BlockCollctn.Count

FOR EACH i IN BlockCollctn

ACMApp.Msg "Block " & i.Name & " uses Model " & i.TypeName & "."

NEXT

From a script at Flowsheet level:

Dim BlockCollctn

Set BlockCollctn = Blocks

Application.Msg "Number of blocks on Flowsheet is " & BlockCollctn.Count

FOR EACH i IN BlockCollctn

Application.Msg "Block " & i.Name & " uses Model " & i.TypeName & "."

NEXT

Block.IsKindOf

Returns true if the object accessed is of the type given, false if not. 1 argument is required which can be:

�Flowsheet�

�Hierarchy�

�Block�

�MaterialStream�

�ControlStream�


�ConnectionStream�

�Stream�

Note that these are not exclusive so a material stream will return true with the arguments �Stream� or �MaterialStream�.

Example


for each blk in Blocks

if blk.IsKindOf("Hierarchy") then

application.msg "Hierarchy " & blk.name

for each sblk in Blocks

application.msg " " & sblk.name

next

else

application.msg blk.name

end if

next

In this example the blocks in a hierarchy are processed.

Streams Collection Properties and Methods

You can access information about all the streams on your flowsheet or in other blocks or streams. Note that structures cannot contain blocks or streams. The information about the streams is returned as a collection. You can use the standard collection properties and methods:

Method or Property

Description

Count Integer, the number of stream objects in the collection

Item([integer] Index) Gets the stream object at position Index in the collection, the first item is at position 1, and the last at position Count

Item([string] Name) Returns the stream object whose name matched Name

You can use the information to read the names of the streams on your flowsheet and determine the models used by the streams, and you can also use the information in For loops.

Example

Using external Microsoft® Visual Basic®:

Dim Using external Microsoft Visual Basic:

Dim StreamCollctn

StreamCollctn = ActiveDocument.Flowsheet.Streams


ACMApp.App.Msg "Number of Streams on Flowsheet is " &

StreamCollctn.Count

FOR EACH i IN StreamCollctn

ACMApp.Msg "Stream " & i.Name & " uses Stream Model " & i.TypeName

NEXT


Dim StreamCollctn

Set StreamCollctn = Streams

Application.Msg "Number of Streams on Flowsheet is " & StreamCollctn.Count

FOR EACH i IN StreamCollctn

Application.Msg "Stream " & i.Name & " uses Stream Model " & i.TypeName

NEXT

Structures Collection Properties and Methods

You can access information about all the structures contained in a block, stream or structure. Note the flowsheet itself cannot contain structures. The information about the structures is returned as a collection. You can use the standard collection properties and methods: Method or Property

Description

Count Integer, the number of structure objects in the collection

Item([integer] Index) Gets the structure object at position Index in the collection, the first item is at position 1, and the last at position Count

Item([string] Name) Returns the structure object whose name matched Name

You can use the information to read the names of the structures and determine the models used by the structures, and you can also use the information in For loops.

Example

Using external Microsoft Visual Basic:

Dim StructureCollctn

StructureCollctn = ActiveDocument.Flowsheet.B1.Structures

ACMApp.App.Msg "Number of Structures in B1 is " &

StructureCollctn.Count

FOR EACH i IN StructureCollctn


ACMApp.Msg "Structure " & i.Name & " uses Structure Model " & i.TypeName

NEXT


Dim StructureCollctn

Set StructureCollctn = B1.Structures

Application.Msg "Number of Structures on Flowsheet is " & StructureCollctn.Count

FOR EACH i IN StructureCollctn

Application.Msg "Structure " & i.Name & " uses Structure Model " & i.TypeName

NEXT

Port and Control Ports Collection Methods and Properties

The Ports and ControlPorts methods return collections of port objects. The Ports collection contains all the conventional ports and multiports, and the ControlPorts collection contains all the control ports in the object. Note that structures cannot contain ports. You can use the standard collection properties and methods:

Method or Property

Description

Count Integer, the number of port objects in the collection

Item([integer] Index) Gets the port object at position Index in the collection, the first item is at position 1, and the last at position Count

Item([string] Name) Returns the port object whose name matched Name

Example

This script will print the names of all the ports in block "b1":

set b = Blocks("b1")

application.msg "Ports of " & b.name

for each p in b.Ports

application.msg " " & p.name

next

application.msg "Control ports of " & b.name

for each p in b.ControlPorts

application.msg " " & p.name

next


FindMatchingVariables Method

The method FindMatchingVariables takes from 1 to 7 arguments. It returns a collection of variable objects which match the specifications in the arguments when they are applied to the current object. All the arguments are optional, if no arguments are given all variables and parameters will be returned including inactive ones.

Argument 1 is a string argument which is used as a pattern to match against all the variables contained within the object. The pattern syntax is the same as that used for snapshots and Variable Find.

Argument 2 is a string to match the spec attribute of the required variables. This should be a delimited list of any combination of �Fixed�, �Free�, �Rateinitial� or �Initial�. E.g. �fixed free initial� will return all but rateinitial variables. It is case insensitive.

Argument3 is a string giving the variable type to be used. Only variables of that type will be returned. It is case insensitive.

Argument 4 is Boolean and specifies if parameters should be included. The default is true.

Argument 5 is Boolean and specifies if algebraic variables should be included. The default is true.

Argument 6 is Boolean and specifies if state variables should be included. The default is true.

Argument 7 is Boolean and specifies if inactive variables should be included.

The default is true.

Example

At the Flowsheet level:

'Get a collection of all fixed variables in block B1

set vars = blocks("B1").FindMatchingVariables("~", �fixed�,��,false,true,true,false)

application.msg "Listing fixed variables for flowsheet..."

for each v in vars

application.msg " " & v.name & ".spec = " & v.spec

next

This will list out all variables in B1 with a spec of fixed excluding parameters and inactive variables.

GetVariableValues Method

When values are required for many variables there is a considerable overhead in performance getting values one at a time when they are required in an external application such as Excel or in a Visual Basic application. This method allows you to get many values in one call, which is much faster. It can be used to get values for a list of variable paths, variable objects, or variable collections in the same way as the UpdateVariables Method except that GetVariableValues always requires an argument.


Note that the method returns an array of variants that can hold values other than numerical data. Care must be taken if a real array is used to receive values as a failure will occur for non-numeric values e.g. from string parameters.

Example

Set vars1 = ACMFlowsheet.FindMatchingVariables("B1~")

Set vars2 = ACMFlowsheet.FindMatchingVariables("B2~")

Set vars = ACMFlowsheet.NewVariableSet

vars.AddValues vars2, vars1

ACMFlowsheet.UpdateVariables vars

novars = 0

varvalues = ACMFlowsheet.GetVariableValues(vars)

For Each varvalue In varvalues

novars = novars + 1

Sheet1.Cells(novars + 1, 3) = varvalue

Next

In this example a collection of variable objects is assembled into vars and then used in UpdateVariables to make sure the values are up to date and then in GetVariableValues to get an array of values. The For Each statement goes through each value in vars and places it in a cell in an Excel sheet.

UpdateVariables Method

When it is necessary to have up-to-date data for a variable, it is retrieved on demand from the server. If you know in advance that you are going to access a number of variables, it is more efficient to update all the relevant variables in a single operation. The UpdateVariables method enables you to do this. When it is used with no arguments, UpdateVariables updates all the variables in the scope of the object on which it is invoked. It can also update a list of variable paths, variable objects, or variable collections.

Example

Running a script at Flowsheet level:

B1.UpdateVariables 'Updates all the variables in the block B1

Set var = B2.Height

UpdateVariables("B2.Vol",var) 'Updates the values of B2.Vol and B2.Height


ACMApp.Simulation.Flowsheet.B1.UpdateVariables 'Updates all the variables in the block B1

Set var = ACMApp.Simulation.Flowsheet.B2.Height

ACMApp.Simulation.Flowsheet.UpdateVariables("B2.vol", var)


'Updates the values of B2.Vol and B2.Height

Global Method

You can access most variables directly, using their property path from the flowsheet. However, because global variables are not in the scope of the flowsheet, the Global method is provided to enable you to access global variables.

Example

The following example shows how to access the global variable "P_Max" in a Flowsheet script:

Set var = Global.P_Max

Invoking Scripts

To invoke a script contained in a block, stream or in a flowsheet, use the path to that script.

You can pass arguments to and receive arguments back from a library script. Arguments added after the library name and script name will be passed into the library script:

e.g. Flowsheet.B1.InvokeLibraryScript("Custom Modeling", "LibraryScript","B1")

The script LibraryScript will receive the string B1 in the variable input(1).

Examples

Running a script at Flowsheet level from external Microsoft Visual Basic:

ACMApp.ActiveDocument.Flowsheet.SetUpScript

Running script at Block level from external Microsoft® Visual Basic®:

ACMApp.ActiveDocument.Flowsheet.B1.BlockScript

Running script at Flowsheet level:

SetUpScript

Running script at Block level from Flowsheet level:

B1.BlockScript

Note: You can also invoke scripts given a string path using the Invoke method, for example:

Flowsheet.Invoke"B1.BlockScript"

is equivalent to:

Flowsheet.B1.BlockScript

To invoke a script that is in a library script's folder, use InvokeLibraryScript. This takes the name of the library as the first argument and the name of the script as the second argument, for example:


Flowsheet.B1.InvokeLibraryScript"Custom Modeling", "LibraryScript"

If the library is given as an empty string (that is, ""), all libraries are searched to find the named script.

DisableIncrementalUpdate and EnableIncrementalUpdate Methods

By default, whenever a change is made to the simulation that will require the update of assignments, connections, or equations, the update happens immediately. For example, the following script will perform two incremental updates, one after each assignment:

'Incremental update happens after this assignment

B1.PropMode = "Local"

'and again after this assignment

B2.Nstages = 10

To batch together a number of simulation changes, the following methods are provided on the Flowsheet object:

Method Description

DisableIncrementalUpdate Call this to stop incremental updates

EnableIncrementalUpdate Call this to enable incremental updates

The methods DisableIncrementalUpdate and EnableIncrementalUpdate operate on a lock counter which is incremented by DisableIncrementalUpdate and decremented by EnableIncrementalUpdate. This allows scripts called within scripts to use Disable and EnableIncrementalUpdate without overriding the lock on incremental updating that may have been established in the calling script.

When a script is invoked via the GUI, the lock count is automatically restored to its original state when the script completes. If these methods are used from external automation, ensure that there are matching calls to DisableIncrementalUpdate and EnableIncrementalUpdate.

Example

To batch the operations of the above script:

'do not update until we have completed edit


B1.PropMode = "Local"

B2.NStages = 10

'incremental update happens after this command



BeginLongOperation and EndLongOperation Methods

Sometimes in a script, a lengthy operation may need to be performed. While the script is executing, it is unable to process normal windows messages. If the condition lasts a long time, a Server Busy dialog box is automatically displayed. You can use the following methods to disable the display of this dialog box:

Method Description

BeginLongOperation() Call this before starting the long operation

EndLongOperation() Call this after the operation is complete

Example

The following example shows the use of BeginLongOperation and EndLongOperation:

BeginLongOperation 'Disable server busy dialogs

ExcelObject.Calculate

EndLongOperation 'Re-enable the server busy dialogs

Invoke Method

This method runs a script, given the path to that script.

Example

The following example shows the use of Invoke:

Invoke"B1.Initialize"

LaunchFormView, LaunchCustomFormView and LaunchLibraryFormView Methods

These methods enable you to display a named form on a model. LaunchFormView is used for a form that is defined within the model. LaunchLibraryFormView was used for a form that is defined in a library. Changes to the way form configuration data is saved in Aspen Custom Modeler 2004.1 mean that LaunchLibraryFormView is becoming redundant.

To launch a form based on a custom ocx, use the new automation method: LaunchCustomFormView.

LaunchCustomFormView Parameters

The LaunchCustomFormView parameters are:

LaunchCustomFormView(Progld As String, FormName = NULL As String, x=0 As Integer, y=0 As Integer, cx=0 As Integer, cy=0 As Integer).

This takes 1, 2 or 6 parameters:

• Progld is the progid of the custom form to be loaded.

• FormName is the caption to appear in the frame of this form.


• The remaining parameters are the x, y co-ordinates and size of the form.

Example

The following example shows the use of LaunchFormView:

B1.LaunchFormView("AllVariables")

Forms Collection Methods and Properties

The Forms method returns collections of form objects. You can use the standard collection properties and methods: Method or Property Description

Count Integer, the number of port objects in the collection

Item([integer] Index) Gets the port object at position Index in the collection, the first item is at position 1, and the last at position Count

Item([string] Name) Returns the port object whose name matched Name

Example:





next

VariablesPaths Property

VariablesPaths is the collection of strings which contains the names of the variables selected on a form.

Example:





next

Forms Property

Forms property is the collection of forms of the parent object.


Example:





next

Tasks Property

Tasks property is the collection of tasks of the owning object.

Example:

The following script prints the name of each task in the current object and whether it is active or not.

for each task in tasks if task.active then

MsgBox task.name & " Task Active"

else

MsgBox task.name & " Task Inactive"

end if

next

Flowsheet-Specific Methods The Flowsheet object supports all the methods common to flowsheets, blocks, and streams. For more information on common methods, see Methods Common to Block, Stream, and Flowsheet Objects:

• AddBlock()

• AddStream()

• RemoveBlock()

• RemoveStream()

• IsValidBlockName()

• IsValidStreamName()

• CreateTask()

• DeleteTask()

• EditTask()

• GetTaskText()

• CreateScript()

• EditScript()

• DeleteScript()

• GetScriptText()


• StructureContainers

• AddStructureContainer • RemoveStructureContainer

Editing the Flowsheet

You can use the following methods to edit a flowsheet:

Method Description

AddBlock([string] BlockType, [optional, string] BlockName)

Add a block of type BlockType to the flowsheet with name BlockName. If BlockName is not given, an auto-generated name is used. Returns the block object that has been added.

AddStream([string] StreamType, [optional, string] StreamName)

Add a stream of type StreamType to the flowsheet with name StreamName. If StreamName is not given, an auto- generated name will be used. Returns the stream object that has been added.

RemoveBlock([string] BlockName)

Removes the block BlockName from the flowsheet.

RemoveStream([string] StreamName)

Remove the stream StreamName from the flowsheet.

IsValidBlockName([string] BlockName)

Returns true if BlockName can be used as a valid name for a new block.

IsValidStreamName([string] StreamName)

Returns true if StreamName can be used as a valid name for a new stream.

Example

This flowsheet script example adds a block to the flowsheet, first checking that the name is valid:

BlockType = "PID"

BlockName = "cntrl"

if (Not IsValidBlockName(BlockName) ) then

MsgBox "Block name """ & BlockName _

& """ is invalid or already exists"

else

AddBlock BlockType, BlockName

CreateTask (TaskName, TaskText)

CreateTask creates a new task at the flowsheet level. It takes two parameters. The first is a string, which is the name of the task. The second is a string, which contains the full text of the task (each line terminated by a carriage return or a line feed).

Example


tasktext="task Task1 runs when time == .1" & vbcrlf _

& "print ""task running"" ;" & + vbcrlf _


& "end"

CreateTask "Task1" , tasktext

DeleteTask(TaskName)

DeleteTask deletes an existing task at the flowsheet level. It takes one string parameter, which is the name of the task to be deleted.

Example


DeleteTask "Task1"

EditTask(Taskname, TaskText)

Replaces the language text of TaskName with TaskText and recompiles.

GetTaskText(Taskname): result string

Returns the language text for the named task.

CreateScript(Scriptname, ScriptText)

Creates a new script called ScriptName and text ScriptText.

EditScript(Scriptname, ScriptText)

Replaces the language text of ScriptName with ScriptText.

DeleteScript(Scriptname)

Deletes script the script called scriptname.

GetScriptText(Scriptname): result string

Returns the language text for the named script.

StructureContainers

StructureContainers �Structure Container Name�

This automation method returns the structure container object with the given name. Alternatively if the argument is omitted it returns a collection of structure container objects

AddStructureContainer

AddStructureContainer "StructureContainer Name"

Creates a structure container object under the flowsheet with the given name.

RemoveStructureContainer

RemoveStructureContainer "StructureContainer Name"

Removes a structure container object with the given name from the flowsheet.


Stream-Specific Methods You can use all the methods common to flowsheets, blocks, and streams on the Stream object. For more information on common methods, see Methods Common to Block, Stream, and Flowsheet Objects:

• IsControlSignal()

• InputPort()

• InputConnected()

• InputBlockPort()

• OutputPort()

• OutputConnected()

• OutputBlockPort()

• CanConnectInput()

• ConnectInput()

• CanConnectOutput()

• ConnectOutput()

For control signal streams, the following methods are also available:

• InputVariable()

• OutputVariable()

IsControlSignal Method

The Streams collection includes both conventional streams and control signals. To distinguish a control signal from a conventional stream, the IsControlSignal method returns True for control signals.

Example

This script will print the names of all control signals:

set coll = streams

for each s in coll

if s.IsControlSignal then

application.msg " " & s.Name & " is a control signal"

end if

next

Querying the Connectivity of a Stream

The following methods enable you to determine the topology of a flowsheet by enumeration of its streams:

Method Description

InputPort() The stream's input port object

InputConnected() True if the streams input is connected

InputBlockPort() The block port to which the stream input is connected

OutputPort() The streams output port object


OutputConnected() True if the streams output is connected

OutputBlockPort() The block port to which the stream input is connected

For control signals, the following methods are also provided:

Method Description

InputVariable() The variable the control signals input is connected to.

OutputVariable() The variable the control signal output is connected to.

Examples

The following flowsheet script prints the names of all the stream input and output ports:

set coll = streams

for each s in coll

application.msg "The name of the Input Port of " & s.name _

& " is " & s.InputPort.Name

application.msg "The name of the Output Port of " & s.name _

& " is " & s.OutputPort.Name

next

This script prints the topology of the flowsheet:

set app = application

set coll = streams

app.msg "Now iterating through the streams"

for each s in coll

app.msg "Stream " & s.name

if s.InputConnected then

set p = s.InputBlockPort

set b = p.Parent

app.msg " Input is connected to " & p.GetPath _

& " of block " & b.name

if s.IsControlSignal then

app.msg " Input variable is " & s.InputVariable.Name

end if

else

app.msg " Is a Feed Stream"

end if

if s.OutputConnected then


set p = s.OutputBlockPort

set b = p.Parent

app.msg " Output is connected to " & p.GetPath _

& " of block " & b.name

else

app.msg " Is a Product Stream"

end if

next

Changing the Connectivity of a Stream

To change the connectivity of the flowsheet, you can use the following methods for flowsheet level streams:

Method Description

CanConnectInput ([string] BlockPortName)

True if the streams input can be connected to the named block port

ConnectInput ([string] BlockPortName)

Connects the stream input to the named block port

DisconnectInput() Disconnects the stream input

CanConnectOutput ([string] BlockPortName)

True if the streams output can be connected to the named block port

ConnectOutput ([string] BlockPortName)

Connects streams output can be connected to the name block port

DisconnectOutput() Disconnects the stream output

Control signals support an equivalent set of methods but the arguments differ:

Method Description

CanConnectInput ([string] VariablePath, [optional, string] ControlPort)

Returns true if the control signals input can be connected to the named variable via the specified control port. If the control port is not specified then the default control port will be used.

ConnectInput ([string] VariablePath, [optional, string] ControlPort)

Connects the control signal input to the named variable via the specified control port. If the control port is not specified the default control port will be used.

DisconnectInput() Disconnects the control signals input.

CanConnectOutput([string] VariablePath, [optional, string] ControlPort)

Returns true if the control signals output can be connected to the named variable via the specified control port. If the control port is not specified then the default control port will be used.

ConnectOutput ([string] VariablePath, [optional, string] ControlPort)

Connects the control signal output to the named variable via the specified control port. If the control port is not specified the default control port will be used.

DisconnectOutput() Disconnects the control signals output.


Examples

This flowsheet script will add a new block called Mixer and then connect existing streams to the Mixer block:

AddBlock "Makeup", "Mixer"

Streams("IS0").ConnectOutput "Mixer.FeedInlet"

Streams("IS6").ConnectOutput "Mixer.RecycleInlet"

Streams("IS1").ConnectInput "Mixer.MixerOutlet"

This flowsheet script will add a control signal and a PID block, then connect the input of the PID block to the variable Mixer.Ratio:

AddStream "ControlSignal", "c1"

AddBlock "PID", "Cntrl"

Streams("c1").ConnectInput "Mixer.Ratio"

Streams("c1").ConnectOutput "cntrl.pv"

Port Object All the properties of ports in the modeling language are exposed as properties of the port object. For example, to access the flow variable of the feed port property of a mixer M1 in the flowsheet you can write:

FlowVar = Simulation.Flowsheet.M1.feed.flow

You can also use the following additional methods for port objects:

Method Description

Name() The name of the object relative to its parent model

GetPath() The full path to an object from the flowsheet

TypeName() The name of the type of an object

Resolve() Convert a string path to an object

Name and GetPath Methods for Ports The Name method returns a string which is the path to the port relative to its parent model. In contrast, the GetPath method will return the full path to the port.

Example

The following examples show the use of Name and GetPath:

Str = B1.Feed.GetPath 'result is "B1.feed"

Str = B1.Feed.Name 'result is "feed"


Testing Whether a Port is Connected To determine whether a conventional port is connected, you can check the value of the IsConnected parameter. If the port is a multiport, you must test whether the Connection array is non-empty.

Examples

The following example tests whether a conventional port is connected.

In a script:

If( B1.Feed.IsConnected.Value ) then

application.msg "B1.Feed is connected"

End if

The next example tests whether a multiport feed is connected:

If( B1.Feed.Connection.Count > 0 ) then

application.msg "B1.Feed is connected"

End if

The next example iterates over the connection ports of a multiport:

For each p in B1.Feed.Connection

application.msg " connection " & p.Name

Next

In ACM modelling language:

If( Feed.IsConnected) then ...

Testing Whether a Port is Connected to Hierarchy Connector or Is Linked The IsLinked parameter can be used to test if a stream is connected to an off sheet connector in a hierarchy block. It can also be used to test if a port in a sub-model has been linked to a port in a containing model.

Examples

The following example tests whether a conventional port is linked.

From a script:

If( S1.Source.IsLinked.Value ) then application.msg "S1.Feed is connected" End If

In ACM modelling language:

If( Source.IsLinked) then ...


Variable Object All the language attributes of variables and parameters are exposed as properties of the Variable object in Microsoft® Visual Basic®.

Example


'Get the current value of temperature

realValue = B1.Temperature.value

'Change the current value of temperature

B1.Temperature.Value = 100.0


Set var = ACMApp.ActiveDocument.Flowsheet.B1.Temperature

'Get the current value of temperature

realValue = var.value

'Change the current value of temperature

var.value = 100.0

Note: The following will not return the value of B1.Temperature:

realValue = B1.Temperature 'This is an error

Units of Measurement For attributes that support UOM scaling (for example, value and derivative of RealVariable types) the example calls under Variable Object.

To obtain the value of a variable in a specific set of units use the following syntax:

'obtain the value in units of C centigrade = B1.T.Value("C") 'set the value in units of F B2.T.Value("F") = 1.8*centigrade + 32

There are three special unit strings:

"CurrentUnits" Scales the attribute to the current display units.

"BaseUnits" Forces the attribute to be returned in base units.

"GlobalUnits" Scales the attribute according to the current selected global units set (for example, in US will be scaled to Farenheight irrespective of whether the variables units attribute has been set).

The current display units for a variable can be accessed via the units string property, for example:


UOMstring = B1.x.units

The correct global units for a variable can be looked up, even if the current display units are different. For example, if the global UOM is set to SI but a mass variable stemmass is set to be displayed in lbs then the following string will return Kg:

B1.stemmass.defaultunit

Working with Set Attributes When a variable attribute is a set, the object returned is a StringSet collection object or IntegerSet collection object, as appropriate. This collection is a copy of the attribute's value: it can be enumerated as per conventional collections, and also supports AddValues and RemoveValues methods for modifying the contents of the set collection.

Use StringSet and IntegerSet collection objects to overwrite the existing contents of a set attribute. Note that changing the contents of the set collections does not change the value of the attribute.

To create a new StringSet or IntegerSet collection object:

• Use either the NewStringSet method or NewIntegerSet method, as appropriate. Both methods are available with any object that can contain variables (for example, blocks, streams or ports).

To change the value of the set attribute:

• Assign the collection to the attribute.

Examples

The first example obtains the value of an attribute, modifies a collection, and assigns the collection to the attribute:

set index1set = B1.index1.value 'Gets the value of the stringset

index1set.RemoveValues "ABC","XYZ" 'Remove "ABC" and "XYZ" from collection

index1set.AddValues "FGH" 'Add string "FGH"

B1.index1.value = index1set 'Assigns the set collection to the modified stringset

The next example creates a new set object and assigns it to the attribute:

set myset = B1.NewStringSet 'Create a new string set

myset.AddValues "A1","A2" 'Add some strings

myset.AddValues("A3")

B1.index1.value = myset 'Assigns the set collection to the new stringset

The final example shows the other methods available with StringSet and IntegerSet collection objects:

set myset = B1.index1.value


Application.msg myset.Name ' This is the full string set as text

for I = 1 to myset.Count ' Can loop through the set getting individual strings

Application.msg myset.Item(I)

next

About the History Method The values of variables are saved for a simulation when:

• The Record property of the variables have been set to True before running the simulation.

• In Run settings, Record History for All Variables was selected before running the simulation.

The History method gives you access to the recorded history of a variable for the current simulation run. The recorded history is a collection of values for a variable, recorded over a period of time, at regular intervals.

This collection of values is built from the information stored in the server when the history method is invoked. You can build the set of values in two ways:

• Invoke the method with arguments. The order for the arguments is the start time, the end time, and the interval.

• Invoke the method without arguments. The start time is 0, the end time is the current time, and the interval is set to the current value of the communication interval. When the specified end time is greater than the current time, the current time is used.

The syntax for the History method is:

method history([in: real, optional] StartTime, [in: real, optional] EndTime, [in: real, optional] Interval) result: history collection

The parameters are all optional and are as follows:

StartTime Time of the earliest point to be included in the history,

default=0.0

EndTime Time of the latest point to be included in the history, default=current simulation time

Interval Time interval between points in the history.

To get the full history of a variable use the following syntax:

set hist = b1.x.history

When the history collection is returned, the actual StartTime, EndTime, and Interval are available as read-only properties of the collection.


Note. You should access the methods and properties on the object returned by the history method rather than using the history method again as this will get the history again. e.g. b1.x.history.interval If you have previously used the history method with arguments to specify time range or interval the above statement will overwrite that history with the default range and interval. Using the history method repeatedly will also be slower.

Example

The following example shows the history starting from time 1 and ending at time 2, with an interval of 0.1:

set hist = Blocks("B1").stage(1).T.history (1, 2, 0.1)

app.msg "History, number of data points: " & cstr(hist.count)

app.msg " start time = " & cstr(hist.starttime)

app.msg " end time = " & cstr(hist.endtime)

app.msg " interval = " & cstr(hist.interval)

History Properties and Methods Properties and methods are available for History.

History Properties

The parent property of the history collection will return the variable to which the history applies.

The following properties are available for History:

• History.Count

• History EndTime

• History.Interval

• History.StartTime

• History.Units

History.Count

Returns the number of data points in this history. It is a read-only property.

Example

set hist = Blocks("B1").stage(3).T.history

npoints = hist.count

History.EndTime

Returns the end time of the history. It is read-only property.


If invoked before any simulation has taken place or after the simulation has been restarted, it returns -1. If invoked after an initialization or steady state run, it returns 0.

Example

set hx = B1.x.history

Application.Msg "End time " & Cstr(hx.endtime)

History.Interval

Returns the value of the time interval which was set when the variable history was created. It is read-only property.

Example


Application.Msg "Interval " & Cstr(hx.interval)

History.StartTime

Returns the start time of the history (double). It is a read-only property.

If invoked before any simulation has taken place or the simulation has been restarted, it returns -1.

If invoked after an initialization or steady-state run, it returns 0.

Example


Application.Msg "Start time " & Cstr(hx.starttime)

History.Units

By default, the values returned by the collection are in the base units of the variable. You can change the units by setting the unit's property:

property Units: type string

The interpretation of this string is the same as that described in Units of Measurement. For example, to return the history in the current display units, write:

hist.Units = "CurrentUnits"

Notes:

• The values stored in the history data are in the base units of the variable

• No error is detected if the unit string is not compatible with the base units of the variable. The value returned is still in the base units.

Example


The following example shows a history scaled in the current units, and selected units:

' history scaled in the current units set hist = B1.x.history hist.units = "CurrentUnits" uom = hist.units val = hist.AtTime(2.0) ' history scaled in the selected units hist.units = "C" ' for example in centigrade -- which has to be compatible with the base ' units of the variable valc = hist.AtTime(2.0)

History Methods

You can refresh the history by calling the GetHistory method, which takes the same parameters as the variable's history method.

The following methods are available for History:

• History.AtTime(t)

• History.Item

• GetAtTime

• ForEach loops

History.AtTime(t)

This method interpolates in the available data points to return the value of the variable at the specified time t, which is counted from the start time. If no history data for the specified time is available, an error is detected and the following message is printed in the Simulation messages window:

Error in script scriptname: "No History available"

Example


t = 2.34

Application.Msg "Value at time " & Cstr(t) & " = " & Cstr (hx.AtTime(t))

History.Item

A specific point may be indexed directly using the item method, for example:

set hist = B1.x.history val = hist(1)

Note: The valid range for the item index is 1 to hist.Count.


For Each Loops

The history collection can be enumerated in the conventional way using, a for each loop, for example:

set hist = B1.x.history for each v in hist application.msg " " & v next

Exploring Variable Time History You can access the data points for each loop sequentially.

set hist = B1.x.history for each p in B1.x.hist Application.Msg " value " & Cstr(p) next

An alternative way uses the item method:

set hist = B1.x.history

for i=1 to hist.count Application.Msg "value " & Cstr(hist.item(i)) next

The time of the item(i) is StartTime + (i-1)*Interval. Note it starts with i=1, not i=0, to return the first point (at the start time).

Examples of Exploring Variable Time History

The first example shows how to use variable time history for Aspen Dynamics�, whereas the second example shows how to use variable time history for Aspen Custom Modeler®.

Example 1: Aspen Dynamics

The following example shows how to retrieve the value of a variable from the start of the simulation and export it into a spreadsheet, for a column created for Aspen Dynamics:

' loop on the stages to get t, p, compositions

'

' this script writes the data in a spreadsheet

dim excel

set excel = getobject ("c:\My Documents\Book1.xls")

' name of the block

blockname = "B1"

' because this flowsheet is created with Aspen Dynamics, the name of block

' has to be enclosed in the Blocks("xxxx") function.


' list of the component names

' we assume that all the blocks within the column are using the same

' componentlist (otherwise, you need to include this in the loop)

set comps = Blocks(blockname).componentlist.components

icol = 1

' do a loop over history to set the time in the first column in spreadsheet

set hist = Blocks(blockname).stage(1).T.history

dt = hist.interval

t = hist.starttime

excel.worksheets("Sheet1").Cells(1,icol).Value = "Time"

excel.worksheets("Sheet1").Cells(2,icol).Value = " "

for irow = 1 to hist.count

excel.worksheets("Sheet1").Cells(irow+2,icol).Value = t

t = t + dt

next

' do a loop over all the stages temperature

for istage = 1 to Blocks(blockname).nstage.value

icol = icol + 1

excel.worksheets("Sheet1").Cells(1,icol).Value = "T"

excel.worksheets("Sheet1").Cells(2,icol).Value = istage

irow = 0

for each point in Blocks(blockname).stage(istage).T.history

irow = irow + 1

excel.worksheets("Sheet1").Cells(irow+2,icol).Value = point

next

next

' do a loop over all the stages pressure


icol = icol + 1

excel.worksheets("Sheet1").Cells(1,icol).Value = "P"


irow = 0


for each point in Blocks(blockname).stage(istage).P.history

irow = irow + 1


next

next

' composition


for each c in comps

' liquid mole fractions

icol = icol + 1

excel.worksheets("Sheet1").Cells(1,icol).Value = "x " & Cstr(c)


irow = 0

for each point in Blocks(blockname).stage(istage).x(c).history

irow = irow + 1


next

' vapor mole fractions

icol = icol + 1

excel.worksheets("Sheet1").Cells(1,icol).Value = "y " & Cstr(c)


irow = 0

for each point in Blocks(blockname).stage(istage).y(c).history

irow = irow + 1


next

next

next

Example 2: Aspen Custom Modeler


The following example shows how to extract the simulation history from Aspen Custom Modeler®, using a Microsoft® Excel macro:

The only difference is that you need to prefix all the variable with the name of the object created to access Aspen Custom Modeler®.

Sub history()

Set ACM = GetObject("tank.acmf")

Set hist = ACM.flowsheet.B1.s.history

Sheet1.Cells(1, 1).Value = hist.starttime

Sheet1.Cells(2, 1).Value = hist.endtime

Sheet1.Cells(3, 1).Value = hist.Count

For i = 1 To hist.Count

Sheet1.Cells(i + 4, 1).Value = hist.starttime + (i - 1) * hist.interval

Sheet1.Cells(i + 4, 2).Value = hist.Item(i)

Next

End Sub

Other Custom Methods This section describes other custom methods.

BaseTypeName

The BaseTypeName method returns the name of the base type of the variable.

Example:


Str = Blocks("Reactor").T.BaseTypeName 'result is "RealVariable"

Change TypeName Method

The TypeName method returns the name of the type of the variable.

Example:


Str = Blocks("Reactor").T.TypeName 'result is "Temperature"

ConvertToBaseUOM and ConvertFromBaseUOM Methods

These methods take a real number and a unit string. ConvertToBaseUOM converts the value of a real number to the variable's base units.


ConvertFromBaseUOM converts the real number from base units to those of the unit string.

Example

cent = temp.convertToBaseUOM(32, "F");

far = temp.convertFromBaseUOM(cent, "F");

DefaultValue Method

This method returns the default value of the variable ' set T_def to default value of T in block B1

T_def = blocks("B1").T.DefaultValue

FixedValue Method

This method sets the value of the variable to the value given and also sets the value of the specification attribute to �Fixed�.

e.g. var.FixedValue = 12.3

FreeValue Method

This method sets the value of the variable to the value given and also sets the value of the specification attribute to �Free�.

e.g. var.FreeValue = 12.3

GetPath Method

The following method returns the full path for the variable, for example, "b1.in_p.F("CO")":

GetPath: result string

Note: The GetPath method always returns the full path of an object.

InitialValue Method

This method sets the value of the variable to the value given and also sets the value of the specification attribute to �Initial�. Using this method allows you to change both the value and the specification of the variable with a single statement, which improves performance and makes the script more compact.

e.g. var.InitialValue = 12.3

IsAlgebraicVariable Method

The following method returns true if the variable is currently active as an algebraic variable in the simulation:

IsAlgebraicVariable: result boolean


IsHidden Method

The following method returns true for variables declared as hidden:

IsHidden: result boolean

IsInput Method

The following method returns true if the variable allows input control connections:

IsInput: result boolean

IsOutput Method

The following method returns true if the variable allows output control connections:

IsOutput: result boolean

IsParameter Method

The following method returns true if the variable is a parameter:

IsParameter: result boolean

IsStateVariable Method

The following method returns true if the variable is currently active as a state variable in the simulation:

IsStateVariable: result boolean

Name Method

The following method returns the full path for the variable, for example, "b1.in_p.F("CO")":

Name: result string

Note: Unlike GetPath, the Name method returns the full path for variables, but the path relative to the parent for models.

Parent Method

The following method returns the port or model that contains the variable:

Parent: result object

Property Method

The Property method provides access to the properties of a variable by string.

Examples

' The value of derivative

val = var.Property("derivative")

' Set the variable value


var.Property("value") = 10.0;

'set the value in Fahrenheit

var.Property("value", "F") = 10.0;

Reset Method

This will reset the named property to its default value.

Example

var.Reset("value");

TypeName Method

The following method returns the name of the type of the variable:

TypeName: result string

ValidValues Method

The following method returns the valid values that can be assigned to Attribute:

ValidValues([in: optional, string, default="value"] Attribute): result String collection

ValidValues: result String collection

This form is used to determine all the possible values for a variable defined as a string parameter, for example:

Model fragment:

PARAMETER HXType USES stringparameter

Valid as stringset(["Shortcut","Hot Tube","Hot Shell"]);

value:"Shortcut";

END

CalcType as HXType (Description:"Calculation type for heat exchanger");

External Microsoft® Visual Basic® fragment:

Dim coll As Object

Dim s As Variant

cbo.Clear

Set coll = MyBlock.CalcType.ValidValues

For Each s In coll

cbo.AddItem s

Next


cbo.Text = Var.value

This fragment initializes a combobox (cbo) list with the range of values available to CalcType. In this case "ShortCut", "Hot Tube", and "Hot Shell".

ValidValues(OptionalString) Method

ValidValues can optionally take a string to determine which attribute to examine. This form is often used to determine the valid units available to a variable.

Note: An error is raised if the variable attribute is undefined (for example, no units).

Example

External Microsoft® Visual Basic® fragment:

Dim coll As Object

Dim s As Variant

cbo.Clear


Set coll = Var.ValidValues("units")

If Err.Number = 0 Then

For Each s In coll

cbo.AddItem s

Next

cbo.Text = Var.units("CurrentUnits")

cbo.Visible = True

Else

cbo.Visible = False

End If

This fragment initializes a combobox (cbo) list with the range of units available to Var. If no units are defined then the control is hidden.

Variable.IsKindOf

Returns true if the object accessed is of the type given, false if not. 1 argument is required which can be:

�IntegerParameter�

�LogicalParameter�

�IntegerSet�


�Parameter�

�RealVariable�

�RealParameter�

�SlackVariable�

�StringParameter�

�StringSet�

�Variable�

Note that these are not exclusive so a string parameter type will return true with the arguments �StringParameter� or �Parameter�.

Example


set vars = FindMatchingVariables("~")

for each var in vars

if(var.IsKindof("IntegerParameter")) then

application.msg var.Name & " is a IntegerParameter"

elseif(var.IsKindof("RealParameter")) then

application.msg var.Name & " is a RealParameter"

elseif(var.IsKindof("LogicalParameter")) then

application.msg var.Name & " is a LogicalParameter"

elseif(var.IsKindof("IntegerSet")) then

application.msg var.Name & " is a IntegerSet"

elseif(var.IsKindof("StringParameter")) then

application.msg var.Name & " is a StringParameter"

elseif(var.IsKindof("StringSet" )) then

application.msg var.Name & " is a StringSet"

elseif(var.IsKindof("Parameter")) then

application.msg var.Name & " is a Parameter"

elseif(var.IsKindof("RealVariable")) then

application.msg var.Name & " is a RealVariable"

elseif(var.IsKindof("SlackVariable")) then

application.msg var.Name & " is a SlackVariable"

elseif(var.IsKindof("Variable")) then

application.msg var.Name & " is a Variable"

end if

next


This example obtains all the variables in the current flowsheet and prints out their name and type to the message window.

RealVariables Methods These methods are specific to RealVariables.

InputVariable Method

Returns the name of the variable that is connected to an input variable by a ControlSignal stream using this method:

InputVariable(): result variable object

Example


Dim VarInput

Set VarInput = V1.ValveStemPosition.InputVariable

ACMApp.Msg VarInput & " is connected to the Valve V1 Stem Position variable."

OutputVariables Method

Returns which variables are connected to an output variable by a ControlSignal stream using this method.

OutputVariables: result variable object collection

The information about the variables attached to an output variable is returned as a collection of variable objects. You can access the following properties from the collection:

Property Meaning

Count Number of variables connected to the output variable

Item(Index) The variable object at position Index in the variable collections

Example


Set VarOutput = B1.Out1.Temp.OutputVariables

ACMApp.Msg VarOutput.Count & " variable(s) is/are connected to the output temperature of block B1."

for I = 1 to VarOutput.Count

ACMApp.Msg "Variable " & I & " is the variable " & VarOutput.Item(I).Name

next


Task Object Event-driven tasks can be accessed as properties of their containing block, stream, or flowsheet.

Example


Task1.Active = True


ACMApp.ActiveDocument.Flowsheet.Task1.Active = True

Note: Use the Resolve method if you need to give the name of the task as a string variable:

taskname = "Task1" on error resume next set task = Application.Simulation.Flowsheet.Resolve(taskname)if Err.Number <> 0 then Err.Clear ' task does not exist else task.Active = True end if

The Task object has the following properties:

• Active

• LanguageText

Active Property You can use this Boolean property to determine whether a particular task at flowsheet level is active, and to set whether it is active.

Note: To be activated, a task must be event-driven (that is, it is declared with the "RUNS [ONCE] WHEN condition" syntax). For more information see the Modeling Language Reference.

Example


if Task1.active then

MsgBox "Task Active"

else

MsgBox "Task Inactive"


end if

Task1.Active=True

LanguageText Property This is a read-only property that will return the language task for the task object.

Example

From a script at the Flowsheet level

Text = Task1.LanguageText

Homotopy Object The Homotopy object has properties and methods.

Homotopy Properties The following properties are available for the Homotopy object.

• Homotopy.Count

• Homotopy.HomotopyEnabled

• Homotopy.Theta

• Homotopy.Variable

Homotopy.Count

Returns a count of the number of Homotopy variables currently in the simulation.

Example

count = Homotopy.Count

"Number of Homotopy variables = " &CSTR(count)

Homotopy.HomotopyEnabled

Can be True or False. Controls whether the next run will use homotopy.

Example

Homotopy.HomotopyEnabled = True

Homotopy.Theta

Returns the current value of the Homotopy parameter. Value will be 0 before a homotopy run has been performed. A value of 1 indicates that the last homotopy run was successful.

Example

Theta = Homotopy.Theta

application.msg "value of theta is " &CSTR(theta)


Homotopy.Variable

Variable(index) returns a string containing the name of the variable at position index. Index is zero-based: 0 is the first element in the list.

Example

dim name

name = Homotopy.Variable(1)

Homotopy Methods application.msg "Variable 1 is " &name

The following methods are available for the Homotopy object.

• Homotopy.AddTarget

• Homotopy.GetTarget

• Homotopy.RemoveAll

• Homotopy.SetTarget

Homotopy.AddTarget

The AddTarget method adds a homotopy variable, and optionally enables you to set a target and the UOM of the target. The Target Value and UOM specifier are optional. If you omit the Target Value, it is taken to be the current value, and if you omit the UOM specifier, the UOM is taken to be the base UOM for that variable.

Example

The following example adds the homotopy variable "FEEDEMB.TOTAL" and specifies the target as 12000, and the UOM of the target as kmol/hr:

Homotopy.AddTarget "FEEDERMB.TOTAL", 12000, "kmol/hr"

Homotopy.GetTarget(VarName)

GetTarget gets the target value of the variable. It returns an error if you have not added the variable name to the homotopy specification.

Homotopy.RemoveAll

The RemoveAll method clears the existing homotopy specification.

Example

Homotopy.RemoveAll

Homotopy.SetTarget

The SetTarget method changes a target value for a variable already added using the AddTarget method and optionally enables you to set the UOM. You must supply the target. If you omit the UOM, the units are assumed to be base UOM for that variable.

Example


The following example adds a variable using AddTarget, and then sets a target value and UOM using SetTarget:

Homotopy.AddTarget "MEREACTOR.TEMP"

Homotopy.SetTarget "MEREACTOR.TEMP", 480, "F"

Optimization Object The Optimization object has properties and methods.

Optimization Properties The following properties are available for the Optimization object.

• Optimization.ControlElementTime

• Optimization.EndTime

• Optimization.EndTimeFixed

• Optimization.IsDynamic

• Optimization.LowerTimeBound

• Optimization.MaxMove

• Optimization.MaxMoveEnabled

• Optimization.MovingElementSizes

• Optimization.NumberOfElements

• Optimization.OptimizeFinalTime

• Optimization.PiecewiseLinear

• Optimization.UpperTimeBound

Optimization.ControlElementTime

Used for dynamic optimization only. Sets the time corresponding to a particular control element. The number of control elements must previously have been set to at least that number. The time cannot be set for the first control element (because it is always at time zero).

Example

Optimization.NumberOfElements = 4

Optimization.EqualElementSizes = False

Optimization.EndTime = 20.0

� needn�t set element 1

Optimization.ControlElementTime(2) = 5.0 Optimization.ControlElementTime(3) = 10.0 Optimization.ControlElementTime(4) = 15.0

Optimization.EndTimeFixed

Used for dynamic optimization only. If this Read/Write Boolean property is True then the EndTime for the simulation will not be changed in the course of the optimization run.


Example

Optimization.EndTimeFixed = False

Optimization.IsDynamic

Can be True or False. Set this to True for a dynamic optimization, or False for steady-state optimization.

Optimization.LowerTimeBound

Used for dynamic optimization only. This Read/Write floating property is the minimum value to which time may vary during the simulation run. It is only relevant if the end time of the run is not fixed (see Optimization.EndTimeFixed).

Example

Optimization.LowerTimeBound = 0.5

Optimization.MaxMove

Used for dynamic optimization only. This Read/Write floating property determines the maximum amount that a control variable may change from one element to the next. It is only enforced if the MaxMoveEnabled property of the Control Variable is True.

Example

Optimization.MaxMoveEnabled ("UNIT1.Theta") = True

Optimization.PieceWiseLinear = True

Optimization.MaxMove ("UNIT1.Theta") = 21.4

Optimization.MaxMoveEnabled

Used for dynamic optimization only. This Read/Write Boolean property of a control variable is True if there is a limit on the amount a control variable may change in value from one control element to the next. It is used in conjunction with the MaxMove property.

Example

Optimization.MaxMoveEnabled ("UNIT1.Theta") = True

Optimization.PieceWiseLinear = True

Optimization.MaxMove ("UNIT1.Theta") = 21.4

Optimization.MovingElementSizes

Used for dynamic optimization only. This Read/Write Boolean property is True if the control element sizes are allowed to be varied during a simulation run.

Example

Optimization.MovingElementSizes = True


Optimization.NumberOfElements

Used for dynamic optimization only. This Read/Write integer property sets the number of control elements that span the time between time zero and the simulation end time. Each control variable may have one value specified for each control element, resulting in a set of values across time.

Example

Optimization.NumberOfElements = 10

Optimization.OptimizeFinalTime

Used for dynamic optimization only. This Read/Write Boolean property is True if final time is to be optimized. The EndTimeFixed property should also be set False if time is being optimized.

Example

Optimization.EndTimeFixed = False

Optimization.OptimizeFinalTime = True

Optimization.PiecewiseLinear

Used for dynamic optimization only. This Read/Write Boolean property is True if piecewise linear control discretization is to be used, and False if piecewise constant control discretization is to be used.

Example

Optimization.PiecewiseLinear = False

Optimization.UpperTimeBound

Used for dynamic optimization only. This Read/Write property is the maximum value to which time may vary during the simulation run. It is only of relevance if the end time of the run is not fixed (see Optimization.EndTimeFixed).

Example

Optimization.UpperTimeBound = 20.0

Optimization Methods The following methods are available for the Optimization object.

• Optimization.AddDynVariable

• Optimization.AddInteriorPoint

• Optimization.AddSSVariable

• Optimization.AddVariable

• Optimization.ClearVariables

• Optimization.SetControlElementValue

• Optimization.SetControlElementValueBounds

• Optimization.SetDynVariableParams

• Optimization.SetInitialParams


Optimization.AddDynVariable

AddDynVariable: Is used to add a dynamic constraint to an optimization simulation, using the following syntax:

Optimization.AddDynVariable "VariableName", Active, Handle

VariableName Must be the name of a variable in your flowsheet

Active True or False, Switches the constraint on or off.

Handle An output parameter. This will be set to a unique value used to refer to this constraint when calling other methods, i.e. SetDynVariableParams and AddInteriorPoint

Example

dim Handle1

Optimization.AddDynVariable "UNI1.temp", TRUE, Handle1

Optimization.AddInteriorPoint

AddInteriorPoint: Is used to add an interior point to a dynamic constraint in an optimization simulation, using the following syntax:

Optimization.AddInteriorPoint "VariableName", InteriorPoint, Active, ElementSize, LowerBound, UpperBound, Handle


InteriorPoint The zero bases index number of the interior point

Active True or False, Switches the interior point constraint on or off

ElementSize The size of the interior point expressed as a fraction of the element

LowerBound The lower bound to be used for this interior point during a dynamic optimization run

UpperBound The upper bound to be used for this interior point during a dynamic optimization run

Handle This is the unique value returned by the AddDynVariable method

Example

dim Handle1


Optimization.SetDynVariableParams "UNI1.temp", TRUE, 2, TRUE, 0.5, 2.0, Handle1

Optimization.AddInteriorPoint "UNI1.temp", 0, TRUE, 0.5, 0.25, 2.0, Handle1

Optimization.AddInteriorPoint "UNI1.temp", 1,

TRUE, 0.5, 0.75, 2.0, Handle1


Optimization.AddSSVariable

AddSSVariable: Is used to add a steady state constraint to an optimization simulation, using the following syntax:

Optimization.AddSSVariable "VariableName", LowerBound, UpperBound, Active


LowerBound The optimizer will attempt to solve the optimization problem such that the value of the variable will not be below this value during the simulation

UpperBound The optimizer will attempt to solve the optimization problem such that the value of the variable will not be above this value during the simulation

Active True or False, Switches the constraint on or off

Example

Optimization.AddSSVariable "UNI1.u", 0.5, 1.5, TRUE

Optimization.AddVariable

AddVariable is used to add variables to an optimization simulation, using the following syntax:

Optimization.AddVariable "VariableName", "type"


Type Can be Objective, Design, Initial, or Control. For steady-state optimization, you must specify an objective variable and a design variable. For dynamic optimization, you must specify an objective variable and at least one other type. Objective variables must be Free or Initial or RateInitial variables. Design and Control variables must be Fixed and the Initial variable type must have an Initial or RateInitial specification.

Example

Optimization.AddVariable "UNI1.obj", "Objective"

Optimization.ClearVariables

This clears any existing optimization definitions.

Example

Optimization.ClearVariables

Optimization.SetControlElementValue

The number of the control element for which a value is being set. If using Piecewise Constant Discretization then the number should be between 1 and the number of elements(inclusive). If using Piecewise Linear Discretization then the number should be between 1 and the number of elements+1 (inclusive). The extra final value corresponds to the value of the control variable at the simulation final time.

Example


Optimization.SetControlElementValue "UNI1.u", 3, 0.5

Optimization.SetControlElementValueBounds

SetControlElementValueBounds: Is used to set the upper and lower bounds of a control variable for a particular control element, using the following syntax:

Optimization.SetControlElementValueBounds "VariableName", Element, LowerBound, UpperBound


Element The number of the control element for which a value is being set. If using Piecewise Constant Discretization then the number should be between 1 and the number of elements(inclusive). If using Piecewise Linear Discretization then the number should be between 1 and the number of elements+1 (inclusive). The extra final value corresponds to the value of the control variable at the simulation final time

LowerBound The value of the variable will not be allowed to drop below this value within the specified element

UpperBound The value of the variable will not be allowed to exceed this value within the specified element

Example

Optimization.SetControlElementValueBounds "UNI1.u", 3, 0.5, 1.5

Optimization.SetDynVariableParams

SetDynVariableParams: Is used to set the parameters for a dynamic constraint in an optimization simulation, using the following syntax:

Optimization.SetDynVariableParams "VariableName", FinalTimeOnly, InteriorPointsPerElement, Active, FinalTimeLowerBound, FinalTimeUpperBound, Handle


FinalTimeOnly True, if the constraint applies to the final time only. False, if the constraint is a path constraint

InteriorPointsPerElement

The number of interior points per element

Active True or False, Switches the constraint on or off

FinalTimeLowerBound The lower bound to be used when the constraint applies to the final time only

FinalTimeUpperBound The upper bound to be used when the constraint applies to the final time only

Handle This is the unique value returned by the AddDynVariable method

Example

dim Handle1


Optimization.SetDynVariableParams "UNI1.temp", TRUE, 5, TRUE, 0.5, 2.0, Handle1


Optimization.SetInitialParams

SetInitialParams: Is used to set the initial value and the upper and lower bounds of an initial variable, using the following syntax:

Optimization.SetInitialParams "VariableName", InitialValue, LowerBound, UpperBound


InitialValue The Initial value of the variable

LowerBound The minimum initial value

UpperBound The maximum initial value

Example

Optimization.SetInitialParams "UNI1.h", 3, 2.5, 3.5

OnLineLinks Object This object provides access to the OnLine Links facility for automation. It has methods and properties.

To access the object, the syntax is:

Set OLL = Simulation.OnLineLinks

OnlineLinks Properties The following properties are available for the OnlineLinks object:

• ServerName

• IOTiming

• ReadingMode

• QualityHandling

• BoundsHandling

• BeforeSteadyStateRun

• AfterSteadyStateRun

• BeforeInitializationRun

• AfterInitializationRun

• BeforeDynamicStep

• AfterDynamicStep

• BeforeInitializationStep

• AfterInitializationStep

• Enable

ServerName

This property contains the name of the data server to be used by OnLineLinks.

Example


OLL.ServerName = "SST.SimulationOpcSvr.1"

IOTiming

This property contains the current setting of the IOTiming mechanism. It can have either of the two values "Synchronous" or "Asynchronous".

Example

OLL.IOTiming = "Asynchronous"

ReadingMode

This property specifies the current mode to be used for reading variables. It can have one of the two values "Cached" or "Device".

Example

OLL.ReadingMode = "Device"

QualityHandling

This property specifies how data with a quality that is not GOOD should be handled. It can have one of the values "UseLast", "Override", or "Pause".

Example

OLL.QualityHandling = "Pause"

BoundsHandling

This property specifies how to handle values read from the data server that are out of the simulation variable�s bounds. It can have one of the values "Clip", "UseLast" or "Pause".

Example

OLL.BoundsHandling = "UseLast"

BeforeSteadyStateRun

This property indicates whether or not OLL data should be exchanged before a steady-state run. This property takes a boolean argument which is TRUE for the input variables and FALSE for the output variables. The property itself is also boolean.

Example

' Disable reading before a steady state run

OLL.BeforeSteadyStateRun(TRUE) = FALSE

' Enable writing before a steady state run

OLL.BeforeSteadyStateRun(FALSE) = TRUE

AfterSteadyStateRun

This property indicates whether or not OLL data should be exchanged after a steady-state run. This property takes a boolean argument which is TRUE for the input variables and FALSE for the output variables. The property itself is also boolean.


Example

' Disable reading after a steady state run

OLL.AfterSteadyStateRun(TRUE) = FALSE

' Enable writing after a steady state run

OLL.AfterSteadyStateRun(FALSE) = TRUE

BeforeInitializationRun

This property indicates whether or not OLL data should be exchanged before an initialization run. This property takes a boolean argument which is TRUE for the input variables and FALSE for the output variables. The property itself is also boolean.

Example

' Disable reading before an initialization run

OLL.BeforeInitializationRun(TRUE) = FALSE

' Enable writing before an initialization run

OLL.BeforeInitializationRun(FALSE) = TRUE

AfterInitializationRun

This property indicates whether or not OLL data should be exchanged after an initialization run. This property takes a boolean argument which is TRUE for the input variables and FALSE for the output variables. The property itself is also boolean.

Example

' Disable reading after an initialization run

OLL.AfterInitializationRun(TRUE) = FALSE

' Enable writing after an initialization run

OLL.AfterInitializationRun(FALSE) = TRUE

BeforeDynamicStep

This property indicates whether or not OLL data should be exchanged before a dynamic step. This property takes a boolean argument which is TRUE for the input variables and FALSE for the output variables. The property itself is also boolean.

Example

' Disable reading before a dynamic step

OLL.BeforeDynamicStep(TRUE) = FALSE

' Enable writing before a dynamic step

OLL.BeforeDynamicStep(FALSE) = TRUE


AfterDynamicStep

This property indicates whether or not OLL data should be exchanged after a dynamic step. This property takes a boolean argument which is TRUE for the input variables and FALSE for the output variables. The property itself is also boolean.

Example

' Disable reading after a dynamic step

OLL.AfterDynamicStep(TRUE) = FALSE

' Enable writing after a dynamic step

OLL.AfterDynamicStep(FALSE) = TRUE

BeforeInitializationStep

This property indicates whether or not OLL data should be exchanged before a dynamic initialization step. This property takes a boolean argument which is TRUE for the input variables and FALSE for the output variables. The property itself is also boolean.

Example

' Disable reading before a dynamic initialization step

OLL.BeforeInitializationStep(TRUE) = FALSE

' Enable writing before a dynamic initialization step

OLL.BeforeInitializationStep(FALSE) = TRUE

AfterInitializationStep

This property indicates whether or not OLL data should be exchanged after a dynamic initialization step. This property takes a boolean argument which is TRUE for the input variables and FALSE for the output variables. The property itself is also boolean.

Example

' Disable reading after a dynamic initialization step

OLL.AfterInitializationStep(TRUE) = FALSE

' Enable writing after a dynamic initialization step

OLL. AfterInitializationStep(FALSE) = TRUE

Enable

This property specifies whether OnLineLinks are enabled or not. It can have one of the values "On", "ReadOnly" or "Off".

Example

OLL.Enable = "ON"

OnLineLinks Methods The following methods are available for the OnlineLinks object.


• AddInputVariable

• AddOutputVariable

• FindInputVariable

• FindOutputVariable

• RemoveInputVariable

• RemoveOutputVariable

AddInputVariable

This method adds a simulation variable to the OLL input variable list. The method takes two arguments, the name of the simulation variable and the OLL data server�s tag-name to which that variable is to be linked.

Example

OLL.AddInputVariable "b1.theta", "Simulated Card.Simulated Node.COS"

AddOutputVariable

This method adds a simulation variable to the OLL output variable list. The method takes two arguments, the name of the simulation variable and the OLL data server�s tag-name to which that variable is to be linked.

Example

OLL.AddOutputVariable "b1.alpha", "Simulated Card.Simulated Node.FLOAT"

FindInputVariable

This method returns an OLL Variable Object that is the OLL link in the OLL input list, specified by its simulation variable�s name, and, optionally by the corresponding OLL tag-name. Once the object is obtained, the properties of the OLL Variable Object can be accessed.

Example

Set var1 = OLL.FindInputVariable("b1.theta")

Set var2 = OLL.FindInputVariable("b1.beta"," Simulated Card.Simulated Node.FLOAT")

FindOutputVariable

This method returns an OLL Variable Object that is the OLL link in the OLL output list, specified by its simulation variable�s name, and, optionally by the corresponding OLL tag-name. Once the object is obtained, the properties of the OLL Variable Object can be accessed.

Example

Set var1 = OLL.FindOutputVariable("b1.theta")

Set var2 = OLL.FindOutputVariable("b1.beta"," Simulated Card.Simulated Node.FLOAT")


RemoveInputVariable

This function removes a variable from the OLL Input variable list, specified by the simulation variable�s name.

Example

OLL.RemoveInputVariable "b1.theta"

RemoveOutputVariable

This function removes a variable from the OLL Output variable list, specified by the simulation variable�s name.

Example

OLL.RemoveOutputVariable "b1.alpha"

OLL Variable Object This object provides access to the various properties of individual links in the OLL input and output variable lists. In order to query or modify these properties, the object must first be located using FindInputVariable or FindOutputVariable, as appropriate.

OLL Variable Object Properties The following properties are provided:

• VariableName

• TagName

• Mode

• Bias

• Gain

• OverrideValue

• ConversionUnits

• ChangeTolerance

• NoiseStandardDeviation

VariableName

This property contains the name of the simulation variable in the OLL link.

Example

Set var = OLL.FindInputVariable("b1.theta")

'Change the simulation variable in the link

Var.VariableName = "b1.alpha"

TagName

This property contains the OLL tag name for the variable in the link.

Example


Set var = OLL.FindOutputVariable("b1.alpha")

Application.PrintToMessageWindow "b1.alpha is connected to" & var.TagName

Mode

This property contains the mode of the variable in the link. It can be one of the values "Manual" or "Auto".

Example

Set var = OLL.FindInputVariable("b1.gamma")

'Switch to manual mode

var.Mode = "Manual"

Bias

This property contains the bias applied to values read from or written to the variable in the link.

Example


'set the bias for this link to 0.1

Var.Bias = 0.1

Gain

This property contains the gain applied to values read from or written to the variable in the link.

Example


'set the gain for this link to 2.0

Var.Gain = 2.0

OverrideValue

This property contains the override value for the link.

Example

Set var = OLL.FindINputVariable("b1.gamma")

'Set override value to 0.25 (Simulation units)

Var.OverrideValue = 0.25

ConversionUnits

This property contains the conversion units for the link.

Example


'Set conversion units to millimeters


Var.ConversionUnits = "mm"

ChangeTolerance

This property contains the change tolerance for the link.

Example

Set var = OLL.FindInputVariable("b1.alpha")

Var.ChangeTolerance = 1e-3

NoiseStandardDeviation

This property is only meaningful for a variable in the output list, and specifies the standard deviation of the random noise to be applied to the simulation value before it is written to the OLL data server.

Example


Var.NoiseStandardDeviation = 0.03

OLL Variable Object Methods The OLL Variable object specifies the following methods:

• ReverseWrite

• ReverseRead

ReverseWrite

This method allows the current value for an input variable, which would normally be read from the OLL data server, to be written to the server.

ReverseRead

This method allows the current value for an output variable, which would normally be written to the OLL data server, to be read from the server.

CDI Object Properties and methods are available for the CDI object.

For an example, see Using DMCplus.

CDI Properties The following properties are available for the CDI object.

• StepResponseAbsoluteTolerance

• StepResponseAbsoluteRampTolerance

• StepResponseIntegrationsPerInterval

• StepResponseMaxIntervals

• StepResponseMinIntervals


• StepResponseRelativeTolerance

• StepResponseRelativeRampTolerance

• StepResponseTimeInterval

• STMIntegrationStep

• STMTime

• STMZeroTolerance

• ZeroTolerance

StepResponseAbsoluteTolerance

Defines the absolute tolerance used to compute the responses of the measured variables.

It has a default of 1.e-5 and the range is 0 to 1. You may need to decrease this tolerance if your measured variables have very small values.

Example

StepResponseAbsoluteTolerance = stepabstol

StepResponseAbsoluteRampTolerance

Defines the absolute tolerance used to detect if any of the measured variables are "ramping", that is, not at steady state. Ramping variables can exist even though all the state variables in your flowsheet have settled down to steady state after the step changes in the manipulated variables. You may need to change this tolerance depending on the scaling and range of your measured variables to avoid falsely detecting ramping variable.

It has a default of 1.e-2 and a range 0 to 1. Make sure the value is greater than StepResponseAbsoluteTolerance.

Example

StepResponseAbsoluteRampTolerance = steprampabstol

StepResponseIntegrationsPerInterval

Specifies a positive integer defining the number of integration steps taken per time interval used to generate the step response. The default is 10.

Example

StepResponseIntegrationsPerInterval Interval = stepsperinterval

StepResponseMaxIntervals

Defines the maximum number of sample time intervals of the measured variables to be calculated, with a default of 1000.

Note: The number of intervals produced will be a multiple of 30, 45, 60, 75, 90, 105 or 120, for compatibility with DMCPlus.

Example

StepResponseMaxIntervals = maxint


StepResponseMinIntervals

Defines the minimum number of sample time intervals to be computed before the step response is defined to be at steady state, with a default of 12. This can be used to terminate the step response too early in the case of controllers with "dead time" or in special cases where the response settles down before moving to the true steady state later.

Example

StepResponseMinIntervals = minint

StepResponseRelativeTolerance

Defines the relative tolerance used to compute the responses of the measured variables.

It has default 1.e-5 and range 0 to 1.

Example

StepResponseRelativeTolerance = stepreltol

StepResponseRelativeRampTolerance

Defines the relative tolerance used to detect if any of the measured variables are "ramping", that is not at steady state. You may need to change this tolerance depending on the scaling and range of your measured variables.

It has default 1.e-2 and range 0 to 1. Make sure the value is greater than StepResponseRelativeTolerance.

Example

StepResponseRelativeRampTolerance = steprampreltol

StepResponseTimeInterval

Specifies a positive value interval time defining the sample times of the response of the measured variables to steps in the manipulated variables.

Default is equal to the current value of the Communication time.

Example

StepResponseTimeInterval = intervaltime

STMIntegrationStep

Defines the step size used by the implicit fixed step Implicit Euler method used to compute the approximation to the SEM. Default is 0.01 * STMTime. Range is 0 to STMTime.

Example

STMIntegrationStep = h

STMTime

Defines the double precision time at which the State Transition Matrix (STM) is required. There is no default. Range is 0 to 10E9.

Example


STMTime = time

STMZeroTolerance

Rounds to zero any elements in the State Transition Matrix (STM) that are below the value zerotol. Default is 1.e-16. Range is 0 to 1.

Example

STMZeroTolerance = zerotol

ZeroTolerance

Specifies what the CDI will return as a non-zero value in the state-space matrices. Any value smaller than value is treated as zero. The default is 1.0e-16.

Example

ZeroTolerance = value

CDI Methods The following methods are available for the CDI object

• AddInputVariable()

• AddOutputVariable()

• Calculate()

• FilesRequired()

• GenerateStepResponse()

• GetMRIStatus()

• GetMRIValue ()

• GetNIStatus()

• GetNIValue()

• Inputs()

• MatricesRequired()

• MatrixCols("Matrix")

• MatrixNonZeros("Matrix")

• MatrixRows("Matrix")

• MatrixStatus("Matrix")

• MatrixValues("Matrix")

• NumberofInputs()

• NumberofOutputs()

• NumberofStates()

• Outputs()

• Reset()

• States()

• STMAddIgnoredState("var path")

• STMStates()


AddInputVariable()

Used to add input variables to the interface.

Examples

AddInputVariable "var path"

Note: If the variable name includes double quotes, you must insert two of these in the variable path for input and output variables, for example:

CDI.AddInputVariable "Feed1.F(""CH4"")"

AddOutputVariable()

Used to add output variables to the interface.

Example

AddOutputVariable "var path"

Calculate()

Calculates and specifies the name of the MDL file. The filename argument provides a file name prefix. If you provide a prefix, the file is named prefix.dat. If you do not supply a file name prefix, the file is named cdi_.mdl.

Example

Calculate "filename argument"

GenerateStepResponse()

Requests computation of the response of the measured variables with respect to perturbations in the manipulated variables. The results of the step response calculation are output in the form of a DMCplus .mdl file.

Example

The following is an example of generating a DMCplus .mdl file:

Set Doc = ActiveDocument

Set MDL = Doc.CDI

MDL.Reset

MDL.AddInputVariable "b1.valueposition"

MDL.AddOutputVariable "b1.level"

MDL.GenerateStepResponse

MDL.StepResponseTimeInterval = 1

MDL.StepResponseIntegrationsPerInterval = 10

MDL.StepResponseMinIntervals = 30

MDL.StepResponseMaxIntervals = 800

MDL.Calculate "myresponse"


FilesRequired()

Default is True (.dat files of matrices are created). If it is set to False, no .dat files are created and all matrices can be accessed by automation only. This is particularly useful if only automation access is required, or when the State Transition Matrix (STM) is calculated, as the resulting file could be very large.

GetMRIStatus()

This command returns TRUE if the value is available and FALSE if not. It can be used to stop a script failing if the value is unavailable.

GetMRIValue ()

This command returns the values of the MRI. If you have not requested this value before the calculation, an error occurs in the script.

GetNIStatus()

This command returns TRUE if the value is available and FALSE if not. It can be used to stop a script failing if the value is unavailable.

GetNIValue()

This command returns the values of the NI. If you have not requested this value before the calculation, an error occurs in the script.

Inputs()

Returns an array of strings containing the variable names of each input, that is the columns of the B and D matrices.

Example

Inputs()

MatricesRequired("Matrix")

Tells the interface which matrices to calculate. "Matrix" can be one or more of A, B, C, D, G, RGA, NI, MRI, STM, or ALL. The default is "ALL".

Note: "STM" requests that the State Transition Matrix (STM) will be generated at the next CDI Calculate call. "ALL" does not include the STM matrix: it must be requested explicitly. For more information on STM, see State Transition Matrix.

Example

MatricesRequired "matrix","matrix", ...

MatrixCols("Matrix")

Returns an integer array of size GetMatrixNonZeros("Matrix") of the rows of the non-zero elements of Matrix.


MatrixNonZeros("Matrix")

Returns an integer equal to the number of non-zeros in the sparsity pattern for the given Matrix.

Example

MatrixNonZeros("Matrix")

MatrixRows("Matrix")

Returns an integer array of size GetMatrixNonZeros("Matrix") of the rows of the non-zero elements of Matrix.

Example

MatrixRows("Matrix")

MatrixStatus("Matrix")

Returns a logical value. If the Matrix is available, True is returned; if it is not available, False is returned.

Example

MatrixStatus("Matrix")

MatrixValues("Matrix")

Returns a double array of size GetMatrixNonZeros("Matrix") of the non-zero values of Matrix.

Example

MatrixValues("Matrix")

NumberofInputs()

Returns an integer equal to the number of input variables in the state-space model.

Example

NumberofInputs()

NumberofOutputs()

Returns an integer equal to the number of output variables in the state-space model.

Example

NumberofOutputs()

NumberofStates()

Returns an integer equal to the number of state variables in the state-space model.

Example

NumberofStates()


Outputs()

Returns an array of strings containing the variable names of each output, that is, the rows of the B and C matrices.

Example

Outputs()

Reset()

Clears the list of variables and resets the other parameters to their default values.

Example

Reset

States()

Returns an array of strings containing the variable names of each state, that is the columns of the A and C matrices

Example

States

STMAddIgnoredState("var path")

Used to define states which are ignored in the State Transition Matrix (STM) calculation. This produces a "reduced" STM. By default, the STM is based on ALL state variables.

STMStates()

Similar to the CDI States command, but this method returns a list of the variable names in the columns of the (reduced) STM.

StructureContainer Object The following methods are available for the StructureContainer object.

• AddStructure

• RemoveStructure

• Structures

• IsValidStructureName Method

StructureContainer Methods AddStructure

AddStructure "Structure Type", "Structure Name"

This automation method adds an instance of the structure type given, with the name given to the structure container.


RemoveStructure

RemoveStructure "Structure Name"

This automation method removes the structure instance with the name given from the structure container.

Structures

Structures �Structure Name�

This automation method returns the structure instance object with the given name. Alternatively if the argument is omitted it returns a collection of structure instances.

IsValidStructureName

IsValidStructureName "Structure Name"

This automation method returns true if the given name is a valid name for a structure instance.

Defining an Estimation Simulation You can define and run steady-state and dynamic parameter estimation simulations, as well as steady-state data reconciliation simulations.

For information on how to use the Estimation dialog box to interactively define Estimation simulations, see the online Help on running Estimation simulations.

You can also use automation methods and properties to define and run your estimation simulation, and to view the results. One use of this is for reading data or writing results to a spreadsheet package such as Microsoft® Excel.

For information on the solver options available for Estimation simulations, see the Aspen Modeler Reference.

Defining Estimated Variables You can define an estimated variable using the following automation method

APPLICATION.SIMULATION.ADDESTIMATEVARIABLE �BlockName.VariableName�

BlockName The name of the block containing the variable you

are estimating

VariableName The name of the variable you are estimating

Repeat this statement once for each variable to be estimated.

Note: To make a variable an Estimated variable, it must have a Spec of either Fixed or Initial.


Spec of either Fixed or Initial.

Defining Estimated Variables Example

The following example shows two variables being defined as estimate variables for an estimation simulation:

Application.Simulation.AddEstimateVariable "Reactor1.RK1"

Application.Simulation.AddEstimateVariable "Reactor1.RK2"

Defining Steady-State Estimation Experiments For each steady state experiment you must give an experiment name and define the experiment as steady-state. You must also add measurement points for the experiment. You can also specify changes that were made to the values of fixed variables for each experiment.

Syntax for Defining Steady State Estimation Experiments

DIM ThisExp SET ThisExp = APPLICATION.SIMULATION.NEWEXPERIMENT ( "ExperimentName", "STEADY STATE" ) ThisExp.ADDSSMEASUREPOINT "BlockName.VariableName", MeasuredValue, MeasurementWeight :

ThisExp.ADDFIXEDPOINT "BlockName.VariableName", FixedValue :

ThisExp.SETWEIGHT ExperimentWeight

APPLICATION.SIMULATION.ADDEXPERIMENT(ThisExp)

ThisExp A reference to the new experiment object

ExperimentName A name you give for this experiment. This name is used when reporting the results of the experiment

Steady State Keyword that identifies this experiment as a steady-state experiment

BlockName Name of the block containing the variable for this data point

VariableName Name of the variable for this data point

FixedValue Value of a fixed variable for this data point

MeasuredValue Value of a measured variable for this data point

MeasurementWeight Value of a weighting applied to this data point

ExperimentWeight Value of a weighting applied to this experiment


Remarks on Defining Steady-State Estimation Experiments

You can define any number of experiments. The experiment is only used once it has been added with the AddExperiment method. This means you can define a number of experiments but use a subset of these for a given run. This enables you to quickly test the effect of using different combinations of experiments on the estimation results.

For each experiment you can define any number of measurement points and fixed points.

When the heteroscedasticity parameter for a measured variable is not fixed, the Automation Method AddSSMeasurepoint resets the estimated heteroscedasticity parameter to 1.

If a variable name includes quotation marks, you must use double quotation marks as shown in the following example.

For a detailed example of a steady-state estimation simulation, follow the instructions in the online Help, under Examples, Steady-State Estimation of a Methanol Reactor Example.

Example of Defining Steady-State Estimation Experiments

The following example shows two experiments being defined for a simulation. The first measurement is given ten times the waiting of the second, and the second experiment is given double the weighting of the first:

SET SSExpt1 = _

Application.Simulation.NewExperiment("Experiment1","Steady State")

SSExpt1.AddFixedPoint "Rctr1.In1.Flow(""ReagentA"")", 1.0

SSExpt1.AddFixedPoint "Rctr1.In1.Flow(""ReagentB"")", 9.0

SSExpt1.AddSSMeasurePoint "Rctr1.Out1.x(""ReagentA"")", 0.092, 10.0

SSExpt1.AddSSMeasurePoint "Rctr1.Out1.x(""ReagentB"")", 0.904, 1.0

SSExpt1.SetWeight 1.0

SET SSExpt2 = _








Application.Simulation.AddExperiment(SSExpt1)


Defining Dynamic Estimation Experiments For each experiment, you must give an experiment name and define the experiment as dynamic. You must also add measurement values for the experiment at time points during the experiment. You can add initial conditions for the derivatives or state variables, and change the value of fixed variables for each experiment.

Syntax for Defining Dynamic Estimation Experiments

DIM ThisExp SET ThisExp = APPLICATION.SIMULATION.NEWEXPERIMENT ( "ExperimentName", "Dynamic" ) ThisExp.ADDDYNMEASUREPOINT "BlockName.VariableName", MeasurementTime, MeasuredValue, MeasurementWeight :

ThisExp.ADDFIXEDPOINT "BlockName.VariableName", FixedValue :

ThisExp.AddFixedRampPoint "BlockName.VariableName", FixedTimeValue, FixedValue

:

ThisExp.ADDINITIALPOINT "BlockName.VariableName", InitialValue :

ThisExp.ADDRATEINITIALPOINT "BlockName.VariableName", RateInitialValue :

ThisExp.SetWeight ExperimentWeight APPLICATION.SIMULATION.ADDEXPERIMENT(ThisExp)

ThisExp A reference to the new experiment object

ExperimentName A name you give for this experiment. This name is used when reporting the results of the experiment

Dynamic Keyword that identifies this experiment as a


dynamic experiment

BlockName The name of the block containing the variable for this data point

VariableName The name of the variable for this data point

FixedValue Value of a fixed variable for this data point

FixedTimeValue Time at which the associated fixed value should be applied

InitialValue Value of an initial variable at time zero of the experiment. The variable must have Spec = Initial

RateInitialValue Value of a derivative of a state variable at time zero of the experiment. The variable must have Spec = Initial

MeasurementTime Time at which the MeasuredValue is taken during the experiment

MeasuredValue Value of a measured variable for this data point

MeasurementWeight Value of the weighting applied to this data point

ExperimentWeight Value of the weighting applied to this experiment

Remarks on Defining Dynamic Estimation Experiments

You can define any number of experiments. The experiment is only used once it has been added with the AddExperiment method. This means you can define a number of experiments but use a subset of these for a given run. This enables you to quickly test the effect of using different combinations of experiments on the estimation results.

If a variable name includes quotation marks, you must use double quotation marks as shown in the following example.

For a detailed example of a dynamic estimation simulation, follow the instructions in the online Help, under Examples, Reactor Dynamic Estimation Example.

Example of Defining Dynamic Estimation Experiments

This example shows two dynamic experiment defined. The initial value of methanol in a reactor is supplied for time zero. Measurements are taken at 10 minutes, 20 minutes, and 30 minutes into the experiment. The initial amount of methanol in the reactor is different for the two experiments.

SET DynExpt1 = _

Application.Simulation.NewExperiment("DynamicExperiment1","Dynamic")

DynExpt1.AddInitialPoint "Rctr1.x(""CH3OH"")", 0.012

DynExpt1.AddFixedPoint "Rctr1.Temp", 200.0

DynExpt1.AddFixedPoint "Rctr1.Press", 12.5

DynExpt1.AddDynMeasurePoint "Rctr1.x(""CH3OH"")", 0.1667, 0.019, 1.0




SET DynExpt2 = _

Application.Simulation.NewExperiment("DynamicExperiment1","Dynamic")

DynExpt2.AddInitialPoint "Rctr1.x(""CH3OH"")", 0.009

DynExpt2.AddFixedPoint "Rctr1.Temp", 200.0

DynExpt2.AddFixedPoint "Rctr1.Press", 12.5




Application.Simulation.AddExperiment(DynExpt1)

Application.Simulation.AddExperiment(DynExpt2)

Resetting Estimation Experiments If you wish to change or remove some experiments before performing a new estimation run you must first use the ResetEstimation method to remove all existing experiments, and then add all of the experiments to be used for the new run.

Syntax for Resetting Estimation Experiments

APPLICATION.SIMULATION.RESETESTIMATION

This automation method clears all of the experiments defined previously.

Example of Resetting an Estimation Experiment

The following example shows the use of ResetEstimation to clear any existing experiments before adding the experiment SSExpt1. Without ResetEstimation, if you ran the script twice it would fail the second time because it would be trying to add an experiment with the same name as one that already exists.

SET SSExpt1 = _








Application.Simulation.ResetEstimation


Accessing Results of Estimation Simulations You can access the results of an estimation simulation through the automation interface. One use of this is for writing results to a spreadsheet package such as Microsoft® Excel.

You can access:

• Individual estimated variable values.

• Individual correlation values.

• The complete correlation matrix.

• Individual standard errors (also known as standard deviations).

Accessing Estimated Variables' Values You can access the values of the estimated variables using the following syntax.

Estimated Variable Syntax

The syntax for accessing estimated variables' values is:

APPLICATION.SIMULATION.ESTIMATEDVALUE("EstVariable")

EstVariable The name of the estimated variable for which you

want the estimated value

Example of Accessing the Value of an Estimated Variable

This example shows how to access the value of an estimated variable following a successful estimation simulation:

Dim EstVal1

EstVal1 = Application.Simulation.EstimatedValue("Rctr.K1")

Application.Msg "Estimated value for K1 is " + Cstr(EstVal1)


Accessing Standard Errors After an estimation simulation is complete, you can access the standard errors (also known as standard deviations) for the estimated variables.

Syntax for Accessing Standard Error

To obtain the standard error for a single estimated variable, use the following syntax

APPLICATION.SIMULATION.DEVIATION ("EstVariable ")

EstVariable The name of the estimated variable for which you

want the standard error

Example of Accessing Standard Errors

In this example, the standard error of a variable is printed out after a successful estimation run.

Dim StdDev

StdDev = Application.Simulation.Deviation("Reactor.K1")

Application.Msg "The standard error for K1 is " + Cstr(StdDev)

Testing for Standard Error Results You can test to see if the standard error results are available to download and view.

Syntax for Testing for Standard Error Results

APPLICATION.SIMULATION .DEVIATIONARRAYPRESENT

The property DeviationArrayPresent returns a logical value.

Example of Testing for Standard Error Results

The following example verifies that the standard error (also known as standard deviation) results are present. and if results are available, prints the error values to the Simulation Messages window.

IF Application.Simulation.DeviationArrayPresent = True THEN

Application.Msg "Standard Error K1 = " + _

Cstr(Application.Simulation.Deviation("Reactor.K2"))





ELSE


Application.Msg "Standard Error results not available"

END IF

Accessing Individual Correlation Results After an estimation run has completed, you can access correlation coefficients between two estimated variables.

Syntax for Accessing Individual Correlation Results

To get the correlation between two of the estimated variables, use this syntax:

APPLICATION.SIMULATION.CORRELATION("EstVar1", "EstVar2")

EstVar1, EstVar2 Names of the two estimated variables for the

correlation coefficient

Example of Accessing Individual Correlation Results

This example represents a script at flowsheet level that is invoked following an estimation run. K1 and K2 are reaction rate constants. The correlation between them is printed to the Simulation Messages window.

Dim Corr

SET Corr = Application.Simulation.Correlation ("Reactor.K1", _

"Reactor.K2")

Application.Msg "Correlation between K1 and K2 is " + Cstr(Corr)

Accessing the Correlation Matrix After an estimation simulation you can access the complete correlation matrix for all of the estimated variables in your simulation.

The correlation matrix is returned as a two-dimensional array, representing a square matrix. The size of the matrix is equal to the number of estimated variables. The order of the estimated variables is the order in which the estimated variables were added by the AddEstimateVariable method.

Syntax for Accessing the Correlation Matrix

Use the following syntax for accessing the correlation matrix:

APPLICATION.SIMULATION.CORRELATIONMATRIX

Note that the Correlation matrix is indexed from 0 to the number of estimated variables minus one.


Example of Accessing the Correlation Matrix

The following example shows the estimated variables being defined, a previously defined experiment being applied, and the estimation simulation running. In this example, the correlation matrix is 3 by 3. The column / row order is in the order the estimated variables are added. The nine elements of the correlation matrix are printed out to the simulation messages window.

Dim Sim, Corr

SET Sim =Application.Simulation

:

Sim.AddEstVar("Reactor.K1")



Sim.AddExperiment (DynExpt)

Sim.Runmode = "Estimation"

Sim.Run (True)

Corr = Sim.CorrelationMatrix

FOR i = 1 TO 3

FOR j = 1 TO 3

Application.Msg "Correlation " + CStr(i) + ", " + Cstr(j) + " = " _

+ CStr(Corr(i-1 ,j-1))

NEXT

NEXT

Testing for the Correlation Matrix You can test to see if the correlation matrix is present before attempting to access the matrix.

Syntax for Testing for the Correlation Matrix

APPLICATION.SIMULATION.CORRELATIONMATRIXPRESENT

The property CorrelationMatrixPresent returns a logical value.

Example of Testing for the Correlation Matrix

This example checks to see if the correlation matrix is present before loading the matrix into an array:

Dim Corr

IF Application.Simulation.CorrelationMatrix Present = True THEN


Corr = Application.Simulation.Correlation Matrix

ELSE

Application.Msg "WARNING : Correlation Matrix Not Present"

END IF

5 Synchronous and Asynchronous Simulation Runs 169

5 Synchronous and Asynchronous Simulation Runs

When running a simulation, you can choose whether control returns to Microsoft® Visual Basic® only when the run finishes (synchronous run), or immediately (asynchronous run).

This chapter describes:

• Synchronous runs

• Asynchronous runs

Using Synchronous Runs In many cases, synchronous running behavior is appropriate. For an example of code that results in synchronous running, see Synchronous Run Example.

However, the time that the following line takes to execute is indeterminate:

ATSimulation.Run (True)

Depending on the simulation, this step may take a few milliseconds or it may last for days. This has the following disadvantages:

• For the duration of the run, the application driving your Aspen Modeler product through Visual Basic® will stop processing events and be unresponsive to users.

• In the case of a dynamic simulation, the driving program is unable to retrieve and use values from the simulation while it is still running.

To resolve these issues, Aspen Modeler products support running simulations asynchronously.

Synchronous Run Example In the following code fragment of external Visual Basic® that runs Aspen Custom Modeler®, because True is passed as the parameter to the run method, control will not return to Visual Basic® until the run finishes or terminates:


' Example of loading and running a simulation











' Note that the path is fictitious; you should substitute

' one that exists on your machine.



' set the run mode to dynamic

ACMSimulation.RunMode = "Dynamic"

ACMSimulation.EndTime = 10.0

' and run the simulation, waiting for it to complete


' will get to this line when run completes

MsgBox "Run complete"

' save the changes

' and shut down the ACM application ACMApp.quit

Using Asynchronous Runs To resolve the issues arising from synchronous running, Aspen Modeler products support asynchronous simulation runs.

e.g. ATSimulation.Run (False)

will start the attached simulation run and will return immediately allowing the calling program to proceed.

However care must be taken when running like this. For example:

• Because the driving program and the Aspen Modeler application are no longer locked in step, commands sent from the driving program to the Aspen Modeler application may occur at a different stage of the run each


time the programs are used, depending on how the operating system allocates resources to each process. If for example you set the value of a variable during a run it cannot be predicted when the value will be used. It is best to pause the run before making such changes.

• Some OLE automation commands which worked previously when the run was paused will give errors when the simulation is running e.g. editing the flowsheet or trying to start a run again.

You can use automation events to let your driving program know when the run has finished or has taken a step. This could be used for example to re-enable facilities that needed to be disabled while the simulation was running. You could also use them to get simulation results after each time step in a dynamic run using the OnStepComplete event.

Asynchronous Run Example The following code fragment is a rewritten version of the Synchronous Run Example:











' Note that the path is fictitious; you should substitute

' one that exists on your machine.



' set the run mode to dynamic

ACMSimulation.RunMode = "Dynamic"

ACMSimulation.EndTime = 10.0

' and run the simulation, not waiting

' for it to complete

ACMSimulation.Run (False)

Do

' Stay responsive to the user


DoEvents

' write out the simulation time to a label on

' the form of the driving program

lblTime.Caption=ACMSimulation.Time

Loop While (ACMSimulation.State = "Running")

' will get to this following line when run

' completes or fails

if ACMSimulation.Successful then

msgBox "Simulation Complete"

else

msgBox "Simulation Failed"

endif

' save the changes


ACMApp.quit

Now the program driving Aspen Custom Modeler® through Visual Basic® can remain responsive while waiting for the run to complete. It can also display the current simulation time in a label on its own form.

Note: The value of ACMSimulation.Successful is indeterminate until ACMSimulation.State ceases to be "running".

6 Using the Aspen Modeler Type Libraries 173

6 Using the Aspen Modeler Type Libraries

Aspen Modeler type libraries are available for the following products:

• Aspen Custom Modeler

• Aspen Dynamics

• Aspen Water

• Aspen Adsim

• Aspen Chromatography

You can access the type libraries for the AspenTech products you have installed.

Referencing a Type Library from a Microsoft Visual Basic Project A type library is registered as part of the Aspen Modeler installation. To reference it from a Microsoft Visual Basic project:

1 From the Project menu, click References.

2 Fom the Available References list, select the type library for your installed AspenTech product, and then click OK.

The name also includes the current version number.

Using the Object Type Names in Your Code After you have referenced the type library in your Visual Basic project, you can use object type names for your Aspen Modeler product in your Visual Basic code. For example, if you are using Aspen Custom Modeler:

Dim ACM As AspenCustomModeler

6 Using the Aspen Modeler Type Libraries 174

Dim ACMSimulation As AspenModelerSimulation

Set ACM = New AspenCustomModeler

ACM.Visible = True

Set ACMSimulation = ACM.OpenDocument("C:\aspen\fivetank.acmf")

ACMSimulation.Run False

This code fragment will launch Aspen Custom Modeler, make the application visible, load up an input file, and start it running.

7 Solver Properties Dialog Box 175

7 Solver Properties Dialog Box

The Solver Properties dialog box enables you to change the default settings for the numerical algorithms used in your simulation. For example, you may need to change some algorithm properties to:

• Solve a difficult simulation or to improve the speed of a dynamic run.

• Get comprehensive diagnostic output from your simulation to determine why a simulation does not converge or runs more slowly than expected.

Take care when changing solver properties and follow these guidelines:

• Never make a change without first thinking about why you are making the change.

• Consider the side effects of changing a tolerance; you could lose accuracy or cause problems elsewhere in your simulation.

• Do not change more than one property between runs; you need to understand the effect of each change. Some combinations of solver property changes can cause new problems.

If you find a combination of solver property changes makes your simulation converge, consider which changes gave the improvement. As far as possible, keep the maximum number of solver properties set to their default values.

This chapter describes the following:

• Diagnostics tab

• Tearing tab

• Tolerances tab

• Integrator tab

• Linear Solver tab

• Non-Linear Solver tab

• Optimizer tab

• Homotopy tab

• Estimator tab

Diagnostics Tab The Diagnostics tab enables you to change the way diagnostic information is displayed.


Solver Reporting Level

You can change Solver Reporting Level to control the amount of detail sent to the Simulation Messages window and the external simulation log file. The higher the reporting level, the more detailed the resulting output.

The recommended print level depends on the type of work you are doing:

Type of Work Solver Reporting Level

General model and flowsheet design High or Medium

Running a tried and tested simulation Medium or Low

Diagnosing run time errors Very High or Maximum

Operator Training. Running a robust simulation

None

Properties Reporting Level

You can set the value of Properties Reporting Level to change the amount of detail provided by the physical properties database you are using. The higher the properties reporting level, the more detail you get about the information that is passed between Aspen Modeler products and the properties database.

The recommended properties reporting level depends on your type of work:

Type of Work Properties Print Level

Running simulations and general design work

None

Simulation design for a properties intensive flowsheet

Low

Diagnosing properties run time errors High or Maximum

Watch Group

Use this option when you want to understand why a particular equation group fails to converge. The most useful equation group to watch is typically the first group that fails to converge.

You can define the number of an equation group for which you want to see detailed convergence information in situations where:

• Convergence information for groups is normally suppressed.

• You do not wish to increase the Solver Reporting Level to High or above and get information on ALL groups.

For example, during dynamic runs with the Explicit Euler, Implicit Euler, VSIE or Runge Kutta 4 integrators, no information on convergence of groups is displayed in the Simulation Messages window unless the Solver Reporting Level is High or above. If you define an equation group number, you can see the convergence of that group alone for each integration step during the dynamic run.

This diagnostic is also helpful for estimation and optimization simulations.


Note: You can obtain the equation group number from the decomposition information in the Simulation Explorer. Unconverged equation groups are shown with a red cross mark on the equation group icon.

Watch Torn Sub-Group

You can use this option to specify a sub-group of a torn group for which you want to see detailed convergence information in situations where:

• Convergence information for groups is normally suppressed.

• You do not wish to increase the Solver Reporting Level to High or above and get information on ALL groups.

For example, during dynamic runs with the Explicit Euler, Implicit Explicit Euler, VSIE or Runge Kutta 4 integrators, no information on convergence of groups is displayed in the Simulation Messages window unless the Solver Reporting Level is High or above. If you define an equation group number, you can see the convergence of that group alone for each integration step during the dynamic run.

This diagnostic is also helpful for estimation and optimization simulations.

To use this option, you must have entered the number of the torn group in the Watch Group option.

Check Procedure Derivatives

You can specify that the analytical derivatives you return from your procedures are checked against the numerical derivatives derived by Aspen Modeler. This option can be used as a diagnostic tool to determine that your procedures calculate derivatives correctly.

Available options are:

Option Meaning

Off (default) No derivative checking

Active Derivatives All active derivatives for the current run mode are checked

Active Derivatives are derivatives of variables that are neither fixed nor calculated from a previously solved equation (this may change between run modes).

Note: After you have verified your procedure derivative calculations, turn this option off, otherwise you do not gain the speed benefits by returning derivatives from procedures.

Relative and Absolute Checking Tolerance

The Relative and Absolute Checking Tolerances determine the tolerance that decides whether the analytical derivative returned from a procedure call is acceptably close to the numerical derivative calculated by Aspen Modeler.


The expression that determines whether the derivative returned from a procedure is acceptable is:

( ) lDerivAbsTolDerivRelTo 1 +∗<− +KKK XXY

Where

KX = Procedure derivative value calculated numerically by Aspen Modeler

KY = Procedure derivative value calculated analytically within the procedure

DerivRelTol = Relative Checking Tolerance

DerivAbsTol = Absolute Checking Tolerance

This means that if the procedure derivative calculated analytically within the procedures is close enough to the numerically derived derivative, the procedure calculated derivative is considered to be correct.

List variables in equivalences for highest variable steps and residuals

When using the Diagnostics: Highest Variable Steps or Diagnostics: Highest Residuals options, if the diagnostics involve an equivalened variable, the entire list of variables in that equivalence are also output for clarity. If the equivalence involves many variables this can cause a large amount of output. Switching the option off stops the equivalence list being output and therefore reduce the amount of output.

Tearing Tab The Tearing tab enables you to control the options for procedure tearing.

Aspen Modeler is an equation-based simulator. For steady-state or initialization simulations, and for re-initializations with Gear (11.) integrators, or when the Re-initialize After Variable Step Change option is checked, all the simulation equations are solved simultaneously. To make this task easier, Aspen Modeler applies decomposition to break down the sets of equations into groups. Each equation group is then solved in sequence.

The degree to which the equations can be broken down into groups depends on the nature of the simulation. Typically, simulations of processes with recycles require that more of the equations be solved together in one large group. This is more difficult than solving many smaller groups.

Procedure tearing enables you to influence the way a simulation is solved and to improve the decomposition by de-coupling the procedure inputs and outputs.

Use procedure tearing to break the simulation down into smaller groups of equations. Breaking down the simulation into smaller groups of equations enables the simulation to solve more robustly and quickly for solution methods that use decomposed equation groups.


Note: Torn output variables are clipped to their bounds.

Procedure Tearing

You can set Procedure Tearing to the following options:

Procedure Tearing Action

None No procedure tearing

Update (default) Torn procedures are calculated throughout solution of decomposed runs

Start Torn procedures are calculated once at the start of the simulation

Complete Torn procedures are never calculated

None

All tears are ignored and the simulation treats all torn procedures as normal procedures.

Update

Aspen Modeler calls each torn procedure once at the start of the simulation with the initial values of the input variables. Aspen Modeler then fixes the procedure outputs to those calculated during that call. They become, in effect, fixed variables.

The remainder of the simulation is then solved as normal. After this, Aspen Modeler compares the original Procedure outputs with those from the latest solution. If these are the same to within a tolerance, the simulation is converged. Otherwise Aspen Modeler updates the new procedure output values, and the process is repeated until successive Procedure outputs are the same.

A steady-state or initialization simulation solved with tearing gives the same results as a simulation solved without tearing. Tearing only affects the ability to find the solution and the time taken.

For a dynamic run , torn procedures are converged at initialization and re-initialization.

For a dynamic run using Implicit Euler, Explicit Euler Runge Kutta 4 or Gear, torn procedures are not re-converged after initialization.

Start

Each torn procedure is called once at the start of the simulation. The values of the procedure input variables are the start values for the simulation. The outputs remain fixed to the values calculated from this first procedure call for the whole simulation.

Use Start mainly in dynamic simulations. This option is not normally recommended for steady-state or initialization runs. Because the outputs from the torn procedure are not updated, using them can result in solutions that do not satisfy the torn procedures.


Complete

The torn procedures are not called at all. The output variables are fixed to their start values for the whole simulation.

Use Complete mainly in dynamic simulations. This option is not normally recommended for steady-state or initialization runs. Because the outputs from the torn procedure are not updated, using them can result in solutions that do not satisfy the torn procedures.

Tear Update Strategy

You can define the algorithm used to converge torn procedures. The options are:

Strategy Action

Direct Uses direct substitution

Wegstein Uses Wegstein acceleration

Direct substitution is a reliable method for converging torn procedures. If you want a faster convergence, you can select the Wegstein convergence method. In some cases you need to tune the Minimum and Maximum Acceleration Parameters for Wegstein convergence.

If oscillatory convergence occurs in direct substitution, switch to Wegstein. Then give values for the minimum and maximum acceleration parameters of between 0 and 1. This may help to damp down any oscillations.

The Wegstein acceleration parameter is calculated for each torn variable with these equations:

( )1−=

SSQ

( ) ( )1

1

−

−

−−

=KK

KK

XXXGXG

S

Where:

X = Estimate of variable value

G(X) = Resulting Calculated variable value

K = Iteration number

The new estimate calculated by the Wegstein method is:

( ) ( )KKK XGQXQX ∗−+∗=+ 11

The following table shows the effect of the value of Q on convergence:

If Then the effect is

Q < 0 Accelerated convergence

Q = 0 Direct substitution convergence

0 < Q < 1 Damped convergence


The value of Q causes oscillatory behavior, and perhaps divergence, when greater than 1, and monotonic divergence when too negative. For this reason, the value of Q calculated by the Wegstein method is bounded by a Minimum and Maximum Acceleration Parameter.

The Direct substitution method can be derived from the Wegstein equation as a limiting case when Q = 0. With Q = 0 the Wegstein equation becomes:

( )KK XGX =+1

This means that the estimate of the value of the variable at the next convergence iteration is simply the calculated value for the current iteration.

Relative and Absolute Tear Tolerance

For runs using the Update option, you can control the accuracy within which a tear is converged, using relative and absolute tolerances.

Aspen Modeler uses these tolerances to determine if a tear is converged. The simulation is converged when the change in each output variable from the torn Procedure satisfies the following inequality:

( ) ( ) TearabstolXabsTearreltolXXabs KKK +∗<− ++ 11

Where:

Error! Objects cannot be created from editing field codes.

= Value of Procedure output variable after k iterations


= Value of Procedure output variable after k+1 iterations

Tearabstol = Value of Absolute Tear Tolerance

Tearreltol = Value of Relative Tear Tolerance

Minimum and Maximum Acceleration

The minimum and maximum acceleration are used to determine the stability and speed of the Wegstein convergence option for Tear Update Strategy.

The Wegstein acceleration parameter needs limits to avoid oscillations and/or divergence. The default values of the minimum and maximum acceleration of -5 and 0 are sufficient for most simulations.


Normally, you should use the maximum acceleration of 0. If the tear convergence is slow, you can use smaller values of the minimum acceleration, such as -25 or -50.

For non-divergent oscillatory behavior, use values for maximum and minimum acceleration between 0 and 1.

Maximum Number of Tear Iterations

The maximum number of tear iterations defines the tear iterations limit for steady state and initialization simulations using procedure tearing. The value can be any positive integer. If you define the maximum number of tear iterations to 0, there is no limit to the number of tear iterations.

Tolerances Tab The Tolerances tab enables you to change the options for controlling tolerances, and to control solver scaling and the elimination of equivalence equations.

You can change the value of the tolerances to affect the speed and accuracy of the solution under most solution methods available.

Relative and Absolute Variable Tolerance

The relative and absolute variable tolerances are used to:

• Converge non-linear equation groups when the convergence criterion includes a test on variable convergence.

• Determine whether the estimated local integration error for a variable is acceptable with the Gear (11.1) or VSIE integrators.

The test used for the two cases above is as follows:

( )ToleranceAbsoluteToleranceRelativeerrorLocal +∗⇐ X

Where:

X = Tested variable

The default values for the Relative and Absolute Variable Tolerances of 1E-5 are suitable for most simulations.

Absolute Equation Tolerance

The absolute equation tolerance defines the solution accuracy for the non-linear equation solver where the convergence criterion depends upon residual convergence. Iteration stops when the absolute value of the residual of each of the equations in the simulation is reduced below this tolerance.

The Absolute Equation Tolerance is used in the following types of simulation:

• Steady-state and initialization simulations.

• Re-initialization of dynamic simulations using the Gear integrator.

• Dynamic simulations using Explicit Euler, Implicit Euler, or Runge Kutta 4 integrators.


• Each iteration of a steady-state estimation or data reconciliation simulation.

The Absolute Equation Tolerance can take a real number greater than 1E-10. The default value of 1E-5 is accurate enough for most simulations.

Variable Change Tolerance

While Aspen Modeler is integrating a dynamic simulation, any change in any variable is compared to the variable change tolerance.

Under the following conditions, the integrator takes action depending on the integrator chosen:

ChangeTolXIFXChangeTolXX newnewoldnew ≥∗>−

or

ChangeTolXIFChangeTolXX newoldnew <>−

Where:


= Latest value of a fixed variable


= Value of a fixed variable at the previous integration step

ChangeTol = Variable Change Tolerance

With the Gear (11.1) integrator, if the integrator takes action due to the magnitude of change in a variable, the integrator re-initializes the simulation.

Variable change tolerance has no effect on the ImpEuler (11.1) integrator.

With the remaining integrators, the action taken depends on whether the Re-initialize after variable step change� box on the Integrator Solver Options Tab is ticked or not.

Numerical Derivative Absolute and Relative Perturbation

The perturbation for evaluating elements of the Jacobian matrix that are not available analytically is defined by:

If lDerivAbsToXlTolDeriv >×Re then XlTolDeriv ×= Reε

Otherwise lDerivAbsTo=ε


Where:


= Perturbation on Jacobian matrix element

X = Value of Jacobian matrix element to be perturbed

DerivAbsTol = Derivative Absolute Perturbation

DerivRelTol = Derivative Relative Perturbation

You can alter the values of the numerical derivative perturbation parameters to improve the evaluation of procedures that do not return analytical derivatives.

If the partial derivative of the procedure output variables with respect to the input variables is close to zero, the perturbations to the procedure inputs used to calculate the numerical derivatives may not produce any change in the output variables.

You can increase the perturbation to the input variables so that there is a detectable change to the output variables.

Tip: To get more accurate numerical derivatives for procedures, you can change the values of the perturbations. If your simulation is failing to converge and you suspect your procedures are highly non-linear, try reducing the values of the perturbations.

Solver Scaling

Aspen Modeler products enable you to scale variables for your simulations. Careful scaling can improve the robustness of the convergence and in some cases the performance of your simulations.

How Scaling Works

You supply scale values for the variables and Aspen Modeler computes appropriate equation scales to make the derivatives well-scaled to improve numerical stability.

The scaled variables� values are the values of the unscaled variables, divided by their scale value. The scaled results are then converted back to unscaled values for the reporting of results.

Scaling of variables is always applied, but the default scaling factor is 1 (this is inherited from the RealVariable type). When you supply a scale value to a variable, this scale factor is automatically applied to the solution algorithms for that variable, even if you do not request solver scaling.


If you switch on scaling, additional equation scaling is applied. This means that the solvers use the scaled equations, but the convergence tests use the original un-scaled equations.

Make sure that the equations you write in your models are well scaled, so that you produce a robust and easily-solved simulation. Use Solver Scaling to further improve your simulation performance. Do not rely on Solver Scaling to improve the performance of poorly scaled equations.

Supplying Values for Each Variable Type

To supply scaling values for each variable type, supply a value for the property called scale when you define the variable type, for example:

Variable FlowRate

Upper: 1000;

Lower: 0.0;

Value: 25;

Scale: 100;

End

In general, choose a scale factor such that the scaled variable is of magnitude 1 during the simulation.

If you do not want to scale a particular variable type, enter a scale value of 1.

Supplying Values for Individual Variables

To provide scaling values for individual variables, define a scale value for the variable�s scale property, for example:

Model Test

Temp as Temperature(Value:25, Scale:20) ;

Vol as Volume(Value: 1275, Scale: 1.0e3);

.

.

End

When you use scaling, the run-time output during solution from all non-linear blocks is in terms of the scaled variables and the corresponding scaled bounds.

Eliminate Equivalence Equations

An equivalence equation is an equation equating two variables.

An equivalence equation is stated mathematically as:

VariableX = VariableY ;

You can eliminate many equations of this form by enabling this option. When two variables are equivalenced, they will be replaced in the simulation by a "variable" with a name of the form AM_Equivalence<nnnn>, where <nnnn> is an integer which uniquely identifies the equivalence. These equivalences can


be seen in the Explorer Diagnostics views and you can examine the variables they contain.

An Equivalence behaves as if it were a variable in the simulation, with a value, bounds, scale factor, and specification.

Equivalence equations are generated from:

• Model equations.

• Connection of blocks in the flowsheet.

• Port matching.

• Equations in sub-block declarations.

An equivalence equation will NOT be eliminated if:

• The equation is within a run-time IF, or a SWITCH.

• Either variable is a parameter.

• Either variable is the time-derivative of another variable.

• Either variable has a specification of FIXED or INITIAL.

• Both variables are state variables.

• Both variables are algebraic variables with assigned values which differ by more than the Absolute Equation Tolerance.

Notes:

• Equivalencing happens before any snapshot is applied. Saving the simulation and re-loading can increase the compression ratio (which is the percentage of the equations in the simulation that have been eliminated).

• Equivalencing reduces the size of the solved problem, improving server performance by reducing memory use and CPU time, but can sometimes lead to groups in the problem being more difficult to solve. On rare occasions, a simulation will solve when equivalence equations are not eliminated, but not when they are: this usually indicates a modeling problem.

• If the ranges of the two variables do not overlap (that is, if the lower bound of one variable is greater than the upper bound of the other) then the problem is indeterminate because there is no value that can simultaneously satisfy both sets of bounds.

Elimination Precedence

The elimination precedence rules are used to determine the initial value and scale factor of the equivalence.

The bounds of the equivalence are such that the lower bound is the maximum of the lower bounds of all the variables in the equivalence, and the upper bound of the equivalence is the minimum of the upper bounds of all the variables in the equivalence.


The initial value of the equivalence is the average of the values of all the variables in the equivalence with the highest precedence from the following list:

Lowest • Variables of type RealVariable.

• Variables of type ControlVariable.

• Variables of any other type.

Highest • Variables (of any type) that have been assigned a value.

The scale factor of an equivalence is the largest scale factor of the variables in the list with the highest precedence

Example of Exception to Arbitrary Rule

In the following example, an equation of the form c=x; is shown:

C(IndexSet) as Large_pos_number (50);

X(IndexSet) as Molefraction (1.0/SIZE(IndexSet));

The equation will not be removed by the arbitrary rule if the Standard elimination method has been selected, provided no user-assigned values have been applied to either variable.

Use Group Decomposition

Group Decomposition is the process of breaking the problem to be solved into a number of much smaller sub-problems. Solving a series of sub-problems is usually more efficient than solving the whole problem simultaneously, and Aspen Custom Modeler uses group decomposition by default.

The 'Use Group Decomposition' check box controls the decomposition. When checked, a normal decomposition with potentially many sub-groups, is used. When unchecked, the entire problem is solved simultaneously. In either case, the 'decomposition' is visible in the Simulation Explorer under Diagnostics.

Integrator Tab The Integrator tab in the Solver Properties dialog box enables you to choose the integrator you use for your simulation. The integrator you choose depends on the type of models you have in the flowsheet and the objective of the run. Consider whether you are looking for speed, or accuracy and robustness.

Integrator Characteristics and use

Explicit Euler Explicit first order method. Fastest integration method with consistent speed but can become unstable. Often requires a very small step size to maintain stability.

Runga Kutta 4 Fourth order explicit method. Suitable for some stiff systems. Variable step size used to maintain error. Can be good for problems with a large number of disturbances.

ImpEuler (11.1) First order Implicit Euler method from ACM 11.1. Fixed


step size.

Used for simple flowsheets where a reliable, predictable integration is needed.

Implicit Euler First order Implicit Euler method. Step size can be variable (to control integration error) or fixed (integration error ignored). Fixed step method can be used for simple flowsheets where a reliable, predictable integration is needed. Variable step method (the default) should be used error must be controlled.

VSIE (11.1) Old method from ACM 11.1. Used for general simulations for speed, accuracy and stiff systems. Handles discontinuities well.

Gear (11.1)

Gear

Old Gear method from ACM 11.1 Used for general simulations when good event detection is required. Good for stiff systems. Decomposition is not used and tearing is ignored. Model discontinuities are located.

Variable order, variable step backward difference implicit method. Uses decomposition and obeys procedure tearing. You can define the behavior of the method for model discontinuities and variable step changes. Use when high accuracy is required.

When you have decided on the appropriate integrator, click the Name box to select the integrator.

Note: All integrators use decomposition except Gear(11.1) when solving your problem dynamically.

Except for Gear (11.1), during integration non-linear groups in the decomposition are solved using the solver and options specified in the Solver Options Non-linear tab.

Migrating from 11.1 Integrators to 12.1 Integrators Migrating from ImpEuler (11.1) to Implicit Euler 12.1 When migrating from ImpEuler (11.1) to the new version in 12.1, it is important to select the correct solver options if you wish to ensure the performance and accuracy of your simulation is as close as possible to the old version.

The following table lists the new integrator solver options and how you should set them to make the new Implicit Euler behave as close as possible to ImpEuler (11.1). Integrator Solver Option to be Set

Value or Source Solver Option

Step size type Fixed

Step size ImpEuler (11.1) integration step


Migrating from VSIE (11.1) to Implicit Euler 12.1

When migrating from VSIE (11.1) to the new version in 12.1, it is important to select the correct solver options if you wish to ensure the performance and accuracy of your simulation is as close as possible to the old version.

The following table lists the new integrator solver options and how you should set them to make the new Implicit Euler behave as close as possible to VSIE (11.1).

Integrator Solver Option to be Set

Value or Source Solver Option

Step size type Variable

Absolute integration error tolerance 5*VSIE(11.1) Absolute integration error tolerance

Relative integration error tolerance 5*VSIE(11.1) Absolute integration error tolerance

Absolute tear integration error tolerance 5*VSIE(11.1) Tear integration error tolerance

Relative tear integration error tolerance 5*VSIE(11.1) Tear integration error tolerance

Include sensitivity errors Checked

Re-converge torn variables As VSIE(11.1) Re-converge torn variables

Integration test error test includes States

Initial step size VSIE(11.1) Initial integration step

Minimum step size VSIE(11.1) Minimum integration step

Maximum step size VSIE(11.1) Maximum integration step

Always enforce minimum step size Unchecked

Interpolate communication time As VSIE(11.1) Use interpolation

Locate model discontinuities Unchecked

Re-initialize after Variable Step Change Unchecked

Non-Linear Tab Maximum iterations VSIE(11.1) Maximum corrector iterations

Migrating from Gear (11.1) to Gear 12.1

When migrating from Gear (11.1) to the new version in 12.1, it is important to select the correct solver options if you wish to ensure the performance and accuracy of your simulation is as close as possible to the old version.

The following table lists the new integrator solver options and how you should set them to make the new Gear behave as close as possible to Gear (11.1).

Integrator Solver Option to be Set Value or Source Solver Option

Step size type Variable

Absolute integration error tolerance Tolerances Tab Absolute variable tolerance

Relative integration error tolerance Tolerances Tab Relative variable tolerance

Maximum order 5

Include sensitivity errors Checked

Re-converge torn variables Unchecked

Integration test error test includes States and Algebraics

Initial step size Gear (11.1) Initial integration step*

Minimum step size Gear (11.1) Minimum integration step*

Maximum step size +Gear (11.1) Maximum integration* step

Always enforce minimum step size Checked


Interpolate communication time Checked

Locate model discontinuities Checked

Re-initialize after model discontinuities Checked

Discontinuity tolerance Gear(11.1) Event tolerance

Re-initialize after Variable Step Change Checked

Step size after Variable Step Change Gear(12.1) Initial step size

Non-Linear Tab Maximum iterations Gear(11.1) Maximum corrector iterations

Tearing Tab Procedure Tearing None

Non-Linear Solver Tab Method Fast Newton

Non-Linear Solver Tab Convergence criterion

Variable

Integrator Tab: Explicit Euler Explicit Euler is the simplest form of integrator. You can use Explicit Euler to run simulations where a faster and more regular simulation speed is more important than greater accuracy.

For Explicit Euler, the equation used to integrate state variables is:

( ) ( ) ( )tyhtyhty &•+=+

Where:

h = Integration time step

y(t) = Value of state variable at time t

y(t+h) = Value of state variable at time t+h

)(ty& = Time derivative of state variable at time t

Explicit Euler is a fixed step explicit integrator that uses Euler's method. It has the following advantages and disadvantages:

• Normally less accurate than other integrators.

• Because the step length is fixed, it is less accurate than Gear and Implicit Euler in tracking fast transients. In these cases, Gear and Implicit Euler cut their step length to follow the transients more closely. However, this slows down the speed at which the integration progresses.

• Ideal for use in operator training simulators, where real time performance is important because Explicit Euler continues at a near constant speed.

Note: Because Explicit Euler is an explicit method, the integration may become unstable, causing the run to terminate. This is not an error, but is a feature of this relatively simple integration method. If instability occurs, try reducing the size of the Step Size, or changing the formulation of your model.

You can specify the following options for Explicit Euler:

• Step size

• Interpolate step size


Caution: A larger integration step may make the simulation unstable. Unlike other integrators, Explicit Euler does not stop integrating if the accuracy of the solution starts going out of tolerance. Always validate the data produced from Explicit Euler with a more accurate integrator.

Integrator Tab:Runge Kutta 4 You can use Runge Kutta to integrate using an explicit fourth order method. It is a variable step, fourth order, explicit Runge-Kutta integrator. Because it has a high order and a variable step, it is normally more accurate than Explicit Euler. For given values of the Integration and Tear error tolerances, the accuracy is comparable to that of the Gear and VSIE (variable step) integrators.

Runge Kutta 4 is suitable for a wide range of applications, although Gear is more suitable for very stiff systems. It can be very effective on some problems which have a large number of disturbances.

Caution: Avoid using a large value of the Relative Tolerances (greater than 1e-3), as this may result in excessively large integration steps, causing instability or failure of the integration.

You can specify the following integrator options for Runge Kutta 4:

Absolute and Relative integration

Absolute and Relative tear

Re-convergence torn variables

Initial step size

Minimum step size

Maximum step size

Interpolate to communication time

Integrator Tab: ImpEuler (11.1) The Implicit Euler integrator is the default and is very fast for basic simulations.

Implicit Euler is a first-order, fixed-step implicit integrator that uses a backward Euler's method.

For Implicit Euler the equation used is:

( ) ( ) ( )htyhtyhty +•+=+ &

Where:





( )hty +& = Time derivative of state variable at time t+h

Fixed-step Implicit Euler has the following advantages and disadvantages:

• Remains more stable than Explicit Euler whatever the value of the integration step size.

• Becomes increasingly inaccurate as you increase the step size.

• Steps over discontinuities without locating the event or re-initializing.

• For a given simulation and step size, is normally slower than Explicit Euler, because it has to perform iterative calculations to solve the integration equations.

Implicit Euler: Integration Step

You can specify the Integration Step to control the speed of the simulation. In general, the larger the integration step, the faster a simulation runs. Try to obtain an optimum integration step for your simulation because too large an integration step causes your run to fail to converge.

Integrator Tab: Implicit Euler The Implicit Euler integrator is the default and, when the step is variable, very fast for basic simulations.

Implicit Euler is a first-order, implicit integrator that uses a backward Euler's method.

For Implicit Euler the equation used is:

( ) ( ) ( )htyhtyhty +•+=+ &

Where:




( )hty +& = Time derivative of state variable at time t+h

You can choose between a fixed or variable step size using the Fixed and Variable radio buttons. Integration error is ignored when the step is fixed: use this when you want consistent and predicable dynamic simulation performance over time. To obtain greater accuracy and efficiency, the step size should be variable.

Implicit Euler has the following advantages and disadvantages:

• Remains more stable than Explicit Euler whatever the value of the integration step size.

• Becomes increasingly inaccurate as you increase the step size.

• For a given simulation and step size, is normally slower than Explicit Euler, because it has to perform iterative calculations to solve the integration equations.

You can specify the following integrator options for Implicit Euler.


Error tolerances:

Absolute and Relative integration

Absolute and Relative tear

Include sensitivity errors

Re-convergence torn variables

Integration error test includes

Step size: fixed or variable

Initial step size

Minimum step size

Maximum step size

Always enforce minimum step size


Locate model discontinuities

Discontinuity tolerance

Re-initialize after variable step change

Step size after variable step change

Show highest integration errors

Show highest tear integration errors

Integrator Tab: VSIE (11.1) VSIE combines the speed advantages of Implicit Euler and the robustness around fast transients of variable step integrators like Gear. You can use VSIE for simulations that are fairly stiff where you want an improvement in speed over the Gear integrator.

VSIE has the following advantages:

• Can take large step sizes.

• Maintains accuracy according to an error control strategy.

• For many dynamic simulations, consumes less overall computational time than the fixed-step option.

• For many dynamic simulations, provides more accurate results during highly transient conditions than the fixed-step option.

VSIE: Initial Integration Step

You can specify the size of the first integration step after initialization or re-initialization by changing the value of Initial Integration Step.

You can use this option to improve the speed and robustness of a simulation, for example, if a run fails or goes slowly just after initialization or re-initialization. If error messages report that the step is too large after an initialization or re-initialization, decrease the initial integration step to a value of about the same size as the step reported in the message window when converging. The default value is 0.005.


VSIE: Maximum and Minimum Integration Step

You can limit the maximum and minimum size of an integration step by setting Maximum Integration Step and Minimum Integration Step.

You can set the maximum and minimum integration steps to avoid situations where the integrator may miss a discontinuity, or where you want the integrator to step over a unrealistic discontinuity, such as a step change in property data where phase changes are taking place. The minimum and maximum step sizes are 0.001 and 0.05 respectively.

Tip: Setting too large a value for the minimum integration step may result in inaccurate results. If you see the integrator rejecting steps of this size, you may wish to decrease the minimum to allow a greater degree of accuracy.

Note: If you set these two properties to the same value, then the VSIE acts in the same way as Implicit Euler.

VSIE: Step Reduction Factor

When an integration step is rejected as being out of tolerance, the integration step is reduced by a factor. The default factor of 0.5 means that the step is halved when the integration step fails. You can change the step reduction factor to a more aggressive value (greater than 0.5) or a more conservative value (less than 0.5).

To determine your change to the step reduction factor, note how often the integrator is cutting back the integration step. If a simulation repeatedly cuts back the step, reduce the value of the step reduction factor. If you want to improve the speed of integration during a simulation with mild transients, try increasing the step reduction factor.

VSIE: Maximum Step Increment Factor

When the VSIE integrator detects that there are no significant transients in the simulation, the integrator gradually increases the step size to speed up the integration. You can limit how aggressive the increase in step size is by decreasing the maximum step increment factor. A smaller value causes the integrator to be more cautious in increasing the step size.

If you know that there are repeated step changes in the simulation, try reducing the maximum step increment factor. This ensures that the step does not get too large and time is wasted repeatedly cutting the integration step at each discontinuity.

VSIE: Absolute and Tear Integration Error Tolerance

The absolute integration error tolerance is used by the integrator to determine any increase in integration step based on the values of state variables in the simulation.


When you enable torn procedure calls, the tear integration error tolerance determines any increase in integration step based in the values of torn variables.

At each integration step, the following calculations are made to determine the value of the next integration step.

4.0

21

=

RMS_StateIntErrTolTemp 4.0

2

=

RMS_TearTearErrTolTemp2

( )Temp2 Temp1, Fac,MaxStepIncMINTemp3 =

( )Temp3 0.5,MAXStepIncFac =

Where:

RMS_State = Root-mean-square of the relative differences between the predicted and corrected values of the state variables

RMS_Tear = Root-mean-square of the relative differences between the current and the previous integration step�s values of torn variables

IntErrTol = Integration Error Tolerance

TearIntErrTol = Tear Integration Error Tolerance, default 0.01

Temp1, Temp2, Temp3

= Intermediate variables

MaxStepIncFac = Maximum Step Increment Factor, default 1.5

StepIncFac = Step Increment Factor for the next integration step

VSIE: Maximum Corrector Iterations

Maximum Corrector Iterations is the maximum number of iterations the corrector can take to converge a step. The default of 150 is suitable for most simulations. However, for some difficult simulations you may need to supply a larger number.

VSIE: Show Highest Integration Errors

When set to a value x greater than zero, the integrator will display the x variables with the largest contribution to the integration error and the x variables with the largest contribution to the tear error. This is useful when attempting to diagnose why a simulation is failing to converge. There is a slight performance penalty for using this option, so set it until zero unless you need to use it.


VSIE: Use Interpolation

You can use interpolation to improve the speed of your simulation. When Use Interpolation is cleared, the simulation will cut an integration step to coincide with a reporting interval, giving the most accurate results possible with the current simulation settings. When Use Interpolation is selected, values of reporting intervals are calculated using a linear interpolation between the two adjacent integration points. This allows the integrator to maintain its current step size and avoids slowing the simulation, but reduces the accuracy of the results.

VSIE: Reconverge Torn Variables

You can choose to converge all the output variables for torn procedures if the procedure tearing option is set to update. If the procedure tearing option is set to start or complete, torn variables are not updated at all during integration.

By default, output variables for torn procedures are not converged at each integration step. Instead, the values of the output variables are simply updated if the procedure tearing option is set to update.

If you select Reconverge Torn Variables, this forces the torn variables to be converged iteratively at the end of each integration step. Reconverging the torn variables gives a more accurate and possibly more stable solution. However, it requires more processing which can cause a simulation to run more slowly.

Integrator Tab: Gear(11.1) The Gear integrator uses a modified Gear�s method algorithm. Gear automatically varies the integration step and integration algorithm order so that the estimated integration errors are within a tolerance determined from the Relative and Absolute Variable tolerances.

Gear can cope with partially indeterminate systems. (An indeterminate variable is one that has no unique value, that is, any value will satisfy your equations.) This situation can occur when, for example, there is no holdup in a vessel in a simulation where there are several components. The composition of components in an empty vessel cannot be determined. This type of system is singular. To handle this situation, Gear maintains the values of the composition at the time the values were last able to be determined, such as at the point the vessel became empty. When the vessel starts to fill again, the composition becomes determinate again.

Use the Gear integrator where you want to use a fast robust integrator that can handle difficult discontinuities, indeterminate simulations, and stiff systems.

Note: Gear(11.1) is the ACM 11 version of Gear and included in ACM 12 for backwards compatibility. It does not use decomposition, and tearing is ignored.


Gear: Show Highest Integration Errors

You can specify the number of variables shown that are giving the greatest integration errors in the simulation. To do this, you need to specify a number for the highest integration errors shown.

Use this feature to determine which variables are causing the integrator to take smaller integration steps than necessary, and are causing the run to slow down. You may want to change the scale of a variable if the variable consistently creates the highest integration error.

Gear: Initial Integration Step

You can specify the size of the first integration step after initialization or a re-initialization by changing the value of initial integration step.

You can improve the speed and robustness of a simulation if you find that a run fails or goes slowly just after initialization or re-initialization by changing the initial integration step.

If there are error messages that the step is too large after an initialization or re-initialization, decrease the initial integration step to a value of about the same size as the step reported in the message window when converging.

Gear: Maximum and Minimum Integration Step

You can limit the maximum and minimum size of an integration step by setting Maximum Integration Step and Minimum Integration Step

You can set the maximum and minimum integration steps to avoid situations where the integrator may miss a discontinuity, or where you want the integrator to step over a unrealistic discontinuity, such as a step change in property data where phase changes are taking place.

Gear: Event Tolerance

You can define the accuracy to which discontinuities are located by specifying a value of Event Tolerance.

You can reduce the value of event tolerance to get a more accurate location of an error. If you have a simulation that repeatedly locates a discontinuity at the same time point but cannot integrate past this discontinuity, you can decrease the event tolerance to locate the discontinuity better and resolve it before continuing to integrate.

Gear: Jacobian Update Policy

You can change the value of the Jacobian update policy to change the maximum number of corrector steps before the Jacobian matrix is updated.

Jacobian Update Policy controls the Jacobian matrix update strategy for the integrators shown in the following table.

Jacobian Update Policy can take an integer greater than 0. The default is shown in the table:

Integrator Default

Explicit Euler, RUNGE KUTTA 4, 5


Implicit Euler, and VSIE only when Fast Newton is used

Gear 0

This means Gear uses its own internal policy to decide when to update the Jacobian, based on rates of convergence.

If the Hybrid or Newton non-linear solver methods are used with Explicit Euler, Runge Kutta 4, Implicit Euler or VSIE, the Jacobian is updated every iteration. The Jacobian update policy has no effect.

These default values for Jacobian Update Policy are of general applicability. In some simulations, you can improve solution speed or robustness by adjusting this parameter. However, adjusting this parameter to improve one simulation may not produce an improvement in another simulation.

If you are having convergence difficulties, you can try reducing the value of Jacobian Update Policy. However, before spending time adjusting this parameter, first check that the cause of the convergence failure is not within your own simulation definition.

Gear: Re-initialization Method

During integration with Gear, the integrator needs to re-initialize whenever it encounters a discontinuity.

A discontinuity may be caused by:

• A step change in an input variable.

• A conditional equation switching from one branch to another.

• A sudden change in an output from a procedure.

You can use re-initialization method to control re-initialization during dynamic runs. Valid settings are:

Setting Result

Normal Use standard re-initialization

Fast Use fast re-initialization

Save Use re-initialization that saves additional numerical information, resulting in faster re-initialization (default)

If you specify fast re-initialization, an alternative re-initialization method is used for dealing with discontinuities. With fast re-initialization, rather than locating and solving all the equations at the discontinuity point, then integrator attempts to step over the discontinuity by making a number of small, first order integration steps. This alternative method can result in faster handling of the discontinuity but can give slightly less accurate results.

If you specify Save, additional information about the linear solver is saved. This reduces the calculations needed at re-initialization, which uses additional memory but reduces the time taken to re-initialize. If your computer has plenty of memory, we recommend that you use the Save option for all your dynamic simulations.


The Re-initialization Method switch is most useful in increasing the speed of simulations with a large number of discontinuities, when very high accuracy is not required. The default value is Save.

Gear: Show Highest Corrector Steps

Show Highest Corrector Steps enables Gear to show the variables that are producing the greatest corrector errors. If your simulation is failing due to corrector errors, you can use this option to determine which variables are contributing most to the integration failure.

Gear: Maximum Corrector Iterations

Maximum Corrector Iterations is the maximum number of corrector iterations the Gear integrator can take to converge a step. Set Maximum Corrector Iterations to be an integer greater than 0. The default is 5. However, for some difficult simulations you may need to supply a larger number.

Gear: Keep Solution within Bounds

If you enforce bound checking (Track or Clip), Gear enforces bounds at all times. If you do not have bound checking set (Off), bounds are only enforced at re-initialization.

The options are:

Select For Gear to

Track Track the variables as they lie on their bounds by cutting the integration step size

Clip Enforce bounds by clipping individual variable steps as they cross the bound

Off The solver allows variables to move outside their bounds during integration

Notes:

• In some cases, you may need to use Clip rather than Track to avoid the integrator taking very small step sizes.

• Although bound checking can improve the robustness of simulations, it sometimes causes an integration to proceed slowly. If the solution for a variable lies along its bound, Gear spends time checking that it does not cross the bound. If the variable bounds are causing Gear to slow down, you can set bound checking to Off or Clip.

• Values displayed in variable tables are always clipped within their bounds, regardless of the bound checking option. It is recommended that you change the bounds rather than rely on the bound checking Off option.

It is dangerous to use the Off option and allow variables to go outside their bounds during simulation. This should be done for debugging purposes only.


If you need to use this option to get a simulation to converge, it is better to enlarge the variable bounds, or work out why variables go outside their bounds.

Integrator Tab: Gear The Gear integrator uses an integration method based on Gear�s algorithm. It automatically varies the integration step (if the step size is Variable <link>) and integration algorithm order so that the estimated integration errors are within a tolerance determined by the Relative and Absolute Variable tolerances.

Use the Gear integrator where you want to use fast and accurate integration that can handle and stiff systems.

See Integrator solver options for the options can be used to control the behavior of the Gear integrator.

Integrator Solver Options Maximum Order

Defines the maximum order allowed when using the Gear integrator method. Default is 5 with range 1 to 5.

Error tolerances • Absolute and Relative integration.

• Absolute and Relative tear.

These tolerances only have an effect if the step size is Variable.

The absolute integration error tolerance is used by the integrator to determine any change to the size of the integration step based on the values of variables in the simulation.

When you enable torn procedure calls, the tear integration error tolerance determines any increase in integration step based in the values of torn variables.

The integration variable step size at time t is accepted if:

1)(

)()(11

2

0

≤

+

−∑

=

N

i

p

ATOLixRTOLixix

N (1)

and, when there are torn procedures in the ACM flowsheet and procedure tearing is set to update [2], if

1)(

)()(11

2

0

0 ≤

+−

∑=

N

i AtearTOLiRtearTOLii

N θθθ

(2)

where:


x: corrected state (and algebraic if Integration Error test includes is set to states and algebraics) variables at time t

px : predicted state (and algebraic if Integration Error test includes is set to

states and algebraics) variables at time t

0x : state and (and algebraic if Integration Error test includes is set to states

and algebraics) variables at time t-h

θ : torn output variables at time t

0θ : torn output variables at time t-h

n: number of equations

h: current integration step size

RTOL: relative integration error tolerance

ATOL: absolute integration error tolerance

RtearTOL: relative tear error tolerance

AtearTOL: absolute tear error tolerance

Include sensitivity errors

When checked (the default), and the integrator is computing sensitivities with a variable step size, the error in the sensitivity variables is taken into account when computing the step size. When unchecked, errors in the sensitivities are ignored.

In simulations where dynamic sensitivities are computed (dynamic parameter estimation, dynamic optimization and dynamic runs with sensitivities) and a variable step integration step method is used, it is recommended (and it is the default) to include a sensitivity error check at each integration point to make sure the sensitivities are accurate to within the integration error tolerances. When the sensitivity integration errors are greater than the integration errors in your usual flowsheet variables, then the current integration step size will be cut and a new integration step taken.

In some extreme cases, the integrator step can become very small due to repeatedly sensitivity integration error failures (set the Solver Reporting Level to High and look for "Step rejected due to sensitivity" messages in the Simulation Messages Window to see if this is occurring in your simulation), often resulting in your simulation running slowly. In these cases, it may be appropriate to un-check the Include Sensitivity Errors box to improve performance, at the expense of having less accurate sensitivities. In some cases, this may result in the dynamic estimation or optimization simulation failing; if it does, try tightening the integrator error tolerances, reducing the maximum integration step size, reducing the variable or equation tolerances or relaxing the estimator or optimizer tolerances.

Re-converge torn variables

You can choose to converge all the output variables for torn procedures.


By default, output variables for torn procedures are not converged at each integration step. Instead, the values of the output variables are simply updated if the procedure tearing option is set to update.

If you select Reconverge Torn Variables, this forces the torn variables to be converged iteratively at the end of each integration step. Reconverging the torn variables gives a more accurate and possibly more stable solution. However, it requires more processing which can cause a simulation to run more slowly.

Integration error test includes

You can switch between the state variables only and states and algebraic variables (the default) radio button to control which variables in your simulation are included in the integration error control. For maximum accuracy you should include both the states and algebraics.

Step Size

To fix the integrator step size (and ignore integration error), select the Fixed radio button and specify the step size to be used in the Step size box (default 0.01, range >0 and <1).

To use a variable step size, select the Variable radio button. The step size will be changed, subject to the initial, minimum and maximum step sizes , so that the integrator satisfies the error norm <link to error norms above> at every integration step size. The step will be variable to obtain best accuracy.

Initial Step Size

You can specify the size of the first integration step after initialization or a re-initialization by changing the value of initial integration step.

You can use this option to improve the speed and robustness of a simulation, for example, if a run fails or goes slowly just after initialization or re-initialization. If error messages report that the step is too large after an initialization or re-initialization, decrease the initial integration step to a value of about the same size as the step reported in the message window when converging. The default value is 0.005 and range is >0 to <1.

Minimum and Minimum step size

You can limit the maximum and minimum size of an integration step by setting Maximum Integration Step and Minimum Integration Step.

You can set the maximum and minimum integration steps to avoid situations where the integrator may miss a discontinuity, or where you want the integrator to step over a unrealistic discontinuity, such as a step change in property data where phase changes are taking place. The minimum and maximum step sizes are 0.001 and 0.05 respectively.

Tip: Setting too large a value for the minimum integration step may result in inaccurate results because the integrator will not go below the minimum even if the integration error is above tolerance. If you see the integrator stuck on the minimum step size, you may wish to decrease it to allow a greater degree of


accuracy.

Always enforce minimum step size

When checked, the minimum step size is enforced � the integrator will never choose a step size smaller than the minimum. When unchecked (the default), the integrator can go below the minimum to attempt to recover and continue integrating when there are repeated convergence failures when integrating.

Step Reduction Factor

This option controls how much the current integration step size is reduced by following a convergence failure during a dynamic run. The default is 0.5 and range between 0 and 1. For example, if the step reduction factor is set to 0.1 and a convergence failure occurs, the next step chosen is a tenth of the previous one.

Increasing or decreasing this value may improve the performance of your simulation if there are repeated corrector failures.


You can use interpolation to improve the speed of your simulation.

When Interpolate to Communication Time is unchecked, the simulation will cut an integration step to coincide with a communication time, giving the most accurate results possible with the current simulation settings.

When Interpolate to Communication Time is checked, variable values at communication times are calculated using interpolation. This allows the integrator to maintain its current step size for best performance, but can slightly reduce the accuracy.

Event Handling Locate model discontinuities

When checked, the integrator will detect when model discontinuities (IF and switch statements changing branch) occur, locate where they occur within the Discontinuity tolerance, step to that point and restart the integrator. When unchecked (default) , model discontinuities are not located and the integrator simply steps over them.

Discontinuity tolerance

This is the tolerance to which model discontinuities are located. Default if 1.e-5 and range >0 and <1.

Re-initialize after model discontinuity

Determinates the behavior after a model discontinuity is located. When checked, an algebraic re-initialization is performed. When unchecked (default), the integrator restarts by resuming integration at the located point and, when the step size is variable, uses the initial integration step.


Re-initialize after Variable Step Change and Step Size after Variable Step Change

Determines the behavior of the integrator following a step change in a variable value (when a fixed variable changes by more than the Variable Change Tolerance). When checked, an algebraic re-initialization is performed. When unchecked (the default), the integrator resumes using the fixed step size or, if the step size is variable, the initial step size if the Use Initial step size radio button is active (default) or continues using the previous step size if the Use previous step size radio button is active:

Note: A ramped variable has a step change at the start and end of the ramp.

Diagnostics Show highest integration errors

You can specify the number of variables shown that are giving the largest contribution to the integration errors in the simulation.

This diagnostic shows the largest values of the relative error term:

ATOLiRTOLixix

+

−

)()()(

0

0

θ

used in the integration error norm over all variables contributing to the error test,

where:

x : corrected state and algebraic variables at time t

0x : predicted state and algebraic variables at time t

RTOL : relative integration error tolerance

ATOL : absolute integration error tolerance

To do this, you need to specify a number for the highest integration errors shown.

Use this feature to determine which variables are causing the integrator to take smaller integration steps than necessary, and are causing the run to slow down. You may want to change the scale of a variable if the variable consistently creates the highest integration error.

Show highest tear integration errors

You can specify the number of tear output variables shown that are giving the largest contribution to the integration errors in the simulation.

You can specify the number of tear output variables shown that are giving the largest contribution to the integration errors in the simulation.


This diagnostic shows the largest values of the relative error term:

AtearTOLiRtearTOLii

+

−

)()()(

0

0

θθθ

used in the integration tear error norm over all torn variables contributing to the tear error test,

where:

θ : torn output variables at time t

0θ : torn output variables at time t-h

RtearTOL: relative tear error tolerance

AtearTOL: absolute tear error tolerance



Use this feature to determine which tear output variables are causing the integrator to take smaller integration steps than necessary, and are causing the run to slow down. You may want to change the scale of a variable if the variable consistently creates the highest integration error.

Linear Solver Tab The Linear Solver tab in the Solver Properties dialog box enables you to choose the linear solver you use for your simulation.

To change the linear solver, click the Name box on the Linear Solver tab.

Linear Solver Tab: MA48 The linear solver is used to solve simple equalities. It is the fundamental routine that lies at the heart of all modes of simulation. Changes to the linear solver options affect all solution methods.

MA48 is an updated version of MA28, with the advantages of faster execution times. The default solver properties for MA48 are applicable for most situations. Any changes to the MA48 properties should be made with caution and good reason.

MA48: Drop Tolerance

You can alter the drop tolerance to force Aspen Modeler to calculate whether an element in the Jacobian matrix is small enough to be considered zero.

If you increase the value of drop tolerance, more elements are dropped from the Jacobian matrix, and the solution can be faster. However, more information is lost and the solution may not converge.


MA48: Pivot Tolerance

The pivot tolerance controls partial pivoting of the Jacobian matrix in the MA48 solver. Any pivot value below the pivot tolerance is considered numerically to be zero by the MA48 solver.

This feature is useful for cases where the Jacobian matrix is singular. The default value of zero is suitable for most simulations. If you have some very small values in the Jacobian matrix, setting the pivot tolerance to a small non-zero value, such as 1e-25, prevents pivoting on very small matrix element values.

MA48: Re-Analyze Threshold

The re-analyze threshold value determines when a Jacobian re-ordering step is required. Aspen Modeler keeps a moving average of the number of floating point operations (FLOPS) over a period defined by the Re-analyze FLOPS Window Size parameter. This average is compared to the number of FLOPS immediately after the previous Jacobian matrix re-ordering.

A new re-ordering operation is called when:

ialFLOPS_initThreshold analyze-RerageFLOPS_ave ∗>=

Where:

FLOPS_average = Average number of FLOPS over the previous number of factorizations defined by Re-analyze FLOPS Window Size

FLOPS_initial = Number of FLOPS immediately after previous re-order operation

The re-analyze threshold is the factor by which the initial number of FLOPS after the last Jacobian matrix re-order is allowed to increase before the next Jacobian matrix re-order is called.

MA48: Re-Analyze FLOPS Window Size

For each equation group the number of floating point operations (FLOPS) required to perform an MA48 factorization is stored over the number factorizations defined by the FLOPS window size. This enables Aspen Modeler to determine by how much the number of FLOPS is increasing and how to act on this change. Aspen Modeler keeps a moving average of the number of FLOPS. If this exceeds the Re-analyze Threshold, re-ordering of the Jacobian matrix is requested.

If you define a large FLOPS window size, Aspen Modeler evaluates a moving average of the number of FLOPS over a large number of factorizations. This means any sharp increase in the number of FLOPS may not be acted upon, as the sample taken for the average number of FLOPS is large.

If you define a smaller FLOPS window size, then a sharp increase in FLOPS quickly affects the moving average and Aspen Modeler responds to this change.

This option enables you to make Aspen Modeler sensitive to increases in the number of FLOPS taking place by decreasing the FLOPS window size, or to


make Aspen Modeler indifferent to FLOPS growth, by increasing the FLOPS window size.

MA48: Re-pivot every n Factorizations

You can define how often a re-pivot operation on the Jacobian matrix is performed. The default value is re-pivot every 0 factorizations. This means that MA48 re-pivots the Jacobian matrix whenever a zero pivot is found during factorization.

You can change this option if you suspect that convergence is being hindered because the MA48 solver needs a new pivot sequence. A typical value in this case is to re-pivot every 5 factorizations.

MA48: Solver Searches n Columns for Pivots

The number of columns searched for pivots determines how many columns the MA48 solver searches the Jacobian matrix for a suitable pivot point. The default value of 3 is suitable for most simulations. A value of 0 means that all columns in the Jacobian matrix are searched.

If you increase the number of columns searched, this can reduce the performance but can produce a more accurate solution. Only change the number of columns searched for a very sensitive simulation that is close to singularity.

MA48: Use Transpose

When checked, MA48 uses a transpose of the matrix instead of the original matrix when solving linear systems. This has the effect of changing the direction in which MA48 searches for pivots. For some models, using the transpose will be faster than using the original matrix. You may wish to use this option if your simulation is very slow (particularly if each non-linear iteration is taking a long time) to improve performance.

Linear Solve Tab: MA38 AOS_MA38 uses the MA38 package from the Harwell Subroutine Library, written by T.A. Davis and I.S Duff. It solves the system of linear equations Ax = b by factorizing the matrix A into LU factors and then performing a back/forward solve to compute x for a given b. We refer the reader to the references for full details of the algorithm and implementation. The package uses an unsymmetric multifrontal method of solution. It makes extensive use of Level 3 BLAS routines, attempting to exploit dense blocks within the matrix, potentially giving better performance because direct rather than indirect addressing can be used for such blocks.

All memory allocation is handled by the AOS MA38 wrapper code, making the AOS solver DLL very easy to use. The implementation is as efficient as possible and the minimum amount of work is performed when solving linear equations (for example, by avoiding re-pivot and re-analyze operations unless absolutely necessary).

The solver options exposed for the AOS DLL allow direct access to the options in the MA48 code itself (for example, PivotTolerance), some extra options


(RePivot, UseTranspose) that control the way the AOS DLL manipulates the MA38 code, including influencing the way memory requirements are estimated (GrowthFactor, InitialFactor) and using the Harwell Subroutine MC29 to scale the linear equations (ScaleVariables).

For most applications it is not necessary to change any of these options from their defaults. However, if it is taking a long time or a large amount of memory in the SetMatrixVals method, then changing the following options may help improve the performance:

• InitialFactor

• GrowthFactor

• PivotSearch

• UseTranspose

If it is unexpectedly reported that the problem is singular, then changing PivotSearch; ScaleMatrix; PivotTolerance may help avoid the singularity. See the help on each option for further details.

References

[1] Arioli, M., Demmel, J.W. and Duff, I.S. "Solving sparse linear systems with sparse backward error", SIAM J. Matrix Anal. Appl. 10, p165-190, 1989.

[2] Curtis and Reid, "On the automatic scaling of matrices for Gaussian Elimination", J. Inst. Maths. Applics. 10, p118-124, 1972.

MA38: Solver Parameters Name Description

Print Level Level of detail to print

Scale Matrix Scale matrix using MC29

UseTranspose Use matrix transpose for factorization

BlockTriangularization

Pre-order matrix to block triangular form

PivotSearch Maximum number of columns to search for pivots.

PreferDiagonalPivots Prefer on-diagonal pivots for roughly symmetric matrices

DenseBlockSize Block size for numerical factorization of dense blocks

MaxIterRefinements Maximum number of steps for iterative refinement.

PivotTolerance Tolerance for partial pivoting test

FrontalAmalgamation

Control how much frontal matrix can grow due to amalgamation.

InitialFactor Amount of workspace at start as a multiple of nnz

GrowthFactor Amount to resize workspace as a multiple of nnz

RePivot MA38 Re-pivoting frequency


PrintLevel: Level of detail to print

Type: integer; default 0;

Range: 0 No messages output

1 Only error messages printed.

2 Errors and warnings printed.

3 Errors and warnings and terse diagnostics (only first ten entries of arrays printed, a; thennl duplicate and invalid entries).

4 Errors and warnings and most information on input and output parameters printed.

5 Errors and warnings and all information on input and output parameters printed.

The above are all controls on the output printed by the HSL routines. In addition, a small amount of diagnostic information (relating to resizing the arrays if not enough workspace was specified initially), is printed if the print level is greater than zero.

Warning: Selecting values 4 or 5 for this parameter can give rise to excessively large amounts of output, as it causes MA38 to dump out the entire sparse matrix, and all other arrays. This should only be used for diagnostic purposes if a solve runs into problems.

ScaleMatrix: Scale matrix using MC29

Type: String

Range: No Do not scale matrix (default)

Yes Scale matrix

When "Yes" is selected, the MC29 routine from the Harwell Subroutine Library (see [2]) is used to rescale the rows and columns of the matrix prior to factorization (and to un-scale the resulting solution from the Solve method so that the solution is in the original scale). The scales are re-computed every time MA38 re-factorises. Using scaling can improve the numerical solution of the linear equations and is particularly useful for ill-conditioned or badly-scaled problems.

UseTranspose: Use matrix transpose for factorization

Type: String

Range: No Do not use the transpose of the matrix for

factorization (default)

Yes Use the transpose of the matrix for factorization

The default is "No", but when "Yes" is selected, MA38 uses a transpose of the matrix instead of the original matrix when solving the linear system. This has the effect of changing the direction in which MA38 searches for pivots. For


some models, using the transpose will be faster than using the original matrix. You may wish to use this option if MA38 to improve performance if calls to the SetMatrixVals method are taking a long time.

BlockTriangularization: Pre-order matrix to block triangular form

Type: string;

Range: No do not block triangularise

Yes attempt to block triangularise (default)

Controls whether MA38 attempts to block triangularise the matrix. Re-ordering the matrix into lower block triangular form (whether this is possible depends on the structure of the matrix) and solving each block in term can be more efficient than handling the matrix as a whole (but may introduce small numerical errors into the solution).

PivotSearch: Maximum number of columns to search for pivots.

Type: integer; default 4; range [1, 10000000]

PivotSearch controls how many columns MA38 searches for suitable pivots in the matrix. The default value of 4 is suitable for most simulations. Increasing the number of columns searched may mean MA38 takes more time in the factorization stage, but can produce a more accurate solution. It may be worthwhile to change the number of columns searched for a very sensitive simulation that is close to singularity.

PreferDiagonalPivots: Prefer on-diagonal pivots for roughly symmetric matrices

Type: string;

Range: Yes Prefer on-diagonal pivot elements

No Don�t restrict pivoting to diagonal elements (default)

If "Yes" is selected, then pivots on the diagonal of the matrix are preferred over off-diagonal pivots. If the matrix has been preordered into Block Upper Triangular form, then the diagonal of the permuted matrix is preferred. If "No" then no preference is made. Selecting "Yes" for this option is useful for matrices that are symmetric in structure and diagonally dominant, since fill-in is often less if symmetry is preserved. This is only a preference in the sense that, when searching a column for a pivot, the diagonal entry is accepted if it passes the threshold test (see PivotTolerance), otherwise an off-diagonal in that column can still be chosen.

FullFactor: Block size for numerical factorization of dense blocks



This is the block size for the numerical factorization of the dense frontal matrices. It controls the trade-off between Level 2 and Level 3 BLAS. The best value of this parameter depends on the computer being used. The typical range is 16-64. The default value of 32 should generally not be changed.

MaxIterRefinements: Maximum number of steps for iterative refinement.

Type: integer; default 0; range 0-20.

If this is set to a non-zero value, then this is the maximum number of steps of iterative refinement performed. Normally this should be set to zero, as linear solves are normally used as intermediate steps in a non-linear problem and an exact solution is not normally required. Clearly the more steps used, the longer a solution takes.

PivotTolerance: Tolerance for partial pivoting test

Type: real; default 0.1; range 0-1.

This parameter is used to control the relative numerical pivot tolerance. If zero, then no relative numerical test is made. If greater than zero, a pivot aij(k) musts satisfy the threshold partial pivoting test: | aij(k)| = PivotTolerance * maxi| aij(k)|, where the notation aij(k) refers to the entry in the partially factorized matrix just prior to step k of Gaussian elimination.

FrontalAmalgamation: Control how much frontal matrix can grow due to amalgamation.

Type: real; default 2.0; range 1.0-3.0

Controls how much a frontal matrix can grow due to amalgamation. A value of 1.0 means that no fill-in due to amalgamation will occur. Some amalgamation is necessary for efficient use of the Level 3 BLAS.

InitialFactor: Amount of workspace at start as a multiple of nnz.

Type: real; default 5; range [ 2,100]

This parameter determines the initial amount of real and integer workspace allocated prior to calling MA38. It is expressed as a multiple of the number of non-zeros in the initial matrix. The LU factorization typically generates fill-in, so the decomposition is less sparse than the original. A good default value is 4, but some matrices may generate a lot more fill-in than this. If insufficient workspace has been allocated, then MA38 sets a flag and causes the AOS solver to resize one or both arrays, controlled by the parameter GrowthFactor. However, resizing the matrix every time is inefficient, and if a resize has taken place, then the user should increase the size of this parameter.

GrowthFactor: Amount to resize workspace as a multiple of nnz

Type: real; default 1; range [0.0,5.0]


This option controls the amount of workspace memory allocated with the current amount of memory (see InitialFactor) is insufficient to analyse or factorize the matrix. When the memory is insufficient, MA38 computes an estimate of the likely amount of memory required (this is only an estimate because it is not possible to determine the precise memory requirement in advance or when the numerical values change.)

This option allows an extra GrowthFactor*NNZ of memory to be allocated on top of the MA38 estimate, where NNZ is the number of non-zero entries in the matrix, and thus increasingly the likelihood that the subsequent factorizaton will have enough memory to succeed. The default is 0, which means no extra memory is allocated. This option can be set above zero (e.g. to 0.5) if it is taking a long time to factorize the matrix (the SetMatrixVals method is taking a long time) and it is clear that the memory being used by the DLL is incrementing in a number of steps during the SetMatrixVals call.

RePivot: MA38 Re-pivoting frequency


You can use this option to control how often a re-pivot operation on the matrix is performed by MA38. The default value of 0 means that MA38 re-pivots the matrix only when a zero pivot is found during factorization (this is the most efficient, but not necessarily the most robust).

You can change this option if you find that the convergence is being hindered or is stalled. A typical value in this case is to re-pivot every 5 factorizations.

Linear Solver Tab: MA28 The linear solver is used to solve simple equalities. It is the fundamental routine that lies at the heart of all modes of simulation. Changes to the linear solver options affect all solution methods.

MA28: Drop Tolerance

You can alter the drop tolerance to force Aspen Modeler to calculate whether an element in the occurrence matrix is small enough to be considered zero. If you increase the value of drop tolerance, more elements are dropped from the occurrence matrix, and the solution is faster. However, more information is lost and the linear solvers may not converge.

Non-Linear Solver Tab From the Non-Linear Solver tab in the Solver Properties dialog box, choose Diagnostics, or General, or Tolerances when the selection in the Mode field is �Standard�, or select an Open non-linear algebraic (NLA) solver when the selection in the Mode field is �Open NLA Solver�.


Non-Linear Solver Tab: General The General option is on the Non-Linear Solver tab in the Solver Properties dialog box. The non-linear solver is used to converge sets of simultaneous equations or equations where there is no direct solution.

General: Method

You have a choice of four options for the non-linear solver method.

Option Comments

Newton Most robust, slowest method

Fast Newton Fastest, may not be the best method in some cases

Hybrid Fast, may not converge as well as other methods

Mixed Newton Uses Newton for initialization and steady state steps and Fast Newton for dynamic steps and is the default method. This is the best combination of speed and robustness for most dynamic simulations

General: Newton

Newton calculates a new Jacobian matrix at every iteration. The Newton non-linear solver method is slower than the other available methods, especially if there are a lot of procedure calls that do not return derivative information, because the Jacobian elements for variables output from procedures have to be calculated numerically. However, Newton can be more robust and may solve some simulations that fail to converge using Hybrid.

Newton is most useful for steady-state and initialization runs, where solution speed is not the most important factor.

General: Fast Newton

Fast Newton updates the Jacobian matrix only when convergence progress is poor. By recalculating the derivatives less frequently, it is usually the fastest method, but it may take a different path to solution, so its effectiveness varies.

In general, Fast Newton is the best method when moving a simulation from one solution to a close neighboring solution. It is recommended that you use Fast Newton if you are:

• Using the Explicit Euler, Implicit Euler, VSIE or Runge Kutta 4 integrator options, where the solution of each equation group of the decomposed simulation advances incrementally with time.

• Running steady-state simulations with good initial estimates.

General: Hybrid

To try to improve performance, Hybrid uses an approximate update method, where possible, to estimate values of numerical derivatives in the Jacobian matrix instead of calculating new values every time.


Note: Although the Hybrid method can give an increase in speed, the robustness of the solution may be reduced.

General: Convergence Criterion

You can define the parameters on which a simulation is considered converged:

Convergence Criterion

Description

Residual Convergence determined by the difference between the left and right hand side of an equation

Variable Convergence determined by the largest change in a variable value during the non-linear solution

Residual and Variable Both Residual and Variable convergence must happen

Residual or Variable Either Residual or Variable convergence can happen

General: Maximum Divergent Steps

You can use Maximum Divergent Steps to specify the number of divergent steps the non-linear solver takes before the solver returns to the previous best point and tries again.

You can increase this number if you think that the solver is getting close to converging but proceeding slowly and giving up before reaching the solution.

General: Maximum Step Reductions

You can use Maximum Step Reductions to specify the number of returns to the previous best point allowed before the solver decides it cannot converge.

You can increase this number if you think that the solver is getting close to solution but terminates the attempt before it gets to solution.

Increasing the maximum step reductions can help to converge a solution that fails to converge with the default number of maximum step reductions but does not appear to be divergent close to the solution point.

General: Maximum Iterations

You can specify the maximum number of iterations taken by the non-linear solver before the solver stops looking for a solution.

You can increase this value if you think that the solver is not diverging near the solution point but needs more time to get to a converged solution.

General: Maximum Fast Newton Steps

The number of Fast Newton steps taken before a new Jacobian matrix is calculated is limited by the value of the Maximum Fast Newton Steps parameter.

You can increase this number for stable dynamic simulations to try to improve the speed of integration. If the simulation has fast transients then increasing


the maximum number of fast Newton steps before a new Jacobian matrix is calculated can slow the performance.

General: Dogleg Method

The Dogleg Method option is used to select the method for calculating a variable step.

The default is not to use the Dogleg method, but to use a Newton-based method to determine the search direction.

The Dogleg method uses a combination of the direction calculated by a Newton method and that calculated by a steepest descent method. This may prove more robust for simulations that are difficult to converge, or when it is not possible to provide a good initial guess for the solution.

Dogleg has an effect during steady-state runs; the initialization and re-initialization of dynamic runs; dynamic runs using the Explicit Euler, Implicit Euler, and VSIE integrators; and estimation runs.

Non-Linear Solver Tab: Diagnostics The non-linear solver is used to converge sets of simultaneous equations or equations where there is no direct solution.

You can use the non-linear solver diagnostics to try and understand why a non-linear equation or group of equations containing more than one equation is failing to converge. The Diagnostics option is displayed on the Non-Linear Solver tab in the Solver Properties dialog box.

Diagnostics: Highest Variable Steps

You can define the number of variables shown that take the largest steps between successive non-linear solver iterations. You can see which variables are causing the solver to work hardest to get to solution.

With this information, you can change the equation containing these variables to improve linearity, scale the variables or perhaps give the variable a different starting value.

Diagnostics: Highest Residuals

Highest Residuals defines the number of equations displayed in the simulation output that are furthest from residual solution. These equations are those that have the largest difference between the left and the right hand side. Only the residuals which are above the absolute equation tolerance are displayed.

You can rearrange or re-scale equations that are consistently holding up solution, and so improve the speed of convergence.

Diagnostics: Print Linear Algebra for Groups of Size >= n

You can use this option to specify which equation groups send detailed solution information to the simulation messages window. All equation groups larger than the size you state display the detailed solution information.


Typically you can use this option to determine how hard the linear and non-linear solvers are working to solve the largest equation groups in your simulation.

Non-Linear Solver Tab: Tolerances You can change the default tolerances for the non-linear solvers to try to improve the speed and robustness of convergence.

The Tolerances option is displayed on the Non-Linear Solver tab in the Solver Properties dialog box.

Tolerances: Maximum Range Fraction

Use the Maximum Range Fraction option to constrain a variable step to a fraction of the variable range. The range is the difference between the upper and lower bound for the variable. The variable step may not exceed the product of Maximum Range Fraction and this range, that is:

( )BOUND Lower-BOUND UPPERFraction Range Maximum STEP VARIABLE ∗<

A value of less than 1 is useful if large variable steps are making convergence difficult.

Maximum Range Fraction affects steady-state runs; the initialization and re-initialization of dynamic runs; dynamic runs using the Explicit Euler, Implicit Euler, and VSIE integrators; and estimation runs.

The default value of 0 means that no restraints are imposed. The valid range is any positive real number.

Tolerances: Maximum Approach to Bound

The Maximum Approach to Bound option is used to constrain a variable step that would cross a bound. When solving simultaneous equations, a calculated step for a variable may violate the bound on that variable. By default, Aspen Modeler cuts the step so that the updated value is at the point where the step crosses the bound. It is sometimes better for the step to be cut to some fraction of the distance to the bound, so that it does not end up on the bound. This fraction is the Maximum Approach to Bound.

If a simulation converges very slowly as one or more variables move along a bound, or if the equations become ill-conditioned or singular at the bound, you can try a value of, for example, 0.9.

Maximum Approach to Bound affects steady-state runs; the initialization and re-initialization of dynamic runs; dynamic runs using the Explicit Euler, Implicit Euler, and VSIE integrators; and estimation runs. The default value is 1.0, and the valid range is:

(real) 1Bounds to ApproachMaximum0 ≤<


Tolerances: Absolute and Singularity Perturbation

For steady-state and initialization runs, when the non-linear solver reaches a point where there is a singularity, the singular variables are moved by an amount determined by:

AbsPerturbXIFbSingPertur ≤

� or �

AbsPerturbXIFXbSingPertur ⟩∗

Where:

X = Current singular variable value

AbsPerturb = Absolute perturbation

SingPerturb = Singularity perturbation

You can change the values of Absolute Perturbation and Singularity Perturbation if the default values are not able to move the solution away from a singularity.

For dynamic runs, no perturbation is used for singularities, and the Absolute and Singular Perturbation parameters have no effect.

Tolerances: Maximum Variable Step

You can use the Maximum Variable Step to specify the maximum step taken in a variable by the non-linear solver per iteration. The range is 0.1 to 100 and default is 50.

Reducing this value can improve the robustness of convergence by limiting (damping) how much the Newton solver can move variables from one iteration to the next. Reducing this value can also help when a variable is stepping repeatedly about a solution point but cannot converge to the solution.

The whole Newton step is scaled by a damping factor α such that for the Newton step δX in each variable X:

α * ∆X <= ( Maximum Variable Step * |X_c| if |X_c| > Absolute Perturbation)

( Maximum Variable Step otherwise)

where X_c is the value of X at the current iteration. The Maximum Variable Step is relative provided the absolute current value of the variable is > the value of the Absolute Perturbation option; otherwise it is absolute.

Tolerances: Clip Factor

If a Newton step in the non-linear equation solver results in the value of a variable going outside a bound, then the direction of the Newton step is truncated. The clip factor determines the method of truncation of the step.

The non-linear solver first determines an internal clip factor value between 0 and 1 to ensure the Newton step does not exceed the bounds for the variable.

If the calculated clip factor is less than or equal to Clip Factor, then the Newton step is clipped rather than scaled. Each element of the Newton step


direction that causes the variable bound violation is clipped so that the step in that variable results in the variable value being equal to the bound value.

If the calculated clip factor is greater than Clip Factor, the Newton step is scaled rather than clipped.

If you have defined a value for the Maximum Approach to Bound less than 1, the value of the variable after the Newton step is not equal to the bound value but is determined by the Maximum Approach to Bound factor.

If you set the value of Clip Factor to 1, you ensure that the Newton step is always clipped to the bound. If you set the value of Clip Factor to 0, you ensure that the Newton step is always scaled to the bound. The default value of 1e-6 ensures that the scaling approach is used unless the resulting step is very small, when the clipping approach applies. This means that time is not wasted making very small steps close to the bound.

When you are considering changing the value of Clip Factor, consider how far the current solution point is from the final solution. If the current point is far from the solution, set a small Clip Factor, as this allows a scaled step that gets towards solution faster. If there are many bound violations, a small Clip Factor results in fewer variables with values on the bounds. However, a small Clip Factor may result in slow convergence, as the Newton steps are too conservative. To arrive at the final solution point within a specified number of iterations, a larger Clip Factor may be better, as long as this does not mean that the solution is impeded by bound violations.

You may find that some convergence situations are not affected by Clip Factor, such as when you have small mole fractions and concentrations in the solution. In these cases, the benefits of increasing Clip Factor to give a faster approach to solution are outweighed by the possible closeness of the mole fraction and concentration values to their bounds.

Non-Linear Solver Tab: Open NLA Solver The Open NLA Solver option is displayed from the Mode box on the Non-Linear Solver tab in the Solver Properties dialog box. The non-linear solver is used to converge sets of simultaneous equations or equations where there is no direct solution.

Aspen Custom Modeler® allows external, non-linear algebraic equation solvers to be plugged in and used in the solution of simulations. To Aspen Custom Modeler, an external solver is a software component that implements a number of defined interfaces. These interfaces allow Aspen Custom Modeler to load the solver, set options and to drive the solution.

For more information on using external nonlinear algebraic solvers, see Chapter 12.

Note: You can specify an open solver and change the parameters through automation. For examples of using automation, see the Aspen Modeler Reference, Chapter 4. If the open solver or parameters change through automation then those changes will


be automatically reflected in this dialog box.

Optimizer Tab The Optimizer tab in the Solver Properties dialog box enables you to choose optimization options for your simulation.

You can choose the Optimizer used to solve your optimization problem from the following list:

• FEASOPT

• Nelder-Mead

• SRQP

• Open NLP - reduced space

• Open NLP - full space

• DMO

Optimizer Tab Reporting Level The Reporting Level controls the amount of diagnostics information in the simulation messages window that appears during an optimization simulation. Value Description

None No diagnostics

Low Information on the solution only

Normal As low plus values of the objective at each iteration and Lagrange multipliers at the solution (default)

High As normal plus values of the decision, initial and control variables at each iteration

Very High As high plus constraint and derivative information at each iteration

Homotopy Tab The Homotopy tab enables you to specify the options for homotopy steps. You can perform both steady-state and initialization homotopy runs:

• Steady-state homotopy enables you to step a steady-state solution to another steady-state solution by defining fixed variables.

• Initialization homotopy enables you to vary the initial conditions of an initialization run.

On the Homotopy tab, you can change the size of the first homotopy step, the maximum and minimum step size, and the size by which a step increases and decreases (depending on the success of the last step).

Important Note:


• To use the options you specify on the Homotopy tab, you must enable homotopy, and specify which fixed variables to use.

• Messages in the Simulation Messages window from the homotopy control that refer to values of homotopy variables are in the base units for the variable, not the selected Units of Measurement.

Homotopy Options This section describes the options on the Homotopy tab of the Solver Properties dialog box.

Initial Homotopy Step

In the Initial Homotopy Step box, you can specify the size of the first homotopy step following initialization or re-initialization. This size must be within the range of Maximum Homotopy Step and Minimum Homotopy Step. The range is any non-zero number to 1, and the default is 0.1.

Maximum Homotopy Step

In the Maximum Homotopy Step box, you can specify the maximum size of homotopy step. This size must be greater than the Initial Homotopy Step and Minimum Homotopy Step. The range is any non-zero number to 1, and the default is 1.

Minimum Homotopy Step

In the Minimum Homotopy Step box, you can specify the minimum size of homotopy step. This size must be less than the Initial Homotopy Step and Maximum Homotopy Step. The range is any non-zero number to 1, and the default is 0.05.

Step Size Increment Factor

In the Step Size Increment Factor box, you can specify the factor by which a homotopy step increases or decreases following a successful step. The range is any positive number greater than or equal to 1, and the default is 10. If the maximum number of iterations over all non-linear groups in the decomposition is > Step Size Increment Factor, then the homotopy step is increased by an amount inversely proportional to the number of steps; otherwise the step size is reduced by a factor of Step_Size / (maximum number of iterations).

Step Size Decrement Factor

In the Step Size Decrement Factor box, you can specify the factor by which a homotopy step is cut when the previous homotopy step fails to converge. The range is any non-zero number less than 1, and the default is 0.5.


Estimator Tab The Estimator tab in the Solver Properties dialog box allows you to choose one of the following methods to solve your estimation problem:

• Weighted least squares

• Maximum log likelihood

These options are available from the Estimator tab in the Solver Options dialog box.

Estimator Tab: Least Squares The Least Squares method minimizes the weighted absolute squared error between the observed and predicted values of the measurements. You should set the weights of the measured variables to be the reciprocal of the standard error (if they are known) of the observations.

To change the Estimation solver options, you can use Automation or the Solver Options dialog box. From the Estimator tab in the Solver Options dialog box, you can select least squares estimation. The sum of the differences between the measured data and the predicted values for the data points are minimized. The predicted data always conforms to a feasible solution for the simulation equations.

The following solvers can be used for Least Squares Estimation:

• NL2SOL

• Nelder-Mead

• Open NLP � reduced space

Note: NL2SOL uses the bounds on estimated and reconciled variables when choosing step size.

NL2SOL: Absolute Function Tolerance

If the absolute value of the sum of the squares of the weighted errors is less than the absolute function tolerance, the estimation run is considered converged. The estimation run successfully solves with absolute convergence.

If you use the default value of absolute function tolerance, in most cases the simulation will not solve by absolute convergence. This is because the default value of absolute function tolerance is deliberately very small, which means the measured data must have a very good fit with the simulation equations.

The default value of the absolute function tolerance is 1.0e-20. The valid range is any real number between 0.0 and 1.0.

NL2SOL: Relative Function Tolerance

If the predicted change in the sum of the squares of the weighted errors for the next NL2SOL iteration is less than the product of the relative function convergence and the current value of the sum of the squares of the weighted errors, and the last NL2SOL iteration achieved less than twice the predicted decrease in the sum of the squares of the weighted errors, the estimation run


is considered converged. The estimation run successfully solves with relative convergence.

The default value of relative function convergence is good for most simulations. If you reduce the value of relative function convergence below its default value, you need to increase the accuracy of the computation of the estimation experiments by reducing the value of the equation and/or variable tolerances (Solver Options Tolerances tab). In addition, for dynamic estimation runs you need to reduce the integrator tolerances. These additional tolerance changes ensure that the sum of the squares of the weighted errors are calculated to a sufficient accuracy.

The default value of the relative function tolerance is 1.0e-4. The valid range is any real number between 0.0 and 0.1.

NL2SOL: Solution Tolerance

If the relative change in the estimated parameters at the end of an NL2SOL iteration is less than the solution tolerance, and the last NL2SOL iteration achieved less than twice the predicted decrease in the sum of the squares of the weighted errors, the estimation run is considered converged. The estimation run successfully solves with solution convergence.

The default value of relative function convergence is good for most simulations. If you reduce the value of relative function convergence below its default value, you need to reduce the value of the residual tolerance. In addition, for dynamic estimation runs you need to reduce the values of the absolute and relative equation tolerances. These additional tolerance changes ensure that the changes in the estimated parameter values are calculated to a sufficient accuracy.

The default value of the solution tolerance is 1.0e-4. The valid range is any real number between 0.0 and 1.0.

NL2SOL: False Convergence Tolerance

If an attempted NL2SOL iteration produces less than 10% of the predicted reduction in the sum of the least squares of the weighted errors, and the relative change in the sum of the least squares of the weighted errors is less than the false convergence tolerance, and no other convergence test is met, then the run is considered to be at a false convergence point and stops.

The default value of false convergence tolerance is 0, which means that the tolerance is calculated from the machine accuracy. The default value should be used in most simulations. If you get a false convergence solution, investigate the following possible causes:

Cause Action

The experiments are not being calculated accurately enough to satisfy solution tolerances.

Do one of the following:

• Increase the Relative Function Tolerance and the Solution Convergence Tolerance. To change these tolerances, in the Simulation Explorer make sure Simulation is selected and then in the Contents pane double-click Solver Options and then click the Estimator tab.

� or �


• Decrease the Absolute Equation Tolerance, Absolute variable Tolerance, and Relative Variable Tolerance. To change these tolerances, in the Simulation Explorer make sure Simulation is selected and then, in the Contents pane click Solver Options and then click the General tab.

The measured variables is discontinuous around the solution point.

Review your model equations to make the simulation continuous about the estimation solution point.

If you think you are getting a false convergence due to the reasons given above, and you want the simulation to stop before reaching such a false convergence point, increase the value of the false convergence tolerance.

The default value for the false convergence tolerance is 0. The valid range is any real value between 0.0 and 1.0.

NL2SOL: Maximum Iterations

You can change the number of iterations NL2SOL attempts to solve the estimation simulation. Increase the number of iterations if you think the estimation run is converging slowly on a solution point and needs some extra iterations to get there. Reduce the number of iterations if you want to restrict the number of attempts to converge the estimation run for a large simulation.

Normally the default value should be used.

The default value for the maximum NL2SOL iterations is 50.

The valid range is any positive integer. Setting the value to zero will perform a simulation of each of your experiments at the current values of your estimated variables. This is useful to perform manual testing of how your measured variables depend on the estimated variables or how good the fit is for certain values of the estimated variables.

NL2SOL: Reporting Level

The Estimation Reporting Level controls the amount of diagnostics information in the simulation messages window that appears during an estimation simulation.

The values are:

Value Description

None No diagnostics

Low Information on the solution only

Normal As low plus values of the objective (least squares or maximum likelihood) at each iteration and covariance, correlation and standard error statistics at the solution (default)

High As normal plus values of the estimated variables at each iteration

Very High As high plus residual and derivative information at each iteration


Estimator Tab: Maximum Log Likelihood The Maximum Log Likelihood method maximizes the log of the likelihood function of the predicted and observed values. When the log of the likelihood function (and hence the likelihood function itself since log is a monotonically increasing function) is maximized, the probability of obtaining the given set of measurements from the estimated variables is maximized. This corresponds to getting the best fit of your measurements.

The following solvers can be used Maximum Log Likelihood Estimation:

• FEASOPT

• Nelder-Mead

• Open NLP - reduced space

Solvers for Optimization and Estimation The following table details the solvers available for Optimization and Estimation. Nelder-Mead and Open NLP - reduced space are common solver options. The other solvers are specific to the tab they are selected from (including the FEASOPT solver).

Optimization solvers:

Solver Type of Optimization Method

FEASOPT Steady state or dynamic Reduced space

Nelder-Mead Steady state or dynamic Reduced space

SRQP Steady state Full space

Open NLP - reduced space

Steady state or dynamic Reduced space

Open NLP - full space Steady state Full space

DMO Steady state or dynamic Reduced space

Reduced space optimization is where only the additional constraint equations (inequalities and equalities) in the flowsheet constraints section are handled by the optimization solver. The remaining flowsheet equations are solved at each value of the optimization variables (decision, initial and control) separately by steady state or dynamic simulations

Full space optimization is where both the additional constraint equations and all flowsheet equations are simultaneously handled by the optimization solver. It can only be used for steady state optimization.

Estimation solvers:

Solver Type of Estimation

NL2SOL Least squares only


FEASOPT Maximum likelihood only

Nelder-Mead Least squares or maximum likelihood

Open NLP - reduced space Least squares or maximum likelihood

NL2SOL, FEASOPT and Nelder-Mead are built in solvers supplied with ACM. The Open NLP interface allows you to interface your own solver.

FEASOPT FEASOPT is a feasible path successive quadratic programming optimizer. It can be used for optimization or maximum log likelihood estimation.

Note: To get a good starting point for FEASOPT, you should first successfully solve a steady-state or dynamic simulation before starting an optimization run.

FEASOPT evaluates the objective variable (the maximum likelihood function in the case of estimation) at the current point and moves the design variables, initial and control variables (in the case of optimization) or estimated variables (in the case of estimation) to take the objective variable towards its optimum value. After solving with the new values of the design, initial, and control variables or estimated variables, FEASOPT re-evaluates the objective variable. In this way, FEASOPT steps towards the optimum solution.

FEASOPT solves the simulation at each step subject to:

• Simulation equations

• Variable bounds

• Any constraints applied to the optimization

Note: Any changes you make to solver tolerances or Linear and Non-Linear options affect an optimization or estimation run using FEASOPT.

At each step, FEASOPT uses the solvers, equation group decomposition, and tearing to obtain a steady-state or dynamic solution, depending on the type of optimization chosen or type of estimation experiments. If after a step a solution cannot be obtained, FEASOPT goes back to the previously solved position and tries different values of the design, initial, and control variables or estimated variables.

FEASOPT: Solution Tolerance

The Solution Tolerance determines whether the improvement in the objective variable is small enough to consider the optimum point reached. If the absolute value of the improvement in the objective function is less than the Optimization Tolerance, the optimization or estimation run completes successfully.

You may increase the value of the Optimization Tolerance if your simulation contains discontinuities, or if you suspect that the simulation is poorly scaled. Increasing the value of Solution Tolerance makes the optimum easier to find, but the optimum point may not be as accurately located. You may have a


simulation that has local optimum values. Making the Solution Tolerance smaller may help to locate the true optimum point. The tolerance must be any positive real number. The default is 1.e-4.

Note: You must ensure that this tolerance is greater than the solver tolerances used to perform the optimization simulations or estimation experiments. It is recommended that you set this tolerance to at least an order of magnitude greater than the solver tolerances.

FEASOPT: Maximum Iterations

The Maximum Iterations determines how many steps towards an optimum point are attempted before the simulation stops looking for an optimum. The default value for the Maximum Iterations is 100. The valid range is any positive integer.

Setting the value to zero will perform a simulation of each of your experiments at the current values of your estimated variables. This is useful to perform manual testing of how your measured variables depend on the estimated variables or how good the fit is for certain values of the estimated variables.

You may need to increase the Maximum Iterations from the default of 100 in very rare circumstances. You can increase the Maximum Iterations if you believe the optimizer is approaching a true optimum, but slowly. If there is a small improvement in the objective variable at each step, you may be working in a flat region. Also consider increasing the value of the Solution Convergence Tolerance.

You may want to reduce this value to avoid excessive computations if the optimizer has problems in trying to find an optimum solution.

FEASOPT: Maximum Absolute Step

This determines the maximum absolute amount FEASOPT can move the optimization variables (decision, initial or control variables) from one iteration to the next. The default value is 0.01 and range 0.001 to 1. FEASOPT will not move each variable by more than:

{Maximum Absolute Step if Maximum Relative Step*abs(current value) <=Maximum Absolute Step

{Maximum Relative Step * abs(current value) otherwise

You can use this option to restrict how much FEASOPT moves the optimization variables which may improve the robustness of some optimization simulations.

FEASOPT: Maximum Relative Step

This determines the maximum relative amount FEASOPT can move the optimization variables (decision, initial or control variables) from one iteration to the next. The default value is 10 and range 0.01 to 10000. FEASOPT will


not move each variable by more than:

{Maximum Relative Step * abs(current value) if Maximum Relative Step*abs(current value) >Maximum Absolute Step

{Maximum Absolute Step otherwise

You can use this option to restrict how much FEASOPT moves the optimization variables which may improve the robustness of some optimization simulations.

Nelder-Mead Nelder-Mead is a direct search solver based on the simplex algorithm (see reference [1] for details). It: • Can require many more iterations to converge than gradient based

methods such as NL2SOL or FEASOPT. However, it may be able to solve estimation problems which fail to converge using NL2SOL or FEASOPT.

• Does not use gradient information. Therefore sensitivities of the measured variables with respect to the estimated variables are not computed during the iterations (with the exception of the last one because sensitivities are required to compute covariance and standard error). This can make each steady state or dynamic simulation performed during an estimation or optimization simulation faster.

• Nelder-mead is an unconstrained optimization method but this implementation has a penalty function to ensure that the solution lies within the variable upper and lower bounds. It is best suited for estimation simulations or optimization simulations that do not have additional equality or inequality constraints. It is sometimes suitable for optimization simulations with additional constraints provided an appropriate value penalty parameter is chosen.

• Nelder mead is not guaranteed to always converge to the optimal solution. On some problems it can converge to a sub-optimal solution. To check that a converged solution is not sub-optimal, it is recommended to change the number of restarts and/or initial simplex and perform a second optimization starting from the previously converged point. The second optimization may give a better solution than the first.

Reference

[1] W. H. Press, S. A. Teukolsky, W. T. Vetterling, B. P. Flannery, "Numerical Recipes in FORTRAN. The Art of Scientific Computing", Second edition, Cambridge University Press 1992.

The Nelder Mead solver has the following options:

• Number of restarts

• Initial simplex

• Maximum iterations

• Optimization tolerance

• Penalty parameter


Number of restarts

An integer >=0 with default 1.

This controls the number of times the Nelder Mead solver is automatically restarted from a converged solution. It is advisable to perform at least one restart to ensure the optimum has been found because the algorithm can occasionally terminate at sub-optimal points.

Initial simplex

A double >0.0 with default 0.2.

This controls the initial size of the simplex generated about the initial point. Each vertex of the simplex is generated by a relative peturbation, that is perturbing each estimated variable by the value of perturbation option multiplied by the current absolute value of the initial value. This option can be used to generate a larger initial simplex if smaller a smaller simplex converges to a sub optimal solution. It can also be used to restrict the size of the initial simplex if your flowsheet has robustness problems converging too far away from the initial point. If the current absolute value of the variable is less than 1.e-6, then an absolute perturbation is used rather than relative. Increasing the initial simplex increases the initial search space and can reduce the number of iterations.

Maximum iterations

An integer >0 with default 500

Controls the maximum number of iterations. Typically Nelder-Mead requires a large number of iterations to converge so you may need to increase this value for some problems.

Optimization Tolerance

A double >0 and <=1.

Controls the accuracy to which the Nelder-Mead algorithm computes the optimum. The algorithm terminates when the relative difference between the smallest and largest value of the objective over all vertices of the simplex is less than this tolerance.

Penalty parameter

A double >=1.e-16 <=1.e+30

Controls the amount of penalty applied to the constraint violations when they are infeasible. The default is 1. Nead-Mead is best suited to unconstrained optimization, but can be useful for some constrained problems for which you may need to increase this value so that Nelder Mead obtains that a solution that satisfies your constraints.

SRQP SRQP is a successive reduced quadratic programming method to maximize or minimize the objective function subject to upper and lower bounds on the variables and general equality and inequality constraints. SRQP handles both


the flowsheet equations and additional equality and inequality constraints in the constraints section of your flowsheet section simultaneously. It can only be used for steady state optimization and sometimes can be more robust than the "reduced space" methods such as FEASOPT.

If during the optimization simulation some constraints are found to be incompatible (no feasible region), SRQP attempts to get around the problem by allowing some violation of the constraints. This may result in some variables exceeding their bounds. However, the final solution should lie within the bounds.

The SRQP solver has the following options:

• Feasibility improvement

• Hessian Scaling

• Maximum Iterations

• Optimization Tolerance

• Print Level

• Variable initialization policy

Feasibility improvement

Integer - 0 (default) or 1

Selecting 1 will keep the residuals of the constraints and flowsheet equations small as the optimizer searches for the optimum. In order to stay close to the constraints, extra iterations per optimization step are preformed.

Hessian Scaling

Controls the Hessian scaling policy. 0=no scaling (default), 1=scale. It is recommended that the default is used unless the variables have initial values close to the expected solution and are realistically bounded. Scaling affects the relative weight of the decision variables and their initial values are used to calculate the scaling factors.

Maximum Iterations

Integer >0

Defines the maximum number of iterations allowed during the optimization simulation. The default is 100.

Optimization tolerance

Double >0 and <1

Controls the accuracy of the optimization, that is how accurately the optimum is found and how accurately the solution satisfies the equalities and inequalities in the constraint section and how small the residuals of your flowsheet equations are. Default is 0.001.

Print Level

Controls the amount of diagnostic information from SRQP. 1=no information, 2=medium, 3=high, 4=very high. Default is 1.


Variable initialization policy

Controls the dependent (free) variable initialization policy. 0=no initialization, 1=initialization (default). If set to 1, then a steady state step is performed initially before the optimization begins.

NL2SOL NL2SOL is a least squares nonlinear solver. The algorithm is a variation on Newton's method in which part of the Hessian matrix is computed exactly and part is approximated by a secant (quasi-Newton) updating method. To promote convergence from a poor initial point, a trust-region is used along with a choice of model Hessian.

Open NLP - reduced space This allows you to use your own reduced space optimization solver interfaced using the AspenTech Open Solver (AOS) interfaces.

Open NLP - full space This allows you to use your own full space optimization solver interfaced using the AspenTech Open Solver (AOS) interfaces.

DMO Summary

Solves non-linear optimization problems using an implementation of a variant of the successive quadratic programming (SQP) algorithm. It performs the optimization by solving a sequence of quadratic programming sub-problems. Used extensively for on-line optimization.

Attributes:

Solver type: NLP

DLL Name: aos_dmo.dll

Author: Dimitrios Varvarezos

Dependencies: aos_services.dll (AOS); aos_zedmo.dll, aosutils.dll, blas.dll, rtanalysis.dll, rtharwell.dll (OOMF)

AOS extended interfaces used: AOSNumericLASystemExtended, AOSNumericESOExtension, AOSNumericSolverExtension, AOSNumericESOExtension2

Restrictions: • Code is not thread or instance safe.

• DLL is built and delivered as part of OOMF, which must be installed.

• Solver parameters have very wide bounds in the AOS wrapper and the AOS client must therefore ensure that the values are within the bounds as documented here.


• DMO uses a modified version of MA48 for linear equation solving. It is not possible to switch to a different linear solver.

Use in AspenTech products: ACM; OOMF; Aspen Optimizer.

How to use The DMO solver implements a variant of the successive quadratic programming (SQP) algorithm to solve small or large-scale optimization problems. It performs the optimization by solving a sequence of quadratic programming sub-problems.

DMO offers various options for controlling the line search and trust region methods to improve efficiency and robustness, particularly for large problems. DMO is also useful for solving cases with no degrees of freedom, such as equation-oriented simulation and parameter estimation.

The general optimization problem that DMO solves can be expressed as follows:

• Minimize f(x)

• Subject to c(x) = 0

• xmin ≤ x ≤ xmax

Where: X Vector of unknown variables

F(x) Objective function

C(x) Vector of constraint equations

xmin Vector of lower bounds on x

xmax Vector of upper bounds on x

A simplified description of the DMO algorithm is outlined as follows:

1 Given an initial estimate of the solution vector, x0

2 Set iteration counter, k = 0

3 Evaluate derivative of the objective function, gradient, and the derivative of the constraints, Jacobian.

4 Initialize or update an approximation of the second derivative matrix, or Hessian, of the Lagrange function.

The Lagrange function, f(x) + ∑ λici, accounts for constraints through weighting factors λi , often called Lagrange multipliers or shadow prices.

5 Solve a quadratic programming subproblem to determine a search direction, dk. In the quadratic programming subproblem, the objective function is replaced by a quadratic approximation, constraints are linearized, and bounds are included.

6 Check for convergence or failure. If the optimization convergence criteria are satisfied or if the maximum number of allowed iterations is reached, then end.

Convergence is achieved when:

• Objective function gradient <= objective function convergence tolerance


• Scaled or unscaled constraint residuals <= residual convergence tolerance

7 Perform a one-dimensional search to determine a search step αk so that xk+αkdk is a better approximation of the solution as measured by a line search or merit function. The reduction of merit function requirement is sometimes relaxed to achieve a full correction step.

8 Update iteration counter, k = k + 1, and loop back to step 3.

You can change the following DMO solver parameters referred to in step 6:

• Maximum number of allowed iterations to reach convergence

• Objective and residual convergence tolerance

The DMO solver parameters are grouped into Basic or Advanced type. The table lists all the DMO solver parameters (the prefix of Basic or Adv in the description refers to the type of parameter) with links for detailed help on each parameter. The detailed help is grouped into specific topics relating to the DMO solver.

Note: We recommend that you start your equation-oriented solution with the default parameter settings for the Advanced parameters..

Viewing DMO Solver Report Information DMO outputs information to two report files:

• EO Solver Report File (*.atslv)

• DMO Active Bounds Report (*.atact)

The DMO Active Bounds Report (*.atact) and EO Solver Report (*.atslv) report files are similar. However, the Active Bounds report lists all of the problem variables and independent variables; whereas the Solver Report does not.

The following sections describe contents of the EO Solver report for the DMO solver:

• Problem information

• Basic iteration information

• Largest unscaled residuals

• Constrained variables and shadow price

• General iteration information

• Nonlinearity ratios

Problem Information

The EO Solver report begins with a summary of the problem. This shows the size of the problem and the values of some important parameters. Model or plant name C2S Solution case OPTIMIZE Number of variables 1024 Number of equality constraints 1004 Number of fixed variables 18 Actual degrees of freedom 2


Number of lower bounded variables 1024 Number of upper bounded variables 1024 Total number of constraints 3052 Maximum number of iterations 50 Printing frequency -1 Objective function tolerance 1.0D-06 Residual convergence tolerance 1.0D-06 Derivative perturbation size 1.0D-06 Solution mode NORMAL Maximum number of models 4000 Maximum number of soft bounds 1500 Time of run 15:46:44 Date of run 13-AUG-00

Basic Iteration Information

At each iteration, the following header is printed, showing the iteration number and the value of the objective function: +----------------+ | Iteration 0 | +----------------+ Objective Function => -2.779

Largest Unscaled Residuals

This section of the EO Solver report shows the largest unscaled residuals. A similar section shows the largest scaled residuals. This section is particularly helpful when the solver has trouble closing all the residuals, because it points to the largest residual. Shadow Index Most Violated UNSCALED Residuals Residual Price ====== ======================================= ============ =============

975 MSMT.T2.BLKEQN_OFFSET -5.06330D-03 3.17244D-03 974 MSMT.T1.BLKEQN_OFFSET -8.05215D-04 5.21167D-04 575 C2S.BLKEQN_PHSEQBL_81_C2H4 1.72885D-05 8.55130D-03 568 C2S.BLKEQN_PHSEQBL_80_C2H4 1.72406D-05 7.37848D-03 561 C2S.BLKEQN_PHSEQBL_79_C2H4 1.63227D-05 6.39407D-03 582 C2S.BLKEQN_PHSEQBL_82_C2H4 1.61711D-05 9.91235D-03 554 C2S.BLKEQN_PHSEQBL_78_C2H4 1.49203D-05 5.59494D-03 589 C2S.BLKEQN_PHSEQBL_83_C2H4 1.38826D-05 1.14612D-02 547 C2S.BLKEQN_PHSEQBL_77_C2H4 1.33611D-05 4.97392D-03 540 C2S.BLKEQN_PHSEQBL_76_C2H4 1.18602D-05 4.52121D-03

Constrained Variables and Shadow Price

This section of the EO Solver report shows the variables that lie on their bounds and reports the variable number, which bound is active, the variable name, the current value and the shadow price. The shadow price is also known as the Lagrange multiplier. This is the derivative of the objective function with respect to the value of the constraint and represents the cost for the constraint. Projected Active Constraints Shadow Index for the Next Iteration Bound Price ====== ======================================= ============ =============

949 Upper Bnd C2SDDEF.SPC.MOLEFR.C2H6 2.00000D-04 -4.32924D+02

The shadow price is based on the value of the objective function that is seen by DMO. That means the shadow price is in SI units, such as $/sec, and is affected by any scaling. This is true even if you declare the units to be something other than SI (such as $/HR).


Consider this example. We have a tower with a composition constraint, expressed as a mole fraction of a component. The following table shows the results of two optimization runs at two different values of the composition constraint: Value Objective Shadow Price

0.0002 2.853 432.924

0.0003 2.893 258.664

The large change in the shadow price indicates that the effect of the composition on the objective function is very nonlinear. We can manually estimate the average shadow price in this region by a finite difference method:

Price = ∆Obj/∆x = ( 2.893-2.853 ) / ( 0.0003 - 0.0002 ) = 400.00 $/sec/mole fraction

This value lies between the two prices.

If the objective function had a scale factor of 100., we would get the following: Value Objective Shadow Price

0.0002 285.4 43290.7

0.0003 289.3 25860.2

We would have to remember to unscale the shadow price by dividing by 100.

General Iteration Information

This section of the EO Solver report appears after the residual output:

Iteration status => Normal Degrees of freedom => 2 Constrained variables => 0 Current degrees of freedom => 2 Number of function evaluations => 0 Number of Jacobian evaluations => 1 Objective function convergence function => 4.78209D-03 Residual function convergence function => 5.78057D-06 LU decomposition time (seconds) => 2.77D-01 Search direction time (seconds) => 3.91D-01

Reported Item Description

Iteration status The exit condition of that iteration, where:

Normal indicates a normal successful iteration.

Warning indicates a successful iteration despite some solver difficulties.

Error indicates a failure.

Solved indicates the final iteration of a successfully solved problem.

Degrees of freedom The number of declared independent variables in the problem

Constrained variables Those variables at bounds in the QP subproblem

Current degrees of freedom

The degrees of freedom less the constrained variables. This is the true degrees of freedom for the problem. A highly constrained solution is one that has very few current degrees of freedom.

Number of function evaluations

An accumulative count of function evaluations, which generally matches the number of iterations

Number of Jacobian evaluations

An accumulative count of Jacobian evaluations, which generally matches the number of iterations

Objective function The norm of the Jacobian for the objective function. At the solution,


convergence function this value should be near zero.

Residual function convergence function

The sum of the scaled residuals. At the solution, this value should be near zero.

Nonlinearity Ratios

This section of the EO Solver report shows the nonlinearity ratio of the worst block, the objective function, and the worst equations. The criterion is the accuracy of the predicted change in the equation. If the function is linear, then the new value would match the predicted value and the nonlinearity ratio would be one. A value of the ratio other than one indicates some degree of nonlinearity. A negative value indicates that the function value moved in the opposite of the expected direction. Large negative values could indicate a discontinuity or bad derivative.

This section also shows the step size for the iteration. Model nonlinearity ratios => ---------------------------- C2S = 0.69071 Model nonlinearity ratios of 6 model(s) between 0.99 and 1.01 Objective function nonlinearity ratio => 1.0000 Non-Linearity Report for Iteration 11 : Step Fraction = 1.00000D+00 Index Worst Equation Non-Linearity Ratios Ratio Deviation ===== ======================================== ============ ============ 484 C2S.BLKEQN_PHSEQBL_68_C2H4 1.53058D+00 5.30578D-01 491 C2S.BLKEQN_PHSEQBL_69_C2H4 1.48206D+00 4.82055D-01 498 C2S.BLKEQN_PHSEQBL_70_C2H4 1.43615D+00 4.36148D-01 499 C2S.BLKEQN_PHSEQBL_70_C2H6 1.43222D+00 4.32219D-01 505 C2S.BLKEQN_PHSEQBL_71_C2H4 1.39245D+00 3.92447D-01

Guidelines for Using the DMO Solver In this section, we describe some ideas to improve the performance of the DMO solver and to help diagnose common problems, including:

• Scaling

• Handling infeasible solutions

• Handling singularities

• Variable bounding

• Run-time intervention

Scaling

Generally, it is not necessary to scale your equations or variables beyond what is done by default in the models. However, it may be more efficient to scale your objective function.

The scaling of the objective function plays an important role, since it affects the overall convergence behavior. This is particularly important in cases where there is a large change between the original value of the objective and the expected optimum.

A good rule of thumb is to scale the objective function so that its value is on the order of 10 to 1000.


Handling Infeasible Solutions

Infeasible solutions often occur during optimization cases where it is not possible to simultaneously solve all the equations while respecting all the variable bounds. This does not happen in simulation cases, because DMO ignores bounds in simulation cases.

If you solve a simulation case that violates a bound, then the optimization case will start at an infeasible point. In this case, the following is reported in the EO Solver report: Information => QP step for variable 1157: C2SDDEF.SPC.MOLEFR.C2H6 was adjusted to satisfy its UPPER bound = 2.0000000E-04 The size of QP step violation was = 2.5673465E-04

Here, the value of the variable had to be adjusted to respect the bound. When the optimization proceeds and there is no feasible solution for the equality constraints, the screen output might look like this: Residual Objective Objective Overall Model Convergence Convergence Function Nonlinearity Nonlinearity Worst Iteration Function Function Value Ratio Ratio Model --------- ----------- ----------- ----------- ------------- ------------- ------

Warning ... QP slack variable = 2.29070D-01 0 9.312D-04 4.809D-03 -2.779D+00 9.968D-01 -2.834D-01 C2S Warning ... QP slack variable = 1.80624D-01

1 5.244D-04 4.667D-02 -2.792D+00 2.900D-01 -1.846D+02 C2S Warning ... QP slack variable = 1.44771D-01

2 1.552D-02 5.479D-02 -2.922D+00 -7.475D-01 -1.540D+01 C2S Warning ... QP slack variable = 6.09502D-01

3 3.853D-02 2.379D-03 -3.083D+00 9.908D-01 9.914D-01 C2S Warning ... QP slack variable = 1.87163D-01

4 1.496D-02 1.040D-02 -3.075D+00 8.346D-01 6.012D-01 C2S

Warning ... QP slack variable = 3.18508D-01

+---------------------- ERROR ----------------------+

Error return from [DMO] system subroutine DMOQPS because the problem has NO FEASIBLE SOLUTION.

Action : Check the bounds that are set on variables to insure consistency. Check the .atact file for information on initial infeasibilities.

+---------------------------------------------------+

Error return, [DMO] System Status Information = 5

Optimization Timing Statistics Time Percent ================================ ======== =======

MODEL computations 1.32 secs 31.10 % DMO computations 0.91 secs 21.28 % Miscellaneous 2.03 secs 47.61 % -------------------------------- --------- ------- Total Optimization Time 4.26 secs 100.00 %

Updating Plex

Problem failed to converge

Note the messages from the QP indicating an invalid value for a slack variable.

To solve this problem, you need to be aware of the initial message, indicating that the initial value of a variable violated its bound. In this case,


C2S.SPC.REFL_RATIO_MASS is causing the problems. Unfortunately, the EO Solver report does not list this variable as constrained, since it could never solve the QP successfully.

Handling Singularities

Singularities often occur when a library model is moved into a region where the equations are not well defined. The most common example of this is when a stream flow becomes too small. If singularities exist, they are usually detected at the start of the problem. In this case, some information is written to the EO Solver report file (*.atslv), which can help locate the cause of the problem. In general, you should prevent stream flows from going near zero by placing nonzero lower bounds on the flow (e.g., 10 kg/hr). This is especially important on streams from flow splitters or feed streams whose total flow is being manipulated. In the case of a singularity the following message is displayed: +-------------------- WARNING ----------------------+ A NUMERICALLY SINGULAR matrix is detected during the ANALYSIS phase of LU decomposition. The number of dependent equation set(s) detected = 1 Check the output file for more information. +---------------------------------------------------+

The EO Solver report includes information on the possible cause of the singularity similar to the following: +-------------------- WARNING ----------------------+

A NUMERICALLY SINGULAR matrix is detected during ANALYZE phase of LU decomposition.

WARNING: The dependent equation set is NOT unique. It depends on the options for performing LU decomposition.

==> Dependent equation set: 1

The partial derivatives of the following equations with respect to variable 1: Strm 1 moles lbmol/h in the reduced matrix are zero.

Equation -> 10: Enthalpy balance M Btu/lbmol is a function of the following variables: 1: Strm 1 moles lbmol/h = 0.00000D+00 -> Calc 4: Strm 1 enth M Btu/lbmol = -7.45977D+01 -> Const 12: Strm 2 moles lbmol/h = 0.00000D+00 -> Const 15: Strm 2 enth M Btu/lbmol = -7.45977D+01 -> Const 23: Heat loss MM Btu/h = 0.00000D+00 -> Const 25: Prod moles lbmol/h = 8.93760D-07 -> Calc 28: Prod enth M Btu/lbmol = -7.45977D+01 -> Calc

Equation -> 9: Prod C9H20_1 mf is a function of the following variables: 1: Strm 1 moles lbmol/h = 0.00000D+00 -> Calc 10: Strm 1 C9H20_1 mf = 4.52017D-01 -> Const 12: Strm 2 moles lbmol/h = 0.00000D+00 -> Const 21: Strm 2 C9H20_1 mf = 4.52017D-01 -> Const 25: Prod moles lbmol/h = 8.93760D-07 -> Calc 34: Prod C9H20_1 mf = 4.52017D-01 -> Calc

Sometimes, singularities are simply caused by the optimization being too aggressive. This moves the models into a region where the equations are not well defined. To make the optimization more robust, DMO has a creep mode. This mode simply causes smaller steps to be taken for a specified number of iterations.


When the creep mode is enabled, the following message is displayed at each iteration: <Line Search Creep Mode ACTIVE> ==> Step taken 1.00D-01

By default, this will operate for 10 iterations with a step size of 0.1. You can use the creep mode Iterations and Step size parameters to change these values.

Variable Bounding

By default DMO does not respect bounds during the solution of an EO Simulation or Parameter-Estimation case. However, you can impose bounds in a square case by using a different line search parameter. This is recommended only in cases where there are truly multiple solutions to a model (e.g. the cubic equation) and you want to use a bound to eliminate an unwanted solution.

To use this mode, change the LINESEARCH parameter to square.

In general, it is not recommended to heavily bound an optimization problem for reasons that are both practical and algorithmic. Bounds on independent variables are recommended in order to avoid unbounded problems. All other bounds should be used only if they are absolutely necessary. Finally, redundant bounds should be avoided.

References None.

Solver parameters The solver parameters are grouped in different types: Basic and Advanced. Within Basic, there are two sub-groups � Search and Report. Within Advanced, there are six sub-groups � Search, QP1, QP2, Linear algebra 1, Linear Algebra 2 and Workspace. These grouping are useful for guiding the user to the scope, effect and complexity of each group of parameters.

Name Description

ACTIVEINIT Adv.QP2: Restore active set? (0=no;1=yes)

ACTIVERPT Adv.QP1: Print initial active set? (0=no;1=yes)

ACTIVESAVE Adv.QP2: Save active set? (0=no;1=yes)

ACTIVESPACE Adv.Workspace: Active set workspace factor

ADCVITER Adv.Search: Iterations start

ADCVMETH Adv.Search: Trust region flag (0=off;1=on)

ADCVOBJCVG Adv.Search: Starting objective convergence tolerance

ADCVRESCVG Adv.Search: Starting residual convergence tolerance

ANALYSISTHRES Adv.LinAlg1: Fill-in monitoring factor

BOUNDRPT Adv.QP1: QP report bounds (0=off;1=on)

BTF Adv.LinAlg2: Block lower triangularization? (0=no;1=yes)

CREEPFLAG Basic: Enable(1)/disable(0) creep mode

CREEPITER Basic: Number of creep steps

CREEPSIZE Basic: Creep step size fraction

CWORKF Adv.LinAlg2: Density ratio


DENSITYRATIO Adv.LinAlg2: Density ratio

DROPTOL Adv.LinAlg1: Drop tolerance

FACTORSPACE Adv.Workspace: Linear algebra factorisation workspace factor

FACTORSPEED Adv.LinAlg2: Factorisation speed (1=normal;2=fast)

FREEONLY Adv.LinAlg2: Free variables only? (0=no;1=yes)

HESSIANSCL Basic.Search: Hessian scale

HESSIANUPDATES Basic.Search: Hessian updates stored

IPSIRPT Adv.QP1: Infeasibility report level (0=off;1=brief;2=full)

IWORKF Adv.Workspace: Integer workspace factor

LINESEARCH Basic.Search: Line search algorithm (0=Exact,1=Square,2=Residual,3=Normal

LINESRCMODE Basic.Search: Line search control (0=Normal,1=Aggressive,2=Conservative)

LSMODEITER Basic.Search: Line search iterations

LUSTATS Adv.LinAlg2: Report statistics (0=no;1=yes)

MAXITER Basic: Maximum number of iterations

MINBTFSIZE Adv.LinAlg2: Minimum block size

MINITER Basic: Minimum number of iterations

OBJCVG Basic: Objective convergence tolerance

PIVOTANAL Adv.LinAlg1: Pivot Analysis frequency (0=Medium;1=;2=

PIVOTSEARCH Adv.LinAlg1: Number of columns to search for pivots

PIVOTTHRESH Adv.LinAlg1: Stability threshold

PIVOTZERO Adv.LinAlg1: Zero pivot threshold

PRINTFREQ Basic.Report: Iteration print frequency (-ve sign:normal;+ve sign:full)

QPCONVTOL Adv.QP2: QP convergence tolerance

QPDEPDIAG Adv.QP1: QP dependencies output target(0=Neither;1=File;2=FileandScreen

QPHESSIANUPD Adv.QP2: Hessian updates stored

QPITER Adv.QP2: Incomplete QP parameter

QPMICROINF Adv.QP1: QP micro infeasibility handling switch (0=off;1=on

QPMICROMAX Adv.QP1: QP micro infeasibility maximum corrections

QPMICROTOL Adv.QP1: Micro infeasibility bound relaxation tolerance

QPSTATS Adv.QP1: QP statistic reporting (0=off;1=on)

RESCVG Basic: Residual convergence tolerance

RIGORUPDATES Adv.QP2: QP rigorous constraint updates

RWORKF Adv.Workspace: Real workspace factor

SAVEJDFFILE Expert: 1=Creates a total derivative of Jacobian

SCREENFORM Basic.Report: Target for solver output (0=File;1=MessagesHandler)

SEARCHMODE Basic.Search: Hessian initialisation (0=aggressive;1=normal;2=advanced;3=scaled)

SINGULARHAND Adv.LinAlg2: Singularity handling(0=normal;1=active;2=structual;3=none)

TRUSTITER Adv.Search: Trust region fixed iterations

TRUSTMODE Adv.Search: Trust region method (0=Normal;1=Any;2=Iterations;3=Objective;4=Resid;5=All

TRUSTRAMPIT Adv.Search: Trust region ramp iterations

TRUSTSIZE Adv.Search: Trust region initial size

USEDROPTOL Adv.LinAlg1: Drop small Jacobian entries? (0=no;1=yes)

VARSCALE Basic.Search: Variable scaling factor (0=off;1=on)


VMS_P1 Expert: VMS workspace offset (do not use)

DMO Basic Solver Parameters Use these parameters to specify the commonly used parameters that control:

• The accuracy, performance, and robustness of the DMO solver

• Diagnostic reporting for variables and residuals

There are the most commonly used parameters for controlling the accuracy, performance, and robustness of the DMO solver.

Convergence is achieved if the residual and objective function tolerances are satisfied, or if the maximum number of allowed iterations is reached. Tighter convergence tolerances usually increase the accuracy of the solution at the expense of additional running time.

MAXITER: Basic: Maximum number of iterations

Type: integer; Default 50; Range [0,2147483647]

Lets you specify the maximum number of SQP iterations allowed.

MINITER: Basic: Basic: Minimum number of iterations

Type: integer; Default 0; Range [0, 2147483647]

Lets you specify the minimum number of SQP iterations allowed.

OBJCVG: Basic: Objective convergence tolerance

Type: real; Default 1.e-6; Range [0,1e+35]

Lets you specify the residual convergence tolerance.

RESCVG: Basic: Residual convergence tolerance

Type: real; Default 1.e-6; Range [0,1e+35]

Lets you specify the residual convergence tolerance.

Viewing Iteration Summary Information By default DMO displays iteration summary information via AOSMessagesHandler and to the DMO .atact and .atslv files. Use the following options to determine the amount of information displayed.

PRINTFREQ: Basic.Report: Iteration print frequency (-ve sign:normal;+ve sign:full)

Type: integer; Range: n<0 print normal/brief information every nth

iteration

0 no information is printed

n>0 print full information every nth iteration

The diagnostic printing frequency for variables and residuals, where variables are residuals are printed at every nth iteration. The default is -1.


Brief prints the ten worst residuals (default); Full prints all variables and residuals

Note: Full print can result in a very large amount of output..

This is a sample of the Control Panel output: Residual Objective Objective Overall Model Convergence Convergence Function Nonlinearity Nonlinearity Worst Iteration Function Function Value Ratio Ratio Model

--------- ----------- ----------- ---------- ------------ ------------ -------

0 5.781D-06 4.782D-03 -2.779D+00 9.950D-01 -4.485D+00 C2S

1 1.640D-04 2.774D-02 -2.792D+00 5.528D-01 -2.011D+01 C2S

2 5.560D-03 4.533D-03 -2.870D+00 9.020D-01 9.269D-01 C2S

3 1.247D-04 1.109D-03 -2.857D+00 7.547D-01 9.498D-01 C2S

4 9.993D-06 2.506D-05 -2.853D+00 9.233D-01 9.510D-01 C2S

5 2.751D-07 7.327D-06 -2.853D+00 9.504D-01 8.874D-01 C2S

6 4.162D-08 1.637D-05 -2.853D+00 5.642D-01 -3.939D+00 C2S

7 6.724D-07 7.624D-05 -2.853D+00 5.956D-01 -1.281D+00 C2S

8 9.962D-07 4.329D-05 -2.854D+00 9.176D-01 8.254D-01 C2S

9 2.691D-07 3.344D-06 -2.854D+00 7.505D-01 6.581D-01 C2S

10 1.324D-07 4.748D-06 -2.854D+00 8.463D-01 6.907D-01 C2S

11 4.804D-08 1.700D-06 -2.854D+00 9.487D-01 8.925D-01 C2S

12 1.395D-08 4.722D-07 -2.854D+00

*******************************************************************************

Successful solution.

Optimization Timing Statistics Time Percent ================================ ======== =======

MODEL computations 2.38 secs 40.88 % DMO computations 0.72 secs 12.40 % Miscellaneous 2.72 secs 46.72 % -------------------------------- --------- ------- Total Optimization Time 5.83 secs 100.00 %

Here, the Objective Convergence Function refers to the Jacobian of the objective function. The Nonlinear Ratio is a measure of the nonlinearity of the problem. The closer the value is to one, the more linear the problem. A negative value indicates that the problem behaved in the opposite of what was expected. Near the solution, as the step sizes become small, this value becomes close to one.

The last section of the output shows the execution times for the various parts of the problem.

In this example, we can see that convergence was achieved when the residual and objective convergence functions were less than their respective tolerances at iteration 12.

From this output, we also see that there have been no line searches. Thus the step size for each iteration is one. When a line search is performed for an iteration, a message similar to this appears: <Line Search ACTIVE> ==> Step taken 3.26D-01


SCREENFORM: Basic.Report: Target for solver output (0=File;1=MessagesHandler)

Type: integer; Range: 0 iteration information sent to file and

AOSMessagesHandler

1 iteration information sent to AOSMessagesHandler only

Note: file (.atslv) output shows more significant figures.

Basic Search options The parameters line search options, including parameters for initializing or updating the second derivative matrix, or Hessian. You can use these parameters to set the convergence behavior of the DMO solver between conservative and aggressive.

SEARCHMODE: Basic.Search: Hessian initialisation (0=aggressive;1=normal;2=advanced;3=scaled)

Type: integer; Range: 0 Aggressive

1 Normal (default)

2 Advanced

3 Scaled

Lets you select the Hessian initialization mode:

Aggressive - Uses small values. This mode moves the problem to its bounds faster than the normal mode and is the preferred mode for highly constrained optimization problems with few degrees of freedom at the solution.

Normal � Uses identity matrix.

Advanced � Uses second order information. This mode is recommended for problems with many degrees of freedom at the solution. It is ideal for reconciliation problems.

Scaled � Combines small values (aggressive) and second order information (advanced). This mode is recommended for highly constrained optimization problems with few degrees of freedom at the solution and a nonlinear objective function.

VARSCALE: Basic.Search: Variable scaling factor (0=off;1=on)

Type: integer Range: 0 off

1 on (default)

Lets you specify whether to enable variable scaling.

HESSIANSCL: Basic.Search: Hessian scale

Type real; Default 1.0; Range [1.e-9,2]


Lets you specify the scaling factor for scaling the identity matrix when using the scaled Hessian initialization mode.

HESSIANUPDATES: Basic.Search: Hessian updates stored

Type integer; Default 0; Range [0, 2147483647]

Lets you specify the number of Hessian updates kept before reinitializing.

LINESEARCH: Basic.Search: Line search algorithm (0=Exact,1=Square,2=Residual,3=Normal

Type integer; Range: 0 Exact

1 Square

2 Residual

3 Normal (default)

Lets you select the line search algorithm:

Exact: Exact penalty. This is too conservative for most practical problems.

Residual: A proprietary line search designed to initially favor convergence of residuals over the objective function improvement.

Normal: A proprietary line search designed to balance robustness with efficiency.

Square: A line search designed to attempt enforcing bounds on cases with no degrees of freedom. It should be used only in cases where there are multiple solutions to a problem and the desired one lies within the bounds.

LINESRCMODE: Basic.Search: Line search control (0=Normal,1=Aggressive,2=Conservative)

Type: integer; Range: 0 Normal (default)

1 Aggressive

2 Conservative

Lets you select the line search step control.

LSMODEITER: Basic.Search: Line search iterations

Type: integer; Default 0 or 5; Range [0,2147483647]

Lets you specify the number of step control iterations. If the step control (LINESRCMODE) is Normal, the default is 0; otherwise the default is 5.

Using the Creep Mode DMO has a creep mode to make the optimization more conservative and robust. This mode simply makes the optimizer take smaller steps for a specified number of iterations.

Creep mode is very helpful when the problem diverges. It can also prevent the DMO optimizer from making aggressive moves that cause singularities when models are taken into regions where the equations are not well defined.

• The following options control the use of the Creep mode:


CREEPFLAG: Basic: Enable(1)/disable creep mode

Type: integer; Range: 0 off (default): disables creep mode

1 on: enables creep mode

CREEPITER: Basic: Number of creep iterations

Type: integer; default 10; range [0,2147483647]

The number of iterations to perform creep steps.

CREEPSIZE: Basic: Creep step size fraction

Type: real; default 0.1; range [1.e-10, 1]

The step size, as a fraction of the full step size when in creep mode.

Advanced Solver Parameters Use these parameters to specify:

• Advanced search and convergence parameters for the DMO solver

• DMO solver parameters related to the quadratic programming (QP) subproblem

• Parameters for controlling the solution of the sparse linear equation systems that arise during the DMO solution process

• More memory workspace

In most cases, the recommended default values are sufficient.

Use the trust region parameters to enable and control a trust region for the optimization variables. Use the advanced convergence parameters to control the method for terminating optimization moves while closing any remaining open residuals.

Advanced Search options These include parameters for optimization variables and advanced convergence parameters to control the method for terminating optimization moves while closing any remaining open residuals.

TRUSTMODE: Adv.Search: Trust region method (0=Normal;1=Any;2=Iterations;3=Objective;4=Resid;5=All

Type: integer Range: 0 None (default)

1 Any

2 Iterations

3 Objective

4 Residual

5 All

Lets you select the method for terminating the optimization moves while closing any remaining residuals.


ADCVITER: Adv.Search: Iterations start

Type integer; Default 100; Range [0,2147483647];

Lets you specify the number of iterations before activating the advanced convergence method.

ADCVOBJCVG: Adv.Search: Starting objective convergence tolerance

Type real; Default 1,e-6; Range [0,1+e35];

Lets you specify the convergence tolerance threshold for the objective function, before activating the advanced convergence method.

ADCVRESCVG: Adv.Search: Starting residual convergence tolerance

Type real; Default 1,e-6; Range [0,1+e35];

Lets you specify the residual convergence tolerance threshold before activating the advanced convergence method.

Applying a Trust Region The application of a trust region limits the optimization moves for the optimized variables only. The optimized variables are allowed to move within an initial range for a fixed number of iterations. The size of the trust region is specified as a fraction of the original variable bound range. Following the fixed iterations, the size of the trust region is gradually increased until it reaches the original variable bound range.

These options provide better reliability and execution efficiency to a number of problem classes such as parameter reconciliation (typically found in refinery optimization) and design optimization. In some cases, up to 80% improvement of execution time has been reported.

TRUSTSIZE: Adv.Search: Trust region initial size

Type real; Default 0.1; Range [1e-6,1]

The range that the optimized variables are initially allowed to move for all of the fixed iterations, expressed as a fraction of the original variable bound range. The default is 0.1.

ADCVMETH: Adv.Search: Trust region flag (0=off; 1=on)

Type integer; Range: 0 Disables the application of a trust region

(default)

1 the application of a trust region that limits the optimization

TRUSTITER: Adv.Search: Trust region fixed iterations


The number of iterations that the trust region will be applied with a fixed size.


TRUSRAMPIT: Adv.Search: Trust region ramp iterations


The number of iterations, following the fixed iterations, over which the size of the trust region is gradually increased until it reaches the original variable bound range.

QP options 1 These advanced DMO solver parameters are related to the quadratic programming (QP) subproblem. Usually, the default values should be used with these advanced parameters.

You can use the micro infeasibility handling option when a problem may be incorrectly declared as infeasible due to round-off error.

You can also enable diagnostic reporting of the QP subproblem.

Use the micro infeasibility handling option when a problem may be incorrectly declared as infeasible due to roundoff error and turn on diagnostic reporting for the QP subproblem.

IPSIRPT: Adv.QP1: Infeasibility report level (0=off;1=brief;2=full)

Type integer; Range: 0 Off - suppresses all infeasibility information,

except slack value (default)

1 Brief - reports only the top three contributors of each category.

2 Full - reports all the relevant information on the likely causes (equations, fixed variables, bounds) of the infeasibility

Flag controlling the amount of information printed in the OUT file as a result of an infeasible QP problem.

BOUNDRPT: Adv.QP1: QP report bounds (0=off;1=on)

Type integer; Range: 0 Do not report bounds

1 Report bounds (default)

Lets you specify whether to report all bounds in the active file.

QPDEPDIAG: Adv.QP1: QP dependencies output target(0=Neither;1=File;2=FileandScreen

Type: integer; Range: 0 Neither

1 File

2 FileandScreen�(default)

Lets you select the output device for reporting warning messages on linear dependencies when an active set change causes a singularity:

FileandScreen � messages are written to the output report file and displayed on the �terminal� or �window� on the GUI (via the AOSMessagesHandler);


File � messages are written to the output report file only.

Neither � messages are not reported.

QPSTATS: Adv.QP1: QP statistic reporting (0=off;1=on)

Type: integer Range: 0 off (default)

1 on

Lets you specify whether to enable diagnostic reporting for the QP subproblem. If the report print option is Full, the report can be very large, including the Jacobian.

Using Micro-Infeasibility Handling This option pertains to the situation where a problem may become infeasible due to very small errors in one or more constraints. This often happens in optimization cases as a result of round-off or machine precision errors, or loose convergence tolerance.

Employing this option leads to far fewer cases of solver failure due to infeasible problems, thus improving robustness and enhancing usability.

Use the micro infeasibility handling option when a problem may be incorrectly declared as infeasible due to roundoff error and turn on diagnostic reporting for the QP subproblem.

QPMICROINF: Adv.QP1: QP micro infeasibility handling switch (0=off;1=on)

Type integer; Range: 0 Disable (default)

1 Enables the Micro Infeasibility handling in the QP

QPMICROTOL: Adv.QP1: Micro infeasibility bound relaxation tolerance

Type real; Default 1.e-12 ; Range [0,1e+35]

The absolute relaxation of an infeasible bound in the QP while micro-infeasibility handling is enabled.

QPMICROMAX: Adv.QP1: QP micro infeasibility maximum corrections


Lets you specify the maximum number of micro-infeasibility handling attempts that can be handled in one DMO iteration.

QP options 2 These advanced DMO solver parameters are related to the quadratic programming (QP) subproblem. Usually, the default values should be used with these advanced parameters.


You can use active set initialization to improve convergence of planning problems that have a large number of degrees of freedom and often involve the solution of a solved problem that has been slightly modified. The reuse of active set information from previous solutions is expected to decrease solution times and potentially increase success rates.

Specify active set initialization parameters for improving convergence of planning problems that have a large number of degrees of freedom and often involve the solution of a solved problem that has been slightly modified.

QPCONVTOL: Adv.QP2: QP convergence tolerance

Type: real; Default 1e-10; Range [0,1e+35]

Lets you specify an internal QP convergence tolerance.

Warning: Changing the default value may degrade solution performance and robustness.

QPHESSIANUPD: Adv.QP2: Hessian updates stored


Lets you specify the number of QP Hessian updates stored.

QPITER: Adv.QP2: Incomplete QP parameter


Lets you specify the degree of completeness in finding the optimal active set at each QP iteration, for the first 10 iterations. The values are between 1 and 10, where 1 is the most incomplete and 10 is the most complete.

RIGORUPDATES: Adv.QP2: QP rigorous constraint updates


Lets you specify the number of constraint updates before a rigorous analysis phase.

Specifying Active Set Initialization Parameters The active set is the set of variable bounds that hold with equality at any feasible point. The active set initialization procedure in DMO provides both efficiency and robustness. It produces a "warm" start, based on the existing information of a successful execution. This is very important for applications with a large number of degrees of freedom (above 100). For such applications, up to 50% improvement in execution speed has been reported in addition to improved robustness.

ACTIVESAVE: Adv.QP2: Save active set? (0=no;1=yes)

Type: integer; Range: 0 No � do not save active set (default)

1 Yes - writes to the .set file every time a QP subproblem successfully converges in Optimization and Reconciliation run modes.


The file contains information on which variables were active at bounds. When the "restore active set" parameter is set to Yes, the information in the file can be used to initialize the active set of another run.

ACTIVEINIT: Adv.QP2: Restore active set? (0=no;1=yes)

Type integer; Range: 0 Do not restore the active set (default)

1 The information in the .set file is used to initialize the active set as an initial guess of the active set.

ACTIVERPT: Adv.QP1: Print initial active set? (0=no;1=yes)

Type integer; Range: 0 Do not print the initial active set (default)

1 Print the initial active set

Flag that controls the reporting of the active set at the end of iteration zero. It is written to the <prob>.out file.

Linear Algebra options 1 Use these parameters for controlling the solution of the sparse linear equation systems that arise during the DMO solution process. Usually, the default values should be used with these advanced parameters.

You can use the parameters to drop small non-zeros from the matrix of first derivatives (Jacobian). The linear solution will then require less storage but will be inaccurate.

You can also control the pivoting strategy to compromise between maintaining sparsity and controlling loss of accuracy through roundoff.

ANALYSISTHRES: Adv.LinAlg1: Fill-in monitoring factor

Type integer; Default 2; Range [1.00001,10]

Lets you specify a fill-in monitoring factor (default=2) to control the automatic reanalysis of the Jacobian by monitoring fill-in. The automatic reanalysis is invoked once the number of non-zeros has grown by a factor equal to this parameter.

DROPTOL: Adv.LinAlg1: Drop tolerance

Type real; default 1.e-20; range [0,1e+35]

Lets you specify the non-zero drop tolerance used to remove small Jacobian values (default=1.e-20). A larger tolerances reduces the number of non-zeros and decreases factorization time. Too large a value reduces the accuracy of the Jacobian.

PIVOTANAL: Adv.LinAlg1: Pivot Analysis frequency

Type: integer; Range: 0 Medium

1 Low (default)


2 High

Lets you select a re-analysis frequency, which determines the Jacobian pivot reanalysis strategy.

PIVOTSEARCH: Adv.LinAlg1: Number of columns to search for pivots

Type: integer; Default 10; range [1,2147483647]

Lets you specify the maximum number of columns used in a pivot search.

PIVOTTHRESH: Adv.LinAlg1: Stability threshold

Type: real; Default 0.1; range [0,1]

Lets you specify a pivot strategy threshold. Values near zero emphasize sparsity and values near one emphasize stability.

PIVOTZERO: Adv.LinAlg1: Zero pivot threshold

Type: real; Default 0; range [0,1]

Lets you specify a pivot strategy zero threshold. This is the minimum pivot element for near singular problems. If this parameter is set to a positive value, any pivot whose modulus is less than this value is treated as zero.

USEDROPTOL: Adv.LinAlg1: Drop small Jacobian entries? (0=no;1=yes)

Type: integer Range: 0 no (default)

1 yes

Lets you specify whether to enable the dropping of small Jacobian non-zeros.

Linear Algebra options 2 Use these parameters for controlling the solution of the sparse linear algebra equation systems that arise during the DMO solution process. Usually, the default values should be used with these advanced parameters.

You can use these advanced parameters to try to improve the performance and robustness of the numerical factorization phase of the linear solver used in DMO.

You can enable and disable several reporting options related to linear algebra.

BTF: Adv.LinAlg2: Block lower triangularization? (0=no;1=yes)

Type integer; Range: 0 Do not use block triangularisation

1 Use block triangularisation (default)

DENSITYRATIO: Adv.LinAlg2: Density ratio

Type real; default 0.7; range [0,1]

Lets you specify a density ratio. When the ratio of the number of non-zeros in the reduced matrix to the number that it would have as a full matrix is


greater than the specified density ratio, the solver switches from sparse to full matrix processing.

FACTORSPEED: Adv.LinAlg2: Factorisation speed (1=normal;2=fast)

Type integer Range: 1 normal (default)

2 fast

Lets you select the linear matrix factorization method:

Normal � optimizes pivot at every iteration

FREEONLY: Adv.LinAlg2: Free variables only? (0=no;1=yes)

Type integer Range: 0 no (default)

1 yes

Lets you specify whether to include free variables (i.e. those not fixed or a constant) when solving the problem.

LUSTATS: Adv.LinAlg2: Report statistics (0=no;1=yes)

Type: integer Range: 0 Off (default)

1 On

Lets you specify whether to enable diagnostic printing for linear algebra.

MINBTFSIZE: Adv.LinAlg2: Minimum block size


Lets you specify the minimum size of a block creating during block triangularisation.

SINGULARHAND: Adv.LinAlg2: Singularity handling(0=normal;1=active;2=structual;3=none)

Type: integer Range: 0 normal (default)

1 active

2 structural

3 none

Lets you specify a strategy handling singular problems.

Workspace options Use this sheet to increase the amount of memory workspace used by the DMO solver. Usually, the default values should be used with these parameters.

ACTIVESPACE: Adv.Workspace: Active set workspace factor



Lets you specify the workspace allocated for part of the active set strategy. The default should suffice for most cases.

CWORKF: Adv.Workspace: Character workspace factor

Type integer; Default 1; Range [1,10]

Lets you specify a character workspace size multiplier.

FACTORSPACE: Adv.Workspace: Linear algebra factorisation workspace factor


Lets you specify the workspace allocated for the solution of the linear system of equations. Problems with excessive fill-in may require a higher number.

IWORKF: Adv.Workspace: Integer workspace factor


Lets you specify a integer workspace size multiplier.

RWORKF: Adv.Workspace: Real workspace factor


Lets you specify a real workspace size multiplier

Expert Solver Parameters These options should not be changed. They are documented for completeness only.

SAVEJDFFILE: Expert: 1=Creates a total derivative of Jacobian

Type: integer; Range: 0 Do not create a total derivative

1 Create a total derivative

For internal debugging purposes only.

VMS_P1: Expert: VMS workspace offset (do not use)

Type: integer; Range [?];

Do not use this option.

8 Using Calculation Options for Properties Plus 253

8 Using Calculation Options for Properties Plus

To use Properties Plus you need to:

1 Use Aspen Plus® to specify the components, property methods, and any additional information needed, for example your own physical properties information and calculation options.

2 Decide whether to specify values for various calculation options. If you do not specify values for the calculation options, default values are used. You should make sure that the default settings are appropriate.

3 Generate a file, runid.appdf which will be used in the simulator environment.

The calculation options can be used in the component list you create. The calculation options that you can change within a component list are:

• OPSET

• FREE-WATER

• CHEMISTRY

• TRUE-COMP

• HENRY-COMPS

• SOLU-WATER

• KBASE

• MAXIT

• TOLERANCE

• RETENTION

For more detailed information on the possible values for each of these options, see the Aspen Plus User Guide, Volume 1, Chapter 8.

About Properties Plus

Properties Plus® enables you to use the features of the Aspen Plus® 10 physical properties system. For more information on physical properties methods, see the Aspen Plus User Guide, Volume 1, chapters 7 and 8; and the Aspen Plus® reference volumes, Physical Property Methods and Models, and Physical Property Data.

Properties Plus also provides all of the physical properties calculations supported by the Aspen Custom Modeler® library. Other products have libraries which reference modeler.acml to access Properties Plus where they


use the same core Aspen Custom Modeler simulation environment. Aspen Dynamics� is one of these products. For further information on the library property procedures, see the Aspen Custom Modeler Library Reference.

OPSET Option Use OPSET to specify the primary property method for calculating all properties for the component list.

Valid Values

Valid values include any property method listed in the Properties Plus® input file, using Aspen Plus®.

Default Value

The default value is the global property method specified in the Properties Specifications Global sheet (in Aspen Plus).

If no property method is specified, IDEAL (Ideal property method) is used.

FREE-WATER Option Use the FREE-WATER calculation option for petroleum processes only.

When you use the FREE-WATER approximation, you must specify the property method to be used for the free water phase. This property method calculates all thermodynamic and transport properties for the free-water phase.

For further information, see the Aspen Plus User Guide, Volume 1 for further details.

Valid Values

Valid values include any property method listed in the Properties Plus® file.

Default Value

The default value is the Free-Water property method specified in the Properties Specifications Global sheet (in Aspen Plus).

If no property method is specified, STEAM-TA, the ASME steam table correlation, is used.

CHEMISTRY Option Use the CHEMISTRY option for electrolyte systems only.

The CHEMISTRY option specifies which Chemistry ID (defined in Aspen Plus®) is used for property calculations.

Electrolyte systems involve ionic components and reactions that must be defined to complete the components specification. Therefore, you need to


select which ionic reactions set you want to use. CHEMISTRY is required when you wish to model dissociation, equilibrium reaction, or salt precipitation in the liquid phase. For more details see the Aspen Plus User Guide, Volume 1, Chapter 6, and Volume 2, Chapter 27.

Valid Values

Valid values are any Chemistry ID specified in the Properties Plus® file, using Aspen Plus®.

Default Value

The default value is <none>.

TRUE-COMP Option Use the TRUE-COMP option for electrolyte systems only.

TRUE-COMP specifies whether property calculations for the component list are to be performed in terms of true or apparent components.

If you choose apparent components (TRUE-COMP=No) the input to all thermodynamic and transport property procedure calls should be in terms of apparent components. The procedure will internally automatically calculate the true composition where needed as part of it's property calculations.

If you choose true components (TRUE-COMP=Yes) the input to all thermodynamic and transport property procedure calls must be in terms of the true equilibrium composition. Your model must calculate this before calling these property procedures. You can do this using the pTrueCmp2 or pTrueCmpVLS procedures. pTrueCmp2 is suitable for liquid-solid systems, and pTrueCmpVLS is suitable for vapor-liquid-solid systems.

If no Chemistry ID is specified, then the true and apparent approaches are equivalent, so you do not need to specify a value for TRUE-COMP.

For a description of the differences between the apparent and true component approaches, see Aspen Plus Physical Property Methods and Models, Chapter 5.

Valid Values

Valid values for TRUE-COMP are YES (true component approach) or NO (apparent component approach).

Default Value

The default value is NO.

HENRY-COMPS Option Use the HENRY-COMPS calculation option with property methods based on activity coefficient models only.

In the activity coefficient approach for computing vapor-liquid equilibrium, Henry's Law is used to represent the behavior of dissolved gases or other


supercritical components. HENRY-COMPS is used to specify the components (if any) for which Henry's Law is to be used.

For information on how to specify the set of Henry Components in Aspen Plus®, see the Aspen Plus User Guide, Volume 1, Chapter 6.

Valid Values

Valid values include any Henry's component list ID specified in the Properties Plus® file.

Default Value

If a Henry's Law component list is referenced in the Properties Plus file for the property method you have selected, this list will be used.

If no Henry's Law component list is referenced, the default is <none> and no Henry's components are used.

SOLU-WATER Option Use the SOLU-WATER option with petroleum processes only.

SOLU-WATER is used to specify the method for calculating the K-value of water.

For properties procedures, the FREE-WATER calculation option is always used, except for three-phase flash procedures with the FULL option.

For further information, see the Aspen Plus User Guide, Volume 1, Chapter 7.

Valid Values

Valid values for SOLU-WATER are:

Value Method Used

0 Water solubility correlation. Vapor phase fugacity for water calculated by free water phase option set.

1 Water solubility correlation. Vapor phase fugacity for water is calculated by primary option set.

2 Water solubility correlation with a correction for unsaturated systems. Vapor phase fugacity for water is calculated by primary option set.

3 Primary option set. Not recommended for water-hydrocarbon systems unless water-hydrocarbon interaction parameters are available.

Default Value

The default value is 3.

Important Note: Change the default value only if you want to use free water approximations.


KBASE Option KBASE is used to define the thermodynamic reference state to be used for property calculations. For further information, see the Aspen Plus® reference manual, User Models.

Valid Values

Valid values for KBASE are:

Value Option Used

0 Pure compounds in ideal gas state at 298.15K. If you model reactions, you must explicitly include the heat of reaction term in the energy balances.

1 Elements in their standard states at 298.15K. The heat of reaction term is built into the enthalpy calculations.

Default Value

The default value is 1.

MAXIT Option Use MAXIT to define the maximum number of iterations to be used for flash calculations before a failure code is returned.

If a failure code is returned, the run will stop automatically. The default value of 100 is nearly always adequate. However, if a run fails because the maximum number of iterations has been reached, it is worth trying a larger value.

Note: Flash calculations are used in determining mixed phase properties such as mixed phase enthalpy, or mixed phase entropy, as well as by the flash procedure itself.

Valid Values

Valid values for MAXIT are 30, 100, and 500.

Default Value

The default value is 100. This default is larger than the Aspen Plus® default.

TOLERANCE Option Use TOLERANCE to define the tolerance within which flash calculations must be converged.

The default value of 1E-6 is good for most applications. A smaller value gives more precise values from flash calculations, and enables numerical


derivatives to be calculated more precisely. However, this can also slow down the simulation.

Valid Values

Valid values for TOLERANCE are:

1E-3 1E-4 1E-5 1E-7 1E-6 1E-8 1E-9 1E-10 1E-11 1E-12

Default Value

The default value is 1E-6. This default is smaller than the Aspen Plus® default.

RETENTION Option Use RETENTION to retain intermediate results for flash calculations between calls. Using RETENTION may substantially reduce the time taken for flash calculations where many flash calculations are performed.

Valid Values

Valid values are ON and OFF.

Default Value

The default value is OFF.

9 Interfacing Your Own Physical Properties 259

9 Interfacing Your Own Physical Properties

You can link in your own physical property package if it can be:

• Written in Fortran or C

• Organized to permit calls to subroutines that return physical properties as they are required in models

Note for C Programmers: Make sure all calls obey Fortran calling conventions

The following sections describe:

• How the interface communicates with Properties Plus.

• The two sets of routines that comprise the Generalized Physical Properties Interface (GPPI): − Generalized Physical Properties Interface routines. − Entry point routines.

• Linking property procedure types to property routines.

• Fortran programmer's checklist.

• Installing the physical properties interface.

For information on property procedure types, see the Aspen Custom Modeler Library Reference Chapter 2.

How the Interface Communicates with Properties Plus The interface is implemented as two DLLs, described in this table:

This DLL Is Used To

gpp_setup.dll Correctly set up the environment that gpp.dll needs by modifying the PATH environment variable so that it includes the A+ xeq directory.


This means when gpp.dll is loaded, references to Aspen Plus DLLs can be resolved. Doing it this way avoids the need for the A+ directories to be added to the PATH at installation time.

gpp.dll Implement these GPP_ functions:

o GPP_SETUP

o GPP_INI

o GPP_QUERY

o GPP_LOAD

o GPP_UNLOAD

o GPP_END

o GPP_OPTIONS

In addition to the GPP functions above, you also need to define a set of Aspen Modeler procedures through which properties calculations can be called from models. These functions are normally be implemented in a separate DLL.

Installing your Interface

To install your interface you must put gpp_setup.dll and gpp.dll in one of the directories listed in the PATH environment variable, so that they get loaded in preference to the two DLLs that were provided for the Properties Plus interface.

The search path that Windows uses for loading a DLL is current working directory first, then directories on the PATH, and finally the Windows system directories.

Phase specific Variable Types and Property Procedures The argument lists for phase specific property procedures have been updated to include non-phase specific variable types.

Where phase specific variable types are defined they now inherit from non phase variable specific type.

For example:

• The output variable type for procedure pCond_liq has been changed from cond_liq to conductivity and the variable type cond_liq now inherits from variable type conductivity i.e.: − Variable cond_liq uses conductivity.

This change means that a variable for a mixture property can be an output from a phase specific property procedure, and you do not need to have another intermediate variable of the correct type.

If you have definitions of phase specific variable types in your input file, which are used in the argument list of property procedures, you may get errors on loading the file of the form:

1000: CALL (K) = pCond_liq (T,P,Z);


Error at position 32: Procedure output argument 1 must be (or inherit) variable type conductivity

To fix these errors you must modify the definitions of the phase specific variables in your input file so that they inherit from the non-phase specific type e.g.

Change:

Variable cond_liq

to

Variable cond_liq Uses conductivity

Generalized Physical Properties Interface Routines The Generalized Physical Properties Interface (GPPI) routines are used to:

• Initialize the physical properties system.

• Query the names of the components and the thermodynamic options available.

• Load data from the physical properties system and initialize constants and parameters that will apply to future physical property calls.

• Reset the physical properties system if the data changes.

• Provide access to the physical properties output level.

• Terminate the physical properties system.

This section describes each of the GPPI routines. For each routine, the following information is provided:

Under this heading Find this information

Requirement Whether or not you must provide the routine

Purpose Purpose of the routine

Definition The first few lines of the routine. This defines the argument list, and the meaning of the variables.

Important

Note the following points when you are writing GPPI routines:

• All code linked in via shared or dynamically linked libraries (DLLs) must be thread safe.

• If your routine can fail under certain circumstances, use the parameter IFAIL to return the failure status. Always assign IFAIL a value of 1 if the call is successful or 4 if the call is unsuccessful. The following error flags are defined: 1 Normal. Continue execution.

2 Warning. Continue execution.

3 Error. Continue execution.


4 Fatal error. Stop execution immediately and return to executive.

• Use the routine ACM_PRINT for printing diagnostic output.

GPP_SETUP Requirement

Optional

Purpose

This routine is loaded from an optional DLL called GPP_SETUP, which is loaded before the main GPP_DLL, so it can set up the runtime environment for GPP.DLL.

Definition

The argument list of GPP_SETUP is:

SUBROUTINE GPP_SETUP (IFAIL)

Name Type Description

IFAIL I Failure flag

GPP_INI GPP_INI passes the name and path of the simulation physical properties definition file. Even if there is no such file provided by your interface, you should include dummy arguments for PATH & FILEID in the argument list.

Requirement

Compulsory.

Purpose

The routine is called with the user defined path and full filename of the simulation physical properties definition file. Use this routine to initialize your interface as required.

Definition

The argument list of GPP_INI is:

SUBROUTINE GPP_INI (PATH, FILEID, IFAIL)


PATH C*(*) Location of the physical properties definition file

FILEID C*(*) Name of the physical properties definition file in the form: <filename>.<filetype>, e.g. gasplant.appdf



GPP_QUERY GPP_QUERY reads component and options data from the .appdf file.

If your interface does not have an equivalent of the .appdf file, GPP_QUERY returns the list of components and options that your package supports.

This data is then displayed in the GUI dialog boxes where component lists are defined. If the properties being used in a simulation are defined in a Modeling Language file, then the data returned from GPP_QUERY is used to validate the description given in the Properties definition. In fact, when a file containing a Properties definition is loaded, Editing Properties appears in the status bar, then gpp.dll is loaded, and gpp_ini and then gpp_query are called.

Requirement

Compulsory

Purpose

Used to query the physical properties system for a complete list of component names and valid keywords or thermodynamic options such as PENG and IDEAL.

Definition

The argument list of GPP_QUERY is:

SUBROUTINE GPP_QUERY (IACTION, NUM, KEYW, VAL1, VAL2, IFAIL)

The data to be returned depends on the value of IACTION as follows:

IACTION Subroutine GPP_QUERY Response

1 Called once. Returns total number of components known to the property package in the second argument NUM and the string values COMPONENT NAME and FORMULA in the arguments KEYW and VAL1 respectively.

2 Called once for each known component. Returns the name of the NUMth component in the argument KEYW, and its formula in the argument VAL1.

3 Called once. Returns the total number of valid property options and their values known to the property package in the second argument NUM.

4 Called once for each valid property option. Returns the name of the NUMth property option in the argument KEYW, and its value in the argument VAL1. Note, if a property option has more than one value, then GPP_QUERY should return the same name in KEYW for each value. If KEYW is a vector then VAL2 has the word "VECTOR" �that is it accepts a list of options at once. If VAL2 is not set, it is assumed to be scalar.


GPP_LOAD GPP_LOAD describes the component list to the package and is called when you exit the Build Component List dialog box. Aspen Modeler products associate a number with each component list used in a simulation. When a procedure call equation which has the PROPERTIES option associated with it is called, this number is passed in to the call as the extra ICLST argument. From this number, the package knows which components and options were chosen for the component list associated with the procedure call.

Requirement

Compulsory

Purpose

Used to:

• Perform any loading of pure component and interaction data that is required.

• Establish which calculation options have been specified for each component list.

• Process data supplied through the Graphical User Interface (GUI) client into a suitable form for efficient use by the physical properties package. This also includes assigning and copying files for use by the physical properties package.

Definition

The argument list of GPP_LOAD is:

SUBROUTINE GPP_LOAD (NOCLIS, NCOMP, COMPNA, NOVAL, OPTKWD, OPTVAL, MAXCSU, MAXVAL, IFAIL)

Name Type Dimensions Description

NOCLIS I � Total number of components lists

NCOMP I NOCLIS Number of components in each component list

COMPNA C*(*) MAXCSU, NOCLIS

Names of components in each component list

NOVAL I NOCLIS Number of option values in each component list

OPTKWD C*(*) MAXVAL, NOCLIS

OPTion KeyWorD for the options in each component list

OPTVAL C*(*) MAXVAL, NOCLIS

OPTion VALues for the options in each component list

MAXCSU I � Maximum number of components for any component list

MAXVAL I � Maximum number of option values for any component list

IFAIL I � Failure flag


GPP_UNLOAD GPP_UNLOAD is called when the data passed to GPP_LOAD is not required anymore. Use GPP_UNLOAD to clean up anything done in GPP_LOAD.

Requirement

Compulsory

Purpose

When a run terminates or the component lists are redefined, this routine is called to reset the package so that it is ready to accept a new set of component lists. This routine is also used for unassigning and deleting files.

Definition

The argument list of GPP_UNLOAD is:

SUBROUTINE GPP_UNLOAD (IFAIL)



GPP_END GPP_END is called when simulator shuts down; it implements anything necessary to clean up what was done in GPP_INI.

Requirement

Compulsory

Purpose

Called when the simulator shuts down or a different physical properties package is selected.

Definition

The argument list of GPP_END is:

SUBROUTINE GPP_END (IFAIL)



GPP_OPTIONS Requirement

Compulsory


Purpose

Provides access to the diagnostic print level for the physical properties interface and/or package.

Definition

The argument list of GPP_OPTIONS is:

SUBROUTINE GPP_OPTIONS (PROP_LEVEL, IFAIL)


PROP_LEVEL I The property output level


Entry Point Routines The entry point routines are a set of routines that intercept internal procedure calls and call the necessary routines within the physical property package with an appropriate argument list.

ACM Library Procedure Declaration

Each entry point routine is defined by an internal procedure declaration in the ACM Library.

For information about Procedure Declaration, see Modeling Language Reference, Chapter 3-9.

Procedures with Analytic Derivatives

For procedures that return analytic derivatives, a typical procedure declaration is:

PROCEDURE <procedure_name>

CALL : <subroutine_name>;

LIBRARY : "<dllname>�;

IMPLEMENTATION : SUBROUTINE;

LANGUAGE : FORTRAN;

OPTIONS : PROPERTIES, DERIVATIVES;

INPUTS : <input_var_type> [,<input_var1_type>];

OUTPUTS : <output_var_type> [,<output_var1_type>];

END;

Note: The appearance of the keyword DERIVATIVES under the OPTIONS statement.

<procedure_name> Name of the declared procedure


<subroutine_name> Name of the fortran subroutine

<dllname> Name of the Dynamics Link Library

<input_var_type> [,<input_var1_type>]

List of input variable types. For array variables with a single dimension, a wildcard size, given by (*), is used.

<output_var> [,<output_var1_type>]

List of output variable types. For array variables with a single dimension, a wildcard size, given by (*), is used.

The corresponding fortran entry point subroutine headings are in the form:

SUBROUTINE <subroutine_name> (<input_var1> [, <input_var], <output_var> [, <output_var1>, IFLAG, ICLST, DERIV, NDOUT, NDIN, ICALL)


<input_var> [,<input_var1>] List of real input variables. For array variables with a single dimension, the dimension of the array is inserted automatically as an integer value immediately after the variable. Values of input variables should never be changed by entry point routines.

<output_var> [,<output_var1>]

List of real output variables. For array variables with a single dimension, the dimension of the array is inserted automatically as an integer value immediately after the variable.

IFLAG An integer flag, initially set to 1. You can use this parameter to return error codes from your routine. See Status Codes Returned from Procedures.

The following error flags are defined:

1 Normal. Continue execution

2 Warning. Continue execution

3 Error. Continue execution


Note: Thus if an iterative routine fails to converge, it can set IFLAG to 3 if the result is close to tolerance. If the error is too large, it can set IFLAG to 4. In the first case, execution continues, but a warning message is issued. In the second case, execution is terminated immediately on return from the routine. You should use the error return code wherever appropriate.

ICLST An integer value representing the component list for which the physical property calculation is requested.

DERIV A 2-D real array of size (NDOUT, NDIN) containing analytic derivatives of the output variables WRT the input variables.

NDOUT Number of output variables

NDIN Number of input variables

ICALL An integer flag from the calling code which declares the type of the procedure call. See ICALL codes passed to Procedures.

The following calling status are relevant:

0 Requires Property calculation only


3 Requires Derivatives only

4 Requires both Property calculation and Derivatives

Note: Your subroutine coding must respond correctly to the above 3 different instances of ICALL from ACM Executive. For example, when ICALL=0, that is, when Derivatives are not required, NDOUT and NDIN are zeros and DERIV is of zero size.

To use with Aspen Modeler products, you need to generate a (standard) fortran wrapper routine for the Procedure.

Status Codes Returned from Procedures

All procedures must return a status code, normally an argument called IFLAG. The calling code will initialize this to 1

The following values for the status code are defined:


2 Warning. Issue message and continue execution

3 Severe Error. Issue message and continue execution

4 Fatal error. Issue dialog and stop execution.

Note: You should return a FATAL error if there is no possibility of recovery from the error: for example, if a necessary data file cannot be found, or if data is unitilialized. If the error is caused by values going out of range, you should return a SEVERE error, which will allow the solver to perturb the solution point and try again.

If you generate a template for your procedure code, suitable symbolic values are defined for you to use in your code.

ICALL codes passed to Procedures

Procedures are normally passed a flag, usually called ICALL, to indicate the kind of call that is being made to the procedure. If the procedure does not need PRECALL, POSTCALL, or DERIVATIVES, then ICALL is not passed to the procedure, as it will always be zero.

The following codes may occur:

0 Requires calculation of outputs only

1 PRECALL � use to open files, initialize workspace, COMMON data.

2 POSTCALL � use to close files.

3 Requires calculation of derivative values only.

4 Requires both calculation outputs and derivatives.


Note: Your subroutine coding must respond correctly to the above different values of ICALL from ACM Executive. For example, when ICALL=0, that is, when Derivatives are not required, NDOUT and NDIN are zeros and DERIV is of zero size, and may not have been allocated by the calling code (hence an attempt to read from it or write to it would result in an access violation).

Example of Procedure Declaration with Analytic Derivatives The following example shows a typical Procedure Declaration for a Fortran entry point routine that returns Analytic Derivatives:

PROCEDURE pEnth_Mol_Liq

// Specific Liquid Molar Enthalpy with Analytic Derivatives

CALL : gpidlhx;

LIBRARY : "gpp.dll";


LANGUAGE : FORTRAN;

OPTIONS : PROPERTIES, DERIVATIVES;

INPUTS : Temperature, Pressure, Molefraction(*);

OUTPUTS : enth_mol;

END;

Example of Entry Point Routine that returns Analytic Derivatives The following fortran subroutine reflects the above declared Procedure pEnth_Mol_Liq defining the entry point routine GPIDLHX:

SUBROUTINE GPIDLHX ( T, P, X, NX, IFAIL, ICLST,

& DERIV, DOUT, DIN, ICALL )

C Return Stream Specific Molar Enthalpy

IMPLICIT DOUBLE PRECISION (A-H, O-Z)

COMMON /LOADED/ ILOAD

DIMENSION X(NX)

C

C Array for the returning composition derivatives

DIMENSION dHHdX(NX)


C Parameterize the required UOM conversion factors

PARAMETER ( UCFProp = 1.0D-3, UCFTemp = 273.15,

& UCFPres = 1.0D-4, UCFComp = 1.0D-3 )

C

C Check whether correct Component List data loaded

IF (ICLST.NE.ILOAD) CALL LOAD(ICLST)

C Convert T from Celsius to Kelvin

TK = T + 273.15D0

C

C CALL Physical Property Package Routine

CALL PPPACK ( TK, P, X, .. <argument list>..., HH,

& dHHdT, dHHdP, dHHdX, ISTATUS )

C

C Check the status of the call to Subroutine PPPACK

IF (ISTATUS.LE.0) THEN

IFAIL = 4

GOTO 999

ENDIF

C Respond to the incoming ICALL flag

IF (ICALL.EQ.0 .OR. ICALL.EQ.4) THEN

C Both cases require the return of the Property

H = HH * UCFProp

ENDIF

IF (ICALL.EQ.3 .OR. ICALL.EQ.4) THEN

C Both cases require the return of all property derivatives

C Get Temperature derivative with UOM conversion

DERIV(1,1) = dHHdT * UCFT%emp

C Get Pressure derivative with UOM conversion

DERIV(1,2) = dHHdP * UCFPress

C Get Compositon derivatives with UOM conversion

DO I = 1, NX

DERIV(1,I) = dHHdX(I) * UCFComp

ENDDO

ENDIF


999 CONTINUE

RETURN

END

Procedures without Analytic Derivatives

For procedures that do not return analytic derivatives, a typical procedure declaration is:

PROCEDURE <procedure_name>

CALL : <subroutine_name>;

LIBRARY : "<dllname>�;


LANGUAGE : FORTRAN;

OPTIONS : PROPERTIES;

INPUTS : <input_var_type> [,<input_var1_type>];

OUTPUTS : <output_var_type> [,<output_var1_type>];

END;

Note: the absence of the keyword DERIVATIVES under the OPTIONS statement.

<procedure_name> Name of the declared procedure


<dllname> Name of the Dynamics Link Library

<input_var_type> [,<input_var1_type>]

List of input variable types. For array variables with a single dimension, a wildcard size, given by (*), is used.

<output_var> [,<output_var1_type>]

List of output variable types. For array variables with a single dimension, a wildcard size, given by (*), is used.

The corresponding fortran entry point subroutine headings are in the form:

SUBROUTINE <subroutine_name> (<input_var1> [, <input_var], <output_var> [, <output_var1>, IFLAG, ICLST)


<input_var> [,<input_var1>]

List of real input variables. For array variables with a single dimension, the dimension of the array is inserted automatically as an integer value immediately after the variable. Values of input variables should never be changed by entry point routines.

<output_var> [,<output_var1>]

List of real output variables. For array variables with a single dimension, the dimension of the array is inserted automatically as an integer value immediately after the variable.

IFLAG An integer flag, initially set to 1. You can use this parameter to return error conditions from


your routine.

The following error flags are defined:


2 Warning. Continue execution

3 Error. Continue execution


Note: Thus if an iterative routine fails to converge, it can set IFLAG to 3 if the result is close to tolerance. If the error is too large, it can set IFLAG to 4. In the first case, execution continues, but a warning message is issued. In the second case, execution is terminated immediately on return from the routine. You should use the error return code wherever appropriate.

To use with Aspen Modeler products, you need to generate a standard fortran wrapper routines for a C calling program from ACM Executive.

Example of Procedure Declaration without Analytic Derivatives The following example shows a typical Procedure Declaration for a Fortran entry point routine that does not return Analytic Derivatives:

PROCEDURE pEnth_Mol_Liq

// Specific Liquid Molar Enthalpy

CALL : gpilhx;

LIBRARY : "gpp.dll";


LANGUAGE : FORTRAN;

OPTIONS : PROPERTIES;

INPUTS : Temperature, Pressure, Molefraction(*);

OUTPUTS : enth_mol;

END;

Example of Entry Point Routine that Does Not Return Analytic Derivatives The following fortran subroutine reflects the above declared entry point Procedure pEnth_Mol_Liq defining the entry point routine GPILHX:

SUBROUTINE GPILHX ( T, P, X, NX, IFAIL, ICLST )

C Return Stream Specific Molar Enthalpy


IMPLICIT DOUBLE PRECISION (A-H, O-Z)

COMMON /LOADED/ ILOAD

DIMENSION X(NX)

C

C Parameterize the property UOM Conversion Factor

PARAMETER ( UCFProp = 1.0D-3)

C

C Check whether correct Component List data loaded

IF (ICLST.NE.ILOAD) CALL LOAD(ICLST)

C

C Convert T from Celsius to Kelvin

TK = T + 273.15D0

C

C CALL Physical Property Package Routine

CALL PPPACK ( TK, P, X, .. <argument list>...,

& HH, ISTATUS )

C

C Check the status of the call to Subroutine PPPACK

IF (ISTATUS.LE.0) THEN

IFAIL = 4

GOTO 999

ENDIF

C

C UOM conversion

H = HH * UCFProp

C

CONTINUE

C

RETURN

END


Linking Property Procedure Types to Subroutines When implementing a physical property interface, you can link to any property routines you choose. However, you must link to all physical properties that are used by your models. If you are using the Aspen Technology property procedure types, you are advised to link to all the procedures in the Library.

Property Procedures with Analytic Derivatives The following table is a list of all the physical property procedures that returns analytic derivatives used by the Library, and their subroutines. Subroutine names of this category begin with GPID, as shown in the table. For detailed information on linking each routine, see Generalized Physical Properties Interface Routine.

Procedure Name

Subroutine Name

Description

pCond_Liq GPIDLKX Liquid thermal conductivity

pCond_Vap GPIDVKX Vapor thermal conductivity

pCp_Mol_Liq GPIDLCP Liquid molar heat capacity at constant pressure

pCp_Mol_Vap GPIDVCP Vapor molar heat capacity at constant pressure

pCv_Mol_Liq GPIDLCV Liquid molar heat capacity at constant volume

pCv_Mol_Vap GPIDVCV Vapor molar heat capacity at constant volume

pDens_Mass_Liq GPIDLDX Liquid mass density

pDens_Mass_Vap GPIDVDX Vapor mass density

pDens_Mol_Liq GPIDLMX Liquid molar density

pDens_Mol_Vap GPIDVMX Vapor molar density

pDiffus_Liq GPIDLDC Liquid diffusion coefficients of components in a mixture

pDiffus_Vap GPIDVDC Vapor diffusion coefficients of components in a mixture

pEnth_Mol_Liq GPIDLHX Liquid molar enthalpy

pEnth_Mol_Vap GPIDVHX Vapor molar enthalpy

pEntr_Mol_Liq GPIDLSX Liquid molar enthalpy

pEntr_Mol_Vap GPIDVSX Vapor molar enthalpy

pFuga_Liq GPIDLFU Component liquid fugacity coefficients

pFuga_Vap GPIDVFU Component vapor fugacity coefficients

pGibbs_Mol_Liq GPIDLGX Liquid molar Gibbs free energy

pGibbs_Mol_Vap GPIDVGX Vapor molar Gibbs free energy

pKllValues GPIDKLL Component liquid/liquid equilibrium K values

pKValues GPID0KX Vapor liquid equilibrium K values

pSurf_Tens GPIDLTX Liquid surface tension

pVisc_Liq GPIDLVX Liquid viscosity

pVisc_Vap GPIDVVX Vapor viscosity


Property Procedures Without Analytic Derivatives The following table is a list of all the physical property procedures that do not return analytic derivatives used by the Library, and their subroutines. Subroutine names of this category begin with GPI, as shown in the table. For detailed information on linking each routine, see Generalized Physical Properties Interface Routine.

Procedure Name

Subroutine Name

Description

pAct_Coeff_Liq GPILAX Liquid activity coefficients

pBubt GPIBTX Bubble point temperature at fixed pressure

pDens_Mass_Sol GPISDX Solid mass density

pDens_Mol_Sol GPISMX Solid molar density

pDewt GPIDTX Dew point temperature at fixed pressure

pEnth_Mol GPI2EX Mixed phase molar enthalpy

pEnth_Mol_Sol GPISEX Solid molar enthalpy

pEntr_Mol GPI2SX Mixed phase molar enthalpy

pEntr_Mol_Sol GPISSX Solid molar enthalpy

pFlash GPI2FE Two-phase flash at given temperature and pressure

pFlash3 GPI3FH Three-phase flash at given temperature and pressure

pFlash3PH GPI3PH Three-phase flash at given pressure and enthalpy

pFlash3PV GPI3PV Three-phase flash at given pressure and vapor fraction

pFlash3TH GPI3TH Three-phase flash at given temperature and enthalpy

pFlash3TV GPI3TV Three-phase flash at given temperature and vapor fraction

pFlashPH GPI2PH Two-phase flash at given pressure and molar enthalpy

pFlashPV GPI2PV Two-phase flash at given pressure and vapor fraction

pFlashTH GPI2TH Two-phase flash at given temperature and molar enthalpy

pFlashTV GPI2TV Two-phase flash at given temperature and vapor fraction

pFuga_Sol GPISFU Component solid fugacity coefficients

pGibbs_Mol_IDLGAS

GPIZGX_IDLGAS

Component Ideal Gas Molar Gibbs Free Energies

pGibbs_Mol_Sol GPISGX Solid molar Gibbs free energy

pMolWeight GPI0WX Mean molar weight

pMolWeights GPIZW0 Component molar weights

pSurfTensY GPILTXY Vapor and liquid surface tension

pTrueCmp2 GPITR2 Liquid & Solid species comp. of an electrolyte mixture

pTrueCmpVLS GPITRVLS V, L & S species composition of an electrolyte mixture

pTrueComp GPITRU True species composition of an electrolyte mixture

pVap_Pressures GPIZP0 Component vapor pressure


Definition of GPPI Entry Points This section lists all of the physical property procedures used by the Library, except those for calculating properties of polymer solutions. (Polymer procedures are specific to Properties Plus® and are therefore not relevant if you are interfacing your own property package.)

For each procedure, the following information is provided:

Under this heading Find this information

Purpose Purpose of the procedure

Subroutine Name of the corresponding subroutine

Definition Subroutine definition for the routine. This defines the argument list, and the types and meaning of the variables. The letter I or O after a variable name denotes whether it is an input or output to the subroutine.

pAct_Coeff_Liq Purpose

Liquid phase activity coefficient

Subroutine

GPILAX

Definition

The argument list for GPILAX is:

SUBROUTINE GPILAX (T, P, X, NX, ACTL, NACTL, IFLAG, ICLST) INTEGER NX, IFLAG, ICLST, NACTL, DOUBLE PRECISION T, P, X(NX), ACTL(NACTL)


T I Temperature (C )

P I Pressure (bar)

X I Component mole fractions

NX I Number of components

ACTL O Liquid phase activity coefficient

NACTL I Number of components

IFLAG M Error flag

ICLST I Integer value for component list


pBubt Purpose

Bubble temperature at given pressure

Subroutine

GPIBTX

Definition

The argument list for GPIBTX is:

SUBROUTINE GPIBTX ( P, ZF, NZ, TBUB, IFLAG, ICLST ) INTEGER NZ, IFLAG, ICLST DOUBLE PRECISION P, ZF(NZ), TBUB


P I Pressure (bar)

ZF I Component mole fractions

NZ I Number of components

TBUB O Bubble temperature (C)

IFLAG M Error flag


pCond_Liq Purpose

Liquid phase thermal conductivity with analytic derivatives

Subroutine

GPIDLKX

Definition

The argument list for GPIDLKX is:

SUBROUTINE GPIDLKX ( T, P, X, NX, CONDL, IFLAG, ICLST, DERIV, NOUT, NIN, ICALL ) INTEGER NX, IFLAG, ICLST, ICALL DOUBLE PRECISION T, P, X(NX), CONDL, DERIV(NOUT,NIN)


T I Temperature (C)

P I Pressure (bar)



CONDL O Liquid phase thermal conductivity (W/m/K)


IFLAG M Error flag


DERIV O Analytic derivatives

NOUT I Number of output variables

NIN I Number of input variables

ICALL I Calling status

pCond_Vap Purpose

Vapor phase thermal conductivity with analytic derivatives

Subroutine

GPIDVKX

Definition

The argument list for GPIDVKX is:

SUBROUTINE GPIDVKX ( T, P, Y, NY, CONDV, IFLAG, ICLST, DERIV, NOUT, NIN, ICALL ) INTEGER NY, IFLAG, ICLST, ICALL DOUBLE PRECISION T, P, Y(NY), CONDV, DERIV(NOUT,NIN)


T I Temperature (C)

P I Pressure (bar)

Y I Component mole fractions

NY I Number of components

CONDV O Vapor phase thermal conductivity (W/m/K)

IFLAG M Error flag






pCp_Mol_Liq Purpose

Liquid specific heat capacity at constant pressure with analytic derivatives

Subroutine

GPIDLCP


Definition

The argument list for GPIDLCP is:

SUBROUTINE GPIDLCP ( T, P, X, NX, CPL, IFLAG, ICLST, DERIV, NOUT, NIN, ICALL ) INTEGER NX, IFLAG, ICLST, ICALL DOUBLE PRECISION T, P, X(NX), CPL, DERIV(NOUT,NIN)


T I Temperature (C)

P I Pressure (bar)



CPL O Liquid phase spec. heat capacity at constant pressure (kJ/kmol/K)

IFLAG M Error flag






pCp_Mol_Vap Purpose

Vapor phase specific heat capacity at constant pressure with analytic derivatives

Subroutine

GPIDVCP

Definition

The argument list for GPIDVCP is:

SUBROUTINE GPIDVCP ( T, P, Y, NY, CPV, IFLAG, ICLST, DERIV, NOUT, NIN, ICALL ) INTEGER NY, IFLAG, ICLST, ICALL DOUBLE PRECISION T, P, Y(NY), CPV, DERIV(NOUT,NIN)


T I Temperature (C)


P I Pressure (bar)



CPV O Vapor phase spec. heat capacity at constant pressure (kJ/kmol/K)

IFLAG M Error flag






pCv_Mol_Liq Purpose

Liquid specific heat capacity at constant volume with analytic derivatives

Subroutine

GPIDLCV

Definition

The argument list for GPIDLCV is:

SUBROUTINE GPIDLCV ( T, P, X, NX, CVL, IFLAG, ICLST, DERIV, NOUT, NIN, ICALL ) INTEGER NX, IFLAG, ICLST, ICALL DOUBLE PRECISION T, P, X(NX), CVL, DERIV(NOUT,NIN)


T I Temperature (C)

P I Pressure (bar)



CVL O Liquid phase spec. heat capacity at constant volume (kJ/kmol/K)

IFLAG M Error flag







pCv_Mol_Vap Purpose

Vapor phase specific heat capacity at constant volume with analytic derivatives.

Subroutine

GPIDVCV

Definition

The argument list for GPIDVCV is:

SUBROUTINE GPIDVCV ( T, P, Y, NY, CVV, IFLAG, ICLST, DERIV, NOUT, NIN, ICALL ) INTEGER NY, IFLAG, ICLST, ICALL DOUBLE PRECISION T, P, Y(NY), CVV, DERIV(NOUT,NIN)


T I Temperature (C)

P I Pressure (bar)



CVV O Vapor phase spec. heat capacity at constant volume (kJ/kmol/K)

IFLAG M Error flag






pDens_Mass_Liq Purpose

Stream liquid density with analytic derivatives

Subroutine

GPIDLDX

Definition

The argument list for GPIDLDX is:

SUBROUTINE GPIDLDX (T, P, X, NC, D, IFLAG, ICLST, DERIV, NOUT, NIN, ICALL) INTEGER NC, IFLAG, ICLST, ICALL DOUBLE PRECISION P, X(NC), T, D, DERIV(NOUT,NIN)



T I Temperature (C)

P I Pressure (bar)

X I Vector of component mole fractions of size NC

NC I Number of components

D O Liquid density (kg/m3)

IFLAG M Error flag






pDens_Mass_Sol Purpose

Solid mass density

Subroutine

GPISDX

Definition

The argument list for GPISDX is:

SUBROUTINE GPISDX (T, P, X, NX, DS, IFLAG, ICLST) INTEGER NX, IFLAG, ICLST DOUBLE PRECISION T, P, X(NX), DS


T I Temperature (C)

P I Pressure (bar)



DS O Solid mass density (kg/m3)

IFLAG M Error flag


pDens_Mass_Vap Purpose

Stream vapor mass density with analytic derivatives.


Subroutine

GPIDVDX

Definition

The argument list for GPIDVDX is:

SUBROUTINE GPIDVDX (T, P, X, NC, DV, IFLAG, ICLST, DERIV, NOUT, NIN, ICALL) INTEGER NC, IFLAG, ICLST, ICALL DOUBLE PRECISION P, T, X(NX), DV, DERIV(NOUT,NIN)


T I Temperature (C)

P I Pressure (bar)



DV O Vapor density (kg/m3)

IFLAG M Error flag






pDens_Mol_Liq Purpose

Liquid molar density with analytic derivatives

Subroutine

GPIDLMX

Definition

The argument list for GPIDLMX is:

SUBROUTINE GPIDLMX ( T, P, X, NX, RHOL, IFLAG, ICLST, DERIV, NOUT, NIN, ICALL ) INTEGER NX, IFLAG, ICLST, ICALL DOUBLE PRECISION T, P, X(NX), RHOL DERIV(NOUT,NIN)


T I Temperature (C)

P I Pressure (bar)




RHOL O Liquid density (kmol/m3)

IFLAG M Error flag






pDens_Mol_Sol Purpose

Solid molar density

Subroutine

GPISMX

Definition

The argument list for GPISMX is:

SUBROUTINE GPISMX (T, P, X, NX, RHOS, IFLAG, ICLST) INTEGER NX, IFLAG, ICLST DOUBLE PRECISION T, P, X(NX), RHOS


T I Temperature (C)

P I Pressure (bar)



RHOS O Solid molar density (kmol/m3)

pDens_Mol_Vap IFLAG M Error flag


Purpose

Vapor molar density with analytic derivatives

Subroutine

GPIDVMX


Definition

The argument list for GPIDVMX is:

SUBROUTINE GPIDVMX ( T, P, YF, NY, RHOV, IFLAG, ICLST, DERIV, NOUT, NIN, ICALL ) INTEGER NY, IFLAG, ICLST, ICALL DOUBLE PRECISION T, P, YF(NY), RHOV, DERIV(NOUT,NIN)


T I Temperature (C)

P I Pressure (bar)

YF I Component mole fractions


RHOV O Vapor density (kmol/m3)

IFLAG M Error flag






pDewt Purpose

Dew temperature at given pressure

Subroutine

GPIDTX

Definition

The argument list for GPIDTX is:

SUBROUTINE GPIDTX ( P, Z, NZ, TDEW, IFLAG, ICLST ) INTEGER NZ, IFLAG, ICLST DOUBLE PRECISION P, ZF(NZ), TDEW


P I Pressure (bar)

Z I Component mole fractions


TDEW O Dew temperature (C)

IFLAG M Error flag



pDiffus_Liq Purpose

Liquid diffusion coefficients with analytic derivatives

Subroutine

GPIDLDC

Definition

The argument list for GPIDLDC is:

SUBROUTINE GPIDLDC ( T, P, X, NX, DCL, NDCL, IFLAG, ICLST, DERIV, NOUT, NIN, ICALL ) INTEGER NX, NDCL, IFLAG, ICLST, ICALL DOUBLE PRECISION T, P, X(NX), DCL(NDCL), DERIV(NOUT,NIN)


T I Temperature (C)

P I Pressure (bar)



DCL O Diffusion coefficients (cm2/s)

NDCL I Number of components

IFLAG M Error flag

ICLST Integer value for component list





pDiffus_Vap Purpose

Vapor diffusion coefficients with analytic derivatives

Subroutine

GPIDVDC

Definition

The argument list for GPIDVDC is:

SUBROUTINE GPIDVDC ( T, P, Y, NY, DCV, NDCV, IFLAG, ICLST, DERIV, NOUT, NIN, ICALL ) INTEGER NY, NDCV, IFLAG, ICLST, ICALL DOUBLE PRECISION T, P, Y(NY), DCV(NDCV), DERIV(NOUT,NIN)



T I Temperature (C)

P I Pressure (bar)



DCV O Diffusion coefficients (cm2/s)

NDCV I Number of components

IFLAG M Error flag





pEnth_Mol ICALL I Calling status

Purpose

Mixed phase specific enthalpy

Subroutine

GPI2EX

Definition

The argument list for GPI2EX is:

SUBROUTINE GPI2EX ( T, P, Z, NZ, ENTHM, IFLAG, ICLST ) INTEGER NZ, IFLAG, ICLST DOUBLE PRECISION T, P, Z(NZ), ENTHM


T I Temperature (C)

P I Pressure (bar)



ENTHM O Mixed phase specific enthalpy (GJ/kmol)

IFLAG M Error flag


pEnth_Mol_Liq Purpose

Liquid specific enthalpy with analytic derivatives


Subroutine

GPIDLHX

Definition

The argument list for GPIDLHX is:

SUBROUTINE GPIDLHX ( T, P, X, NX, SPHL, IFLAG, ICLST, DERIV, NOUT, NIN, ICALL ) INTEGER NX, IFLAG, ICLST, ICALL DOUBLE PRECISION T, P, X(NX), SPHL, DERIV(NOUT,NIN)


T I Temperature (C)

P I Pressure (bar)



SPHL O Liquid specific enthalpy (GJ/kmol)

IFLAG M Error flag






pEnth_Mol_Sol Purpose

Solid molar enthalpy

Subroutine

GPISEX

Definition

The argument list for GPISEX is:

SUBROUTINE GPISEX (T, P, X, NX, SPHS, IFLAG, ICLST) INTEGER NX, IFLAG, ICLST DOUBLE PRECISION T, P, X(NX), SPHS


T I Temperature (C)

P I Pressure (bar)



SPHS O Solid specific enthalpy (GJ/kmol)


IFLAG M Error flag


pEnth_Mol_Vap Purpose

Vapor specific enthalpy with analytic derivatives

Subroutine

GPIDVHX

Definition

The argument list for GPIDVHX is:

SUBROUTINE GPIDVHX ( T, P, Y, NY, SPHV, IFLAG, ICLST, DERIV, NOUT, NIN, ICALL ) INTEGER NY, IFLAG, ICLST, ICALL DOUBLE PRECISION T, P, Y(NY), SPHV, DERIV(NOUT,NIN)


T I Temperature (C)

P I Pressure (bar)



SPHV O Vapor specific enthalpy (GJ/kmol)

IFLAG M Error flag






pEntr_Mol Purpose

Mixed phase specific molar entropy

Subroutine

GPI2SX

Definition

The argument list for GPI2SX is:


SUBROUTINE GPI2SX ( T, P, FZ, NZ, SPSM, IFLAG, ICLST ) INTEGER NZ, IFLAG, ICLST DOUBLE PRECISION T, P, FZ(NZ), SPSM


T I Temperature (C)

P I Pressure (bar)

FZ I Component mole fractions


ENTRM O Mixed phase molar entropy (kJ/kmol/K)

IFLAG M Error flag


pEntr_Mol_Liq Purpose

Liquid specific molar entropy with analytic derivatives

Subroutine

GPIDLSX

Definition

The argument list for GPIDLSX is:

SUBROUTINE GPIDLSX ( T, P, X, NX, SPSL, IFLAG, ICLST, DERIV, NOUT, NIN, ICALL ) INTEGER NX, IFLAG, ICLST, ICALL DOUBLE PRECISION T, P, X(NX), SPSL, DERIV(NOUT,NIN)


T I Temperature (C)

P I Pressure (bar)



SPSL O Liquid molar entropy (kJ/kmol/K)

IFLAG M Error flag







pEntr_Mol_Sol Purpose

Solid molar entropy

Subroutine

GPISSX

Definition

The argument list for GPISSX is:

SUBROUTINE GPISSX (T, P, X, NX, SPSS, IFLAG, ICLST) INTEGER NX, IFLAG, ICLST DOUBLE PRECISION T, P, X(NX), SPSS


T I Temperature (C)

P I Pressure (bar)



SPSS O Solid molar entropy (kJ/kmol/K)

IFLAG M Error flag


pEntr_Mol_Vap Purpose

Vapor specific molar entropy with analytic derivatives

Subroutine

GPIDVSX

Definition

The argument list for GPIDVSX is:

SUBROUTINE GPIDVSX ( T, P, Y, NY, SPSV, IFLAG, ICLST, DERIV, NOUT, NIN, ICALL ) INTEGER NY, IFLAG, ICLST, ICALL DOUBLE PRECISION T, P, Y(NY), SPSV, DERIV(NOUT,NIN)


T I Temperature (C)

P I Pressure (bar)




SPSV O Vapor molar entropy (kJ/kmol/K)

IFLAG M Error flag






pFlash Purpose

Two phase flash at fixed temperature and pressure

Subroutine

GPI2FE

Definition

The argument list for GPI2FE is:

SUBROUTINE GPI2FE ( T,P,Z,NZ,Y,NY,X,NX,VF,HV,HL,IFLAG,ICLST,WS,NWS ) INTEGER NZ, NY, NX, IFLAG, ICLST, NWS DOUBLE PRECISION T, P, Z(NZ), Y(NY), X(NX), VF, HV, HL, WS(NWS)


T I Temperature (C)

P I Pressure (bar)

Z I Stream component mole fractions


Y O Vapor component mole fractions


X O Liquid component mole fractions


VF O Vapor fraction

HV O Vapor specific enthalpy (GJ/kmol)

HL O Liquid specific enthalpy (GJ/kmol)

IFLAG M Error flag


WS I/O Workspace array for saving values between calls

NWS I Size of WS array


pFlashPH Purpose

Two phase flash at fixed pressure and enthalpy

Subroutine

GPI2PH

Definition

The argument list for GPI2PH is:

SUBROUTINE GPI2PH ( P,H,Z,NZ,T,VF,Y,NY,X,NX,HV,HL,IFLAG,ICLST,WS,NWS ) INTEGER NZ, NX, NY, IFLAG, ICLST, NWS DOUBLE PRECISION P, H, Z(NZ), T, VF, X(NX), Y(NY), HV, HL, WS(NWS)


P I Pressure (bar)

H I Overall specific enthalphy (GJ/kmol)

Z I Overall mole fractions


T O Temperature (C)

VF O Vapor fraction







IFLAG M Error flag




pFlashPV Purpose

Two phase flash at fixed pressure and vapor fraction

Subroutine

GPI2PV


Definition

The argument list for GPI2PV is:

SUBROUTINE GPI2PV ( P,VF,Z,NZ,T,Y,NY,X,NX,HV,HL,IFLAG,ICLST,WS,NWS ) INTEGER NZ, NX, NY, IFLAG, ICLST, NWS DOUBLE PRECISION P, Z(NZ), T, VF, X(NX), Y(NY), HV, HL, WS(NWS)


P I Pressure (bar)

VF I Vapor fraction



T O Temperature (C)







IFLAG M Error flag




pFlashTH Purpose

Two phase flash at fixed temperature and enthalpy

Subroutine

GPI2TH

Definition

The argument list for GPI2TH is:

SUBROUTINE GPI2TH ( T,H,Z,NZ,P,VF,Y,NY,X,NX,HV,HL,IFLAG,ICLST,WS,NWS ) INTEGER NZ, NX, NY, IFLAG, ICLST, NWS DOUBLE PRECISION P, Z(NZ), T, VF, X(NX), Y(NY), HV, HL, WS(NWS)



T I Temperature (C)

H I Overall specific enthalphy (GJ/kmol)



P O Pressure (bar)

VF O Vapor fraction







IFLAG M Error flag




pFlashTV Purpose

Two phase flash at fixed temperature and vapor fraction

Subroutine

GPI2TV

Definition

The argument list for GPI2TV is:

SUBROUTINE GPI2TV ( T,VF,Z,NZ,P,Y,NY,X,NX,HV,HL,IFLAG,ICLST,WS,NWS ) INTEGER NZ, NX, NY, IFLAG, ICLST, NWS DOUBLE PRECISION P, Z(NZ), T, VF, X(NX), Y(NY), HV, HL, WS(NWS)


T I Temperature (C)

VF I Vapor fraction



P O Pressure (bar)








IFLAG M Error flag




pFlash3 Purpose

Three phase flash at fixed temperature and pressure

Subroutine

GPI3FH

Definition

The argument list for GPI3FH is:

SUBROUTINE GPI3FH ( T, P, Z, NZ, RIGOR, 1 Y, NY, X1, NX1, X2, NX2, 2 VF, L2F, HV, HL1, HL2, IFAIL, ISTR ) INTEGER NZ, NY, NX1, NX2, IFLAG, ICLST DOUBLE PRECISION T, P, Z(NZ), RIGOR, Y(NY), X(NX1), X2(NX2), 1 VF, L2F, HV, HL1, HL2 CHARACTER*(*) RIGOR


T I Temperature (C)

P I Pressure (bar)

Z I Stream component mole fraction


RIGOR I 3-phase flash model type

�full�� perform full 3-phase calculation �decant�� perform 2-phase plus free-water calculation

Y O Vapor component mole fraction

NY O Number of components

X1 O Liquid 1 component mole fraction

NX1 O Number of components

X2 O Liquid 2 component mole fraction

NX2 O Number of components

VF O Vapor mole fraction

L2F O Mole fraction of liquid phase 2, that is,


L2/(L1 + L2 + V)


HL1 O Liquid 1 specific enthalpy (GJ/kmol)


IFLAG M Error flag


pFlash3PH Purpose

Three phase flash at fixed pressure and enthalpy

Subroutine

GPI3PH

Definition

The argument list for GPI3PH is:

SUBROUTINE GPI3PH (P, H, Z, NZ, RIGOR, T, VF, Y, NY, X1, NX1, 1 X2, NX2, L2F, HV, HL1, HL2, IFLAG, ICLST, WS, NWS) INTEGER NZ, NY, NX1, NX2, IFLAG, ICLST, NWS DOUBLE PRECISION P, H, Z(NZ), T, VF, Y(NY), X1(NX1), X2(NX2), 1 L2F, HV, HL1, HL2, WS(NWS) CHARACTER*(*) RIGOR


P I Pressure (bar)

H I Mixture specific enthalpy (GJ/kmol)

Z I Mixture mole fractions


RIGOR I 3-phase flash model type �full� � perform full 3-phase calculation �decant�� perform 2-phase plus free-water calculation

T O Temperature (C)

VF O Vapor fraction

Y O Vapor mole fractions


X1 O Liquid 1 mole fractions

NX1 I Number of components



L2F O Mole fraction of liquid phase 2, that is, L2/(L1+L2+V)





IFLAG M Error flag




pFlash3PV Purpose

Three phase flash at fixed pressure and vapor fraction

Subroutine

GPI3PV

Definition

The argument list for GPI3PV is:

SUBROUTINE GPI3PV (P, VF, Z, NZ, RIGOR, T, Y, NY, X1, NX1, 1 X2, NX2, L2F, HV, HL1, HL2, IFLAG, ICLST, WS, NWS) INTEGER NZ, NY, NX1, NX2, IFLAG, ICLST, NWS DOUBLE PRECISION P, Z(NZ), T, VF, Y(NY), X1(NX1), X2(NX2), L2F, 1 HV, HL1, HL2, WS(NWS) CHARACTER*(*) RIGOR


P I Pressure (bar)

VF I Vapor fraction



RIGOR I 3-phase flash model type �full� � perform full 3-phase calculation �decant�� perform 2-phase plus free-water calculation

T O Temperature (C)







L2F O Mole fraction of liquid phase 2, that is,


L2/(L1+L2+V)




IFLAG M Error flag




pFlash3TH Purpose

Three phase flash at fixed temperature and enthalpy

Subroutine

GPI3TH

Definition

The argument list for GPI3TH is:

SUBROUTINE GPI3TH (T, H, Z, NZ, RIGOR, P, VF, Y, NY, X1, NX1, 1 X2, NX2, L2F, HV, HL1, HL2, IFLAG, ICLST, WS, NWS) INTEGER NZ, NY, NX1, NX2, IFLAG, ICLST, NWS DOUBLE PRECISION P, H, Z(NZ), T, VF, Y(NY), X1(NX1), X2(NX2), 1 HV, HL1, HL2, WS(NWS), L2F CHARACTER*(*) RIGOR


T I Temperature (C)

H I Mixture specific enthalpy (GJ/kmol)




�full� � perform full 3-phase calculation decant�� perform 2-phase plus free-water calculation

P O Pressure (bar)

VF O Vapor fraction












IFLAG M Error flag




pFlash3TV Purpose

Three phase flash at fixed temperature and vapor fraction

Subroutine

GPI3TV

Definition

The argument list for GPI3TV is:

SUBROUTINE GPI3TV (T, VF, Z, NZ, RIGOR, P, Y, NY, X1, NX1, 1 X2, NX2, L2F, HV, HL1, HL2, IFLAG, ICLST, WS, NWS) INTEGER NZ, NY, NX1, NX2, IFLAG, ICLST, NWS DOUBLE PRECISION P, Z(NZ), T, VF, Y(NY), X1(NX1), X2(NX2), 1 HV, HL1, HL2, WS(NWS), L2F CHARACTER*(*) RIGOR


T I Temperature (C)

VF I Vapor fraction




�full� � perform full 3-phase calculation �decant�� perform 2-phase plus free-water calculation

P O Pressure (bar)












IFLAG M Error flag




pFuga_Liq Purpose

Component liquid fugacity coefficients with analytic derivatives

Subroutine

GPIDLFU

Definition

The argument list for GPIDLFU is:

SUBROUTINE GPIDLFU (T, P, X, NX, FUGL, NFUGL, IFLAG, ICLST, DERIV, NOUT, NIN, ICALL) INTEGER NX, IFLAG, ICLST, NFUGL, ICALL DOUBLE PRECISION T, P, X(NX), FUGL(NFUGL), DERIV(NOUT,NIN)


T I Temperature (C)

P I Pressure (bar)



FUGL O Liquid phase fugacity coefficients

NFUGL I Number of components

IFLAG M Error flag







pFuga_Sol Purpose

Component solid fugacity coefficients

Subroutine

GPISFU

Definition

The argument list for GPISFU is:

SUBROUTINE GPISFU (T, P, Z, NZ, FUGS, NFUGS, IFLAG, ICLST) INTEGER NZ, NFUGS, IFLAG, ICLST DOUBLE PRECISION T, P, Z(NZ), FUGS(NFUGS)


T I Temperature (C)

P I Pressure (bar)



FUGS O Solid phase fugacity coefficients

NFUGS I Number of components

IFLAG M Error flag


pFuga_Vap Purpose

Component vapor fugacity coefficients with analytic derivatives

Subroutine

GPIDVFU

Definition

The argument list for GPIDVFU is:

SUBROUTINE GPIDVFU (T, P, Y, NY, FUGV, NFUGV, IFLAG, ICLST, DERIV, NOUT, NIN, ICALL) INTEGER NY, IFLAG, ICLST, NFUGV, ICALL DOUBLE PRECISION T, P, Y(NY), FUGV(NFUGV), DERIV(NOUT,NIN)


T I Temperature (C)

P I Pressure (bar)




FUGV O Vapor phase fugacity coefficients

NFUGV I Number of components

IFLAG O Error flag






pGibbs_Mol_IDLGAS Purpose

Component ideal gas molar Gibbs free energies

Subroutine

GPIZGX_IDLGAS

Definition

The argument list for GPIZGX_IDLGAS is:

SUBROUTINE GPIZGX_IDLGAS (T, Y, NY, ZGi, NG, IFLAG, ICLST) INTEGER NY, IFLAG, ICLST DOUBLE PRECISION T, Y(NY), ZGi(NG)


T I Temperature (C)



ZGi O Component ideal gas molar Gibbs free energies (kJ/kmol)

IFLAG M Error flag


pGibbs_Mol_Liq Purpose

Liquid molar Gibbs free energy with analytic derivatives

Subroutine

GPIDLGX

Definition

The argument list for GPIDLGX is:


SUBROUTINE GPIDLGX (T, P, X, NX, SPGL, IFLAG, ICLST, DERIV, NOUT,NIN, ICALL) INTEGER NX, IFLAG, ICLST, ICALL DOUBLE PRECISION T, P, X(NX), SPGL, DERIV(NOUT,NIN)


T I Temperature (C)

P I Pressure (bar)



SPGL O Liquid molar Gibbs free energy (kJ/kmol)

IFLAG M Error flag






pGibbs_Mol_Sol Purpose

Solid molar Gibbs free energy

Subroutine

GPISGX

Definition

The argument list for GPISGX is:

SUBROUTINE GPISGX (T, P, W, NW, SPGS, IFLAG, ICLST) INTEGER NW, IFLAG, ICLST DOUBLE PRECISION T, P, W(NW), SPGS


T I Temperature (C)

P I Pressure (bar)

W I Component mole fractions

NW I Number of components

SPGS O Solid molar Gibb�s free energy (kJ/kmol)

IFLAG M Error flag



pGibbs_Mol_Vap Purpose

Vapor molar Gibbs free energy with analytic derivatives

Subroutine

GPIDVGX

Definition

The argument list for GPIDVGX is:

SUBROUTINE GPIDVGX (T, P, Y, NY, SPGV, IFLAG, ICLST, DERIV, NOUT, NIN, ICALL) INTEGER NY, IFLAG, ICLST, ICALL DOUBLE PRECISION T, P, Y(NY), SPGV, DERIV(NOUT,NIN)


T I Temperature (C)

P I Pressure (bar)



SPGV O Vapor molar Gibbs free energy (kJ/kmol)

IFLAG M Error flag






pKllValues Purpose

Liquid-liquid equilibrium K-values with analytic derivatives

Subroutine

GPIDKLL

Definition

The argument list for GPIDKLL is:

SUBROUTINE GPIDKLL (T, P, X1, NX1, X2, NX2, KLL, NKLL, IFLAG, ICLST, DERIV, NOUT, NIN, ICALL) INTEGER NX1, NX2, NKLL, IFLAG, ICLST, ICALL DOUBLE PRECISION T, P, X1(NX1), X2(NX2), KLL(NKLL) DOUBLE PRECISION DERIV(NOUT, NIN)



T I Temperature (C)

P I Pressure (bar)

X1 I Component mole fractions in first liquid phase


X2 I Component mole fractions in second liquid phase


KLL O Liquid-liquid equilibrium K values

NKLL I Number of components

IFLAG M Error flag






pKValues Purpose

Vapor-liquid equilibrium K-values with analytic derivatives

Subroutine

GPID0KX

Definition

The argument list for GPID0KX is:

SUBROUTINE GPID0KX (T, P, X, NX, Y, NY, K, NK, IFLAG, ICLST, DERIV, NOUT, NIN, ICALL) INTEGER IFLAG, ICLST, NX, NY, NK, ICALL DOUBLE PRECISION T, P, X(NX), Y(NY), K(NK),DERIV(NOUT,NIN)


T I Temperature (C)

P I Pressure (bar)

Y I Vector of vapor component mole fractions


FX I Vector of liquid component mole fractions


K O Vector of K values

NK I Number of components

IFLAG M Error flag







pMolweight Purpose

Stream molar weight

Subroutine

GPI0WX

Definition

The argument list for GPI0WX is:

SUBROUTINE GPI0WX (X, NC, MW, IFLAG, ICLST) INTEGER NC, IFLAG, ICLST DOUBLE PRECISION X(NC), MW




MW O Stream mean molar weight (kg/kmol)

IFLAG M Error flag


pMolweights Purpose

Component molar weights

Subroutine

GPIZW0

Definition

The argument list for GPIZW0 is:

SUBROUTINE GPIZW0 (MW, NMW, IFLAG, ICLST) INTEGER NMW, IFLAG, ICLST DOUBLE PRECISION MW



MW O Array of component molar weights (kg/kmol)

NMW I Number of components

IFLAG M Error flag


pSurf_Tens Purpose

Liquid surface tension with analytic derivatives

Subroutine

GPIDLTX

Definition

The argument list for GPIDLTX is:

SUBROUTINE GPIDLTX (T, P, X, NX, ST, IFLAG, ICLST, DERIV, NOUT, NIN, ICALL) INTEGER NX, IFLAG, ICLST, ICALL DOUBLE PRECISION T, P, X(NX), ST, DERIV(NOUT,NIN)


T I Temperature (C)

P I Pressure (bar)



ST O Liquid surface tension (N/m)

IFLAG M Error flag






pSurf_TensY Purpose

Surface tension using vapor and liquid mole fractions

Subroutine

GPILTXY


Definition

The argument list for GPILTXY is:

SUBROUTINE GPILTXY ( T, P, X, NX, Y, NY, ST, IFLAG, ICLST ) INTEGER NX, NY, IFLAG, ICLST DOUBLE PRECISION T, P, X(NX), Y(NY), ST


T I Temperature (C)

P I Pressure (bar)

X I Component liquid mole fractions


Y I Component vapor mole fractions


ST O Surface tension (N/m)

IFLAG M Error flag


pTrueComp Purpose

True species composition of an electrolyte mixture

Subroutine

GPITRU

Definition

SUBROUTINE GPITRU (T, P, AZ, NAZ, TZ, NTZ, SF, LF, IFLAG, ICLST) INTEGER NAZ, NTZ, IFLAG, ICLST DOUBLE PRECISION T, P, AZ(NAZ), TZ(NTZ), SF, LF


T I Temperature (C)

P I Pressure (bar)

AZ I Apparent component mole fractions

NAZ I Number of components

TZ O True component mole fractions

NTZ I Number of components

SF O Molar ratio of true solid to true liquid

LF O Molar ratio of true liquid to apparent liquid

IFLAG M Error flag



pTrueCmp2 Purpose

PTrueCmp2 calculates the composition of true species composition in the slurry phase.

(An alternative version to Procedure pTrueComp for electrolytes)

Subroutine

GPITR2

Definition

SUBROUTINE GPITR2 ( T, P, XA, NXA, XT, NXT, XTL, NXTL, XTS, NXTS,SFRAC,T2A,IFLAG,ICLST) INTEGER NXA, NXT, NXTL, NXTS, IFLAG, ICLST DOUBLE PRECISION T, P, XA(NXA), XT(NXT), XTL(NXTL), XTS(NXTS), SFRAC, T2A


T I Temperature (C)

P I Pressure (bar)

XA I Apparent component mole fractions

NXA I Number of apparent components

XT O Overall true component mole fractions

NXT I Number of overall true components

XTL O Liquid true component mole fractions

NXTL I Number of liquid true components

XTS O Solid true component mole fractions

NXTS O Number of solid true components

SFRAC O True solid mole fraction

T2A O True to apparent mole ratio

IFLAG M Error flag


pTrueCmpVLS Purpose

V, L & S species composition of an electrolyte mixture

Subroutine

GPITRVLS

Definition

The argument list for GPITRVLS is:


SUBROUTINE GPITRVLS

pVap_Pressures Purpose

Component vapor pressures

Subroutine

GPIZP0

Definition

The argument list for GPIZP0 is:

SUBROUTINE GPIZP0 (T, PV, NPV, IFLAG, ICLST) INTEGER NPV, IFLAG, ICLST DOUBLE PRECISION T, PV(NPV)


T I Temperature (C)

PV O Component vapor pressures (bar)

NPV I Number of components

IFLAG M Error flag


pVisc_Liq Purpose

Liquid phase viscosity with analytic derivatives

Subroutine

GPIDLVX

Definition

The argument list for GPIDLVX is:

SUBROUTINE GPIDLVX (T, P, X, NX, VL, IFLAG, ICLST, DERIV, NOUT, NIN, ICALL) INTEGER NX, IFLAG, ICLST, ICALL DOUBLE PRECISION T, P, X(NX), VL, DERIV(NOUT,NIN)


T I Temperature (C)

P I Pressure (bar)




VL O Liquid phase viscosity (cP)

IFLAG M Error flag






pVisc_Vap Purpose

Vapor phase viscosity

Subroutine

GPIDVVX

Definition

The argument list for GPIDVVX is:

SUBROUTINE GPIDVVX (T, P, Y, NY, VV, IFLAG, ICLST, DERIV, NOUT, NIN, ICALL) INTEGER NY, IFLAG, ICLST, ICALL DOUBLE PRECISION T, P, Y(NY), VV, DERIV(NOUT,NIN)


T I Temperature (C)

P I Pressure (bar)



VV O Vapor phase viscosity (cP)

IFL O Error flag






Fortran Programmer's Checklist Ensure that your routines conform to the following rules:

• All calls must obey Fortran calling conventions.

• All routines that employ an iterative equation-solving procedure (for example, flash calculations), must ensure that the precision of their results is at least 1.0E-7.


• All real variables must be double precision. To do this, use IMPLICIT NONE, and declare them as double precision variables.

Installing the Physical Properties Interface After you have prepared the Generalized Physical Properties Interface routines and the entry point routines, you must install them.

All your Generalized Physical Properties and entry point routines must be built into a dynamic linked library called gpp.dll. The optional gpp_setup function must be built into its own dynamic linked library, called gpp_setup.dll.

To ensure that your Aspen Modeler product uses your version of gpp.dll, you can either:

• Rename the existing gpp.dll and gpp_setup.dll files (which are valid for Properties Plus) in the bin directory and place your own gpp.dll and gpp_setup.dll files in this directory.

Note: The default installation path for the bin directory containing the DLLs is \Program Files\AspenTech\AMSystem 12.1.

� or �

• Place your gpp.dll and gpp_setup.dll files in the working directory for the simulation.

Make sure you test your interface thoroughly before releasing it for general use.

10 Using the Control Design Interface (CDI) 314

10 Using the Control Design Interface (CDI)

An Aspen Modeler model contains full information on the process being studied. A number of Computer Aided Control System Design (CACSD) software packages take simplified, linear process representations and analyze this data to recommend a control strategy for the process. The Control Design Interface (CDI) enables you to produce linear models from an Aspen Modeler simulation for transfer between Aspen Modeler and a CACSD package, for example MATLAB®.

This chapter explains:

• How CDI works.

• How to create CDI automation scripts to generate the information required for CACSD packages.

• CDI output file format.

Note: Some CDI calculations use LAPACK 2.0.

CDI also produces the following, which can be used in designing control systems:

• Relative Gain Array (RGA).

• Niederlinski Index (NI).

• Morari Resiliency Index (MRI).

• State Transition Matrix (STM).

LAPACK 2.0 is written by E. Anderson, Z. Bai, C. Bischof, J Demmel, J. Dongarra, J. du Croz, A. Greenbaum, S. Hammarling, A. McKenney, S. Ostrouchov, and D. Sorensen.

How CDI Works To understand how the Control Design Interface (CDI) works, you need to understand the differences between the Aspen Modeler DAE models involving differential and algebraic equations, and the linear models that are required by CACSD packages.


About DAE Models Aspen Modeler products provide an equation-based simulation environment and enable you to perform dynamic simulations. A dynamic model of a lumped parameter process is described in terms of differential and algebraic equations (a DAE system). The general form for such a model is:

f tdXdt

X Z U, , , ,

= 0

Where:

t = Time, the independent variable

X = A vector of the variables whose time derivatives appear in the model:

dXdt

These are known as state variables.

Z = A vector of unknowns whose time derivatives do not appear. These are known as algebraic variables.

U = The set of inputs or forcing functions whose time behavior is given.

About Linear Models Dynamic simulators have been used extensively to evaluate process control schemes. These control systems can be designed using Computer Aided Control System Design (CACSD) packages such as MATLAB®. These tools require a linear model of the process. The Control Design Interface (CDI) enables you to produce this model in the state-space form:

( ) ( ) ( )&x t Ax t Bu t= +

( ) ( ) ( )y t Cx t Du t= +

Where:

t = Time

x(t) =

The vector of n perturbations in the state variables in the problem.

u(t) = A vector of r perturbations about the chosen inputs, which refer to a subset of the set variables. These include any potential manipulated variables for the purpose of control system design. Manipulated variables are those varied by a controller.

y(t) =

A vector of m resultant perturbations in the chosen outputs, which are a subset of


the state and unknown algebraic variables. These include measured variables for the purposes of control system design.

A, B, C, D = Coefficient matrices of appropriate dimensions:

A � n x n (square)

B � n x r

C � m x n

D � m x r

These are known as the state-space matrices.

The state space may be produced at any plant state, but is usually produced at the normal operating steady state.

How CDI Produces Linearized Models The Control Design Interface ( CDI ) enables data to be transferred between Aspen Modeler products and CACSD packages. It does this by producing a linearized version of an Aspen Modeler simulation in the form of state-space matrices. For information on how to use CDI to do this, see Creating CDI Automation Scripts.

The state-space matrices A, B, C, and D are the products of CDI. To produce these matrices, CDI eliminates all the algebraic variables from the original dynamic simulation which do not appear in the linear model. For example, by selecting five algebraic output variables in a problem of 100 algebraic unknowns, CDI eliminates 95 variables.

CDI also produces the steady-state transfer function defined as follows:

( ) ( )y t G u t=

Where all derivatives and algebraic variables have been eliminated.

G has the dimensions:

G � m x r

Relative Gain Array (RGA) The Relative Gain Array (RGA), is a matrix of ratios of steady-state gains.

Element (i,j) of the matrix is the ratio between the ith controlled (output) variable and the jth manipulated (input) variable when all other manipulated variables are constant, divided by the steady-state gain between the same two variables when all other controlled variables are constant.

The RGA matrix is useful for avoiding poor pairings of manipulated and controlled variables. If the diagonal element in the RGA is negative, the control system might be unstable and large values of the RGA indicate that


the system can be sensitive to changes in values of parameters in the control system.

Niederlinski Index (NI) The Niederlinski Index (NI), can be used to help determine the stability of your control system based on the input and output variables chosen:

If the index is

Then

Negative The control system is unstable (known as "integral instability").

Positive The control system may or may not be stable.

Morari Resiliency Index (MRI) The Morari Resiliency Index (MRI) is used to give an idea of the controllability of your process flowsheet, using the input and output variables you have chosen. The MRI is computed at zero frequency, that is, based on the steady-state gain array only. The larger the value of the MRI, the more controllable (or "resilient") the process.

Note: When comparing different control schemes, note that MRI depends on the units of measurement used.

State Transition Matrix (STM) The State Transition Matrix (STM) at time T relates the values of the state variables at time T in the linearized state-space model to the initial condition via the following expression:

x(T) = STM(T) . x(0)

Where:

x = A vector of the n state variables in your non-linear model

x(0) = The corresponding initial conditions

T = The time you specify for which the STM is required.

You can choose a subset of the state variables to be ignored and these are dropped from the STM, analogous to model reduction. The choice of variables ignored must be based on engineering knowledge so that a valid STM exists.

The STM is computed using fixed step Implicit Euler integration of the state-space model. You can specify the size of integration step used to compute the STM, which affects both the accuracy of the STM and speed of computation.


Creating CDI Automation Scripts Before you use the CDI on a simulation, make sure:

• The simulation contains at least one CDI input variable and one output variable.

• The simulation does not have an index > 1 for the A, B, C, and D matrices to be computed.

• The current solution is converged.

Note: You can have several CDI automation scripts in a flowsheet.

To create a CDI script:

1 Create a script in the usual way.

2 In the Text Editor window, type the appropriate CDI syntax.

3 Run or save the script as required.

Notes:

• You can perform a CDI calculation at any time during the simulation, provided the simulation is paused. For example, you might want to calculate the A, B, C, D matrices at a number of different time points during a dynamic simulation. To do this, you would pause the simulation and run the CDI script at the times required. (You could also write a task which runs the CDI script at each time point required.)

• You should make sure that your model is not of index>1 before performing a CDI calculation.

• Tearing is ignored during a CDI calculation (that is CDI linearises your model as if tearing is off).

• Delay is ignored during a CDI calculation (that is, the delay is set to zero for your delayed variables).

• You should not perform a CDI calculation at a time when your model contains indeterminate variables.

For general background information on scripts, see the Automation Reference.


Syntax for CDI Automation Scripts For details of the syntax for creating CDI automation scripts, see the Automation Reference.

Example of Creating a CDI Script The following syntax runs the Control Design Interface on the currently open simulation document:

Set Doc = Simulation

set CDI = Doc.CDI

CDI.Reset

'CDI.ZeroTolerance=value

CDI.AddInputVariable "B1.u(1)"

CDI.AddInputVariable "B1.u(2)"

CDI.AddOutputVariable "B1.y(1)"

CDI.AddOutputVariable "B1.y(2)"

' "Matrix" can be one or more of A, B, C, D, G, RGA, NI, MRI, STM, or ALL.

' The default is "ALL".

CDI.MatricesRequired "G","A","B","C","D","RGA"

CDI.Calculate

application.msg "input variables U"

dim inputs

inputs = cdi.inputs()

for i=1 to CDI.numberofinputs

application.msg "U " & i & " is " & inputs(i-1)

next

application.msg "output variables X"

dim outputs

outputs = cdi.outputs()

for i=1 to CDI.numberofoutputs

application.msg "Y " & i & " is " & outputs(i-1)

next


application.msg "state variables X"

dim states

states = cdi.states()

for i=1 to CDI.numberofstates

application.msg "X " & i & " is " & states(i-1)

next

' example to list the elements of a matrix

dim rows, cols, vals

if CDI.MatrixStatus("A") then

application.msg "Matrix A"

rows = CDI.matrixrows("A")

cols = CDI.matrixcols("A")

vals = CDI.matrixValues("A")

for i=0 to CDI.MatrixNonZeros("A")-1

' application.msg rows(i) & " "& cols(i) & " "& vals(i)

application.msg states(rows(i)-1) & " "& states(cols(i)-1) & " "& vals(i)

next

application.msg ""

end if

CDI Output Files The matrix data generated by CDI is in ASCII .dat file format.

The .dat format enables you to import your state-space model into a Computer Aided Control System Design (CACSD) package, for example, MATLAB®.

In addition to the .dat file, the CDI Calculate function also creates a .lis file of the same name. You can use the values in the .lis file to scale the matrices produced.

ASCII DAT Format The .dat ASCII text file contains three columns delimited by spaces: the first column is a list of row indices, the second a list of column indices and the third column a list of values. For example, the .dat file:

1 1 2.0

2 1 -1.0


2 2 3.0

represents the matrix:

[2 0]

[-1 3]

This file can be easily read by other applications or programs. It can be imported into Matlab(R) using the following commands

load A.dat

A = spconvert(A)

where A.dat is the name of the .dat file and A will be the matrix in sparse format.

Note: Because the .dat file is in sparse format (that is, it contains only the non-zero values of the matrix above the threshold), the .dat file is not generated if the matrix has no non-zero values.

About the CDI .lis File The .lis file created by CDI contains the following information:

• A description, including the simulation file name.

• Time of linearization.

• Lists of state, input, and output variables, and for each variable, the index number into the relevant matrix, and the value of the variable at the point of linearization.

You can use the values in the .lis file to scale the matrices produced.

Example CDI .lis File

The following is an example of a CDI .lis file:

CDI information for btxcdi.acmf

Linearized at time 0

CDI summary of matrices computed:

A matrix computed, number of non-zero elements = 2027

B matrix computed, number of non-zero elements = 10

C matrix computed, number of non-zero elements = 9

G matrix computed, number of non-zero elements = 9

RGA matrix computed, number of non-zero elements = 9

MRI = 0.000045

NI = -45.639983


Number of state variables: 152

Number of input variables: 3

Number of output variables: 3

Statevariables:

Row number value, variable name

1 56630.91392788936 BOIL1.H

2 29.34365911855432 BOIL1.HOLD

3 0.001600381056687257 BOIL1.X(1)

4 0.04839961894331289 BOIL1.X(2)

5 0.9500000000000003 BOIL1.X(3)

6 40027.78575458659 BOIL2.H

7 3.374829890424375 BOIL2.HOLD

8 0.09756317794410598 BOIL2.X(1)

9 0.8599999999999991 BOIL2.X(2)

10 0.04243682205589397 BOIL2.X(3)

11 1.26090782888274E-005 COL1CC1.INT_ERROR

12 0.0006108000000000003 COL1LC1.INT_ERROR

13 34124.00295229167 COL1LSD.H

14 1.469734318272604 COL1LSD.HOLD

15 0.489623436584582 COL1LSD.X(1)

16 0.4942614216602229 COL1LSD.X(2)

17 0.01611514175519472 COL1LSD.X(3)

18 55303.67884006869 COL1S1.DTRAY_(1).H

19 1.578342265854297 COL1S1.DTRAY_(1).HOLD

20 0.005000157710917587 COL1S1.DTRAY_(1).X(1)

21 0.08336499426852256 COL1S1.DTRAY_(1).X(2)

22 0.9116348480205604 COL1S1.DTRAY_(1).X(3)

23 53937.18572594383 COL1S1.DTRAY_(2).H

24 1.591115757132761 COL1S1.DTRAY_(2).HOLD

25 0.01407130148293106 COL1S1.DTRAY_(2).X(1)

26 0.1275970773766303 COL1S1.DTRAY_(2).X(2)

27 0.8583316211404389 COL1S1.DTRAY_(2).X(3)

28 51986.67561748526 COL1S1.DTRAY_(3).H

29 1.606739705233883 COL1S1.DTRAY_(3).HOLD


30 0.03630380807061213 COL1S1.DTRAY_(3).X(1)

31 0.1753161450635736 COL1S1.DTRAY_(3).X(2)

32 0.7883800468658145 COL1S1.DTRAY_(3).X(3)

33 49306.68313959331 COL1S1.DTRAY_(4).H

34 1.630876457027793 COL1S1.DTRAY_(4).HOLD

35 0.08443663380975423 COL1S1.DTRAY_(4).X(1)

36 0.2129733680481336 COL1S1.DTRAY_(4).X(2)

37 0.7025899981421124 COL1S1.DTRAY_(4).X(3)

38 45994.13285292211 COL1S1.DTRAY_(5).H

39 1.666987865560976 COL1S1.DTRAY_(5).HOLD

40 0.1708049644348191 COL1S1.DTRAY_(5).X(1)

41 0.2215726719669167 COL1S1.DTRAY_(5).X(2)

42 0.6076223635982644 COL1S1.DTRAY_(5).X(3)

43 41418.83202631665 COL1S1.DTRAY_(7).H

44 1.319435851211945 COL1S1.DTRAY_(7).HOLD

45 0.3122235872826195 COL1S1.DTRAY_(7).X(1)

46 0.2344717468241706 COL1S1.DTRAY_(7).X(2)

47 0.4533046658932101 COL1S1.DTRAY_(7).X(3)

48 39856.29686982051 COL1S1.DTRAY_(8).H

49 1.346612120389595 COL1S1.DTRAY_(8).HOLD

50 0.3427912484734354 COL1S1.DTRAY_(8).X(1)

51 0.2936260349648588 COL1S1.DTRAY_(8).X(2)

52 0.3635827165617058 COL1S1.DTRAY_(8).X(3)

53 38145.34215893035 COL1S1.DTRAY_(9).H

54 1.379424477712419 COL1S1.DTRAY_(9).HOLD

55 0.378355139274437 COL1S1.DTRAY_(9).X(1)

56 0.3621779792418554 COL1S1.DTRAY_(9).X(2)

57 0.2594668814837076 COL1S1.DTRAY_(9).X(3)

58 36616.46598584802 COL1S1.DTRAY_(10).H

59 1.411728819023971 COL1S1.DTRAY_(10).HOLD

60 0.4125512694761682 COL1S1.DTRAY_(10).X(1)

61 0.4252928967717221 COL1S1.DTRAY_(10).X(2)

62 0.1621558337521095 COL1S1.DTRAY_(10).X(3)

63 35473.94728342046 COL1S1.DTRAY_(11).H

64 1.437817415678034 COL1S1.DTRAY_(11).HOLD


65 0.4409875674513755 COL1S1.DTRAY_(11).X(1)

66 0.4702477599755525 COL1S1.DTRAY_(11).X(2)

67 0.08876467257307183 COL1S1.DTRAY_(11).X(3)

68 34694.99810045036 COL1S1.DTRAY_(12).H

69 1.456327384917594 COL1S1.DTRAY_(12).HOLD

70 0.4647758470399063 COL1S1.DTRAY_(12).X(1)

71 0.4929654751627123 COL1S1.DTRAY_(12).X(2)

72 0.04225867779738084 COL1S1.DTRAY_(12).X(3)

73 42610.38072431905 COL1S1.DFTRAY_.H

74 1.713763806847634 COL1S1.DFTRAY_.HOLD

75 0.2900384130099258 COL1S1.DFTRAY_.X(1)

76 0.1920373694422355 COL1S1.DFTRAY_.X(2)

77 0.5179242175478388 COL1S1.DFTRAY_.X(3)

78 33258.77588427347 COL1S2.DTRAY_(15).H

79 1.585593472664548 COL1S2.DTRAY_(15).HOLD

80 0.550675663666079 COL1S2.DTRAY_(15).X(1)

81 0.4468777798630484 COL1S2.DTRAY_(15).X(2)

82 0.002446556470872464 COL1S2.DTRAY_(15).X(3)

83 32687.21777623817 COL1S2.DTRAY_(16).H

84 1.59870339232037 COL1S2.DTRAY_(16).HOLD

85 0.5998167262708132 COL1S2.DTRAY_(16).X(1)

86 0.3992834173940175 COL1S2.DTRAY_(16).X(2)

87 0.0008998563351691505 COL1S2.DTRAY_(16).X(3)

88 31995.1376181745 COL1S2.DTRAY_(17).H

89 1.615340075748922 COL1S2.DTRAY_(17).HOLD

90 0.6628494052313106 COL1S2.DTRAY_(17).X(1)

91 0.3368363178704358 COL1S2.DTRAY_(17).X(2)

92 0.0003142768982534644 COL1S2.DTRAY_(17).X(3)

93 31216.92243668794 COL1S2.DTRAY_(18).H

94 1.6351804701215 COL1S2.DTRAY_(18).HOLD

95 0.7370471341578386 COL1S2.DTRAY_(18).X(1)

96 0.2628502253015669 COL1S2.DTRAY_(18).X(2)

97 0.0001026405405945184 COL1S2.DTRAY_(18).X(3)

99 1.656583671115566 COL1S2.DTRAY_(19).HOLD

100 0.8153884653177895 COL1S2.DTRAY_(19).X(1)


101 0.1845808532812316 COL1S2.DTRAY_(19).X(2)

102 3.068140097857487E-005 COL1S2.DTRAY_(19).X(3)

103 29713.47334158488 COL1S2.DTRAY_(20).H

104 1.677118566833914 COL1S2.DTRAY_(20).HOLD

105 0.8887844439714674 COL1S2.DTRAY_(20).X(1)

106 0.1112076093614257 COL1S2.DTRAY_(20).X(2)

107 7.946667106603748E-006 COL1S2.DTRAY_(20).X(3)

108 33725.94758562 COL1VF.H

109 1.575084246590023 COL1VF.HOLD

110 0.5142481364033974 COL1VF.X(1)

111 0.4793611206033546 COL1VF.X(2)

112 0.006390742993247772 COL1VF.X(3)

113 38495.65648181258 COL2.DTRAY_(1).H

114 0.1101611331477206 COL2.DTRAY_(1).HOLD

115 0.16410365816141 COL2.DTRAY_(1).X(1)

116 0.8114974344797556 COL2.DTRAY_(1).X(2)

117 0.02439890735883355 COL2.DTRAY_(1).X(3)

118 37356.54270046446 COL2.DTRAY_(2).H

119 0.1115288131841191 COL2.DTRAY_(2).HOLD

120 0.2399027544464658 COL2.DTRAY_(2).X(1)

121 0.7409111436863956 COL2.DTRAY_(2).X(2)

122 0.0191861018671378 COL2.DTRAY_(2).X(3)

123 36323.07008250972 COL2.DTRAY_(3).H

124 0.1127401705364569 COL2.DTRAY_(3).HOLD

125 0.3152434180958412 COL2.DTRAY_(3).X(1)

126 0.6671765631006116 COL2.DTRAY_(3).X(2)

127 0.01758001880354662 COL2.DTRAY_(3).X(3)

128 35471.19703044987 COL2.DTRAY_(4).H

129 0.1138176570093002 COL2.DTRAY_(4).HOLD

130 0.3807482795858485 COL2.DTRAY_(4).X(1)

131 0.6023396803845782 COL2.DTRAY_(4).X(2)

132 0.01691204002957304 COL2.DTRAY_(4).X(3)

133 34835.49621452565 COL2.DTRAY_(5).H

134 0.1146683449867835 COL2.DTRAY_(5).HOLD

135 0.4312132095856979 COL2.DTRAY_(5).X(1)


136 0.5522579713440989 COL2.DTRAY_(5).X(2)

137 0.0165288190702029 COL2.DTRAY_(5).X(3)

138 34396.53012457469 COL2.DTRAY_(6).H

139 0.1152730396070888 COL2.DTRAY_(6).HOLD

140 0.4665080600391092 COL2.DTRAY_(6).X(1)

141 0.5172110097593484 COL2.DTRAY_(6).X(2)

142 0.0162809302015423 COL2.DTRAY_(6).X(3)

143 -1.041701473697337E-005 COL2CC1.INT_ERROR

144 1.726221818181818 COL2LC1.INT_ERROR

145 29135.11893854067 COND1.DDRUM_.H

146 28.57538395971298 COND1.DDRUM_.HOLD

147 0.95 COND1.DDRUM_.X(1)

148 0.04999869034720324 COND1.DDRUM_.X(2)

149 1.30965279643544E-006 COND1.DDRUM_.X(3)

150 0.07044514285714286 COND1.P_I_CONTROLLER_ (1).INT_ERROR

151 1.181997073571317E-005 COND1.P_I_CONTROLLER_ (2).INT_ERROR

152 -3.55284602705969E-005 DTC.INT_ERROR

Input variables:

1 0.95 COL1CC1.SET_POINT

2 272.7 MF.TOT_FLOW

3 0.45 MF.X(1)

Output variables:

1 173.6485382570043 BOIL1.TEMP

2 0.3122235872826195 COL1S1.DTRAY_(7).X(1)

3 134.0401535317992 COL1S1.DTRAY_(7).TEMP

Relating Indices to Matrices

The indices are numbered from 1 to the number of states/inputs/outputs (n), and can be mapped to the indices of the matrices produced by the CDI calculation.

For example, matrix A is nStates x nStates in size, so variable 1 represents row 1/column 1 of A.

Similarly, matrix D is nOutputs x nInputs, with the indices of the input variables mapping to the columns of D, and the outputs map to the rows.

Matrix G is nOutputs x nInputs


The following diagram shows the complete mapping:

States Inputs

States A B

Outputs C D

11 Estimation 328

11 Estimation

Estimation is used when you need to fit a model to a set of experimental or actual process data. You can use estimation for both steady-state and dynamic simulations. The model is fitted by finding the appropriate values for the estimated parameters. A special run class is provided with the Aspen Modeler product to allow the estimation of adjustable parameters.

The elements of an estimation simulation are:

• Blocks and streams, as in other run types.

• Experimental data, which you define using the Estimation tool or scripting.

• Regressed parameters (variables), which are selected using the Estimation tool or scripting.

Two different estimation methods are available:

• Weighted least squares minimization.

• Maximum log likelihood.

Mathematical Statement of Flowsheet Equations The mathematical statement of the flowsheet equations in Aspen Modeler products is:

f x x y u( , &, , , )θ = 0 (1)

g x y u( , , , )θ = 0 (2)

consisting of n differential equations f and m algebraic equations g.

The variables are partitioned as:

x t Rn( ) ∈ Differential variables

&( )x t Rn∈ Time derivatives of differential variables

y t Rm( ) ∈ Algebraic variables

u t R( ) ∈ λ Input variables

11 Estimation 329

θ ρ∈R Input variables to be estimated

It should be noted that, for purely steady-state problems, n=0.

About Experimental Data A dynamic experiment is defined by specifying the time variation of the input variables u (t) and a consistent initial condition for the given mathematical model. At various times t>0 during the experiment, measurements (or observed values) are taken of a subset z of x and/or y. Note that the variables being measured are not necessarily the same for different times t.

Let the total number of dynamic experiments be Ndyn; the dimension of z, that is, the number of unique variables z(j), of x or y which have been measured over all the experiments be Nmeas; and the number of measurements of z(j) in experiment i be Mij.

Mij may be zero if variable j is not measured at all in experiment i.

$zijk denotes the kth measurement of variable z(j) in experiment i. It is a

measurement of z j at time

t ijk .

A steady-state experiment is simply a special case of the a dynamic

experiment, with inputs u = constant, for all t≥ 0 and the initial conditions &x =

0. They involve a single measurement only of a subset z of variables x and/or y. Let NSS be the total number of steady-state experiments.

$zij denotes the measurement of variable z(j) in steady-state experiment i.

About Parameter Estimation Methods You can use two methods to solve estimation simulations:

• Weighted least squares minimization.

• Maximum log likelihood.

The choice of which method is appropriate to solve a particular estimation problem depends on the errors in the measurements. The two methods are equivalent in a situation when:

• The estimated variables are normally distributed.

• The errors in the observed values of the measured variables are independent from observation to observation.

• The errors are independent from one measured variable to the next measured variable.

This situation is not common and it is usually not possible even to know if or when the above criteria are satisfied. Hence, an appropriate choice of method

11 Estimation 330

must be made. If you have some idea of the error in the measurements, then the Weighted Least Squares method is appropriate, otherwise the Maximum Log Likelihood method is preferred.

For more information on the two methods available for solving a parameter estimation problem, see the Solver Options Reference.

About Least Squares Parameter Estimation The Least Squares method minimizes the weighted absolute squared error between the observed and predicted values of the measurements. You should set the weights of the measured variables to be the reciprocal of the standard error (if they are known) of the observations.

Given the process model and the experimental measurements, using the least squares method to solve your parameter estimation problem determines the

values of the parameters θ which solve the following minimization problem:

( )( ) ( )Min W z t z w z zijkk

Mij

j

NMeas

j ijk ikji

NDyn

ij ij ijj

NMeas

i

NSS2

111

2

2 2

11=== ==∑∑∑ ∑∑−

+ −

$

θ

subject to:

θ θ θL U≤ ≤

where ( )z tj ijk are calculated (or predicted) by solving the model equations (1)

and (2) with the inputs u and initial conditions corresponding to dynamic experiment i.

The weights Wijk and

Wij (the product of experiment and measurement weights) are user-specified and reflect the importance of, or confidence in, the corresponding experimental measurement.

The lower and upper bounds θL and θ

U serve to keep the parameters within

physically realistic and/or mathematically acceptable limits.

About Log Likelihood Estimation The Maximum Log Likelihood method maximizes the log of the likelihood function of the predicted and observed values. When the log of the likelihood function (and hence the likelihood function itself since log is a monotonically increasing function) is maximized, the probability of obtaining the given set of measurements from the estimated variables is maximized. This corresponds to getting the best fit of your measurements.

11 Estimation 331

The likelihood function used takes into account the standard error of the observations by using a heteroscedasticity parameter for each unique measured variable.

The heteroscedasticity parameter has range 0 to 2:

• 0 corresponds to the error in the measurements being independent of the values of the measurements (constant absolute error).

• 2 corresponds to the error in the measurements being proportional to the values of the measurements (constant relative error).

You can fix the value of the heteroscedasticity parameters (if you know suitable values for them) or ask the method to compute them automatically during maximization of the log likelihood function. This method is particularly useful if you have no idea of the errors in the measurements.

Given the process model and the experimental measurements, using the maximum log likelihood method to solve your parameter estimation problem

seeks to determine the values of the parameters θ (and optionally the

heteroscedasticity parameters γ

of your measurements) to solve the following minimization problem:

( )max,

log log$ ( )

θ γπ

γ

12

2 11

2

11

2

i

NMeas

i i i jijk ijk

ijki

k

Mij

j

NDyn

n n n wz z t

z= ==∑ ∑∑

+ +−

+

( ) ( ) ( )γ π

γi jk

Mij

j

NDyn

ijk i ii

NMeas

i jij ij

iji

j

NSS

w z t n n n wz z

zlog $ log log

$

$== = =∑∑ ∑ ∑

+ + +

−

11 1

2

2

1

12

2 1

+

=

∑γ i j ijj

NSS

w zlog $

1

subject to θ θ θL U≤ ≤ , and where:

γ i = The heteroscedasticity parameter for measured variable z(i)

w j = The weight of experiment j

Note: When the heteroscedasticity is not fixed, the Automation Method AddSSMeasurepoint resets the heteroscedasticity parameter to 1.

12 Using the Simulation Access eXtensions 332

12 Using the Simulation Access eXtensions

The Simulation Access eXtensions (SAX) enable you to control a simulation while it is running, and to access solution data using a programmatic interface. You can use Simulation Access eXtensions in all run modes for a variety of applications, for example, for operator training or online optimization.

To use SAX, you must create a DLL containing a function written in C or C++ with a defined prototype. You register the DLL and function names in the Simulation Access eXtensions dialog box. The function will then be called when specified events occur during a run, for example, at the start of a run, or after a step in a dynamic run. The Simulation Access eXtensions dialog box also enables you to control which events are used, as well as list the variables which are passed as arguments to your function.

Utility functions are also supplied, to enable you to manipulate or retrieve data for these variables within your function.

To use Simulation Access eXtensions, you need to:

1 Write a function for a DLL that will be loaded at run time.

2 Open a simulation.

3 Optionally add variables to the list of input and output variables that are operated on by the function. Pointers to these variables will be passed to your function.

4 Specify the name of the DLL and the function to be called when a specified event occurs during simulation.

5 Make sure that Simulation Access eXtensions are switched on.

6 Run the simulation.

While the simulation is running, your function will be called when the specified events take place. This enables you to modify or get variable values, or add control to the simulation. A number of access functions are available for use within your function.

Caution: Make sure you do not change key variables with SAX while you are performing an estimation, homotopy, or optimization run.


Writing a DLL Function for the Simulation Access eXtension Your Simulation Access eXtensions DLL should contain a function of the following form:

DLL_C_AS_C(int) SAXFunctionName (SAX_EventToken Event, const double Time, const int NoInputs, const SAX_ExternalId *InVariableList, const int NoOutputs, const SAX_ExternalId *OutVariableList, void *pSimulationManager)

SAXFunctionName The name you give to the function

const SAX_EventToken Event

Token giving the type of event which caused this function to be called

const double Time The current simulation time

const int NoInputs The number of variables set up as input variables

const SAX_ExternalID *InVariableList

Array of SAX_ExternalID variable identifiers, one for each variable set up as an input. The array length is NoInputs. You can use variables from the list in variable accessing functions.

const int NoOutputs The number of variables set up as output variables

const SAX_ExternalID *OutVariableList

Array of SAX_ExternalID variable identifiers, one for each variable set up as an output. The array length is NoOutputs. You can use variables from the list in variable accessing functions.

void *pSimulationManager

Pointer to the Simulation Manager object to be used in setting up events

DLL_C_AS_C(int) The return value type is int. The macro DLL_C_AS_C ensures the function is exported from the DLL and has the correct calling convention.

Tips:

• Ensure that the file sax_support.h is included in your function to give you access to the enumeration values. Include this file in your code as follows: #include "sax_support.h"

• Aspen Custom Modeler users can use an example makefile called MakePhconSax as a template for linking DLLs. If you have installed in the default location, this file can be found in:

C:\Program Files\AspenTech\Aspen Custom Modeler 12.1\Examples\Sax\

Using Variable Accessing Functions Variable accessing functions can be used to assign or inquire an attribute value for the variable, for example:


SAX_InquireRealAttribute(OutVariableList[i], SAX_VAR_VALUE, &doublevalue);

This call will get the value of the ith variable in the output variable list. This assumes that the variable is of type double precision. You can inquire the type using the following call:

SAX_InquireIntAttribute(OutVariableList[i], SAX_VAR_TYPE, &intvalue);

The intvalue is an enumeration of the variable type (SAX_INT, SAX_DBL or SAX_STR). You can then use this to select the correct function to assign or inquire the variable value.

If you want to get at a variable which is not in either list, you can get the variable identifier from the variable path, for example:

SAX_GetVariable("B1.TEMPERATURE",id);

Using Return Codes You can use the return code from your function to control the simulation. Set the return code to one of the values listed in this section. This value will normally be SAX_CONTINUE. The effect of these codes depends on the run mode.

Using Return Codes on Steady-State and Initialization Runs

The return codes have the following effects:

Return Code Result

SAX_CONTINUE A single run takes place

SAX_RUN_AGAIN� Another steady-state or initialization run will be carried out

SAX_RUN_COMPLETE No more events are generated

SAX_ABORT_RUN The current solution is aborted and the run is terminated.

� Returned from the SAX_AFTER_SS_RUN or SAX_AFTER_INI_RUN events.

Notes: • When the SAX_ERROR_EVENT is triggered you can return

either of the following: − SAX_CONTINUE, which causes the run to terminate. − SAX_RUN_AGAIN, which repeats the run.

• Use the SAX_WAITING return code when your function is waiting for interactions with external programs or user input. Ensure your function returns this code rather than waiting for the interaction or input operation to complete. Your function will be called again with the same event code when you can check for completion.


Using Return Codes for Dynamic Runs

The return codes have the following effects:

Return Code Result

SAX_CONTINUE The dynamic run keeps going

SAX_RUN_COMPLETE Causes the run to pause

SAX_REINITIALIZE Forces a reinitialization before the next dynamic step. (for the Gear solver only)

SAX_ABORT_RUN The current run is terminated

Notes:

• When the SAX_ERROR_EVENT is triggered you can return either of the following: − SAX_CONTINUE, which causes the run to terminate. − SAX_RUN_AGAIN, which repeats the step.

• Use the SAX_WAITING return code when your function is waiting for interactions with external programs or user input. Ensure your function returns this code rather than waiting for the interaction or input operation to complete. Your function will be called again with the same event code when you can check for completion.

Events in Simulation Access eXtensions When a particular event occurs in the simulation, your SAX function will be called if you have requested this. The type of event that occurs depends on the run mode.

Events in All Run Modes

The following events occur in all run modes. Note that these events cannot be controlled from the Simulation Access eXtensions dialog box.

Event Occurs

SAX_START_OF_SIMULATION When you open an existing simulation or start a new one

SAX_END_OF_SIMULATION When you exit the application or unload a loaded simulation

SAX_ERROR_EVENT On any solution failure. This event cannot be switched off.

Events in Steady-State Runs

The following events occur in steady-state runs.

Event Occurs


SAX_NEW_RUN At the start of a new run, that is, each time the Run button is clicked. Note that this event cannot be controlled from the Simulation Access eXtensions dialog box.

SAX_BEFORE_SS_RUN Before the run and when the Before Run check box is selected in the Simulation Access eXtensions dialog box

SAX_AFTER_SS_RUN On successful completion of the run and when the After Run check box is selected in the Simulation Access eXtensions dialog box

Events in Initialization Runs

The following events occur in initialization runs.

Event Occurs

SAX_NEW_RUN At the start of a new run, that is, each time the Run button is clicked. Note that this event cannot be controlled from the Simulation Access eXtensions dialog box.

SAX_BEFORE_INI_RUN Before the run and when the Before Run check box is selected in the Simulation Access eXtensions dialog box

SAX_AFTER_INI_RUN On successful completion of the run and when the After Run check box is selected in the Simulation Access eXtensions dialog box

Events in Dynamic Runs

The following events occur in dynamic runs:

Event Occurs

SAX_NEW_RUN At the start of a new run, that is, when the Run button is clicked, having either just changed run mode to dynamic or just loaded a simulation with dynamic run mode as the default. Note that this event cannot be controlled from the Simulation Access eXtensions dialog box.

Note: Rewind, Restart and Reset do NOT cause this event. Having started a dynamic run, you can only cause this event again by triggering it for a different run mode or by editing the simulation. Simply changing the run mode and back again is not sufficient.

SAX_BEFORE_DYN_STEP SAX_AFTER_DYN_STEP

Before or after an integration step and when the Before Step or After Step check box is selected in the Simulation Access eXtensions dialog box. This step is controlled by the communication interval set in the Run Options dialog box. You can also request these events using the SAX_ScheduleTimeEvent function.

SAX_BEFORE_INI_STEP and SAX_AFTER_INI_STEP

Before and after the initialization at time 0, and when the Before Initialization or After Initialization check box is selected in


the Simulation Access eXtensions dialog box. For dynamic solvers that do a reinitialization (currently Gear only) these events will also happen on reinitialization. You can also request these events using the SAX_ScheduleTimeEvent function.

The full sequence of events for a dynamic run is:

1 SAX_NEW_RUN

2 SAX_BEFORE_INI_STEP

3 Dynamic initialization carried out.

4 SAX_AFTER_INI_STEP

5 SAX_BEFORE_DYN_STEP

6 Integrate first step.

7 SAX_AFTER_DYN_STEP

If you require events to occur at times other than the step controlled by the communication interval, you can request a timed event, for example:

SAX_ScheduleTimeEvent(pSimulationManager, 0, 5.67)

This causes the SAX_AFTER_DYN_STEP and SAX_BEFORE_DYN_STEP events to occur at the time requested if the given time is after the current time. If not, the request is ignored.

Controlling the Simulation Access eXtensions To open the Simulation Access eXtensions dialog box:

• From the Tools menu, click Simulation Access eXtensions.

This dialog box enables you to specify the following information:

• Input and output variables that will be provided to your interface function.

• The name of the DLL and function in the DLL to be called.

• The simulation events on which the function will be called.

Specifying the Simulation Access eXtensions Input and Output Variables To specify the input and output variables that are to be operated on by the Simulation Access eXtensions function:

1 From the Tools menu, click Simulation Access eXtensions.

2 To add variable names to the Input Variables and Output Variables list boxes, click the relevant tab and then do one of the following:

− Type a variable name in the text box at the bottom of the dialog box and then click the Add button.

− Drag and drop variable names from forms.


− Drag and drop variable names from Variable Find.

Notes:

• You can also use pattern matching to add variables to the list.

• You can rename variables by double-clicking the variable name in the Tag column.

• Tag names do not have to be unique within the simulation.

Specifying the DLL and Function Name for the Simulation Access eXtensions After the DLL has been generated, and you have specified the variables, you can specify the DLL and the name of the function to be called. To do this:

1 In the Simulation Access eXtensions dialog box, click the Procedure tab.

2 In the Function name box, type the name of the function that is to be called.

3 In the Library name box, type the stub name of the DLL which contains your function.

4 In the Events area, select the event(s) which will trigger the function.

5 Make sure the Enable Access eXtensions check box is selected.

6 When you have finished setting up the Simulation Access eXtensions, click Close.

Additional Simulation Access eXtensions Functions This section lists the functions you can use to add functionality to the Simulation Access eXtensions. Most of these functions return an ACMStatus value to show success or failure of the function. Use the code SAX_ERR_Success, or SAX_ERR_Failure when testing the returned value.

Displaying Diagnostic Messages

The following function displays diagnostic messages. For more information, see the Library Reference, Chapter 3.

ACM_Print (....)


Accessing Options Parameters

The following function enables your routines to access the values of Options parameters. For more information, see the Library Reference.

ACM_Rqst(....)

Setting the Value of an Attribute

The following function sets the value of a real attribute of a variable:

ACMStatus SAX_AssignRealAttribute (const SAX_ExternalId id, const SAX_Attribute_Token token, const double Attrib_Value)

const SAX_ExternalId id Variable identifier

const SAX_Attribute_Token token

Integer token identifying the attribute to which the value will be assigned. For information on attribute tokens, see Simulation Access eXtensions Attribute Tokens.

const double Attrib_Value Double value to be assigned

Note: If you change a variable bound such that the current value is outside the new bound, the current value will be reset to the bound. Also any attempt to invert the bounds (that is, if the upper bound is lower than the lower bound), will be rejected.

The following function sets the value of an attribute from an integer value:

ACMStatus SAX_AssignIntAttribute (const SAX_ExternalId id, const SAX_Attribute_Token token, const int Attrib_Value)




const int Attrib_Value Integer value to be assigned

The following function sets the value of an attribute from a character string:

ACMStatus SAX_AssignStringAttribute (const SAX_ExternalId id, const SAX_Attribute_Token token, const char *Attrib_Value)




const char* attrib_value Character value to be assigned


Querying the Value of an Attribute

The following function queries the value of a variable's attribute and returns its value as a real.

ACMStatus SAX_InquireRealAttribute(const SAX_ExternalId id,const SAX_Attribute_Token token , double *Attrib_Value)

const SAX_ExternalId id

Variable identifier

const Attribute_Token token


double *Attrib_Value Double value returned

The following function queries the value of a variable's attribute and returns its value as an integer:

ACMStatus SAX_InquireIntAttribute(const SAX_ExternalId id,const SAX_Attribute_Token token , int*Attrib_Value)


const SAX_Attribute_Token token Integer token identifying the attribute to which the value will be assigned. For information on attribute tokens, see Simulation Access eXtensions Attribute Tokens.

int * Attrib_Value Integer value returned

The following function queries the value of a variable's attribute and returns its value as a string:

ACMStatus SAX_InquireStringAttribute(const SAX_ExternalId id,const SAX_Attribute_Token token , char **Attrib_Value)


const Atribute_Token token Integer token identifying the attribute to which the value will be assigned. For information on attribute tokens, see Simulation Access eXtensions Attribute Tokens.

char ** Attrib_Value Character value returned

Converting a Path Name

The following function converts a full path name to a variable identifier:

ACMStatus SAX_GetVariable(char*const Variable_Name, SAX_ExternalId *VarId)

char*const Variable_Name Name of the variable to be

located


SAX_ExternalId *Var_Id Returned variable identifier for named variable

Note: This function can find only variables or parameters that are active in the simulation, that is, variables or parameters that appear in equations, procedure calls, or run-time conditional expressions.

Scheduling an Event

The following function schedules an event which will cause this function to be called:

ACMStatus SAX_ScheduleTimeEvent(void *pSimulationManager, const int EventType, const double Time)

void * p SimulationManager

Handle to Simulation Manager

const int Event Type Type of event to be scheduled. Default is 0, meaning reporting time is 0.

const double time Time at which event will occur

Simulation Access eXtensions Attribute Tokens Use these tokens in functions where variable attribute information is to be set or received. These tokens are available as symbols from the header file sax_support.h:

Token Symbol Attribute

Description Type Returned

SAX_VAR_NAME (Read only)

Variable Name string

SAX_VAR_VALUE Variable Value double, int or string (Use SAX_VAR_TYPE to find out which)

SAX_VAR_LOWER Variable Lower bound double or int

SAX_VAR_UPPER Variable Upper bound double or int

SAX_VAR_TYPE (Read only) Variable type Integer (one of SAX_INT, SAX_DBL or SAX_STR)

SAX_VAR_TAG (Read only) Variable tag String

SAX_VAR_SPEC (Read only) Variable specification Integer (One of SAX_SPEC_FREE, SAX_ SPEC_FIXED, SAX_ SPEC_INITIAL, SAX_ SPEC_RATEINITIAL) *

SAX_VAR_LLAGR (Read only)

Variable Lagrange Lower Bound (not defined for all variables)

Double


SAX_VAR_ULAGR (Read only)

Variable Lagrange Upper Bound (not defined for all variables)

Double

13 Using Online Links (OLL) 343

13 Using Online Links (OLL)

The Online Links (OLL) facility allows the simulator to access the data provided by an online data server, using one of the published standard interfaces. An interface DLL is loaded by the simulator and communicates with the data server when required.

OLL uses many of the facilities of the Simulation Access eXtensions (SAX), but is independent of SAX. OLL and SAX can be used simultaneously.

Aspen Engineering Suite� supports communication with data servers that conform to the OLE for Process Control (OPC) standard 1.0A, published by the OPC Foundation, dated September 11, 1997. Detailed information about this standard can be obtained from the OPC Foundation web site at:

http://www.opcfoundation.org

The Online Links dialog box enables you to specify:

• The OPC data server you wish to connect to.

• How you want to communicate with the OPC data server.

• At what points to communicate with the OPC data server during the simulation.

• Which data you wish to read from, or write to, the OPC data server.

To use OLL, you need to:

1 Install the data server on a machine accessible to the simulator.

2 Specify the server and its configuration data.

3 Specify the links between the simulator and the data server.

4 Run the simulation.

The OLL interface is affected by the Solver Reporting Level. Messages from the interface appear in the Simulation Messages window, and changing the Solver Reporting Level will increase or decrease the number of messages.

Installing the Data Server for OLL For the simulator to access the data server, the data server must be registered on the same machine as the simulator. Usually, this means that the data server is installed on the same machine as well, but it is possible to


install a data server on one machine and run it from another. For information on how to do this, see the documentation on the data server.

If you have more than one data server and you wish to be able to browse for them from the OLL dialog, or if your data server(s) support an interface that allows for browsing of its data tags, you will need to ensure that your data server(s) are correctly registered on the same machine as the simulation client. If the simulation client and simulation server are running on different machines, this means that the data server(s) will be registered on more than one machine.

Specifying the Data Server Configuration for OLL To specify the data server configuration:

1 From the Tools menu, click Online Links. The Online Links dialog box is displayed, showing the Configuration tab. All the fields on this tab are set to their defaults, and the Server Name field is blank.

2 In the Server Name box, type or click Browse to select the name of the data server you want to use. Note that if one or more data servers are registered on your computer, the browser presents a list of available data servers that support the requested protocol. To select a server, click the ID field of the required server and then click OK.

3 For IO Timing, select one of the options:

Option Description

Synchronous The OLL interface will wait for IO operations to complete

Asynchronous A call-back is specified

Note: Data servers must support either Synchronous or Asynchronous operation, but need not support both. You cannot use both options simultaneously.

4 Select whether the Reading Mode should be CACHED or DEVICE. Your choice depends upon your data server.

Note: The OPC standard expects that synchronous reads should be CACHED, while asynchronous reads should be DEVICE. Some data servers may not support all four possible combinations. If you specify a Timing method and Reading Mode combination that is not supported by your server, OLL will fail to exchange data. If you use Asynchronous operation, you may need to perform reads before a dynamic step rather than after, particularly if the time


taken by the step is of the same order as the time taken for the data server to respond to the request. Make sure you select the combination of IO timing and Reading mode that works best with your simulation.

5 In the Bounds Handling box, you can change the action the OLL interface must take when the value supplied by the data server lies outside the bounds of the simulation variable specified for the link. The values are:

Value Description

CLIP Default value. The value is clipped to the nearest variable bound. A warning message is written to the Simulation Messages window.

USELAST The value is replaced by the last valid value for the link supplied by the interface. A warning message is written to the Simulation Messages window.

PAUSE The run is paused and a message appears informing you of this.

6 In the Quality Handling box, you can change the action the OLL interface must take when the QUALITY of a data item is anything other than GOOD. The values are:

Value Description

USELAST Default value. The value is replaced by the last valid value for the link supplied by the interface. A warning message is written to the Simulation Messages window.

OVERRIDE The value is replaced by the OVERRIDE value specified for the link. A warning message is written to the Simulation Messages window.

PAUSE The run is paused and a dialog is issued to that effect.

Note: The OLL value field of a data item that does not have GOOD quality is displayed in red. GOOD data is displayed in black.

7 In the Update Period box, you can specify a period in milliseconds between updates of the values read from the data server. The default period of 1000ms (1 per second) is suitable for most small to medium sized problems; for larger simulations, you may need to increase the value. The data server may adjust the value you specify to the nearest available value. For example, if you specify an update period of 100ms for an item connected to a sensor that has a response time of 110 ms, the data server may change the specified value to 110 ms (this change will not be reflected on the configuration pane). The update period is not meaningful to some servers when reading synchronously. When reading asynchronously, the data will continue to be sent from the data server even when the simulation run is paused. This will be reflected in the OLL value fields of inputs being continuously updated.


Note: Do not to specify an update period that is too short, otherwise the simulator may spend more time handling the updates than in solving your simulation. The default period of 1000ms (1 per second) is suitable for most small to medium sized problems; for larger simulations, you may need to increase the value.

8 In the Events list, you can change when to interact with the data server. To enable interaction at a given point, select the appropriate box: the boxes headed In are for the interaction points for input variables, and the boxes headed Out are for interaction points for the output variables. To disable an interaction, clear the box.

The events specified by default are:

To At these events And these events

Read inputs Before steady-state and initialization runs

After dynamic initialization steps and dynamic steps

Write outputs After steady-state or initialization runs

After dynamic initialization steps or dynamic steps

Note: OLL does not distinguish between the first initialization step of a dynamic run, and any subsequent re-initializations triggered by discontinuities. Re-initializations only occur when using a locating integrator, such as GEAR.

9 In the Enable box, you can change OLL interactions globally:

Option Description

OFF Default value. No interactions will take place (and no attempt will be made to load the OLL interface or to communicate with the data server when a new run starts).

READONLY Values will be read from the data server to the input variables. Values will not be sent to the OLL data server from the output variables.

ON Reading and writing are both enabled.

Specifying the Links between the Simulator and the OLL Data Server In the Online Links dialog box, you can specify the Input links for which the OLL data server will send values to the simulator, and the Output links for which the data from the simulator will be written to the OLL data server:


When specifying these variables, remember the following rules:

• The variables specified on the Input tab must all be Fixed variables, and should not normally be manipulated by any other means (tasks, scripts, SAX, etc). It is not necessary for Output variables to be Fixed.

• Each Simulation Variable/OLL tag combination must appear only once on a tab. The combination may be repeated on the other tab.

• Each destination (that is, the Simulation Variable on the input tab, or the OLL tag on the output tab) must appear only once on a tab.

Notes:

• These rules are not enforced by the interface, as there are situations when they may safely be ignored.

• The table can be sorted by clicking on one of the column headings.

• The scroll bar at the foot of the tabs does not affect the first two columns (the Simulation Variable name and Simulation Value).

To specify the links on the Input and Output Variables tabs:

1 From the Tools menu, click Online Links and then click the Input Variables tab or the Output Variables tab.

2 Make sure that the Simulation Variable field contains the name of the simulation variable involved in the link, and that it is valid. If it is valid, a green check mark is displayed to the right of the row, but if it is not valid (for example, if it is in a block that has been deleted, a red cross is displayed.

For more information, see Adding New Links for OLL and Changing the Simulation Variable in an OLL Link.

3 In the OLL Tag box, type or select the name of the data item in the OLL data server.

Note: The name must conform to the syntax expected by the data server: remember that some data servers are case-sensitive. The tag is not validated until the data server is connected to the simulation server, at the start of the first run.

4 In the Mode box, select whether links are enabled or disabled:

Value Description

Auto The link operates normally.

Manual The simulation value is replaced by the Override value.

5 In the Override Value box, specify the value to be used for the simulation value when the link�s mode is Manual, or when the Quality Handling is set


to OVERRIDE and the quality of an input item is not GOOD. The value is displayed in simulation units.

6 In the Bias box, you can specify an offset to be added to a written value (input), or subtracted from a read value (input) during the exchange of data. Gain is applied before bias on a write, and after on a read, so that:

OLL value = (Simulation value) * Gain + Bias

7 In the Gain box, you can specify a factor that is used to multiply a written value or divide a read value during the exchange of data. Gain is applied before Bias on a write, and after on a read, so that:

OLL value = (Simulation value) * Gain + Bias

8 For output variables only, you can use the Noise Std Dev box to simulate the effect of measurement noise. When non-zero, it is the standard deviation of a random number with a Gaussian distribution about zero, which is added to the value before being written to the data server. Noise is applied during dynamic runs only, after any bias and gain.

9 In the Change Tolerance box, you can change the absolute tolerance used to minimize traffic between the simulator and the data server. If the simulation value differs from the previous simulation value by less than the tolerance, the data is not exchanged. The change tolerance test is only applied during dynamic runs. The default Change Tolerance value is 1E-5.

10 In the Conversion Units box, specify the units of measurement of the values in the data server. For example, the data server may return the value from a temperature sensor in degrees Celsius, and this value will need conversion after reading or before writing. The list of units of measurement provided is the same as the list for the simulation variable in the link, and thus this field is only useful if the simulation variable is of the appropriate type. If the simulation variable does not have units of measurement, you cannot set the Conversion Units field.

If the units of the data server are arbitrary, or are not available in the list, the you can use the Bias and Gain fields to do the necessary conversions.

Adding New Links for OLL To add Input links (for which the OLL data server will send values to the simulator), and the Output links (for which the data from the simulator will be written to the OLL data server):


2 In the Variable box at the bottom of the tab, type the full name of a simulation variable, and the click Add. A new row is created in the table, with a blank tag name. It is marked by a red cross to the left of the row until a tag name has been entered and validated.

� or �


Add links by selecting a simulation variable from a form or from Variable Find, and drag them to the appropriate tab.

3 In the OLL Tag field, either type the full tag name, or click the Browse for Tags button to locate the tag. When the row has a valid simulation variable and a valid OLL tag, it will be marked by a green check mark on the far left of the row.

Note: The tags are not validated until the data server is connected to the simulation server, at the start of the first run.

Removing OLL Links To remove an OLL link:


2 In the Variable box at the bottom of the tab, click the link and then click Remove. The table row is deleted.

Changing the Simulation Variable in an OLL Link To change the simulation variable in an OLL link:


2 In the Variable box at the bottom of the tab, select the appropriate table row, and then click the Edit Variable button. You can then edit the name of the variable. This name is validated when press ENTER.

Browsing for OLL Tags If your data server supports browsing for tags, and is accessible from your simulation client machine, you can browse the data server for tags. To do this:


2 Next to the OLL Tag box, click the Browse for Tags button. The Tag Browser is displayed.

The tag browser has two panes: the left one is the OLL data for the currently visible tag, and the right one is the list of tags available in the data server.

3 To connect a data server tag to a given simulation variable, click the simulation variable in the left pane, then click the required tag in the right pane, and then click the central arrow button.


When the browser is closed, the links you have specified will be established.

14 Using External Solvers 351

14 Using External Solvers

Aspen Custom Modeler® allows external, non-linear algebraic equation solvers to be plugged in and used in the solution of simulations. There are two types:

• Non-linear algebraic (NLA) equation solvers.

• Non-linear programming (NLP) optimization solvers.

To Aspen Custom Modeler, an external solver is a software component that implements a number of defined interfaces. These interfaces allow Aspen Custom Modeler to load the solver, set options and to drive the solution. To the external solver, Aspen Custom Modeler presents an interface that allows access to the system of equations and/or optimization problem to be solved. The set of interfaces that allow Aspen Custom Modeler to use a solver component are called the AspenTech Open Solver (AOS) interfaces.

For further details of these interfaces, refer to the Aspen Open Solvers User�s Guide, or the Aspen Open Solvers on-line help.

15 Exporting Flowsheets to Aspen Plus 352

15 Exporting Flowsheets to Aspen Plus

Flowsheets written in Aspen Modeler products using the Modeling Language can be used as custom blocks in Aspen Plus® simulations. This means you can:

• Describe proprietary reactors or units for which there is no Aspen Plus model.

• Customize Aspen Dynamics� models to provide variations on existing Aspen Plus models.

Export a flowsheet and use it in Aspen Plus by:

1 Checking you have the necessary software.

2 In your Aspen Modeler product, preparing a flowsheet for export.

3 Generating a dynamic link library (DLL) and an Aspen Plus User Model Library (.apm) file by exporting the flowsheet.

4 In Aspen Plus, reference the new library and select the new unit operation from the Aspen Plus Model Library. You can now use the unit like any other Aspen Plus unit operation.

Software and Hardware Requirements To export a flowsheet from an Aspen Modeler product:

• You must have a C++ compiler�Microsoft® Visual C++ Studio Net is recommended for exporting flowsheets on machines running Microsoft Windows. Your C++ compiler must be configured so that it can be used from the command line.

Note: The C++ compiler is only needed to create the DLL from the Aspen Modeler flowsheet. A DLL can be used in Aspen Plus without having a C++ compiler.

An Aspen Modeler flowsheet running within Aspen Plus requires an Aspen Custom Modeler licence.

16 Preparing an Aspen Modeler Flowsheet for Export 353

16 Preparing an Aspen Modeler Flowsheet for Export

Any Aspen Modeler flowsheet can be exported but a flowsheet must meet some basic requirements if it is to be used successfully in Aspen Plus®. This is because Aspen Plus blocks use certain conventions, for example, they always calculate outputs from inputs, and they must have ports which are compatible with Aspen Plus streams.

Note: It is currently only possible to connect exported Aspen Modeler flowsheets to Aspen Plus streams which have a single mixed sub-stream. You cannot connect exported Aspen Modeler flowsheets to polymer streams, streams containing solids or streams with multiple sub-streams.

This chapter contains information on the following topics:

• Preparing an Aspen Modeler flowsheet for export.

• Exporting the flowsheet.

Preparing a Flowsheet for Export In order to use an Aspen Modeler flowsheet as a custom block in Aspen Plus®, you should ensure that:

• The flowsheet is square.

• The flowsheet has a rating specification.

• The flowsheet contains ports for connecting to Aspen Plus material streams.

• The flowsheet solves in steady-state mode.

Notes:

Note the following restrictions when preparing flowsheets for export:


• If your Aspen Modeler flowsheet uses tearing to influence the order of equations in a decomposition, it may not solve in Aspen Plus. Aspen Plus solvers do not use decomposition to divide the equations into smaller groups of related equations. This means that Aspen Plus solves the equations in the order presented, not in the order produced by the Aspen Modeler decomposition algorithm.

• Do not use the ChangesInputs procedure qualifier in a flowsheet that you want to export. This qualifier allows a procedure equation to change the value of an input variable during solution. The Aspen Plus solvers do not support this functionality.

Making the Flowsheet Square Any Aspen Modeler flowsheet that you want to export to Aspen Plus® must be square.

This is because the solvers used within Aspen Plus can only work with a system of equations that is square. If an Aspen Modeler flowsheet that is not square is exported, then Aspen Plus will not be able to load it during a simulation.

It is possible to change the specification of variables in the exported flowsheet from Aspen Plus. For more information on this, see Exporting Flowsheets to Aspen Plus.

Ensuring the Flowsheet has a Rating Specification Any Aspen Modeler flowsheet that you want to export to Aspen Plus® must have a rating specification.

This means that input (or feed) variables are all fixed and output (or product) variables are all free. This is necessary because an Aspen Plus block uses input stream values to calculate output stream values.

It is possible to export a flowsheet which does not have a rating specification and it is possible to use it in Aspen Plus but this is not recommended as Aspen Plus will not give you a reliable solution.

Using Aspen Dynamics Pressure-Driven Flowsheets

Aspen Dynamics� pressure-driven flowsheets do not have a rating specification. This means that before you can export and use them as Aspen Plus blocks, you must first modify their specification to ensure that all inlet stream variables are fixed.

Aspen Dynamics� flow-driven simulations do have a rating specification so they can be exported without modifying their specification.


Defining Ports for Connecting to Aspen Plus Material Streams To connect an exported flowsheet to Aspen Plus® streams, the flowsheet must define input and output ports. These ports must contain particular variables so that, when the flowsheet has been exported and is running in Aspen Plus:

• Aspen Plus input stream data in SI units can be copied to the input port variables.

• Aspen Plus output stream data can be copied from the output port variables in SI units.

Aspen Modeler identifies the ports to export by searching the flowsheet for unconnected ports containing a parameter called ExportAs. The ExportAs parameter has two purposes:

• To identify ports for export.

• To describe how the port should be exported.

The value of the ExportAs parameter tells Aspen Modeler how to represent the port in the code generated during export. Currently, only one value is supported: �MoleFractionPort�. This value means that the port has the properties needed to connect to an Aspen Plus material stream. The direction of the port determines whether Aspen Plus treats the port as an inlet or an outlet.

MoleFractionPort_SI Definition

The Modeler library contains the definition of a port type called MoleFractionPort_SI, which Aspen Modeler will export as a port suitable for connection to Aspen Plus streams:

Port MoleFractionPort_SI

Description: "A port that conforms to the requirements of a mole fraction port in AspenPlus";

ExportAs as ExportParam("MoleFractionPort");

F as notype (Description:"Molar flow rate");

T as notype (Description:"Temperature");

P as notype (Description:"Pressure");

h as notype (Description:"Molar enthalpy");

V as notype (Description:"Molar volume");

z(componentlist) as notype (Description:"Mole fractions");

End

Note: All the variables are of type notype. This is because the values of these variables are in SI units rather than Aspen Modeler units. Using notype means that Aspen Modeler will not


attempt to convert the values of the variables.

Typically an Aspen Modeler flowsheet will not contain any ports of type MoleFractionPort_SI; if you export such a flowsheet you will not be able to use it in Aspen Plus. Exportable ports are added to a flowsheet by adding blocks that contain ports of type MoleFractionPort_SI.

Every port that is exported can be connected to an Aspen Plus material stream when the simulation is used as a unit operation in Aspen Plus. The name of the block that owns the exported port is used as the port name in Aspen Plus. So a port called WaterFeed.Export in an Aspen Modeler simulation will be called WaterFeed in Aspen Plus. Similarly, a port called DrawOff.Export in Aspen Modeler will be called DrawOff in Aspen Plus.

APlusFeed and APlusProduct Definitions

The Modeler.acml library includes models, called APlusFeed and APlusProduct, that contain ports of type MoleFractionPort_SI. These are the definitions used for the APlusFeed model type:

Model APlusFeed

Description: "Maps a MoleFractionPort_SI to a MoleFractionPort";

Export as input MoleFractionPort_SI;

Feed as output MoleFractionPort;

dummy as hidden notype;

// Fix the Export conditions

Export.F: fixed;

Export.T: fixed;

Export.P: fixed;

Export.h: fixed;

Export.V: fixed;

Export.z: fixed;

// Convert inlet values from SI to Metric...

Export.F * 3600.0 = Feed.F;

Export.T - 273.15 = Feed.T;

Export.P * 1e-5 = Feed.P;

Export.h * 1e-9 = Feed.h;

Export.V = Feed.V;

Export.z = Feed.z;

END


Port MoleFractionPort

Description: "Metric equivalent of an AspenPlus mole fraction port";

F as flow_mol (Description:"Molar flow rate");

z(componentlist) as molefraction (Description:"Mole fractions", 1.0/size(componentlist));

T as temperature (Description:"Temperature");

P as pressure (Description:"Pressure");

V as vol_mol (Description:"Molar Volume");

h as enth_mol (Description:"Molar enthalpy");

End

An APlusFeed block represents an Aspen Plus stream in a simulation. When a simulation containing an APlusFeed block runs in Aspen Modeler, the variables in the port called Export are fixed and should be given values close to those expected when the simulation runs in Aspen Plus. When the flowsheet is exported and runs in Aspen Plus, these variables are initialized with values from the Aspen Plus stream connected to the port.

An APlusProduct block also represents an Aspen Plus stream but it performs the reverse function. When a simulation containing an APlusProduct block runs in Aspen Plus, the values of the variables of the port called Export are copied to the Aspen Plus stream connected to the port.

The variables whose values are copied from Aspen Plus streams or copied to them have to be in SI units. Variables in an Aspen Modeler simulation must be in the Aspen Modeler base unit set. The APlusFeed and APlusProduct models ensure that variable values are appropriately converted; from SI for inputs, and to SI for outputs.

The rating specification ensures that the equations in the simulation calculate the stream outputs from the input variables that were initialized from the Aspen streams connected to the exported input ports.

Ensuring the Flowsheet Solves in Steady-State Mode Aspen Modeler flowsheets must solve using the Steady-State run mode.

This is because Aspen Plus® uses steady-state solvers, not the Aspen Modeler dynamic solvers. The steady-state solvers do not take account of the relationship between derivative and state variables as the Aspen Modeler solvers do.

If you have the Steady-State run mode selected when you export the flowsheet, Aspen Modeler ensures that derivative variables are fixed with a value of 0.0 and variables with a specification of Initial will be made Free. If you have any other run mode selected, Aspen Modeler does not modify the specification of the exported flowsheet. This means that Aspen Plus will solve the flowsheet as specified in Aspen Modeler, treating variables with a specification of Initial as Fixed.


Preparing a Flowsheet That Uses Custom Models If you want to prepare a flowsheet that uses your own custom models for export you need to add custom feed and product blocks containing ports that can be exported.

The process of adding feed and product blocks can be automated using a script. The Aspen Dynamics library, Dynamics.acml contains a script called AddExportBlocks that adds feed and product blocks to an Aspen Dynamics flowsheet automatically. The script also modifies the specification of variables in material streams and it initializes the values of variables in the added blocks.

Adding Custom Feed and Product Blocks Your flowsheet uses particular port definitions and possibly stream models. To export such a flowsheet for use in Aspen Plus the flowsheet must contain feed and product blocks containing ports of type MoleFractionPort_SI. The purpose of the feed blocks is to translate Aspen Plus stream data, which is in SI units, in to the stream representation used in your flowsheet and to convert variable values into Aspen Modeler base units. The purpose of the product blocks is to translate data from the streams used in your flowsheet to the variables whose values, in SI units, will be copied back to an Aspen Plus stream.

Blocks (or streams) representing a flow of feed material are connected to blocks representing unit operations using the built-in Connection stream type or a custom stream model. To run a flowsheet like this in Aspen Plus, the Material Feed Model has to be replaced with a model that can be connected to an Aspen Plus stream. The following is a diagram of the flowsheet.

Aspen PlusStream

Feedblockexportedas a port

CustomUnitOperation

Productblockexportedas a port

Adapting the Example Models The modeler library contains an example feed block called APlusFeed and an example product block called APlusProduct. To adapt these models for use with your flowsheet:

1 Copy the model to the Custom Modeling folder in the Simulation Explorer window

2 Edit the model and change the type of the Feed port from APlusFeed and the Product port in APlusProduct to the port type used in your flowsheet.


3 Modify the equations in the model to map variable values to from the port called Export to the variables in your port type.

After you have developed feed and product models that map variables between exportable ports of type MoleFractionPort_SI and the variables in your port type, you can replace the material feed models used in your flowsheet and add product blocks as required. If you use a stream model to represent a material feed you can connect the inlet end to your new feed block.

Preparing an Aspen Dynamics Flowsheet for Export If you want to prepare an Aspen Dynamics� pressure-driven flowsheet, you must first modify its specification, because it will not have a rating specification. You do not have to modify the specification of Aspen Dynamics flow-driven simulations.

Prepare an Aspen Dynamics� flowsheet for export by:

1 Ensuring that the flowsheet solves in steady-state.

2 Deleting the controllers and control streams added when the flowsheet was created in Aspen Plus®.

3 Switching the flowsheet to use rigorous Physical Properties calculations.

4 Adding blocks.

Solving an Aspen Dynamics Flowsheet in Steady-State Mode

Most Aspen Dynamics� flowsheets will solve in steady-state mode. If you have one that will not converge then the reason is probably that the initial solution generated from Aspen Plus® is not at steady-state.

In this case, to get a solution in steady-state you should:

1 Perform an Initialization run.

2 Take a few dynamic steps.

3 Switch to steady-state mode.

This will help to make sure that all the derivative variables in the problem have a value close to 0.

Tip: You can check the values of the derivatives by creating a table showing all the state variables in the simulation.

Creating a Table Showing All the State Variables

To create a table showing all the state variables:

1 From the Tools menu, click Variable Find.


2 Ensure that the Include Algebraic Variables checkbox is not selected.

3 Click Find. The resulting list of variables contains all the state variables in the simulation.

4 Select all the variables in the list, by selecting one entry then pressing CTRL+A.

5 Click the Table button to create a table in the flowsheet showing the selected variables.

6 Type a name for the table, for example AllStateVariables, and then click OK. The newly generated table appears and a new icon appears in the Contents pane for Flowsheet, showing the new table.

7 If your table does not have a column showing the derivative values:

− Click with the right mouse button on the table and from the menu that appears, click Properties.

− Add derivative to the list of columns being displayed. The table now shows which derivatives are close to 0 and which are not.

Deleting Controllers and Control Streams

To prepare an Aspen Dynamics� flowsheet for export, you can delete the controllers and control streams added when the flowsheet was created in Aspen Plus®. You do not have to do this, but you may want to do so, either because the controllers and control streams are not meaningful in a steady-state run or because you want the exported flowsheet to match an Aspen Plus block closely. By deleting the controllers you will remove the equations associated with them and the control streams from the flowsheet.

To delete controllers and control streams easily you can use the RemoveControl script supplied with the Dynamics.acml library. To do this:

1 In the All Items pane of the Simulation Explorer, expand the Dynamics library and then select the Scripts folder.

2 In the Contents pane, double-click the RemoveControl script. The script removes all controllers and control streams from your flowsheet.

Switching to Rigorous Physical Properties

To prepare your Aspen Dynamics� flowsheet for export, you should switch from local physical properties to rigorous physical properties. The reason for doing this is that the local physical properties are optimized for use with Aspen Modeler�s dynamic solvers. When a flowsheet is exported and solved using Aspen Plus® steady-state solvers, local properties calculations may not work properly. There is no disadvantage in changing to rigorous properties since local properties calculations only improve the performance of dynamic runs.

To switch to rigorous properties:

1 In the Simulation Explorer, select Simulation.


2 In the Contents pane, double-click Globals.

3 Change the value of the global parameter Propmode from local to rigorous.

4 Solve the simulation in steady-state mode.

Adding Feed and Product Blocks

To prepare your Aspen Dynamics� flowsheet for export, you need to add blocks to represent the ports to which Aspen Plus® streams can be connected. Use the script AddExportBlocks to do this automatically. This script:

• Connects an APlusFeed block to each feed stream in the flowsheet.

• Connects an APlusProduct block to every product stream.

• Copies variable values to the newly-added blocks so that the new variables have sensible values.

Note: Running the AddExportBlocks script affects the layout of your flowsheet. After the script has run, you may want to move the added blocks to restore the layout.

To run the script:

1 In the All Items pane of the Simulation Explorer, expand the Dynamics library and then select the Scripts folder.

2 In the Contents pane, double-click the AddExportBlocks script.

Tip: After running the script, you may want to tidy your flowsheet and zoom in.

3 Solve the simulation in steady-state mode to ensure that the new problem is converged.

Exporting an Aspen Modeler Flowsheet When you have prepared a flowsheet for export, follow these steps to export it:

1 From the Tools menu, click Export Compiled Flowsheet. The Export Compiled Flowsheet dialog box appears.


2 In the Flowsheet Export Name box, enter the name of the DLL that you are going to build from the flowsheet or accept the default name (the name of the simulation). If you have an existing DLL with the same name, it will be overwritten.

3 If you want to generate code, select the Generate Flowsheet Code checkbox. You may want to uncheck this box if have already generated a DLL but want to regenerate the corresponding Aspen Plus User Model Library.

4 In the Export Directory box, specify the folder where the DLL should be generated. By default the box shows the working folder. Typically you will want the DLL to be in the same folder as your Aspen Plus input files.

Note: To be sure that Aspen Plus can load the DLL, you must put it :

− In the folder where the Aspen Plus engine is running, that is, the folder where your Aspen Plus .bkp or .inp files are located.

� or �

− In a folder which is listed in the PATH environment variable.


5 If you want the compiler to optimize the generated code, select the Optimize Code checkbox. If this box is selected, the resulting code will run more quickly and the DLL will be smaller. However, it also means that it will take longer to compile the file. It is recommended that you only select Generate Optimized Code when you are satisfied that the exported flowsheet works properly in Aspen Plus®.

6 If you don�t want the generated code to be compiled and linked during the export, select the Create Code Files Only checkbox. This option allows the DLL to be built outside ACM. The advantage of this option is that the compilation and link process is slightly faster and you can use ACM while it is happening. If you compile and link during export you will not be able to use ACM until the link is complete.

Note: If you check this option ACM will generate the necessary files and the Simulation Messages window will contain information on command you need to use to build the DLL outside ACM.

7 Select the Add to Aspen Plus User Model Library checkbox if you want to create a new library file or add the flowsheet to an existing one. The library files is used to add the exported flowsheet to the Aspen Plus Model Library.

8 In the Library File box enter the name of the library in which you want to put the flowsheet.

9 If you want to export a list of input variables which can be updated in Aspen Plus, you should first create a table showing the variables. To export the list, select your table from the drop-down list in the Inputs Table box.

Note: Do not include variables from the export port of a block of type APlusFeed on an input form. If you do, the values of these variables will take precedence over values from the Aspen Plus inlet stream connected to the port. This may lead to Aspen Plus reporting a mass imbalance for an upstream block.

10 You can export a list of result variables for display in Aspen Plus by creating a table showing the variables and then selecting it from the drop-down list in the Results Table box.

When you have selected the options you want, select OK to proceed with the export. Now you are ready to use your flowsheet in Aspen Plus.

17 Using an Exported Flowsheet in Aspen Plus 364

17 Using an Exported Flowsheet in Aspen Plus

When you have prepared an Aspen Modeler flowsheet for export, and exported it, you are ready to use it in Aspen Plus.

This chapter contains information on the following topics:

• Using an exported flowsheet in Aspen Plus®

• Modifying an exported flowsheet

• Licensing of Exported Flowsheets

• Distributing flowsheets to other Aspen Plus users

Using an Aspen Modeler Flowsheet in Aspen Plus To use an exported Aspen Modeler flowsheet in Aspen Plus your Aspen Plus simulation needs to refer to the User Model Library containing the ACM flowsheet. In Aspen Plus follow these steps:

1 From the Library menu, click References.

2 In the list of available libraries, select Browse and navigate to the directory where your User Model Library is located, select the file and use Open to load it into Aspen Plus.

3 Select the ACM Flowsheets tab in the Model Library and select the flowsheet that you want to use.

You can edit the User Model Library in Aspen Plus by selecting the library name on the Library menu and then selecting Edit from the pop-up menu. Use the Aspen Plus help for more information on editing library files.

Modifying an Exported Flowsheet You may need to make changes to a flowsheet after you have exported it. For example, you might want to use a different set of components or you may


need to change the specification of the variables. Some changes to the flowsheet can be made within Aspen Plus®, others can only be made in your Aspen Modeler product.

Within Aspen Plus you can use Aspen Plus input forms for an exported flowsheet to:

• Change the values of variables.

• Change the bounds on variables.

• Change the specification of variables.

• Change flash calculation options.

You must use your Aspen Modeler product if you want to:

• Change the value of a parameter.

• Change the components used in the exported flowsheet.

• Change the Physical Property options used in the flowsheet.

If you make any of these changes in your Aspen Modeler product you will need to export the flowsheet again for your changes to affect Aspen Plus runs.

Licensing of Exported Flowsheets Exported flowsheets running in Aspen Plus® may use an Aspen Modeler license, depending upon your license agreement.

Important Note: If an Aspen Modeler license is required, it is acquired using the Aspen Plus License Manager settings, not the settings for your Aspen Modeler product. This means that if Aspen Plus connects to a particular server to access an Aspen Plus license, the same server must be able to provide an Aspen Modeler license when an exported flowsheet is used in an Aspen Plus simulation.

Distributing the Exported Flowsheet to Aspen Plus Users You can distribute an exported flowsheet to other Aspen Plus® users who do not have an Aspen Modeler product installed by copying to the users' machines:

• The flowsheet DLL.

• The Aspen Plus User Model Library generated by Aspen Custom Modeler®.

• Any other DLLs on which the flowsheet DLL is dependent.


Notes: • If your flowsheet uses procedure equations, the exported DLL

will depend on the DLLs containing their implementation. The flowsheet DLL will not load correctly in Aspen Plus® if these DLLs are not available, so you must copy them in addition to the flowsheet DLL.

• If you export an Aspen Dynamics� simulation, the exported DLL will rely on the following DLLs: − Dynamics.DLL − Modeler.DLL − Gpp.DLL

Tip: Dynamics.DLL, Modeler.DLL, and Gpp.DLL can be found in %SystemDrive%\Program Files\Aspentech\AmSystem 12.1\bin

• If you export an Aspen Custom Modeler simulation that uses procedure calls defined in the modeler.acml library, the exported DLL will rely on the following DLLs: − Modeler.DLL − Gpp.DLL

Tip: Modeler.DLL, and Gpp.DLL can be found in %SystemDrive%\Program Files\Aspentech\AmSystem 12.1\bin

• When you generate a DLL in an Aspen Modeler application, the list of DLLs that it depends on is shown in the Simulation Messages window. If you want to use the exported DLL on a machine which does not have an Aspen Modeler application installed, check the list in the Simulation Messages window to make sure that the correct DLLs are available.

• If you put the extra DLLs in a directory which is always searched when the exported DLL is loaded into Aspen Plus, you will need to copy them to the target machine once only. Any directory on the path will be searched, as will the engine\xeq directory of the Aspen Plus installation.

18 Using Models in Other Applications 367

18 Using Models in Other Applications

Building Custom Unit Operation Models for Aspen Plus and HYSYS Models written in Aspen Modeler products using the Modeling Language can be used as Unit Operation Models in Aspen Plus 12.1 and HYSYS 3.2 simulations.

This means you can:

• Describe proprietary reactors or units for which there is no Aspen Plus/HYSYS model and use the model in either simulator.

• Customize Aspen Dynamics models to provide variations on existing Aspen Plus models that can be used in either simulator.

• Models exported from Aspen Modeler can be configured in Aspen Plus or HYSYS; for example, you can change the values of model parameters in the same way that you can in your Aspen Modeler product. In Aspen Plus the model will automatically use the component specifications made in the Aspen Plus simulation. In HYSYS the components used by the model are defined in a .appdf or a .aprpdf file which is selected as part of the model configuration.

To export a model and use it in Aspen Plus or HYSYS:

1 Check you have the necessary software.

2 In your Aspen Modeler product, create a model that is compatible with Aspen Plus streams and specify model properties, for example, tables, scripts, ports and custom forms, to be included when it is exported. A model that is compatible with Aspen Plus streams will also be compatible with HYSYS streams.

3 Export the model to create a Model Package.

4 Install the Model Package on the machine you want to use the model on.

5 In Aspen Plus, reference the catalog of installed Aspen Modeler models and select the new unit operation from the Aspen Plus Model Library. You


can now use the unit like any other Aspen Plus unit operation. Refer to the �Exporting Models for use in Aspen Plus� tutorial for detailed instructions.

6 In HYSYS, select the User Ops button from the Object Palette and then double-click �ACM Op� or drag it to the PFD and drop it to create an instance. On the Acm Configs page for the block select the installed model that you want to use. Refer to the �Exporting Models for use in HYSYS. tutorial for detailed instructions.

Software and Hardware Requirements To export a model from an Aspen Modeler product:

• You must have a C++ compiler�Microsoft® Visual C++ 6.0 or Microsoft Visual Studio Net is recommended for exporting models on machines running Microsoft Windows. Your C++ compiler must be configured so that it can be used from the command line.

Note: The C++ compiler is only needed to create the DLL when the model is exported from your Aspen Modeler product. A DLL can be used in Aspen Plus or HYSYS without having a C++ compiler.

• An Aspen Modeler model running within Aspen Plus or HYSYS will use either an ACM_MODEL_EXPORT license or a license corresponding to the Aspen Modeler product used to create the model, if an ACM_MODEL_EXPORT license is not available.

• The Aspen Modeler client and server must be installed on the same machine. If the server is installed on a remote machine it will not be possible to export a model.

Creating a Unit Operation Model for Aspen Plus and HYSYS Any Aspen Modeler Model can be exported but a model must meet some basic requirements if it is to be used successfully. This is because Unit Operations in Aspen Plus and HYSYS use certain common conventions., for example an exported model must use port types that allow the model to be connected to Aspen Plus and HYSYS streams.

Note: Currently it is only possible to connect exported Aspen Modeler Unit Operation models to Aspen Plus streams that have a single mixed sub-stream, either with or without polymer stream attributes. You cannot connect exported models to streams containing solids or streams with multiple sub-streams. Polymer stream types are not supported in HYSYS.


This section contains information on the following topics:

• Creating a model compatible with Aspen Plus streams.

• Exporting the model.

• Installing the model for use with Aspen Plus and HYSYS.

Creating the Model • To be used in Aspen Plus or HYSYS a model must:

• Use port types that are compatible with the MOLE_FRAC port specification used in Aspen Plus Equation-Oriented Models.

• For Aspen Plus use, the model must calculate its output streams based on inlet stream data, parameter values and initial values for other internal variables.

• Not depend on procedure tearing or decomposition to solve successfully.

Using Port Types Compatible with Aspen Plus Aspen Plus and HYSYS streams can only be connected to ports on exported models if the port types used in the model contain particular variables. For connections to non-polymer streams in either Aspen Plus or HYSYS it is recommended that you use the one of the following port types:

• MoleFractionPort � which can be found in the Modeler library.

• MaterialPort (or any of the port types derived from it) - which can be found in the Dynamics library if you have Aspen Dynamics installed.

For connections to polymer streams in Aspen Plus it is recommended that you use the MaterialPortRP port type or any of its derivatives. MaterialPortRP can be found in the Aspen Dynamics library.

For a port to be connected to a material stream in Aspen Plus or HYSYS it must contain at least the following variable definitions:

F as flow_mol(Description:"Molar flow rate");

T as temperature(Description:"Temperature");

P as pressure(Description:"Pressure");

V as vol_mol(Description:"Molar Volume");

h as enth_mol(Description:"Molar enthalpy");

z(componentlist)

as molefraction(Description:"Mole fractions");

A compatible port type can contain extra variables but these must be fixed on the inlet side and free on the outlet side and no data will be transferred between the extra variables and connected streams.

Tables Your model may own tables that you have defined to display particular sets of variables and parameters. These tables can be included in the exported model and displayed in both Aspen Plus and HYSYS. By default Aspen Modeler will


include all tables belonging to a model in the exported package. Use the Model Package Properties dialogs to exclude tables if necessary.

Aspen Plus distinguishes between input forms and results forms whereas Aspen Modeler does not. Use the Model Package Properties dialogs to specify whether a form should be considered as an input form or a results form or both in Aspen Plus.

For models that are going to be exported it is advisable to define tables that display either variables or parameters but not both together. Both Aspen Plus and HYSYS distinguish tables that show parameters and tables that show variables.

Custom Forms Your model may contain custom forms implemented using .ocx controls. By default Aspen Modeler will include all the custom forms belonging to a model in the exported package. Use the Model Package Properties dialogs to exclude Custom Forms if necessary.

Exported custom forms will be displayed in the Aspen Plus Data Browser for an instance of an exported Model.

Note: At release 3.2 HYSYS does not support the use of Custom Forms in exported models.

Not all the automation methods that Aspen Modeler supports are available once a model is exported. Custom Forms and Visual Basic scripts associated with a model that is to be exported should only use the automation methods that are supported by exported models. The relevant methods are listed in the table below: Object Methods supported

when using an exported model

Methods that are not supported for exported models

An Instance of any object

Application

ActiveDocument

GetPath

IsKindOf

Name

Parent

TypeName

Application AppName

FullName

Name

Version

Path

Simulation

processID

ActiveDocument

WorkingFolder

PrintToMessageWindow

Msg

OutputLogger


Document Flowsheet

Application

Equations

RunMode

Problem

OutputLogger

Options

FullName

Name

Parent

Degrees

SpecState

State

Variables

Results

UOM

Successful

ScriptIsRunning

Run

Reset

Properties

Variable Value

Units

Description

ValidValues

Name

IsAlgebraicVariable

IsParameter

IsInput

IsOutput

Parent

getPath

IsKindOf

Property

ConvertFromBaseUOM

ConvertToBaseUOM

DefaultUnit

DefaultValue

derivative

spec

ULangrange

LLagrange

IsStateVariable

IsHidden

Reset

TypeName

FixedValue

FreeValue

InitialValue

ComponentList (supports the Variable methods)

Components

OptionsNames

Option

Structure Resolve



RunIncrementalUpdate

Global

NewStringSet

NewIntegerSet

NewVariableSet

FindMatchingVariables

Invoke


GetScriptText

GetVariableValues

Port

(Supports the Structure methods)

IsInput

IsOutput

GetPath

Name

Parent

If your OCX Custom Forms calls an unsupported method the function being executed will fail. This will typically result in the form failing to initialize properly.

We recommend the following techniques should be followed when writing OCX Custom Forms for use in Aspen Plus and Aspen Modeler applications:

• Use case sensitive comparisons on variable names because variable names will be uppercase when running n Aspen Plus. For example, in Visual Basic use Option Compare Text and the �Like� operator when comparing variable names.

• Do not rely on the double quote (�) character being part of variable names involving string indices to arrays. The double quotes in variable names are stripped out in Aspen Plus.

It is possible to debug OCX forms running in Aspen Plus by building a debug version of the OCX and then attaching a debugging tool (for example Microsoft Visual Studio 6) to the apwn process when the OCX is running so that you can trace through the source code.

If your Custom Form uses any of the unsupported methods and you want the form to run in Aspen Plus you should either create a new ocx that does not use these methods, or modify the code for the OCX so that it detects when it is running in Aspen Plus so that it can avoid making calls to unsupported methods.

You can detect whether your Custom Form is running in Aspen Plus using the Application.AppName property: For example:

If application.AppName = �Aspen Plus� then

� running in Aspen Plus

else

if application.AppName = �Aspen Custom Modeler� then

� running in ACM

else

� running in an unknown application

end if

end if


Visual Basic Scripts Your model�s Visual Basic scripts will be exported with a model and can be run in Aspen Plus and HYSYS. Visual Basic scripts are primarily intended to help with model initialization.

Visual Basic scripts can be run in two ways:

• Scripts with one of these standard names will be run at specific times during the process of creating, configuring and solving an instance of a model. Script Name:

Executes when:

PreSolve Immediately before solution following all other updates. The presolve script may be setup to run under specific circumstances depending on the status of certain read only block attributes. For example,

If the presolve script must be run only in the Sequential Modular mode in Aspen Plus then check to see if the SolutionMode block attribute is set to �Sequential Modular�.

If the presolve script should be run only if the block has never been solved then check to see if the SMStatus block attribute is set to �Not solved�. This is especially significant if the exported model is used within a recycle loop in a flowsheet. The relevant syntax may be found in the presolve script for the MyPipe model in the tutorial example titled �Exporting Models for Use in Aspen Plus�. The various possible values for these parameters in Aspen Plus are: SolutionMode � �Sequential Modular� or �Equation Oriented� SMStatus and EOStatus - "Incomplete", "Not solved", "Not converged", "Converged" or "Built in"

In Hysys, SolutionMode will be set to �Sequential Modular� , EOStatus will be set to �Incomplete� and SMStatus will be set to one of - "Incomplete", "Not solved", "Not converged", "Converged" depending on the state of the solution.

In ACM itself the SolutionMode, SMStatus and EOStatus block parameters will always return an empty string.

PostSolve Immediately after solution and before any other action is taken.

Init When the block is placed in the flowsheet and whenever a parameter that changes the number of equations and variables in the block is updated.

• Visual Basic scripts can be invoked manually from the Equation-Oriented (EO) command line in Aspen Plus. The EO command is available in the advanced mode of the Aspen Plus Control Panel when a simulation is running in EO mode. In HYSYS enter the commands needed to invoke a script on the Simulation Engine page.

• The syntax for executing a Visual Basic script is: Invoke <blockname>,<script name> Where <blockname> is the fully qualified name of the instance of the


model that you want to run the script for, and <script name> is the name of the script to be run.

Units of Measure Instances of Aspen Modeler Models will solve in Aspen Modeler�s base units of measure so that any scaling built-in to the model equations will still be appropriate when an instance of the model runs in another simulator.

Unit of Measurement conversions between simulator base Units of Measure and Aspen Modeler base Units are applied automatically as long as:

• Aspen Modeler variables are of a type which has a physical quantity defined.

• The mapping between the Aspen Modeler physical quantity and the Aspen Plus Units table is known. This mapping is defined in calls to the AddPhysicalQuantity method of the UOM Converter object in the Visual Basic script used to build Aspen Modeler�s UOM tables � typically AMSystem 12.1\bin\OnNewDocumentScript.vb.

• HYSYS will display model variables and parameters in the Aspen Modeler base units of measure. This means values can be directly used with the model equations without any conversions.

If a variable has a physical quantity that cannot be mapped to Aspen Plus units it will be treated as being dimensionless.

Solver Options In Aspen Plus an exported Aspen Modeler Model uses the Aspen Modeler SPARSE non-linear solver by default when running in Sequential Modular mode (SM), and whichever solver has been selected when running in Equation-oriented (EO) mode. Alternative solvers can be selected in SM mode using the Block Options form.

In HYSYS an exported Aspen Modeler Model uses the same Aspen Modeler SPARSE non-linear solver by default when running in Steady-State mode. In dynamic mode the model uses the Aspen Modeler Implicit Euler integrator.

Note: Decomposition is not used in either Aspen Plus or HYSYS so it is recommended that you test the model in your Aspen Modeler application with decomposition switched off. To switch decomposition off: select Solver Options from the Aspen Modeler Run menu, then select the Tolerances tab where you can uncheck the �Use Group Decomposition� switch.

Setting Model Package Properties. You can modify the default Model Package properties before exporting a model by:

• Selecting the model you want to export in the Explorer Window using the right mouse button.

• Selecting the Model Package Properties menu item on the context menu and then:


• Following the dialogs shown to specify Package properties.

Note: The Model Package Properties dialogs are not available for models loaded from Aspen Modeler Library files (*.acml). Models exported from libraries will use built-in settings for Model Package Properties. If you want to change the defaults, copy the model from the Library to the Custom Modeling Folder, and then follow the steps described above. The Model Package Properties dialogs are in the form of a Wizard � you must complete each dialog and end with the Finish button for your changes to take effect.

Your Model Package Properties settings will be saved along with your Aspen Modeler simulation.

The Model Package Properties dialogs let you control how the model is exported:

Model Package Properties � General 1 In the Model Library Category field enter the name of the tab where you

want the Model to appear in the Aspen Plus Model Library .

2 Change the Display Name to be the name you want to use for the model in the application where you will use the model. Note, for use in Aspen Plus you must change the display name if your model has the same name as an existing Aspen Plus model.

Model Package Properties � Ports 1 This dialog shows the settings for your model�s ports. You can control

whether a port is accessible in the exported model, what its prompt should be and whether a connection is mandatory or optional.

2 Aspen Modeler will determine a type for each of the ports automatically but you can change it if necessary.

Model Package Properties � Forms 1 This dialog shows your model�s Custom Forms and Tables. You can control

whether a form is included in the Model Package, whether it is an input, results or input and results form. For tables you can also specify whether it displays variables or parameters or a mixture of both variables and parameters.

2 Once exported, a table can only display variables or parameters. If your table displays both there will be two versions of it in Aspen Plus and HYSYS: one will display variables, the other will display parameters.

3 Press Finish to apply your changes.

Exporting the Model Export a model by selecting it with the right mouse button in the Explorer View and then choosing the Export menu item from pop-up menu.


On the Export dialog change the file type to be Model Package (*.msi) in the Save As Type box.

Check export options as required:

• Optimize Code � This option will switch on compiler optimization, which will produce faster code.

• Include Debugging Information � Use this option if you need to be able to debug the generated code.

• Delete Intermediate Files � Check this if you want ACM to delete the intermediate files it creates during the export process.

Navigate to the directory where you want ACM to create Unit Operation Model, use Save to export the model.

When you press Save, Aspen Modeler generates C++ code corresponding to the Aspen Modeler Language statements that define your model. It also exports any Tables, Icons, VB Scripts, Procedure code DLLs and Custom Form OCX files belonging to your model. is complete a DLL is built from the generated code. A Windows Installer Package, a file with the extension .msi, is then created containing all the files that need to be installed to use the model.

When the Windows Installer Package for your model is complete Aspen Modeler will ask whether you want to install the model. If you say �Yes�, follow the install instructions to install the model. If you say �No� you can install the model manually later. Installing the Model Using Windows Explorer describes the steps required to install the model manually. These are the steps that should be followed if you want to install the model on a different machine.

Installing the Model using Windows Explorer To install your Unit Operation model manually:

• Use the Windows Explorer to navigate to the directory containing the Model Package you have exported.

• Select the .msi file created by Aspen Modeler with the right mouse button.

• Select Install from the context menu.

• Follow the installation instructions provided by the Windows Installer.

Note: If you save your Model Package Properties and subsequently recreate the Model Package after it has been installed, the Windows Installer will offer Repair and Remove options rather than an Install option. If the Package has not already been installed, Windows Installer offers the Install option. Once the installation process is complete the model is ready for use in other applications. Note, the Repair option only re-installs currently existing features in the model. For example, if you have added a table or a custom form to your model and re-exported it from ACM, you must use the Remove option and then install the model.


To install this model on another machine copy the .msi file to that machine and follow the same steps.

Using an Aspen Modeler Unit Operation Model in Aspen Plus or HYSYS When you have exported and installed an Aspen Modeler Model you are ready to use it in Aspen Plus or HYSYS.

This section contains information on the following topics:

• Using an Aspen Modeler Model in Aspen Plus or HYSYS.

• Configuring an Exported Model.

• Licensing of Exported Models.

• Distributing Models to other Aspen Plus or HYSYS users.

Using an Aspen Modeler Model in Aspen Plus To use an exported Aspen Modeler Model in Aspen Plus your Aspen Plus simulation must refer to the library of installed Aspen Modeler Models.

In Aspen Plus follow these steps:

1 From the Library menu, click References.

2 In the list of available libraries, check the �ACM Models� entry.

3 Select the �ACM Models� tab in the Model Library and select the Model that you want to use.

Using an Aspen Modeler Model in HYSYS To use an exported Aspen Modeler Model in HYSYS you will need the following:

1 You must have either Aspen Plus (and Aspen Custom Modeler 12.1) installed, or the required Aspen core components installed. The core components can be optionally installed as part of the HYSYS installation procedure. The core components allow you to use Aspen Modeler models in HYSYS, but you can not create new Models.

2 You must have a Properties file. If Aspen Plus is installed on the machine where HYSYS is used, you can use a .appdf file that is generated by Aspen Plus (see �Generate a Properties Plus .appdf File�). If Aspen Plus is not installed on the machine, you must generate a .aprpdf file using Aspen Properties. (Do not use a .appdf file if Aspen Plus is not installed.)


Note: In general, if a model works in Aspen Plus, it should also work in HYSYS.

Configuring an Aspen Modeler Unit Operation Block In Aspen Plus You configure an Aspen Modeler Unit Operation block in the same way as a built-in Aspen Plus Unit Operation block.

Either:

1 Double-click the block in the flowsheet Window to open the Data Browser Input forms for the block or,

2 Open the Data Browser and navigate to the block to open the input forms.

An Aspen Modeler Unit Operation Block has a standard Block Options form, sheets showing Variables, Ports, Parameters and equations and an entry for each OCX form.

The variables sheet has a tab for each Aspen Modeler Variable Table exported with the model. Similarly the Parameter sheet has a tab for each Parameter Table exported with the model. If your model has an �All Parameters� table it will display a parameter called �DOF� which can be used to ensure that the model is square. If your model does not have an �All Parameters� table you can create one in Aspen Plus by:

• Clicking on the tab for any other table using the right mouse button.

• Selecting Insert from the context menu.

• Entering the name you want to use for the new table.

• Accept all the defaults on the query dialog that is displayed.

The new table will display all the parameters in the model.

Use the Variable sheet tabs to specify initial values for variables, use the Parameter sheet tabs to configure model parameters. As in Aspen Modeler products, the set of variables, parameters, equations and ports shown on the sheets change as you configure the model.

Your Aspen Modeler Unit Operation Block is automatically configured with the components entered on the global Components form. As you change the components the block reconfigures itself.

If your unit operation block makes use of more than one component list you can define component lists in the Component Lists sheet of the Block Options form. This sheet allows you to define component lists with their own subset of components and their own Property Options.

Once you have created a component list it appears as an available option for all the Component List parameters shown on the Parameters sheet.

You can connect streams to Unit Operation blocks in the flowsheet window in the normal way. If your Unit Operation Block uses multiports connecting a


stream will extend the multiport creating new variables and equations when the connection is made.

Configuring an Aspen Modeler Unit Operation Block In HYSYS Aspen Modeler Unit Operation in HYSYS can be created via the object palette (press F4) or UnitOps view (press F12).

1 On the object palette, click on the User Ops button then double click on ACM Op or drag the ACM Op icon onto a PFD window.

2 When you have created a new instance, double click on it in the PFD to bring up its property view. On the ACM Configs page, click the Select Property File� button. It allows you to select an .appdf or .aprpdf file. This file defines the available components and property options. (Note that all ACM Op instances share the same property file.)

3 The drop-down selection box on the same page shows a list of installed models. Select the one that you want to use.

4 When you have selected the property file and model, go to the Design, Connections page. This page shows the ports associated with the model and it lets you connect one HYSYS material stream to each port. Connections can also be made via the PFD.

The Design, Properties page allows you to change property options and also select a subset of components to be used, should you wish to do so.

Because HYSYS and the property file use different components, you need to match components on the Design, Component Map page. For each component used by the model, you can select one HYSYS component. The simplest option is to use the Map Components Based on Molecular Weights button to map components automatically. If HYSYS is in steady state, your model now has enough information to solve.

Note: You do not have to map all components (they default to zero). You can also map multiple model components to the same HYSYS component in which case they will be added up or equally divided.

You can change model parameters and variables on the Parameters and Variable tabs which also show you any defined forms or style sheets. You can drag and drop values from these pages to a HYSYS spread sheet, and values can also be imported and exported via the variable navigator.

The Dynamics page allows you to change settings if you wish to use the model in HYSYS Dynamics. You can use a steady state solution of your model if your model does not have dynamic behavior or if you desired a steady state solution. For dynamics mode you need to set ACM Specs as well as PF Specs. On the ACM Specs page, specify which variables should be fixed when the ACM model is being solved. For a typical model you can fix all the inlet port variables and free all the outlet port variables. On the PF Specs page you typically want to select one variable for each HYSYS stream. Do not select a


variable if it corresponds to a stream variable that is also specified in the stream.

The Simulation Engine page allows you to enter OOMF script commands. This can be used for troubleshooting or changing advanced options.

Licensing Exported Models Running in Aspen Plus Exported Models running in Aspen Plus may use an Aspen Modeler license, depending upon your license agreement.

Important Note: If an Aspen Modeler license is required, it is acquired using the Aspen Plus License Manager settings, not the settings for your Aspen Modeler product. This means that if Aspen Plus connects to a particular server to access an Aspen Plus license, the same server must be able to provide an Aspen Modeler license when an exported Model is used in an Aspen Plus simulation.

Licensing Exported Models Running in HYSYS Exported Models running in HYSYS require one license on the HYSYS side (named �HYSYS_ACMOp�). If you use Aspen Plus and Aspen Custom Modeler, those applications also require separate licenses. You do not need a license for the Aspen core components.

Distributing an Exported Model To Aspen Plus Users You can distribute an exported model to other Aspen Plus users who do not have an Aspen Modeler product installed by installing the Model Package created by Aspen Modeler on to the users' machines.

Distributing an Exported Model To HYSYS Users You can distribute an exported model to other HYSYS users who do not have the Aspen Plus or Aspen Modeler products installed by installing the Model Package created by Aspen Modeler on to the users' machines. If these products are not installed, then you will need to install the Aspen core components as part of the HYSYS installation. In this case also be sure to use a .aprpdf properties file and not a .appdf file created by Aspen Plus.


Using the MyPipe Model in HYSYS To use this model in HYSYS:

1 Start HYSYS. Click the New Case button. In the basis environment, click the View button to view the component list, then enter �Water� to add it to the list.

Switch back to the Simulation Basis Manager window and on the Fluid Pkgs tab, click Add. Next select a property package from the list (e.g. ASME Steam). Click the Enter Simulation Environment button.

2 Create a new stream (by double clicking the Material Stream icon on the object palette; this can be opened by pressing F4; and name it S1. In the stream view, specify 50 C, 1 bar and a volume flow of 1 m3 per hour. Set the stream composition to be 100% water. (These conditions should be the same as in the MyPipe case in Aspen Plus, although that is not required.)

You can alternatively open almost any case that has water as a component.

3 On the object palette, click the User Ops icon, then double-click on ACMOp icon.

A new instance is created and its view comes up.

4 On the �ACM Configs� page (which should be open), click the Select Property File button. Navigate to the MyPipe.appdf file that was created when the MyPipe case was saved in Aspen Plus. (The file should be located under the Aspen Custom Modeler 2004.1\Examples\ModelExport directory.)

5 Now, from the list of models, select MyPipe.

6 On the Connections page: Next to IN_F, select S1 from the drop down list. Next to OUT_P, enter S2.

7 Now go to the component map page and click the Map Components Based on Molecular Weights button. The pipe will now solve.

Explore the other tabs which will show you variable and parameters values. For example, you can navigate to the Parameters, Input_Par page and change the pipe roughness.

Note: Further information about this model can be found in the HYSYS documentation.

19 Aspen Custom Modeler Language File 382

19 Aspen Custom Modeler Language File

Aspen Custom Modeler input files with the extension .acmf are ASCII text files which are written out by Aspen Custom Modeler when you save a simulation. .acmf files are intended to be accessed only by the Aspen Custom Modeler program, and are not intended for direct editing by users of Aspen Custom Modeler. In general we recommend that you do not edit these files directly.

Because the file is not intended for direct editing , if you do make direct changes to a .acmf file this may result in the file no longer loading in to Aspen Custom Modeler, and if it does not load there may be no explanatory error messages to say why it does not load. It is also possible that your changes may cause Aspen Custom Modeler to fail when you attempt to load the file.

Having said this, some users have found it useful to edit the file directly, and this is possible if you are careful with the changes that you make. One example where it is convenient to edit the file directly is in a global rename of a block or stream. If many scripts, tasks and forms refer to a given block then it can be tedious to change all of these references from within Aspen Custom Modeler.

Another example is to remove a custom model that is being used with in the flowsheet, to force Aspen Custom Modeler to use a version of this same model that is included in a model library.

This chapter provides an overview of the contents of the Aspen Custom Modeler Language file, looking at each of the main sections in turn. Where the section name is shown in angle brackets (<>) this means the name is not uses in the input file, it is just the name we are using to refer to the section in this documentation.


Version Defines the version of Aspen Custom Modeler that was used to create the file.

Example:

Version "2004-0";

Libraries Lists the ACM libraries to attach to this simulation. Libraries given without a specified path will be searched for in the default library folder for the current application, for example Program Files\AspenTech\AMSystem 2004.1\lib.

Example:

Libraries "Modeler.acml", "SystemLibrary.acml";

<Global Definitions> This section contains definitions of assignments to global variables. Once a global variable has been created by a Block or Stream in your simulation, direct editing in the input file is the only way it can be removed or modified.

Example:

Pi AS RealVariable;

Pi.Spec : Fixed;

Pi : 3.142;

<Type Definitions> Definitions of types which will appear in the custom modeling folder. These can include Variables, Parameters, Ports, Stream types, Procedures, Models and Structures. The syntax is documented in the ACM modelling language documentation. Note that the order in which the types appear is important, types must already have been defined before they can be used in other types. For types which can own icons, forms or scripts a system section is included giving the definition of these. These sections are marked with:-

//SYSTEM SECTION - WARNING: DO NOT EDIT

�

//SYSTEM SECTION END

As the text says, do not try to edit these sections. The END statement which finishes the type appears after the //SYSTEM SECTION END line.

If you delete a type definition from this section ensure you delete everything from the start of the type definition (for example �MODEL Reactor�) to and including the line �end;�. Take care not to delete any types that are used in the flowsheet or by other types, and which are not present elsewhere in a library used by the simulation.


<Plot and History Table Definitions> These appear within the //SYSTEM SECTION markers. Although in general you should not edit this section it can be useful to add form definitions particularly when large numbers of variables are to be added such as on a history table. To add a plot or history table add a form section starting with <FORM NAME= and ending with </FORM>. This should be placed after the <FORMLIST > statement but before the </FORMLIST> statement for the model you want to edit. Take care that this is not in the context of an existing form.

Example:

<FORMLIST DEFAULTFORM="TankResults">

<FORM NAME="TankResults" CLSID="{F6AD2450-A109-11D0-8B2F-0A024E1AC0C}"> { Version : 2 VariablesPaths : [ 1 h 11 FlowIn.flow 1 k 12 FlowOut.flow ] }

</FORM>

</FORMLIST>

The list of variables for the plot or history table appears between the [�] after the VariablesPaths keyword. The number before each variable is the number of characters in name. If your list of variables goes over more than 1 line ensure that each new line starts with the length number. The order in this list is the order in which they will appear on the form.

Flowsheet This section defines the flowsheet content including what blocks, streams and hierarchies are present and how they are connected; the flowsheet graphics; any structure instances, and any user assignments to variables and parameters.

The Flowsheet section can include any of the following:-

StructureContainer This defines a structure container and its contents. There can be several structure containers in a flowsheet. They contain instances of 1 or more structure types.

Example:

StructureContainer Structures

StrInst1 as Struct1;

End


<Blocks, Stream and Connection Statements> Defines what blocks and streams appears on the flowsheet and how they are connected up. The syntax and rules of usage are the same as when these statements are used within a model.

Example 1

Tank1 as Tank;

Tank2 as Tank;

FeedStream as Connection;

IS1 as Connection;

Connect Tank1.FlowIn with FeedStream;

Connect Tank1.FlowOut and Tank2.FlowIn with IS1;

Example 2 - Hierarchy connections

FLOWSHEET

Tank5 as Tank;

HIERARCHY Hier1

B1 as Tank;

S1 as input Connection;

Connect B1.FlowIn with S1;

END

IS5 as Connection;

Connect Tank5.FlowOut and input of Hier1.S1 with IS5;

END

CONSTRAINTS This contains the flowsheet text which appears under the flowsheet folder in the explorer. See Defining Flowsheet Constraints. for more information. The section is terminated with an END statement.

Example:

CONSTRAINTS

// Flowsheet variables and equations...

END

Task <name> Definition of flowsheet level tasks. See Using Task Statements for more information. The section must be terminated with an END statement.

Example:


Task SubTask1

Ramp(Tank1.flowin.flow, 3.0, 5.0);

End

As in models, the Flowsheet section contains a System section which contains the definition of flowsheet level scripts, tasks and forms. You should not edit the contents of this section.

//SYSTEM SECTION - WARNING: DO NOT EDIT

�

//SYSTEM SECTION END

ActiveTasks This is a list of the Tasks that were active in your simulation when you saved the file

Example:

ActiveTasks : ["FillTank", �StartPump�];

<Flowsheet Assignments> Any assignments that you have made to the properties of variables or parameters in any part of the flowsheet, including hierarchy blocks, are saved in the flowsheet assignments list.

Example:

B1.Tank1.ComponentList : "Default";

B1.Tank1.D : 1.954283353193783;

B1.Tank1.FlowIn.Flow.Spec : Fixed;

Graphics The graphics section contains information about the graphical layout of the flowsheet or hierarchy block. This should not be edited. If you change the flowsheet connectivity by deleting blocks or streams or by changing the way existing connections are made in the ACM input file you should delete the graphics section from the Graphics keyword to ENDTEXT as the graphics will no longer be applicable to the flowsheet. Adding items is OK as the extra items will be laid out automatically. If the graphics section is deleted altogether all items in the simulation will be laid out automatically.

HIERARCHY <name> Hierarchy definitions are contained in the Flowsheet definition section. A hierarchy definition can contain anything a flowsheet definition contains including hierarchies but excepting flowsheet assignments and structure containers.

Flowsheet and Hierarchy definitions must end with an END statement.


Properties This section defines the physical properties package to be used for the simulation. It is omitted if no physical properties package is used.

Example 1 - Define Aspen Properties file

Properties

Package : "Aprpdf";

WorkingDirectory : "E:\ACM13\Examples\";

RunID : "absorber.appdf";

Default as ComponentList;

Within Default

Components: ["BUTANE","ETHANE","METHANE"];

Option("OPSET") : "RK-SOAVE";

Option("FREE-WATER") : "STEAM-TA";

Option("TRUE-COMP") : "NO";

EndWithin

End

Examples 2 - Use Aspen Properties directly

Properties

Package : "PropertiesPlus";

DefinitionText : TEXT

�

ENDTEXT;

Default as ComponentList;

Within Default

Components :["C2H6","C3H8","CH4"];

EndWithin

End

The definition text between TEXT and ENDTEXT is the Properties Plus aprbkp file text and should not be edited.

If WorkingDirectory is defined, and you move a properties package file to a different location, you will need to edit the value of WorkingDirectory. Alternatively you can delete this line and place the properties package in the same folder as your .acmf file. The later is recommended because if you move the two files together to another location you will not need to edit the .acmf file again.


Options Contains values for all of the simulation options, as define on the Solver Options, Run Options and Snapshots dialogs. Most of these are self explanatory.

Example:

Options

AbsPerturb: 1.e-005;

AbsTearTol: 1.e-005;

AbsTol: 1.e-005;

ChangeTol: 1.e-005;

CheckProcDerivs: "Off";

Compression: False;

CurrentUOMSet: "Metric";

Decomposer.ProgID: "AspenTech.Decomposer";

Decomposition.MultipleGroup: True;

DerivAbsTol: 1.e-005;

DerivRelTol: 1.e-005;

EqnTol: 1.e-005;

EstimationPrintLevel: "Medium";

EstimationSolver: 2;

Estimator: 1;

ExplicitEventTolerance: 1.e-005;

Feasopt.MaxAbsStep: 10.;

Feasopt.MaxEval: 100;

Feasopt.MaxRelStep: 10.;

Feasopt.ObjFun: "Minimize";

Feasopt.OptTol: 1.e-004;

Gear.BoundCheck: "Track";

Gear.EventTol: 1.e-005;

Gear.HighestErrors: 0;

Gear.InitialStep: 0.;

Gear.JacUpdate: 0;

Gear.MaxCorIter: 5;

Gear.MaxCorSteps: 0;

Gear.MaximumStep: 0.;


Gear.MinimumStep: 0.;

Gear.Reinit: "Save";

Homotopy.Bounded: True;

Homotopy.Delta: 0.1;

Homotopy.HomotopyEnabled: False;

Homotopy.HomotopyType: "Newton";

Homotopy.InitialStep: 0.1;

Homotopy.MaximumStep: 1.;

Homotopy.MaxIters: 5000;

Homotopy.MaxRelStep: 1.;

Homotopy.MinimumStep: 1.e-002;

Homotopy.OnlyOnFail: True;

Homotopy.RelErr: 1.e-004;

Homotopy.StepDecrement: 0.5;

Homotopy.StepIncrement: 10;

Homotopy.WeightJac: False;

Homotopy.Write: False;

ImpEuler.Step: 1.e-002;

Integration.AbsErrorTol: 1.e-005;

Integration.AbsTearTol: 1.e-005;

Integration.DiscontinuityEventTol: 1.e-005;

Integration.EnforceMinStep: False;

Integration.IncSensErrors: False;

Integration.InitStepSize: 5.e-003;

Integration.ItplToComTime: True;

Integration.LocateIEvents: False;

Integration.MaxOrder: 5;

Integration.MaxStepSize: 1.;

Integration.MinStepSize: 1.e-003;

Integration.ProgID: "AspenTech.UnifiedIntegrator";

Integration.RcvTornVars: False;

Integration.ReInitAfterEE: False;

Integration.ReInitAfterIE: False;

Integration.RelErrorTol: 1.e-005;

Integration.RelTearTol: 1.e-005;


Integration.ShowHIErrors: 0;

Integration.ShowHTIErrors: 0;

Integration.StepRedFact: 0.5;

Integration.StepSize: 1.e-002;

Integration.StepSizeType: "Variable";

Integration.TestSAndAVars: False;

Integration.UsePrevAfterEE: False;

Integrator: "ImplicitEuler";

KeepCompiledEvaluationFiles: False;

LinearSolver: "MA48";

LogLikelihood.MaxIter: 100;

LogLikelihood.SolTol: 1.e-004;

MA48.DropTol: 0.;

MA48.PivotSearch: 3;

MA48.PivotTol: 0.;

MA48.ReanalyzeThreshold: 2.;

MA48.ReanalyzeWindow: 0;

MA48.Repivot: 0;

MA48.UseTranspose: 0;

MaxTearIter: 100;

Nl2sol.AbsFuncTol: 1.e-020;

Nl2sol.FalseConvTol: 0.;

Nl2sol.MaxIter: 50;

Nl2sol.RelFuncTol: 1.e-004;

Nl2sol.SolTol: 1.e-004;

NLASolver: "Standard";

Nonlinear.AbsPert: 1.e-005;

Nonlinear.BoundClip: 1.e-006;

Nonlinear.BoundFrac: 1.;

Nonlinear.ConvCrit: "Residual";

Nonlinear.Dogleg: False;

Nonlinear.HiResidual: 0;

Nonlinear.HiVarSteps: 0;

Nonlinear.MathsPrint: 0;

Nonlinear.MaxDivSteps: 10;


Nonlinear.MaxFastNewtonSteps: 5;

Nonlinear.MaxIter: 100;

Nonlinear.MaxStepRed: 10;

Nonlinear.MaxVarStep: 50.;

Nonlinear.Method: "Newton";

Nonlinear.RangeFrac: 0.;

Nonlinear.SingPert: 1.e-002;

OptimizationPrintLevel: "Medium";

Optimizer: 1;

PrintLevel: 2;

PropInfo: -1;

RelPerturb: 1.e-005;

RelTearTol: 1.e-005;

RelTol: 1.e-005;

RunMode: "Dynamic";

SaveFreeVariableValues: True;

Scaling: False;

SensErrorCheck: True;

SnapshotSettings.EnableMaximum: False;

SnapshotSettings.EnableonReinitialization: False;

SnapshotSettings.EnableRegularSnapshot: False;

SnapshotSettings.Interval: 2.;

SnapshotSettings.Maximum: -1;

SnapshotSettings.SaveConvergedOnly: True;

SnapshotSettings.TakeAutoSnapshots: True;

SyncSteps: "Full";

Tearing: "none";

TearUpdate: "Direct";

TimeSettings.CommunicationInterval: 0.1;

TimeSettings.CommunicationUnits: "Hours";

TimeSettings.DisplayUpdateInterval: 2000;

TimeSettings.EnablePauseAt: False;

TimeSettings.EnableStepFor: False;

TimeSettings.PauseAt: 0.;

TimeSettings.RealTimeSyncFactor: 0.;


TimeSettings.RecordHistory: True;

TimeSettings.StepFor: 0;

TimeSettings.TimeDisplayUnits: "Hours";

UseCompiledEvaluation: False;

UseSavedSnapshotOnLoad: True;

VSIE.AbsErrTol: 1.e-004;

VSIE.HighestErrors: 0;

VSIE.InitialStep: 0.1;

VSIE.Interpolation: True;

VSIE.MaxCorIter: 100;

VSIE.MaximumStep: 1.;

VSIE.MaxIncFact: 1.5;

VSIE.MinimumStep: 5.e-002;

VSIE.ReconvergeTorns: False;

VSIE.StepRedFact: 0.5;

VSIE.TearErrTol: 1.;

WatchGroup: 0;

WatchSubGroup: 0;

Wegstein.MaxAcceleration: 1000.;

Wegstein.MinAcceleration: -1000.;

OpenNLASolver: "";

OpenOPTSolver: "";

OpenESTSolver: "";

End


Optimization Contains values for all data entered on the Optimization dialog.

Example:

Optimization

IsDynamic : TRUE;

ElementSizeBoundsAutomatic : TRUE;

EndTime : 30;

Control.FinalTime_Initial : 30;

Control.FinalTime_IsFixed : TRUE;

Control.FinalTime_IsObjective : FALSE;

Control.Elements : 2;

Control.FixedInterval : TRUE;

Control.PiecewiseLinear : FALSE;

Control(0) : 2, 0.02, 4 ;

Control(1) : 2, 0.02, 4 ;

B1.CoolingRate : control;

Control(0).B1.CoolingRate : 0, 0, 1000;

Control(1).B1.CoolingRate : 0, 0, 1000;

Control.MaxMove.B1.CoolingRate : 1, FALSE;

B1.FeedRate : control;

Control(0).B1.FeedRate : 4, 0, 100;

Control(1).B1.FeedRate : 4, 0, 100;

Control.MaxMove.B1.FeedRate : 1, FALSE;

B1.Holdup_C : objective;

b1.temp : Dynamic, TRUE, TRUE, 1, 295, 300;

b1.temp@InteriorPoint(0) : TRUE, 1, 27, 5273;

End


Estimation Contains values for all data entered on the Estimation dialog.

Example:

Estimation

CalcHeteroParams : TRUE;

Reactor.RK1: 5;

Reactor.RK2: 1;

EXPERIMENT

Description: "experiment1";

Weight: 1;

IsDynamic: FALSE;

IsActive: TRUE;

Reactor.FLOW_IN("A"): 1,FIXED;

Reactor.FLOW_IN("B"): 9,FIXED;

Reactor.Output1.M("A"): 0.091887,1,-1,0;

Reactor.Output1.M("B"): 0.904,1,-1,0;

END

END

Homotopy Contains values for all data entered on the Homotopy dialog.

Example:

Homotopy

Enabled: TRUE;

Reactor.FLOW_IN("A"): 6;

Reactor.FLOW_IN("A2B"): 1;

Reactor.FLOW_IN("B"): 0.5;

End


SimulationAccessExtensions Contains values for all data entered on the Simulation Access Extensions dialog.

Example:

SimulationAccessExtension

CALL: SAXFunction;

LIBRARY: "C:\My Simulations\Modeler\SAX\phconsax";

EVENTS: After Step;

ENABLED: false;

OUTPUTS: {CST.Acid.flow};

End

Snapshot <name> There is 1 snapshot section per kept snapshot. The name is internal and should be unique in the input file. The Description is the name that you see in the Snapshots dialog. The section is terminated with END.

Example:

snapshot snap1

// Start of Snapshot Header Information. Please don't modify or move.

description : "Steady State";

solution_date : "27-04-2004 16:02:59";

Solution_Time :0.3 ;

Solution_Convergence :1 ;

Run_Number :1 ;

// End of Snapshot Header Information.

WITHIN global

Pi: 3.14200, FIXED;

ENDWITHIN;

WITHIN B1

WITHIN Tank1

Vol: 6.75000, FREE;

�

ENDWITHIN;

END


General Information 397

General Information

Copyright Version Number: 2004.1

April 2005

Copyright © 1982-2005 Aspen Technology, Inc, and its applicable subsidiaries, affiliates, and suppliers. All rights reserved. This Software is a proprietary product of Aspen Technology, Inc., its applicable subsidiaries, affiliates and suppliers and may be used only under agreement with AspenTech.

Aspen ACOL�, Aspen Adsim®, Aspen Advisor�, Aspen Aerotran®, Aspen Alarm & Event�, Aspen APLE�, Aspen Apollo Desktop�, Aspen Apollo Online�, Aspen AssetBuilder�, Aspen ATOMS�, Aspen Automated Stock Replenishment�, Aspen Batch Plus®, Aspen Batch.21�, Aspen BatchCAD�, Aspen BatchSep�, Aspen Calc�, Aspen Capable-to-Promise®, Aspen CatRef®, Aspen Chromatography®, Aspen Cim-IO for ACS�, Aspen Cim-IO for Csi VXL�, Aspen Cim-IO for Dow MIF�, Aspen Cim-IO for G2�, Aspen Cim-IO for GSE D/3�, Aspen Cim-IO for Hewlett-Packard RTAP�, Aspen Cim-IO for Hitachi PLC (H04E)�, Aspen Cim-IO for Intellution Fix�, Aspen Cim-IO for Melsec�, Aspen Cim-IO for WonderWare InTouch�, Aspen Cim-IO for Yokogawa Centum CS�, Aspen Cim-IO for Yokogawa Centum XL�, Aspen Cim-IO for Yokogawa EW3�, Aspen Cim-IO Interfaces�, Aspen Cim-IO Monitor�, Aspen Cim-IO�, Aspen Collaborative Demand Management�, Aspen Collaborative Forecasting�, Aspen Compliance.21�, Aspen COMThermo TRC Database�, Aspen COMThermo®, Aspen Cost Factor Manual�, Aspen Crude Manager�, Aspen Crude Margin Evaluation�, Aspen Custom Modeler®, Aspen Data Source Architecture�, Aspen Decision Analyzer�, Aspen Demand Manager�, Aspen DISTIL�, Aspen Distribution Scheduler�, Aspen DMCplus® Composite, Aspen DMCplus® Desktop, Aspen DMCplus® Online, Aspen DPO�, Aspen Dynamics®, Aspen eBRS�, Aspen Enterprise Model�, Aspen ERP Connect�, Aspen FCC®, Aspen FIHR�, Aspen FLARENET�, Aspen Fleet Operations Management�, Aspen Framework�, Aspen FRAN�, Aspen Fuel Gas Optimizer Desktop�, Aspen Fuel Gas Optimizer Online�, Aspen General Construction Standards�, Aspen Hetran®, Aspen HX-Net®, Aspen Hydrocracker®, Aspen Hydrotreater�, Aspen HYSYS Amines�, Aspen HYSYS Crude�, Aspen HYSYS Dynamics�, Aspen HYSYS OLGAS 3-Phase�, Aspen HYSYS OLGAS�, Aspen HYSYS OLI Interface�, Aspen HYSYS Tacite�, Aspen HYSYS Upstream Dynamics�, Aspen HYSYS Upstream�, Aspen HYSYS®, Aspen Icarus Process Evaluator®, Aspen Icarus


Project Manager®, Aspen InfoPlus.21®, Aspen Inventory Balancing�, Aspen IQ Desktop�, Aspen IQ Online�, Aspen IQmodel Powertools�, Aspen Kbase®, Aspen LIMS Interface�, Aspen Local Security�, Aspen LPIMS�, Aspen MBO�, Aspen MIMI®, Aspen MPIMS�, Aspen Multivariate Server�, Aspen MUSE�, Aspen NPIMS�, Aspen OnLine®, Aspen Operations Manager - Event Management�, Aspen Operations Manager - Integration Infrastructure�, Aspen Operations Manager - Peformance Scorecarding�, Aspen Operations Manager - Role Based Visualization�, Aspen Order Credit Management�, Aspen Orion Planning�, Aspen Orion�, Aspen PEP Process Library�, Aspen PIMS Blend Model Library�, Aspen PIMS Distributed Processing�, Aspen PIMS Enterprise Edition�, Aspen PIMS Mixed Integer Programming�, Aspen PIMS Simulator Interface�, Aspen PIMS Solution Ranging�, Aspen PIMS Submodel Calculator�, Aspen PIMS XNLP Optimizer�, Aspen PIMS�, Aspen PIPESYS�, Aspen PIPE�, Aspen Planning Accuracy�, Aspen Plant Planner & Scheduler�, Aspen Plant Scheduler Lite�, Aspen Plant Scheduler�, Aspen Plus OLI Interface�, Aspen Plus®, Aspen Polymers Plus®, Aspen PPIMS�, Aspen Process Data�, Aspen Process Explorer�, Aspen Process Manual�, Aspen Process Order�, Aspen Process Plant Construction Standards�, Aspen Process Recipe®, Aspen Process Tools�, Aspen Product Margin & Blending Evaluation�, Aspen Production Control Web Server�, Aspen ProFES® 2P Tran, Aspen ProFES® 2P Wax, Aspen ProFES® 3P Tran, Aspen ProFES® Tranflo, Aspen Properties®, Aspen Pumper Log�, Aspen Q Server�, Aspen RateSep�, Aspen RefSYS CatCracker�, Aspen RefSYS Spiral�, Aspen RefSYS�, Aspen Report Writer�, Aspen Resource Scheduling Optimization�, Aspen RTO Watch Cim-IO Server�, Aspen RTO Watch Server�, Aspen Scheduling & Inventory Management�, Aspen SmartStep Desktop�, Aspen SmartStep Online�, Aspen SQLplus�, Aspen Supply Chain Analytics�, Aspen Supply Chain Connect�, Aspen Supply Planner�, Aspen Tank Management�, Aspen TASC-Mechanical�, Aspen TASC�, Aspen Teams®, Aspen Terminals Management�, Aspen TICP�, Aspen Transition Manager�, Aspen Turbo PIMS�, Aspen Utilities�, Aspen Voice Fulfillment Management�, Aspen Watch Desktop�, Aspen Watch Server�, Aspen Water�, Aspen Web Fulfillment Management�, Aspen WinRace Database�, Aspen XPIMS�, Aspen Zyqad Development Version�, Aspen Zyqad�, SLM�, SLM Commute�, SLM Config Wizard�, the aspen leaf logo, and Plantelligence are trademarks or registered trademarks of Aspen Technology, Inc., Cambridge, MA.

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

This document is intended as a guide to using AspenTech's software. This documentation contains AspenTech proprietary and confidential information and may not be disclosed, used, or copied without the prior consent of AspenTech or as set forth in the applicable license.

Corporate

Aspen Technology, Inc. Phone: (1) (617) 949-1000

Ten Canal Park Toll Free: (1) (888) 996-7001

Cambridge, MA 02141-2201 Fax: (1) (617) 949-1030

USA URL: http://www.aspentech.com

http://www.aspentech.com/


Related Documentation Title Content

Aspen Custom Modeler 2004.1 Getting Started Guide

Contains basic hands-on tutorials to help you become familiar with Aspen Custom Modeler.

Aspen Custom Modeler 2004.1 Examples Guide Contains a general overview of ACM functionality and more complex and extensive examples of using Aspen Custom Modeler.

Aspen Custom Modeler 2004.1 Library Reference

Contains reference information on control models, property procedure types, utility routines, port types, and variable types.

Aspen Custom Modeler 2004.1 DMCplus® Controllers Interface

Contains information on using DMCplus with Aspen Custom Modeler or Aspen Dynamics�.

Aspen Custom Modeler 2004.1 Polymer Simulations with Polymers Plus

Polymers Plus is a layered product of Aspen Custom Modeler. It provides additional functionality to the properties package, Properties Plus, enabling polymers to be fully characterized in Aspen Custom Modeler models.

Technical Support 400

Technical Support

Online Technical Support Center AspenTech customers with a valid license and software maintenance agreement can register to access the Online Technical Support Center at:

http://support.aspentech.com

You use the Online Technical Support Center to:

• Access current product documentation.

• Search for technical tips, solutions, and frequently asked questions (FAQs).

• Search for and download application examples.

• Search for and download service packs and product updates.

• Submit and track technical issues.

• Search for and review known limitations.

• Send suggestions.

Registered users can also subscribe to our Technical Support e-Bulletins. These e-Bulletins proactively alert you to important technical support information such as:

• Technical advisories.

• Product updates.

• Service Pack announcements.

• Product release announcements.

http://support.aspentech.com/

Technical Support 401

Phone and E-mail Customer support is also available by phone, fax, and e-mail for customers who have a current support contract for their product(s). Toll-free charges are listed where available; otherwise local and international rates apply.

For the most up-to-date phone listings, please see the Online Technical Support Center at:

http://support.aspentech.com Support Centers Operating Hours

North America 8:00 � 20:00 Eastern time

South America 9:00 � 17:00 Local time

Europe 8:30 � 18:00 Central European time

Asia and Pacific Region 9:00 � 17:30 Local time

http://support.aspentech.com/

Index 402

Index

A

Absolute Checking Tolerance 177

Absolute Equation Tolerance 182

Absolute Integration Error Tolerance 194

Absolute Perturbation 216

Absolute tear tolerance 181

Absolute variable tolerance 182

Active set initialization parameters (DMO)

specifying 248

Active set initialization parameters (DMO): 248

ActiveDocument.Application 51

ActiveDocument.CloseAllForms 53

ActiveDocument.CreateLibrary 54

ActiveDocument.FullName 52

ActiveDocument.Name 52

ActiveDocument.Parent 52

ActiveDocument.Saved 53

ActiveDocument.SaveDocument 54

ActiveDocument.SaveDocumentAs 54

Application.Activate() 47

Application.ActiveDocument 43

Application.Caption 43

Application.CloseDocument() 47

Application.DefaultFilePath 43

Application.FullName 43

Application.Height 43

Application.Interactive 44

Application.Left 44

Application.Maximize() 47

Application.Minimize() 47

Application.Msg() 47

Application.Name 44

Application.NewDocument() 48

Application.OpenDocument() 48

Application.Path 44

Application.Quit() 49

Application.Restore() 49

Application.SaveDocument() 49

Application.SaveDocumentAs() 50

Application.Simulation 57

Application.StatusBar 45

Application.Top 45

Application.Version 45

Application.Visible 45

Application.Width 45

Applications

automation for 42

Asynchronous runs 169

available 401

B

BeginLongOperation method 108

Blocks

automation for 61, 95, 99

C

CACSD packages 314

CDI

automation for 150

overview 314

Check Procedure Derivatives 177

Index 403

CHEMISTRY physical properties calculation option 254

Clip Factor 217

Component lists

automation for 81

ComponentList.Components 81

ComponentList.IsComponentSet 82

ComponentList.Name 82

ComponentList.Option 83

ComponentList.OptionNames 83

Control Design Interface, overview 314

Control Panel output: 240

Controllers

deleting 360

Convergence Criterion 213

ConvertToBaseUOM and ConvertFromBaseUOM methods 127

CreateObject Visual Basic command 30

CreateScript method 112

CreateTask method 111

Creep mode (DMO)

using 243

Creep mode (DMO): 243

D

Data servers 343

DeleteScript method 112

DeleteTask method 112

Deleting

controllers 360

Derivative calculations

Check Procedure Derivatives option 177

Diagnostic information

Non-Linear Solver tab 214

Solver Reporting Level 176

Direct convergence method 180

DisableIncrementalUpdate command 24

DisableIncrementalUpdate method 107

Discontinuities

locating 197

Disturbances

locating 197

DMO Adv form

QP2 sheet 248

Search sheet 244

DMO Adv form: 244, 248

DMO Basic form

Basic sheet 231

Report sheet 240

DMO Basic form: 231, 240

DMO maximum number of allowed iterations

changing 231

DMO maximum number of allowed iterations: 231

DMO objective function convergence tolerance

changing 231

DMO objective function convergence tolerance: 231

DMO residual convergence tolerance

changing 231

DMO residual convergence tolerance: 231

DMO solver 235

applying a trust region 244

changing parameters 231

creep mode 243

handling infeasible solutions 235

handling singularities 236

scaling 235

troubleshooting 234

variable bounding 237

DMO solver parameters

active set initialization 248

control panel report 240

creep mode 243

micro-infeasibility handling 247

trust region 244, 245

DMO solver parameters: 231, 240, 243, 244, 246, 248

Index 404

DMO solver: 230, 231, 234, 235, 236, 237, 243, 244

Dogleg Method 214

Drop Tolerance

MA28 212

MA48 205

E

EditScript method 112

EditTask method 112

Eliminate Equivalence Equations 185

EnableIncrementalUpdate command 25

EnableIncrementalUpdate method 107

EndLongOperation method 108

Entry point routines 266

EO convergence 235

DMO solver 230, 231

DMO solver problems 234

scaling objective function 235

EO convergence: 230, 234

EO solver report

DMO 231

DMO basic iteration information 232

DMO constrained variables 233

DMO general iteration information 233

DMO largest unscaled residuals 232

DMO problem information 232

DMO shadow price 233

nonlinearity ratios (DMO): 234

EO solver report: 231, 232, 233, 234

Equation group

defining for diagnostics 176

Equivalence equations 185

Estimation simulations

accessing results 164

modeling language for 158

solver options 220

Event Tolerance 197

Exported flowsheets

modifying 364

Exporting

flowsheets to Aspen Plus 359

to Aspen Plus 352, 367

External data, accessing 343

External programs

calling from scripts 23

F

Fast Newton 212, 214

Files 231

DMO active bounds report (*.atact) 231

EO solver report (*.atslv) 231

FindMatchingVariables method 104

Flowsheets

automation for 110

exporting Aspen Dynamics to Aspen Plus 359

Forms

displaying using automation 108

FREE-WATER physical properties calculation option 254

G

Gear 196, 199

General option, Non-Linear Solver tab 212

General tab, Solver Properties dialog box 175

Generalized Physical Properties Interface routines 261

GetObject Visual Basic method 35

Getpath method 97

GetPath method 128

GetScriptText method 112

GetTaskText method 112

GetVariableValues method 104

Global method 106

GPPI routines 261

Index 405

H

HENRY-COMPS physical properties calculation option 255

Highest errors 196

Highest Residuals 215

Highest Variable Steps 215

History

automation method 120, 121

Homotopy

automation for 135

Homotopy simulations 219

Hybrid 212

I

Implicit Euler 191, 192

Indeterminate variables 196, 199

Initial Integration Step

Gear 196, 200

Integerset collection object 119

Integration step

Gear 197

Integration Step

Euler 191

Implicit Euler 191

VSIE 193

Integrator tab, overview 187

Integrators

differences between 187

Gear 196, 199

Implicit Euler 191, 192

VSIE 193

Invoke method 108

IsAlgebraicVariable method 128

IsControlSignal method 113

IsHidden method 129

IsInput method 129

IsOutput method 129

IsParameter method 129

IsStateVariable method 129

J

Jacobian Update Policy 197, 200

K

KBASE physical properties calculation option 257

Keep Solution within Bounds 198

L

LaunchCustomFormView method 108

LaunchFormView method 108

LaunchLibraryFormView method 108

Least squares option 220

Linear Solver tab, overview 205

Linear solvers

MA28 212

MA48 205

Log file 176

M

MA28 212

MA48 205

MATLAB 314

Maximum Approach to Bound 216

Maximum Corrector Iterations

Gear 198

VSIE 195

Maximum Divergent Steps 213

Maximum Eigenvalue 181

Maximum Fast Newton Steps 214

Maximum Integration Step

Gear 197

VSIE 193

Maximum Iterations 214

Maximum log likelihood option 223

Maximum Number of Tear Iterations 182

Maximum Range Fraction 215

Index 406

Maximum Step Increment Factor 194

Maximum Step Reductions 214

Maximum Variable Step 216

MAXIT physical properties calculation option 257

Method, non-linear solver 212

Micro-infeasibility handling (DMO)

using 246

Micro-infeasibility handling (DMO): 246

Minimum Eigenvalue 181

Minimum Integration Step

Gear 197

VSIE 193

Morari Resiliency Index 317

MRI 317

N

Name method 97, 129

Nelder-Mead Direct Search Solver 226

Initial simplex 227

Maximum iterations 227

Number of restarts 227

Optimization tolerance 227

Newton 212

NI 317

Niederlinski Index 317

NL2SOL 229

Non-linear solvers


Numerical Derivative Absolute and Relative Perturbation 183

O

objective function 235

changing the scale 235

OLL

overview 343

Online links

automation 143

overview 343

Online links variable object

automation 148

Open NLP - full space 229

Open NLP - reduced 229

Open non-linear algebraic equation solvers 218, 351

OPSET physical properties calculation option 254

Optimization simulations

automation for 137

OutputLogger.ClearWindow() 87

OutputLogger.FileOutput 84

OutputLogger.Height 85

OutputLogger.Left 85

OutputLogger.MessageCount 85

OutputLogger.Messages 85

OutputLogger.MessageText 86

OutputLogger.Path 86

OutputLogger.Print() 87

OutputLogger.ScreenOutput 86

OutputLogger.Top 86

OutputLogger.Width 86

OutputLogger.WriteFileHeader() 87

P

Parent method 129

pGibbs_Mol_Liq 303

pGibbs_Mol_Vap 305

Physical properties

entry point routines 266

GPPI routines 261

installing the physical properties interface 313

subroutines for property procedure types 274

Pivot Tolerance 205

Ports

automation for 103, 116

Index 407

Print Linear Algebra for Groups of Size Greater than or Equal to 215

Procedures

tearing 178

Properties


Properties Plus

calculation options for 253

Properties Reporting Level 176

Properties.AddComponentList() 80

Properties.ComponentList 79

Properties.ComponentListNames 79

Properties.LoadPropertiesFile() 80

Properties.RemoveComponentList() 81

Property method 129

R

RealVariables methods 133

Re-analyze FLOPS Window Size 206

Re-Analyze Threshold 205

Reconverge Torn Variables 195

Recorded history of variables 120, 121

Re-initialization Method 198

Relative Checking Tolerance 177

Relative Gain Array 316

Relative tear tolerance 181

Relative variable tolerance 182

RemoveControllers script 360

Re-pivot every n Factorizations 206

Reports 231

DMO active bound 231

EO solver report

DMO 231

Reset method 130

Resolve method 97

Results.AutoSnapshot 89

Results.CopyValues() 90

Results.Delete() 91

Results.FindResult() 92

Results.FindSnapshot() 92

Results.GetResult() 92

Results.GetSnapshot() 92

Results.GetSnapshot().Converged 92

Results.GetSnapshot().DateTime 93

Results.GetSnapshot().Description 93

Results.GetSnapshot().Export 93

Results.GetSnapshot().ExportasBinary 94

Results.GetSnapshot().RunNumber 94

Results.GetSnapshot().SimulationTime 94

Results.Import() 94

Results.Interval 88

Results.Limit 88

Results.Refresh() 94

Results.RegularSnapshot 89

Results.ResultCount 89

Results.Rewind() 95

Results.SnapshotCount 89

Results.TakeSnapshot() 95

RETENTION physical properties calculation option 258

RGA 316

S

SAX, overview 332

Scaling 184

Scripts

basic examples 22

calling external applications 23

improving the speed of 24

invoking 106

syntax for 21

Sensitivities 73, 75

Server Busy dialog box 108

Set attributes 119

Show Highest Corrector Steps 198

Show Highest Integration Errors 195, 196

Simulation Access eXtensions, overview 332

Simulation Messages window

Index 408

automation for 84

controlling level of detail in 176

Simulation.AddSensitivityParameter() 73

Simulation.AddSensitivityVariable() 73

Simulation.ClearSensitivities() 73

Simulation.Correlation 58

Simulation.CorrelationMatrix 58

Simulation.CorrelationMatrixPresent 59

Simulation.Covariance 59

Simulation.CovarianceMatrix 59

Simulation.CovarianceMatrixPresent 59

Simulation.CreateLibrary() 74

Simulation.Degrees 59

Simulation.DeviationArrayPresent 60

Simulation.DisableSensitivities() 75

Simulation.DisplayTime 60

Simulation.EnableSensitivities() 75

Simulation.EndStepCount 60

Simulation.EndTime 60

Simulation.Equations 61

Simulation.EstimationRunState 61

Simulation.Flowsheet 61

Simulation.FullName 62

Simulation.GetSensitivityValue 75

Simulation.Interrupt() 76

Simulation.LaunchFormView 76

Simulation.Name 62

Simulation.Options... 62

Simulation.Pause() 76

Simulation.Properties 68

Simulation.Reset() 77

Simulation.ResetEstimation() 77

Simulation.Restart() 77

Simulation.Results 68

Simulation.Run() 77

Simulation.RunMode 68

Simulation.RunNumber 68

Simulation.Saved 69

Simulation.SpecState 69

Simulation.State 69

Simulation.Step() 79

Simulation.Successful 70

Simulation.Termination 71

Simulation.Time 71

Simulation.Variables 71

Simulations

accessing estimation results 164

automation for 57

estimation modeling language 158

Singularity Perturbation 216

Snapshots

automation for 88

SOLU-WATER physical properties calculation option 256

Solver properties

for Estimation runs 220

Solver Reporting Level

described 176

Solver Scaling 184

Solver Searches n Columns for Pivots 206, 207

Speed of simulation

Euler 191

Implicit Euler 191

SRQP solver 228

Feasibility improvements 228

Hessian scaling 228

Maximum iterations 229

Optimization tolerance 229

Print level 229

Variable initialisation policy 229

State Transition Matrix 317

STM 317

Streams


Stringset collection object 119

Synchronous runs 169

Index 409

T

Tasks

automation for 134

Tear Integration Error Tolerance 194

Tear Update Strategy 180

Tearing

Solver Options dialog box 178

Time history of variables 120, 121

TOLERANCE physical properties calculation option 257

Tolerances

absolute and singularity perturbation 216

absolute equation tolerance 182

General tab in Solver Properties dialog box 182

Maximum Variable Step 216


tear 181

variable 182

variable change 183

TRUE-COMP physical properties calculation option 255

Trust region (DMO)

applying 244

Trust region (DMO): 244

TypeName method 97, 130

U

UpdateVariables method 105

Use Interpolation 195

V

ValidValues method 130

Variable Change Tolerance 183

Variable object 118

Variable.Units 118

Variables

automation for 118

VSIE integrator 193

W

Watch Group 176

Watch Torn Sub-Group 177

Wegstein convergence method 180

WorkingFolder 46

Index 410