Professional Documents
Culture Documents
Modeler 2004.1
Aspen Modeler Reference Guide
Who Should Read this Guide
Contents 3
Using the GetObject Method .................................................................................... 35
Example of Using GetObject ............................................................................... 36
Contents 4
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
Contents 5
Using Synchronous Runs ........................................................................................169
Synchronous Run Example ................................................................................169
Using Asynchronous Runs ......................................................................................170
Asynchronous Run Example ...............................................................................171
Contents 6
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
Contents 7
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 8
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
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 9
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
Contents 10
Modifying an Exported Flowsheet.............................................................................364
Licensing of Exported Flowsheets ............................................................................365
Distributing the Exported Flowsheet to Aspen Plus Users.............................................365
Contents 11
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 12
Contents 13
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.
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.
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
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.
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
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:
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
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.
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.
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
DisableIncrementalUpdate
C1.Ntrays = 21
C2.Ntrays = 48
C3.Ntrays = 16
C4.Ntrays = 17
EnableIncrementalUpdate
FeedStream.F = 10.0
Application.Simulation.RunMode = "Steady State"
Application.Simulation.Run(True)
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.
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
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)
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:
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
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
Property Returns
p1.Resolve A specified object
Lastly, note that the Item keyword is optional in Visual Basic® so this
expression is equivalent to:
Simulation.Flowsheet.Blocks("b1")
Simulation.Global.vrbname
where vrbname is the name of the required variables.
For more information on Resolve, see Resolve Method.
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.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"
Running external Microsoft® Visual Basic®:
label1.caption = ACMApp.Caption
Application.DefaultFilePath
Returns the file path name that is initially available on a File / Open...
operation.
Example
Running a script from Flowsheet or Model:
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
Running a script from Flowsheet or Model:
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
Running a script from Flowsheet or Model:
Application.Height = 400
Running external Microsoft® Visual Basic®:
Application.Interactive
Sets whether the user can interact with the GUI. Takes a logical value of True
and False.
Example
Running a script from Flowsheet or Model:
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
Running a script from Flowsheet or Model:
Application.Left = 30
Running external Microsoft® Visual Basic®:
Label1.Caption = ACMApp.Left
Application.Name
Returns the current name of the application.
Example
Running a script from Flowsheet or Model:
Dim CurrentName
CurrentName = Application.Name
Application.Path
Returns the path to the current application.
Example
Running a script from Flowsheet or Model:
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.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
Running a script from Flowsheet or Model:
Application.Top = 10
Running external Microsoft® Visual Basic®:
Label1.Caption = ACMApp.Top
Application.Version
Returns the version of the application. Read-only string.
Example
Running external Microsoft® Visual Basic®:
Label1.Caption = ACMApp.Version
Application.Visible
You can make the GUI visible or invisible. Can be either True or False.
Example
Running external Microsoft® Visual Basic®:
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
Running a script from Flowsheet or Model:
Application.Width = 600
Running external Microsoft® Visual Basic®:
Label1.Caption = ACMApp.Width
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.Activate()
Brings the application's main window to the front and gives it keyboard focus.
Example
Running external Microsoft® Visual Basic®:
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.
Example
Running external Microsoft® Visual Basic®:
ACMApp.CloseDocument(True)
Application.Maximize()
Makes the application's main window occupy the full screen.
Example
Running external Microsoft® Visual Basic®:
ACMApp.Maximize
Application.Minimize()
Iconizes the application's window.
Example
Running external Microsoft® Visual Basic®:
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.
Application.Msg Application.Simulation.RunMode
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().
Example
Running external Microsoft® Visual Basic®:
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().
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
From external Microsoft Visual Basic:
Dim ProcIDs
Application.Quit()
Quits the current session.
Example
Running external Microsoft® Visual Basic®:
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
Running external Microsoft® Visual Basic®:
ACMApp.Restore
Application.SaveDocument()
Saves the currently open simulation document under its existing name.
Example
Running external Microsoft® Visual Basic®:
Dim ACMApp as Object
Set ACMApp= CreateObject("ACM Application")
ACMApp.visible=true
ACMApp.OpenDocument("d:\test\simulation01.acmf")
' other work occurs here…
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
Running external Microsoft® Visual Basic®:
Dim ACMApp as Object
Set ACMApp= CreateObject("ACM Application")
ACMApp.visible=true
ACMApp.OpenDocument("d:\test\simulation01.acmf")
' other work occurs here…
' 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:
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
Running a script from Flowsheet or Model:
Dim ACMApp
Set ACMApp= ActiveDocument.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
Running a script from Flowsheet or Model:
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
Running a script from Flowsheet or Model:
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
Running a script from Flowsheet or Model:
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.FlowsheetWallpaperMode
This Boolean property controls if the flowsheet will be set as the wallpaper
background of the application or as a floating window.
Example
Running a script from Flowsheet or Model:
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
ActiveDocument.CreateLibrary()
Creates a library with the path supplied by its one string argument. The file
name must end with the extension .acml.
Example
Running external Microsoft® Visual Basic®:
Dim ACMApp as Object
Dim ACMDoc as Object
Set ACMApp= CreateObject("ACM Application")
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
Running external Microsoft® Visual Basic®:
Dim ACMApp as Object
Dim ACMDoc as Object
Set ACMApp= CreateObject("ACM Application")
ACMApp.visible=true
Set ACMDoc=ACMApp.OpenDocument("d:\test\simulation01.acmf")
' other work occurs here…
' 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.
• After the document has been saved using this function the
new path becomes the default path for future calls to the
SaveDocument method.
Example
Running external Microsoft® Visual Basic®:
Dim ACMApp as Object
Dim ACMDoc as Object
Set ACMApp= CreateObject("ACM Application")
ACMApp.visible=true
Set ACMDoc=ACMApp.OpenDocument("d:\test\simulation01.acmf")
' other work occurs here…
' 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
Running a script from Flowsheet or Model:
Application.ActiveDocument.LaunchExplorer 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
Running a script from Flowsheet or Model:
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
Running a script from Flowsheet or Model:
Application.ActiveDocument.ShowMessagesWindow 180,497,840,124
Form Object
The following properties are available for the Form object:
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.
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.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
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).
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
Running external Microsoft® Visual Basic®:
Label1.Caption = ACMApp.Simulation.Degrees
Running a script from Flowsheet or Model:
IF Application.Simulation.Degrees < 0 THEN
B1.Input1.Flow.Spec = "Fixed"
ENDIF
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
Running external Microsoft® Visual Basic®:
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:
Example
Running a script from Flowsheet or Model:
Application.Simulation.EndStepCount = 50
Application.Simulation.Termination = "AtTime"
Running external Microsoft® Visual Basic®:
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:
Example
Running a script from Flowsheet or Model:
Application.Simulation.EndTime = 100.0
Application.Simulation.Termination = "AtTime"
Running external Microsoft® Visual Basic®:
Label1.Caption = ACMApp.Simulation.EndTime
Simulation.Equations
Returns the total number of equations in the simulation.
Example
Running external Microsoft® Visual Basic®:
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
Running external Microsoft® Visual Basic®:
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
Running external Microsoft Visual Basic:
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
Running external Microsoft Visual Basic:
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
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.
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.DiscontinuityEvent Discontinuity event tolerance [was
Tol 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
Property Explanation
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
Property Explanation
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("PrintLe
vel") = 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
Property Explanation
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
OpenNLPEstSolverPar Set or get this property to read/write to the OpenNLPEstSolver
ameters.Item("Param parameter "param".For
") example:OpenNLPEstSolverParameters.Item("PrintLevel") = 1 'Set
Timesettings Properties
Property Explanation
TimeSettings. Specifies the communication interval at which data is
CommunicationInterval available for plotting and snapshots
TimeSettings.DisplayUpdateInterva Specifies the interval at which data is updated on
l 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"
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
Running a script from Flowsheet or Model:
Application.Simulation.RunMode = "Dynamic"
Running external Microsoft® Visual Basic®:
Label1.Caption = ACMApp.Simulation.RunMode
Simulation.RunNumber
This read-only property returns the run number of the current simulation.
Example
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
Running a script from Flowsheet or Model:
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
From external Microsoft Visual Basic:
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
Running external Microsoft® Visual Basic®:
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
Running external Microsoft® Visual Basic®:
Simulation.Successful
Returns whether the previous simulation run or step is successfully
converged. Returns a logical value, True or False.
Example
Running a script from Flowsheet or Model:
Sub RunTestSimulation()
Dim ACMobj As Object
Set ACMobj = GetObject("d:\test.acmf")
ACMobj.Application.Visible = True
errorhandler:
MsgBox "default error handler."
End Sub
Simulation.Time
This read-only property returns the current simulation time in communication
units. See also Simulation.DisplayTime.
Example
Running external Microsoft® Visual Basic®:
label1.caption = ACMApp.Simulation.Time
Simulation.Variables
This read-only property returns the total number of active variables in the
simulation.
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()
See the Modeling Language Reference, Chapter 2, Defining an Estimation
Simulation.
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.
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.
Example
From external Microsoft® Visual Basic®:
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
From external Microsoft® Visual Basic®:
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.
Simulation.CloseAllForms
You can close all forms open in the application
Example
Running a script from Flowsheet or Model:
Application.Simulation.CloseAllForms
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
Running a script from Flowsheet or Model:
Application.Simulation.CreateLibrary("C:\project2\heaters.a
cml")
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
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
From external Microsoft® Visual Basic®:
ACMApp.Simulation.DisableSensitivities
Simulation.EnableSensitivities()
You can re-activate the variables you previously de-activated in the current
simulation.
Example
From external Microsoft® Visual Basic®:
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”)
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
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
From external Microsoft® Visual Basic®:
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
Running a script from Flowsheet or Model:
Application.Simulation.LaunchFormView("Plot1")
Application.Simulation.LaunchFormView("B1.FeederTable")
Simulation.NewExperiment()
See the Modeling Language Reference, Chapter 2, Defining an Estimation
Simulation.
Simulation.Pause()
You can pause a simulation.
Example
Running a script from Flowsheet or Model:
Application.Simulation.Pause
Simulation.Reset()
You can return the current simulation to the default values of all the
variables. Optional logical argument specifies what will be 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
Running a script from Flowsheet or Model:
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
errorhandler:
MsgBox "default error handler."
End Sub
Properties Object
Properties and methods are available for the Properties object.
Properties.ComponentList
This property returns a componentlist object specified by name.
Example
Running external Microsoft® Visual Basic®:
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
Running external Microsoft® Visual Basic®:
Dim objPhysProps
Set objPhysProps= ACMApp.simulation.Properties
' populate list box with names of componentlists
Dim Components
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
Running external Microsoft® Visual Basic®:
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
Running external Microsoft® Visual Basic®:
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
Running external Microsoft® Visual Basic®:
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
Running external Microsoft® Visual Basic®:
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
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
Running external Microsoft® Visual Basic®:
'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
Running external Microsoft® Visual Basic®:
Dim objPhysProps
Set objPhysProps= ACMApp.simulation.Properties
Set objComponentList =
objPhysProps.ComponentList("CompList")
MsgBox "Name: " & objComponentList.Name
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
Running external Microsoft® Visual Basic®:
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")
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
OutputLogger.FileOutput
Returns or sets whether run-time output is sent to file.
Example
Running a script from Flowsheet or Model:
IF Application.Simulation.OutputLogger.FileOutput = False
THEN
Application.Simulation.OutputLogger.FileOutput = True
ENDIF
OutputLogger.Left
Sets the horizontal coordinate of the Simulation Messages window.
Example
Running a script from Flowsheet or Model:
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
Running a script from Flowsheet or Model:
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
Running a script from Flowsheet or Model:
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.Path
Sets the path name for the logging file.
Example
Running a script from Flowsheet or Model:
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
Running a script from Flowsheet or Model:
Application.Simulation.OutputLogger.ScreenOutput = True
OutputLogger.Top
Sets the vertical coordinate of the Simulation Messages window.
Example
Running a script from Flowsheet or Model:
Application.Simulation.OutputLogger.Top = 45
OutputLogger.Width
Sets the width of the Simulation Messages window.
Example
Running a script from Flowsheet or Model:
Application.Simulation.OutputLogger.Width = 150
OutputLogger.ClearWindow()
You can clear the text from the Simulation Messages window.
Example
Running a script from Flowsheet or Model:
Application.Simulation.OutputLogger.ClearWindow
OutputLogger.Print()
You can send the contents of the Simulation Messages window to your default
printer.
Example
Running a script from Flowsheet or Model:
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 Then
is
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.
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
Running a script from Flowsheet or Model:
Application.Simulation.Results.Interval = 2.0
Running external Microsoft® Visual Basic®:
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
Running a script from Flowsheet or Model:
Application.Simulation.Results.Limit = 20
Running external Microsoft® Visual Basic®:
Label1.Caption = ACMApp.Simulation.Results.Limit
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
Running external Microsoft® Visual Basic®:
Label1.Caption = ACMApp.Simulation.Results.ResultCount
Results.SnapshotCount
Returns the number of snapshots that are available for the current simulation.
Example
Running external Microsoft® Visual Basic®:
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
Running a script from Flowsheet or Model:
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.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
Running a script from Flowsheet or Model:
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:
To copy the values of all the variables in the same way as the
CopyValues button on the Snapshot Management dialog, use:
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.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
Running a script from Flowsheet or Model:
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
Running a script from Flowsheet or Model:
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
Running a script from Flowsheet or Model:
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
Results.GetSnapshot().DateTime
Returns at what date and time a selected snapshot (or result, if GetResult is
used) was taken.
Example
Running external Microsoft® Visual Basic®:
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
Running external Microsoft® Visual Basic®:
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().RunNumber
Returns the run number for the selected snapshot (or result, if GetResult is
used).
Example
Running external Microsoft® Visual Basic®:
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
Running external Microsoft® Visual Basic®:
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
Running a script from Flowsheet or Model:
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
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.
Example
Running a script from Flowsheet or Model:
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
Running a script from Flowsheet or Model:
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
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
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
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.
acmObj.Application.Visible = True
For i = 1 To 10
Else
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
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”
Method or Description
Property
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
Method or Description
Property
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
Method or Description
Property
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
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.
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
From external Microsoft® Visual Basic®:
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)
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:
Method Description
DisableIncrementalUpdate Call this to stop incremental updates
EnableIncrementalUpdate Call this to enable incremental updates
B1.PropMode = "Local"
B2.NStages = 10
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"
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.
Example:
The following script prints the variables selected on table "Results" from block
B1.
VariablesPaths Property
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.
Forms Property
Forms property is the collection of forms of the parent object.
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()
Method Description
AddBlock([string] BlockType, Add a block of type BlockType to the
[optional, string] BlockName) 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, Add a stream of type StreamType to the
[optional, string] StreamName) 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] Removes the block BlockName from the
BlockName) flowsheet.
RemoveStream([string] Remove the stream StreamName from
StreamName) the flowsheet.
IsValidBlockName([string] Returns true if BlockName can be used as
BlockName) a valid name for a new block.
IsValidStreamName([string] Returns true if StreamName can be used
StreamName) 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
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
From a script at Flowsheet level:
DeleteTask "Task1"
EditTask(Taskname, TaskText)
Replaces the language text of TaskName with TaskText and recompiles.
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.
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.
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
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
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
Method Description
CanConnectInput ([string] True if the streams input can be connected
BlockPortName) to the named block port
ConnectInput ([string] Connects the stream input to the named
BlockPortName) block port
DisconnectInput() Disconnects the stream input
CanConnectOutput ([string] True if the streams output can be connected
BlockPortName) to the named block port
ConnectOutput ([string] Connects streams output can be connected
BlockPortName) to the name block port
DisconnectOutput() Disconnects the stream output
Method Description
CanConnectInput ([string] Returns true if the control signals input can be
VariablePath, [optional, connected to the named variable via the
string] ControlPort) specified control port. If the control port is not
specified then the default control port will be
used.
ConnectInput ([string] Connects the control signal input to the named
VariablePath, [optional, variable via the specified control port. If the
string] ControlPort) control port is not specified the default control
port will be used.
DisconnectInput() Disconnects the control signals input.
CanConnectOutput([string Returns true if the control signals output can be
] VariablePath, [optional, connected to the named variable via the
string] ControlPort) specified control port. If the control port is not
specified then the default control port will be
used.
ConnectOutput ([string] Connects the control signal output to the
VariablePath, [optional, named variable via the specified control port. If
string] ControlPort) the control port is not specified the default
control port will be used.
DisconnectOutput() Disconnects the control signals output.
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
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")
The current display units for a variable can be accessed via the units string
property, for example:
e.g. b1.x.history.interval
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
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.
History.Interval
Returns the value of the time interval which was set when the variable history
was created. It is read-only property.
Example
set hx = B1.x.history
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
set hx = B1.x.history
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
Example
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
set hx = B1.x.history
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)
' composition
for istage = 1 to Blocks(blockname).nstage.value
for each c in comps
' liquid mole fractions
icol = icol + 1
excel.worksheets("Sheet1").Cells(1,icol).Value = "x " &
Cstr(c)
excel.worksheets("Sheet1").Cells(2,icol).Value = istage
irow = 0
for each point in
Blocks(blockname).stage(istage).x(c).history
irow = irow + 1
excel.worksheets("Sheet1").Cells(irow+2,icol).Value =
point
next
' vapor mole fractions
icol = icol + 1
excel.worksheets("Sheet1").Cells(1,icol).Value = "y " &
Cstr(c)
excel.worksheets("Sheet1").Cells(2,icol).Value = istage
irow = 0
for each point in
Blocks(blockname).stage(istage).y(c).history
irow = irow + 1
excel.worksheets("Sheet1").Cells(irow+2,icol).Value =
point
next
next
next
Example 2: Aspen Custom Modeler
BaseTypeName
The BaseTypeName method returns the name of the base type of the
variable.
Example:
The following example shows the use of the TypeName method:
Str = Blocks("Reactor").T.BaseTypeName 'result is
"RealVariable"
DefaultValue Method
This method returns the default value of the variable
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”.
GetPath Method
The following method returns the full path for the variable, for example,
"b1.in_p.F("CO")":
GetPath: result string
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
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
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
cbo.Clear
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.
Example
External Microsoft® Visual Basic® fragment:
Dim coll As Object
Dim s As Variant
cbo.Clear
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”
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
From external Microsoft® Visual Basic®:
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
From external Microsoft® Visual Basic®:
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
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.
Example
From a script at Flowsheet level:
if Task1.active then
MsgBox "Task Active"
else
MsgBox "Task Inactive"
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 Methods
application.msg "Variable 1 is " &name
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
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.
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.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
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
Example
dim Handle1
Optimization.AddDynVariable "UNI1.temp", TRUE, 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
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"
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.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
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
Example
dim Handle1
Optimization.AddDynVariable "UNI1.temp", TRUE, Handle1
Optimization.SetDynVariableParams "UNI1.temp", TRUE, 5,
TRUE, 0.5, 2.0, Handle1
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
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.
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
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
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")
RemoveOutputVariable
This function removes a variable from the OLL Output variable list, specified
by the simulation variable’s name.
Example
OLL.RemoveOutputVariable "b1.alpha"
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
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 var = OLL.FindInputVariable("b1.theta")
'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 var = OLL.FindOutputVariable("b1.alpha")
'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 var = OLL.FindInputVariable("b1.theta")
'Set conversion units to millimeters
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
Set var = OLL.FindOutputVariable("b1.alpha")
Var.NoiseStandardDeviation = 0.03
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
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.
Example
StepResponseMaxIntervals = maxint
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
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()
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"
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.
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()
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.
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.
Application.Simulation.AddEstimateVariable "Reactor1.RK1"
Application.Simulation.AddEstimateVariable "Reactor1.RK2"
ThisExp.ADDSSMEASUREPOINT "BlockName.VariableName",
MeasuredValue, MeasurementWeight
:
ThisExp.SETWEIGHT ExperimentWeight
APPLICATION.SIMULATION.ADDEXPERIMENT(ThisExp)
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.NewExperiment("Experiment2","Steady
State")
SSExpt2.AddFixedPoint "Rctr1.In1.Flow(""ReagentA"")", 2.0
SSExpt2.AddFixedPoint "Rctr1.In1.Flow(""ReagentB"")", 8.0
SSExpt2.AddSSMeasurePoint "Rctr1.Out1.x(""ReagentA"")",
0.179, 10.0
SSExpt2.AddSSMeasurePoint "Rctr1.Out1.x(""ReagentB"")",
0.808, 1.0
Application.Simulation.AddExperiment(SSExpt1)
Application.Simulation.AddExperiment(SSExpt2)
ThisExp.ADDDYNMEASUREPOINT "BlockName.VariableName",
MeasurementTime, MeasuredValue, MeasurementWeight
:
ThisExp.AddFixedRampPoint "BlockName.VariableName",
FixedTimeValue, FixedValue
:
ThisExp.ADDINITIALPOINT "BlockName.VariableName",
InitialValue
:
ThisExp.ADDRATEINITIALPOINT "BlockName.VariableName",
RateInitialValue
:
ThisExp.SetWeight ExperimentWeight
APPLICATION.SIMULATION.ADDEXPERIMENT(ThisExp)
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
DynExpt1.AddDynMeasurePoint "Rctr1.x(""CH3OH"")", 0.3333,
0.038, 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
DynExpt2.AddDynMeasurePoint "Rctr1.x(""CH3OH"")", 0.1667,
0.008, 1.0
DynExpt2.AddDynMeasurePoint "Rctr1.x(""CH3OH"")", 0.3333,
0.015, 1.0
DynExpt2.AddDynMeasurePoint "Rctr1.x(""CH3OH"")", 0.5000,
0.029, 1.0
Application.Simulation.AddExperiment(DynExpt1)
Application.Simulation.AddExperiment(DynExpt2)
SET SSExpt1 = _
Application.Simulation.NewExperiment("Experiment1","Steady
State")
SSExpt1.AddFixedPoint "Rctr1.In1.Flow(""ReagentA"")", 1.0
SSExpt1.AddFixedPoint "Rctr1.In1.Flow(""ReagentB"")", 9.0
Application.Simulation.ResetEstimation
Application.Simulation.AddExperiment(SSExpt1)
Dim EstVal1
EstVal1 = Application.Simulation.EstimatedValue("Rctr.K1")
Application.Msg "Estimated value for K1 is " +
Cstr(EstVal1)
Dim StdDev
StdDev = Application.Simulation.Deviation("Reactor.K1")
Application.Msg "The standard error for K1 is " +
Cstr(StdDev)
Dim Corr
SET Corr = Application.Simulation.Correlation
("Reactor.K1", _
"Reactor.K2")
Application.Msg "Correlation between K1 and K2 is " +
Cstr(Corr)
Dim Corr
IF Application.Simulation.CorrelationMatrix Present = True
THEN
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.
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.
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.
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.
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).
Where
XK = Procedure derivative value calculated
numerically by Aspen Modeler
YK = 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.
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.
Procedure Tearing
You can set Procedure Tearing to the following options:
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.
Strategy Action
Direct Uses direct substitution
Wegstein Uses Wegstein acceleration
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.
Where:
X = Tested variable
The default values for the Relative and Absolute Variable Tolerances of 1E-5
are suitable for most simulations.
or
X new − X old > ChangeTol IF X new < ChangeTol
Where:
Error! = Latest value of a fixed variable
Objects
cannot be
created
from
editing
field
codes.
Error! = Value of a fixed variable at the previous
Objects integration step
cannot be
created
from
editing
field
codes.
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.
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.
Notes:
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.
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.
When you have decided on the appropriate integrator, click the Name box to
select the integrator.
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.
Integrator Default
Explicit Euler, RUNGE KUTTA 4, 5
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.
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)
Notes:
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.
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:
2
1 N x(i ) − x p (i )
≤1
∑
N i =1 RTOL x0 (i ) + ATOL
(1)
and, when there are torn procedures in the ACM flowsheet and procedure
tearing is set to update [2], if
2
1 N θ (i ) − θ 0 (i )
N
∑
≤1
i =1 RtearTOL θ 0 (i ) + AtearTOL
(2)
where:
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.
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
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.
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:
x(i ) − x 0 (i )
RTOL θ 0 (i ) + ATOL
used in the integration error norm over all variables contributing to the error
test,
where:
x : corrected state and algebraic variables at time t
x0 : 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.
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
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
Name Description
Print Level Level of detail to print
Scale Matrix Scale matrix using MC29
UseTranspose Use matrix transpose for factorization
BlockTriangularizati Pre-order matrix to block triangular form
on
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
FrontalAmalgamatio Control how much frontal matrix can grow
n 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
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.
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.
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
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.
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: 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.
Convergence Description
Criterion
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
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.
– or –
SingPerturb ∗ X IF X 〉 AbsPerturb
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.
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
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
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:
Homotopy Options
This section describes the options on the Homotopy tab of the Solver
Properties dialog box.
Cause Action
The experiments are Do one of the following:
not being calculated • Increase the Relative Function Tolerance
accurately enough to and the Solution Convergence Tolerance. To
satisfy solution change these tolerances, in the Simulation
tolerances. Explorer make sure Simulation is selected and
then in the Contents pane double-click Solver
Options and then click the Estimator tab.
– or –
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.
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
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.
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.
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.
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
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
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.
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.
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.
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
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.
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
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).
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
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
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.
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,
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.
+---------------------------------------------------+
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
The diagnostic printing frequency for variables and residuals, where variables
are residuals are printed at every nth iteration. The default is -1.
Lets you select the method for terminating the optimization moves while
closing any remaining residuals.
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.
Flag controlling the amount of information printed in the OUT file as a result
of an infeasible QP problem.
Lets you specify whether to report all bounds in the active file.
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);
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.
Flag that controls the reporting of the active set at the end of iteration zero.
It is written to the <prob>.out file.
Lets you select a re-analysis frequency, which determines the Jacobian pivot
reanalysis strategy.
Lets you specify whether to enable the dropping of small Jacobian non-zeros.
Lets you specify whether to include free variables (i.e. those not fixed or a
constant) when solving the problem.
Lets you specify whether to enable diagnostic printing for linear algebra.
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.
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.
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
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
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:
Default Value
The default value is 3.
Valid Values
Valid values for KBASE are:
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.
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
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.
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
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.
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.
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)
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)
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:
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)
OPTVAL C*(*) MAXVAL, OPTion VALues for the options in each component
NOCLIS list
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
Definition
The argument list of GPP_OPTIONS is:
SUBROUTINE GPP_OPTIONS (PROP_LEVEL, IFAIL)
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)
If you generate a template for your procedure code, suitable symbolic values
are defined for you to use in your code.
PROCEDURE pEnth_Mol_Liq
// Specific Liquid Molar Enthalpy with Analytic Derivatives
CALL : gpidlhx;
LIBRARY : "gpp.dll";
IMPLEMENTATION : SUBROUTINE;
LANGUAGE : FORTRAN;
OPTIONS : PROPERTIES, DERIVATIVES;
INPUTS : Temperature, Pressure, Molefraction(*);
OUTPUTS : enth_mol;
END;
The corresponding fortran entry point subroutine headings are in the form:
SUBROUTINE <subroutine_name> (<input_var1> [, <input_var],
<output_var> [, <output_var1>, IFLAG, ICLST)
To use with Aspen Modeler products, you need to generate a standard fortran
wrapper routines for a C calling program from ACM Executive.
PROCEDURE pEnth_Mol_Liq
// Specific Liquid Molar Enthalpy
CALL : gpilhx;
LIBRARY : "gpp.dll";
IMPLEMENTATION : SUBROUTINE;
LANGUAGE : FORTRAN;
OPTIONS : PROPERTIES;
INPUTS : Temperature, Pressure, Molefraction(*);
OUTPUTS : enth_mol;
END;
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)
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
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)
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)
pCp_Mol_Liq
Purpose
Liquid specific heat capacity at constant pressure with analytic derivatives
Subroutine
GPIDLCP
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)
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)
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)
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)
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
pDens_Mass_Vap
Purpose
Stream vapor mass density with analytic derivatives.
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)
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)
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
pDens_Mol_Vap
IFLAG M Error flag
ICLST I Integer value for component list
Purpose
Vapor molar density with analytic derivatives
Subroutine
GPIDVMX
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
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)
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)
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
pEnth_Mol_Liq
Purpose
Liquid specific enthalpy with analytic derivatives
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)
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
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)
pEntr_Mol
Purpose
Mixed phase specific molar entropy
Subroutine
GPI2SX
Definition
The argument list for GPI2SX is:
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)
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
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)
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)
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)
pFlashPV
Purpose
Two phase flash at fixed pressure and vapor fraction
Subroutine
GPI2PV
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)
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)
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
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
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
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
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
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)
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)
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)
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)
pGibbs_Mol_Liq
Purpose
Liquid molar Gibbs free energy with analytic derivatives
Subroutine
GPIDLGX
Definition
The argument list for GPIDLGX is:
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
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)
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)
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)
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
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
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)
pSurf_TensY
Purpose
Surface tension using vapor and liquid mole fractions
Subroutine
GPILTXY
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
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
pTrueCmpVLS
Purpose
V, L & S species composition of an electrolyte mixture
Subroutine
GPITRVLS
Definition
The argument list for GPITRVLS is:
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)
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)
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)
– 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.
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.
dX
f t, , X , Z, U = 0
dt
Where:
t = Time, the independent variable
X = A vector of the variables whose time derivatives
appear in the model:
dX
dt
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.
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
y (t ) = G u (t )
Where all derivatives and algebraic variables have been eliminated.
G has the dimensions:
G –mxr
If the Then
index is
Negative The control system is unstable (known as "integral instability").
Positive The control system may or may not be stable.
• 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.
Notes:
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
States A B
Outputs C D
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 ) ∈ R n Differential variables
y (t ) ∈ R m
Algebraic variables
u (t ) ∈ R λ Input variables
11 Estimation 328
θ ∈R ρ Input variables to be estimated
It should be noted that, for purely steady-state problems, n=0.
11 Estimation 329
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.
θ L ≤ θ ≤ θU
z t( )
where j 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.
ijk W ij W
The weights and (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 θ and θ serve to keep the parameters within
L U
11 Estimation 330
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:
NSS
+γi
j =1
∑ $
log w j z ij
11 Estimation 331
12 Using the Simulation
Access eXtensions
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.
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\
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.
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.
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.
Event Occurs
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 Before or after an integration step and
SAX_AFTER_DYN_STEP 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 Before and after the initialization at time
and SAX_AFTER_INI_STEP 0, and when the Before Initialization or
After Initialization check box is selected in
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.
Notes:
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)
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)
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)
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)
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)
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.
Option Description
Synchronous The OLL interface will wait for IO operations to
complete
Asynchronous A call-back is specified
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.
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:
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.
Notes:
• The scroll bar at the foot of the tabs does not affect the
first two columns (the Simulation Variable name and
Simulation Value).
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
Note: The tags are not validated until the data server is
connected to the simulation server, at the start of the first run.
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.
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.
Notes:
Note the following restrictions when preparing flowsheets for export:
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
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.
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.
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.
Note: To be sure that Aspen Plus can load the DLL, you must put
it :
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.
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.
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
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
Licensing of Exported
Flowsheets
Exported flowsheets running in Aspen Plus® may use an Aspen Modeler
license, depending upon your license agreement.
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.
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
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:
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:
Script Executes
Name: 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.
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: 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:
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
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.
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
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.
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.
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.
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
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:
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.
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
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
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
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
Application.Msg() 47
A Application.Name 44
Absolute Checking Tolerance 177 Application.NewDocument() 48
Absolute Equation Tolerance 182 Application.OpenDocument() 48
Absolute Integration Error Tolerance 194 Application.Path 44
Absolute Perturbation 216 Application.Quit() 49
Absolute tear tolerance 181 Application.Restore() 49
Absolute variable tolerance 182 Application.SaveDocument() 49
Active set initialization parameters (DMO) Application.SaveDocumentAs() 50
specifying 248 Application.Simulation 57
Active set initialization parameters (DMO): 248 Application.StatusBar 45
ActiveDocument.Application 51 Application.Top 45
ActiveDocument.CloseAllForms 53 Application.Version 45
ActiveDocument.CreateLibrary 54 Application.Visible 45
ActiveDocument.FullName 52 Application.Width 45
ActiveDocument.Name 52 Applications
ActiveDocument.Parent 52 automation for 42
ActiveDocument.Saved 53 Asynchronous runs 169
ActiveDocument.SaveDocument 54 available 401
ActiveDocument.SaveDocumentAs 54
B
Application.Activate() 47
Application.ActiveDocument 43 BeginLongOperation method 108
Application.Caption 43 Blocks
Application.CloseDocument() 47 automation for 61, 95, 99
Application.DefaultFilePath 43
Application.FullName 43
C
Index 402
CHEMISTRY physical properties calculation locating 197
option 254
Disturbances
Clip Factor 217
locating 197
Component lists
DMO Adv form
automation for 81
QP2 sheet 248
ComponentList.Components 81
Search sheet 244
ComponentList.IsComponentSet 82
DMO Adv form: 244, 248
ComponentList.Name 82
DMO Basic form
ComponentList.Option 83
Basic sheet 231
ComponentList.OptionNames 83
Report sheet 240
Control Design Interface, overview 314
DMO Basic form: 231, 240
Control Panel output: 240
DMO maximum number of allowed iterations
Controllers
changing 231
deleting 360
DMO maximum number of allowed iterations:
Convergence Criterion 213 231
ConvertToBaseUOM and ConvertFromBaseUOM DMO objective function convergence tolerance
methods 127
changing 231
CreateObject Visual Basic command 30
DMO objective function convergence tolerance:
CreateScript method 112 231
CreateTask method 111 DMO residual convergence tolerance
Creep mode (DMO) changing 231
using 243 DMO residual convergence tolerance: 231
Creep mode (DMO): 243 DMO solver 235
applying a trust region 244
D changing parameters 231
Data servers 343 creep mode 243
DeleteScript method 112 handling infeasible solutions 235
DeleteTask method 112 handling singularities 236
Deleting scaling 235
controllers 360 troubleshooting 234
Derivative calculations variable bounding 237
Check Procedure Derivatives option 177 DMO solver parameters
Diagnostic information active set initialization 248
Non-Linear Solver tab 214 control panel report 240
Solver Reporting Level 176 creep mode 243
Direct convergence method 180 micro-infeasibility handling 247
DisableIncrementalUpdate command 24 trust region 244, 245
DisableIncrementalUpdate method 107 DMO solver parameters: 231, 240, 243, 244,
246, 248
Discontinuities
Index 403
DMO solver: 230, 231, 234, 235, 236, 237, modifying 364
243, 244
Exporting
Dogleg Method 214
flowsheets to Aspen Plus 359
Drop Tolerance
to Aspen Plus 352, 367
MA28 212
External data, accessing 343
MA48 205
External programs
calling from scripts 23
E
Index 404
H IsStateVariable method 129
Index 405
Maximum Step Increment Factor 194 overview 343
Maximum Step Reductions 214 Online links variable object
Maximum Variable Step 216 automation 148
MAXIT physical properties calculation option Open NLP - full space 229
257
Open NLP - reduced 229
Method, non-linear solver 212
Open non-linear algebraic equation solvers
Micro-infeasibility handling (DMO) 218, 351
using 246 OPSET physical properties calculation option
254
Micro-infeasibility handling (DMO): 246
Optimization simulations
Minimum Eigenvalue 181
automation for 137
Minimum Integration Step
OutputLogger.ClearWindow() 87
Gear 197
OutputLogger.FileOutput 84
VSIE 193
OutputLogger.Height 85
Morari Resiliency Index 317
OutputLogger.Left 85
MRI 317
OutputLogger.MessageCount 85
N OutputLogger.Messages 85
OutputLogger.MessageText 86
Name method 97, 129
OutputLogger.Path 86
Nelder-Mead Direct Search Solver 226
OutputLogger.Print() 87
Initial simplex 227
OutputLogger.ScreenOutput 86
Maximum iterations 227
OutputLogger.Top 86
Number of restarts 227
OutputLogger.Width 86
Optimization tolerance 227
OutputLogger.WriteFileHeader() 87
Newton 212
NI 317 P
Niederlinski Index 317
Parent method 129
NL2SOL 229
pGibbs_Mol_Liq 303
Non-linear solvers
pGibbs_Mol_Vap 305
Non-Linear Solver tab 212
Physical properties
Numerical Derivative Absolute and Relative
Perturbation 183 entry point routines 266
GPPI routines 261
O installing the physical properties interface
313
objective function 235
subroutines for property procedure types
changing the scale 235 274
OLL Pivot Tolerance 205
overview 343 Ports
Online links automation for 103, 116
automation 143
Index 406
Print Linear Algebra for Groups of Size Greater Results.FindSnapshot() 92
than or Equal to 215
Results.GetResult() 92
Procedures
Results.GetSnapshot() 92
tearing 178
Results.GetSnapshot().Converged 92
Properties
Results.GetSnapshot().DateTime 93
automation for 68, 79
Results.GetSnapshot().Description 93
Properties Plus
Results.GetSnapshot().Export 93
calculation options for 253
Results.GetSnapshot().ExportasBinary 94
Properties Reporting Level 176
Results.GetSnapshot().RunNumber 94
Properties.AddComponentList() 80
Results.GetSnapshot().SimulationTime 94
Properties.ComponentList 79
Results.Import() 94
Properties.ComponentListNames 79
Results.Interval 88
Properties.LoadPropertiesFile() 80
Results.Limit 88
Properties.RemoveComponentList() 81
Results.Refresh() 94
Property method 129
Results.RegularSnapshot 89
Results.ResultCount 89
R
Results.Rewind() 95
RealVariables methods 133
Results.SnapshotCount 89
Re-analyze FLOPS Window Size 206
Results.TakeSnapshot() 95
Re-Analyze Threshold 205
RETENTION physical properties calculation
Reconverge Torn Variables 195 option 258
Recorded history of variables 120, 121 RGA 316
Re-initialization Method 198
S
Relative Checking Tolerance 177
Relative Gain Array 316 SAX, overview 332
Relative tear tolerance 181 Scaling 184
Relative variable tolerance 182 Scripts
RemoveControllers script 360 basic examples 22
Re-pivot every n Factorizations 206 calling external applications 23
Reports 231 improving the speed of 24
DMO active bound 231 invoking 106
EO solver report syntax for 21
DMO 231 Sensitivities 73, 75
Reset method 130 Server Busy dialog box 108
Resolve method 97 Set attributes 119
Results.AutoSnapshot 89 Show Highest Corrector Steps 198
Results.CopyValues() 90 Show Highest Integration Errors 195, 196
Results.Delete() 91 Simulation Access eXtensions, overview 332
Results.FindResult() 92 Simulation Messages window
Index 407
automation for 84 Simulation.State 69
controlling level of detail in 176 Simulation.Step() 79
Simulation.AddSensitivityParameter() 73 Simulation.Successful 70
Simulation.AddSensitivityVariable() 73 Simulation.Termination 71
Simulation.ClearSensitivities() 73 Simulation.Time 71
Simulation.Correlation 58 Simulation.Variables 71
Simulation.CorrelationMatrix 58 Simulations
Simulation.CorrelationMatrixPresent 59 accessing estimation results 164
Simulation.Covariance 59 automation for 57
Simulation.CovarianceMatrix 59 estimation modeling language 158
Simulation.CovarianceMatrixPresent 59 Singularity Perturbation 216
Simulation.CreateLibrary() 74 Snapshots
Simulation.Degrees 59 automation for 88
Simulation.DeviationArrayPresent 60 SOLU-WATER physical properties calculation
option 256
Simulation.DisableSensitivities() 75
Solver properties
Simulation.DisplayTime 60
for Estimation runs 220
Simulation.EnableSensitivities() 75
Solver Reporting Level
Simulation.EndStepCount 60
described 176
Simulation.EndTime 60
Solver Scaling 184
Simulation.Equations 61
Solver Searches n Columns for Pivots 206, 207
Simulation.EstimationRunState 61
Speed of simulation
Simulation.Flowsheet 61
Euler 191
Simulation.FullName 62
Implicit Euler 191
Simulation.GetSensitivityValue 75
SRQP solver 228
Simulation.Interrupt() 76
Feasibility improvements 228
Simulation.LaunchFormView 76
Hessian scaling 228
Simulation.Name 62
Maximum iterations 229
Simulation.Options... 62
Optimization tolerance 229
Simulation.Pause() 76
Print level 229
Simulation.Properties 68
Variable initialisation policy 229
Simulation.Reset() 77
State Transition Matrix 317
Simulation.ResetEstimation() 77
STM 317
Simulation.Restart() 77
Streams
Simulation.Results 68
automation for 101, 113
Simulation.Run() 77
Stringset collection object 119
Simulation.RunMode 68
Synchronous runs 169
Simulation.RunNumber 68
Simulation.Saved 69
Simulation.SpecState 69
Index 408
T W
Index 409
Index 410