AspenOOMFScriptLangV7 3 Ref

Aspen OOMF
Script Language Reference Manual
Version Number: V7.3

March 2011
Copyright (c) 1997 - 2011 by Aspen Technology, Inc. All rights reserved.
Aspen OOMF, aspenONE, the aspen leaf logo and Plantelligence and Enterprise Optimization are trademarks or
registered trademarks of Aspen Technology, Inc., Burlington, MA.
All other brand and product names are trademarks or registered trademarks of their respective companies.
This document is intended as a guide to using AspenTech's software. This documentation contains AspenTech
proprietary and confidential information and may not be disclosed, used, or copied without the prior consent of
AspenTech or as set forth in the applicable license agreement. Users are solely responsible for the proper use of
the software and the application of the results obtained.
Although AspenTech has tested the software and reviewed the documentation, the sole warranty for the software
may be found in the applicable license agreement between AspenTech and the user. ASPENTECH MAKES NO
WARRANTY OR REPRESENTATION, EITHER EXPRESSED OR IMPLIED, WITH RESPECT TO THIS DOCUMENTATION,
ITS QUALITY, PERFORMANCE, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
Aspen Technology, Inc.
200 Wheeler Road
Burlington, MA 01803
USA
Phone: (1) (781) 221-6400
Fax: (1) (781) 221-6410
URL: http://www.aspentech.com
Contents
Contents.................................................................................................................iii
Who Should Read this Guide ...................................................................................1
Introducing OOMF Script Language.........................................................................3
Introduction ....................................................................................................3
Using the Interactive Prompt .............................................................................4
Defining and Executing Scripts...........................................................................5
Defining Scripts .....................................................................................5
Executing Scripts ...................................................................................5
Input Language Rules .......................................................................................6
General.................................................................................................6
Related Documentation .....................................................................................6
Technical Support ............................................................................................7
1 Script Commands ................................................................................................9
Command Summary .........................................................................................9
2 OOMF Script Language Basics ...........................................................................21
Redirecting Output and Journaling.................................................................... 21
Redirecting the Output of a Command .................................................... 21
Changing the Report Device .................................................................. 23
Changing the History Device.................................................................. 23
Flushing the Devices............................................................................. 24
Journaling ........................................................................................... 24
Examining the Output Devices ............................................................... 25
Examples of Redirecting Output ............................................................. 25
Script Parameters .......................................................................................... 26
Global Script Parameters....................................................................... 26
Local Script Parameters ........................................................................ 27
Built-In Script Parameters ..................................................................... 27
Setting Script Parameter Values ............................................................. 29
Unsetting Script Parameters .................................................................. 30
Accessing Parameter Values .................................................................. 30
Examples of Script Parameters............................................................... 30
Invoke Commands ......................................................................................... 32
Invoking an External File....................................................................... 32
Invoking a Block Script ......................................................................... 32
Invoking Scripts Within a Scope ............................................................. 33
Script Arguments ................................................................................. 33
Examples of Invoke Commands ............................................................. 33
Program Flow Control ..................................................................................... 34
IF-THEN-ELSE Command ...................................................................... 34
Contents
iii
FOR-DO Command ............................................................................... 35

WHILE-DO Command ........................................................................... 36
Examples of Program Flow Control ......................................................... 36
Expressions and Conditionals ........................................................................... 38
Examples of Math Functions .................................................................. 41
Examples of String Functions ................................................................. 42
Examples of Relational and Logical Functions........................................... 43
Examples of File Functions .................................................................... 43
Examples of List Functions .................................................................... 44
Examples of Query Functions ................................................................. 44
Examples of Miscellaneous Functions ...................................................... 44
Examples of Effects of Units of Measure .................................................. 45
Examples Using String Functions to Create Variable Names ....................... 46
Wildcards ...................................................................................................... 47
Glob-Style Wildcards ............................................................................ 47
Regular Expression Matching ................................................................. 47
Examples of Wildcards .......................................................................... 48
General Commands ........................................................................................ 49
Getting Help ........................................................................................ 49
Exiting the System ............................................................................... 50
Executing System Commands ................................................................ 50
Timer.................................................................................................. 50
OOMF Model Adapters..................................................................................... 51
3 Hierarchies, Blocks, Variables and Equations ....................................................53
Hierarchies .................................................................................................... 53
What are Hierarchies?........................................................................... 53
How are Hierarchies Created? ................................................................ 54
Hierarchy Input.................................................................................... 55
What is the Scope?............................................................................... 55
How Hierarchies are Built ...................................................................... 57
Defining the Scope ............................................................................... 57
Printing the Block Hierarchy................................................................... 58
Finding a Block .................................................................................... 58
Solving at a Scope ............................................................................... 59
Examples of Hierarchy .......................................................................... 59
Block Commands ........................................................................................... 61
Listing Blocks....................................................................................... 61
Excluding Blocks .................................................................................. 61
Including Blocks................................................................................... 62
Listing Block Scripts ............................................................................. 62
Printing Block Convergence ................................................................... 62
Printing Block Statistics......................................................................... 63
Changing Block Attributes ..................................................................... 64
Printing Block Attributes........................................................................ 64
Printing Block Attributes in Detail ........................................................... 65
Printing Block Parameters ..................................................................... 65
Example of Block Commands ................................................................. 65
Variable Commands........................................................................................ 67
Variable Attributes ............................................................................... 67
Changing Variable Attributes ................................................................. 68
Printing Variables ................................................................................. 69
iv
Contents
Printing Variables Fixed in the Current Mode............................................ 69

Printing Variables Fixed in Other Modes .................................................. 70
Printing Variables with Active Bounds ..................................................... 70
Printing Largest Variable Shadow Prices .................................................. 71
Printing Variables Using a Query ............................................................ 72
Examples of Variable Commands............................................................ 73
Alias Commands ............................................................................................ 74
Printing Aliases .................................................................................... 74
Printing Alias Values ............................................................................. 74
Printing Alias Variables.......................................................................... 75
Equation Commands....................................................................................... 76
Excluding Equations.............................................................................. 76
Including Equations .............................................................................. 76
Evaluating Equations ............................................................................ 76
Printing Equations ................................................................................ 77
Printing Largest Residuals ..................................................................... 77
Printing Largest Residual Shadow Prices.................................................. 78
4 Specification Groups and Connections...............................................................79
Specification Group Commands........................................................................ 79
Removing Specification Groups .............................................................. 79
Disabling Specification Groups ............................................................... 80
Enabling Specification Groups ................................................................ 80
Printing Specification Groups ................................................................. 80
Printing Inactive Specification Groups ..................................................... 80
Printing Specification Group Variables ..................................................... 81
Examples of Specification Group Commands ............................................ 81
Stream Commands......................................................................................... 82
Printing Block Ports .............................................................................. 82
Printing Stream Values ......................................................................... 82
Changing Stream Attributes................................................................... 83
Connection Commands ................................................................................... 84
Adding Connections .............................................................................. 84
Adding Custom Connections .................................................................. 85
Removing Connections.......................................................................... 85
Disabling Connections........................................................................... 86
Enabling Connections............................................................................ 86
Checking Connections ........................................................................... 87
Printing Connections ............................................................................. 87
Printing Inactive Connections................................................................. 88
Printing Incomplete Connections ............................................................ 88
Printing Connection Variables................................................................. 89
Examples of Connection Commands ....................................................... 89
5 Measurements ...................................................................................................91
Measurement Commands ................................................................................ 91
Checking Measurements ....................................................................... 91
Disabling Measurements ....................................................................... 92
Enabling Measurements ........................................................................ 92
Printing Measurements ......................................................................... 93
Printing Measurement Variables ............................................................. 93
Examples of Measurement Commands .................................................... 93
Contents
Measurement Qualities.................................................................................... 96
Disabling Simple Measured-Parameterized Pairs....................................... 97
Disabling Measured-Parameterized Pairs in Specification Groups ................ 97
Enabling Specification Groups ................................................................ 98
Executing the Variable Quality Capability................................................. 98
Examples of Measurement Qualities........................................................ 98
6 Saving and Restoring ......................................................................................101
Commands for Saving and Restoring Variable and Block Data ............................ 101
Saving Variables To a Binary File.......................................................... 101
Restoring Variables From a Binary File .................................................. 102
Restoring Free Variables From a Binary File ........................................... 103
Updating Variables In a Binary File ....................................................... 103
Saving Variables To an ASCII File......................................................... 104
Restoring Variables From an ASCII File ................................................. 104
Comparing Variables With an ASCII File ................................................ 105
Saving Variables and Block Attributes to an ASCII File ............................ 106
Reading Variables and Block Attributes from an ASCII File....................... 106
Examples of Commands to Save and Restore Variable Data..................... 107
Persisting Simulation and Block Data in Compound Storage (Binary) Files ........... 107
Saving a Simulation to a Compound Storage File.................................... 108
Opening a Simulation from a Compound Storage File.............................. 108
Adding all the Blocks in a Compound Storage File to a Simulation ............ 109
Saving a Block to a Compound Storage File ........................................... 109
Loading a Block from a Compound Storage File...................................... 109
Examples of Binary Persistence Commands ........................................... 109
Persisting Simulation and Block Data in XML Files............................................. 110
XML Schema for Simulation Persistence ................................................ 110
Writing a Simulation to a XML File ........................................................ 115
Reading a Simulation from a XML File ................................................... 115
Appending all the Blocks in a XML File to a Simulation ............................ 116
Writing a Block to a XML File ............................................................... 116
Reading a Block from a XML File........................................................... 116
Examples of XML Persistence Commands .............................................. 116
7 Objective Functions.........................................................................................119
Objective Function Commands ....................................................................... 119
Changing Objective Function Attributes................................................. 119
Evaluating the Objective Function ........................................................ 120
Evaluating the Objective Functions Derivatives...................................... 120
Evaluating the Objective Functions Hessian .......................................... 120
Printing the Objective Function ............................................................ 121
Jacobian and Derivative Commands................................................................ 121
Analyzing the Jacobian........................................................................ 121
Analyzing the Jacobian Sparsity ........................................................... 121
Evaluating the Jacobian ...................................................................... 122
Printing the Jacobian .......................................................................... 122
Printing Jacobian Variables .................................................................. 122
Printing Jacobian Equations ................................................................. 123
Printing Block Derivative Methods......................................................... 123
Examples Of Derivative Commands ...................................................... 123
vi
Contents
8 Analysis...........................................................................................................125
Analysis Commands...................................................................................... 125
Checking Degrees of Freedom.............................................................. 125
Sensitivity Analysis............................................................................. 125
Analyzing Variables ............................................................................ 126
Analyzing Equations ........................................................................... 127
Examples of Analysis Commands.......................................................... 127
Solver Commands ........................................................................................ 129
Setting the Solver .............................................................................. 129
Viewing Solver Settings ...................................................................... 129
Entering DMO Parameters ................................................................... 129
Entering LSSQP Parameters................................................................. 131
Entering NSOLVE Parameters............................................................... 136
Solving the Problem ........................................................................... 137
Examples of Solver Commands ............................................................ 137
Recovery Commands .................................................................................... 138
Resetting Variables to Initial Values...................................................... 138
9 Printing and Reports .......................................................................................139
Printing Problem Information ......................................................................... 139
Printing the Problem Summary ............................................................ 139
Printing Problem Convergence ............................................................. 139
Examples of Printing Problem Information ............................................. 139
Formatted Printing ....................................................................................... 140
Print Formatted Command .................................................................. 140
Examples of Formatted Printing ........................................................... 142
Miscellaneous Printing Commands .................................................................. 143
The Echo Command............................................................................ 143
Examples of the Miscellaneous Printing Commands................................. 143
Report Commands........................................................................................ 144
Reporting Blocks ................................................................................ 144
Reporting the Objective Function.......................................................... 144
10 Support for Dynamic Models..........................................................................145
Script Parameters that Support Dynamic Models .............................................. 145
Script Language Commands that Support Dynamic Models ................................ 146
Pausing a simulation........................................................................... 146
Running a simulation .......................................................................... 146
Stepping through a simulation ............................................................. 146
Stopping a simulation ......................................................................... 146
Reinitializing a simulation .................................................................... 147
Loading task definitions ...................................................................... 147
Viewing tasks .................................................................................... 147
Deleting a task .................................................................................. 147
Activating a variable profile ................................................................. 147
Inactivating a variable profile............................................................... 148
Viewing a variable profile .................................................................... 148
Viewing a variable history ................................................................... 148
Saving a snapshot .............................................................................. 149
Loading a snapshot ............................................................................ 149
Viewing snapshots.............................................................................. 149
Contents
vii
Deleting a snapshot............................................................................ 149

Task Language............................................................................................. 150
XML Schema for Task Language ........................................................... 150
Example Tasks................................................................................... 155
Assigning a value to a variable ............................................................... 155

Ramping a variable ................................................................................. 155
Suspending a task.................................................................................... 156
Using an IF statement in a task ............................................................... 156
Using a FOR loop in a task ..................................................................... 157
Printing a message from a task ............................................................... 157
Conditional tasks..................................................................................... 158
11 Units of Measure, Physical Types and Connection Types ...............................159
Units of Measure Commands ......................................................................... 159
Changing a Variable's Units of Measure ................................................. 159
Printing Units of Measure .................................................................... 159
Dealing with Untyped Variables ............................................................ 160
Example Units of Measure Commands................................................... 160
Units of Measure .......................................................................................... 161
Physical Types ............................................................................................. 171
Connection Types ......................................................................................... 175
Connection Type Commands.......................................................................... 177
Changing a Variable's Connection Type ................................................. 177
12 Global Structures...........................................................................................179
Overview..................................................................................................... 179
Example...................................................................................................... 180
13 Aspen Properties Data...................................................................................183
Loading Properties Data ...................................................................... 183
Freeing Properties Data....................................................................... 183
Swapping Properties Data ................................................................... 183
Examples Of Properties Commands ...................................................... 184
14 Aspen Plus Extensions...................................................................................185
Using the Interactive Prompt ......................................................................... 185
Defining and Executing Scripts....................................................................... 186
Defining Scripts ................................................................................. 186
Executing Scripts ............................................................................... 186
Command Summary ..................................................................................... 187
Invoke Commands ....................................................................................... 188
Invoking a Local Script........................................................................ 188
Invoking a Global Script ...................................................................... 188
Miscellaneous Commands Specific to Aspen Plus .............................................. 189
Updating Crude Blends........................................................................ 189
Updating the PDF ............................................................................... 189
Hierarchies .................................................................................................. 189
How are Hierarchies Created? .............................................................. 189
Hierarchy Input.................................................................................. 189
Stream Commands....................................................................................... 190
viii
Contents
Adding and Removing Stream Connections............................................ 190

Disabling Stream Connections.............................................................. 190
Enabling Stream Connections .............................................................. 190
Examples of Stream Commands........................................................... 191
HXFlux Commands ....................................................................................... 191
Controlling HXFlux Connections............................................................ 191
Disabling HXFlux Connections .............................................................. 191
Enabling HXFlux Connections ............................................................... 192
Recovery Commands .................................................................................... 192
Recovery........................................................................................... 192
Report Commands........................................................................................ 193
Reporting Everything .......................................................................... 193
Reporting the Flowsheet...................................................................... 193
Reporting Streams ............................................................................. 193
15 Aspen Custom Modeler Models Related Extensions .......................................195
Adding an ACM Model to OOMF ...................................................................... 196
ACM Block Attributes .................................................................................... 197
16 Aspen HYSYS Refining Extensions .................................................................199
Command Summary ..................................................................................... 199
Index ..................................................................................................................201
Contents
ix
Contents
Who Should Read this Guide
This manual is intended for users of the stand-alone OOMF core component or
users of the equation-oriented capabilities of products, such as Aspen Plus,
that embed OOMF. Typically, users write scripts to manipulate the simulation
data. Note that such scripts are not necessary for normal operations of
products that embed OOMF. However, these scripts may be used to extend
the capabilities of these products or to analyze the current simulation.
OOMF is embedded within several AspenTech products such as Aspen Plus,
Aspen HYSYS Refining, Aspen Advisor, Aspen PIMS, Aspen Water, Aspen
HYSYS to host models exported from Aspen Custom Modeler, Aspen MBO etc.
Some of these products have extended the capabilities of the OOMF scripting
language. These product specific extensions may be found in separate
sections at the end of this document.
Introducing OOMF Script

Language
Introduction
This document describes the script language used by the OOMF kernel the
engine behind the EO strategy in products such as Aspen Plus. These script
commands may be typed at the command line or entered into script files or
input forms.
The script language is very effective for tasks such as:
Debugging an equation-oriented run.
Defining sets of process values.
Setting the inclusion status of blocks, measurements, etc.
Creating custom reports.
The script language has many features of an advanced programming

language, such as mathematical and string functions, if-then-else logic, and
for-do loops.
Introducing OOMF Script Language
Using the Interactive Prompt

You can enter script commands interactively into the OOMF kernel.
Launch a command window by clicking on Start, Run, and typing in cmd
and pressing the OK button.
In the command window, use the set path command to add the folder that
contains oomf.exe to the current path environment variable. For example:
set path= C:\Program Files\AspenTech\OOMF<V.n>\Xeq
On the command line, start oomf.exe. You can now type commands at the
OOMF> prompt.
See Also
Aspen Plus Extensions - Using the Interactive Prompt
Aspen Custom Modeler Extensions Using the Interactive Prompt
Aspen HYSYS Refining Extensions - Using the Interactive Prompt
The command line has a variety of features to assist in editing your
commands. These are summarized in the following table:
Key Strokes
Description
HOME
Move cursor to beginning of line.
END
Move cursor to end of line.
BACKSPACE
Delete the character left of the cursor.
DEL
Delete the character right of the cursor.
RETURN
Return the current line.
LEFT ARROW
Move cursor left (back) 1 column.
RIGHT ARROW
Move cursor right (forward) 1 column.
UP ARROW
Fetches previous line from the history list.
DOWN ARROW
Fetches next line from the history list.
Defining and Executing Scripts

In addition to entering script commands at the OOMF prompt, you may also
enter them into a script file. This is nothing more than a series of script
commands that are executed in sequence, not unlike a subroutine.
See Product Specific Features:
Aspen Plus Extensions - Defining and Executing Scripts
Defining Scripts
Scripts may be defined in the following ways:
An external file that may be created with a standard text editor. The
extension of the file should be EBS.
Products using OOMF may define additional ways to create scripts.
Executing Scripts
Scripts may be executed in a number of ways:
By manually executing the script from the command line or from another
script. This may be done with the INVOKE command.
By associating the script with a block or the flowsheet. This is done by

assigning the script as a method attached to the block. A method is a
function that is called at specific times during the execution sequence of
OOMF. The following methods are available:
INIT
This method is executed when the block is created and is available for
all blocks except hierarchies.
PRESOLVE
This method is executed before a solve is started. It can be very useful

for defining run-specific information, such as process data.
POSTSOLVE
This method is executed after a solve is completed. This is useful for

checking the results of the run and writing customized reports.
The script that is assigned as the block method may be an external file.
You may also manually execute a blocks script method with the INVOKE
command.
More on invoking scripts may be found in Invoke Commands.
Input Language Rules

General
Input in EBS files or the command line may start in any column and go to
column 256.
The input is, in general, not case sensitive. (One exception is the format
string for formatted printing.)
Lines may be continued by using the backslash character (\) as the last
character of the line.
Single line comments are denoted by a double slash (//). When script
commands are entered in the INP file a semicolon (;) may be used.
Multi-line comments begin with slash asterisk (/*) and end with asterisk
slash (*/).
Percent signs (%) are used to delimit regular expressions (a powerful

form of wildcarding).
Some commands support single character (also known as glob style)

wildcarding. This is done with an asterisk (*) and question mark (?).
Use double quotation marks (") to enclose strings containing spaces and
to preserve upper and lower case.
Spaces must be used between all operators.
Many of these commands may have their output redirected by using TO

device at the end of the command. To redirect output to a file, use TO
OPENFILE("file"), where file is the name of the file.
Note: Some products using OOMF may have their own methods of entering
scripts which may have additional syntax restrictions. See the chapters for
individual products at the end of this manual for details.
Related Documentation
Title
Content
Aspen Engineering Suite Installation

Manual
Instructions for installing Aspen

Plus and other Aspen Engineering
Suite products
Aspen Plus User Guide
Procedures for using Aspen Plus
Aspen Plus User Models Reference Manual
Instructions for creating custom

models for use in Aspen Plus and
the specifications for those
models
Aspen Plus Input Language Guide
Commands for Aspen Plus input

files
Technical Support
AspenTech customers with a valid license and software maintenance
agreement can register to access the online AspenTech Support Center at:
http://support.aspentech.com
This Web support site allows you to:
Access current product documentation
Search for tech tips, solutions and frequently asked questions (FAQs)
Search for and download application examples
Search for and download service packs and product updates
Submit and track technical issues
Send suggestions
Report product defects
Review lists of known deficiencies and defects
Registered users can also subscribe to our Technical Support e-Bulletins.

These e-Bulletins are used to alert users to important technical support
information such as:
Technical advisories
Product updates and releases
Customer support is also available by phone, fax, and email. The most up-todate contact information is available at the AspenTech Support Center at
http://support.aspentech.com.
1 Script Commands
Command Summary
Below is a list of the script commands. This list may be displayed from the
kernel with the HELP command.
EO Commands
Command
Purpose
ACTIVATE VARIABLE PROFILE
Activate a variable profile
ADD ALIASES
Add variable aliases
ADD BLOCKS
Add blocks to the current scope
ADD CONDITIONAL EQUATION
Add conditional equations
ADD CONNECTIONS
Add variable and port connections
ADD CUSTOM CONNECTIONS
Add custom connections between a pair of ports
ADD MEASUREMENTS
Create a measurement instrument and connection
ADD PORT
Add variables to a new or existing port
ADD SIMULATION
Append the block data from a specified binary file to the current
simulation
ADD SPECIFICATION
CONNECTIONS
Add specification connections
ADD TASKS FROM
Load tasks from a task file
ALIAS
Define or show variable aliases
ANALYZE DOF
Report the current degrees of freedom
ANALYZE EQUATIONS
Perform equation analysis
ANALYZE JACOBIAN
Compare numerical and analytic Jacobian
ANALYZE SPARSITY
Compares the numerical and analytical
ANALYZE VARIABLES
Perform variable analysis
APPEND BLOCKS
Append all the blocks from a specified XML file to the current
simulation
BLOCK SCRIPTS
Show all scripts associated with a list of blocks
BLOCKS
Show or set the list of blocks in the current scope
CHANGE FLUSHING
Change the flushing level of an output device
CHANGE SCOPE
Clear the scope stack and change scope as indicated
1 Script Commands
parsity patterns.
Command
Purpose
CHECK CONNECTIONS
Analyze all connections and connection groups. Report status and any
inconsistencies.
CHECK MEASUREMENT
Print a report showing measurements that have not activated

correctly.
COMPARE VARFILE
Compare database with current values
CONDITIONAL EQUATION
Define conditional equations
CONNECTION
Define or show variable and port connections
DELETE BLOCKS
Delete blocks from the current scope
DELETE PORTS
Delete ports from the current scope
DELETE SNAPSHOT
Delete a specified snapshot
DELETE TASK
Delete a task that has been loaded
DERIVATIVE
Show the derivative method for all blocks in the current scope
DISABLE CONNECTION
Disable any connection whose name matches a list of name

expressions.
DISABLE MEASUREMENT
Disable any measurement whose name matches a list of name

expressions.
DISABLE SPECIFICATION
GROUPS
Disable any specification group whose name matches a list of name

expressions.
ECHO
Print a value
ENABLE CONNECTION
Enable any connection whose name matches a list of name

expressions.
ENABLE MEASUREMENT
Enable any measurement whose name matches a list of name

expressions.
ENABLE SPECIFICATION
GROUPS
Enable any specification group whose name matches a list of name

expressions.
EVALUATE EQUATIONS
Evaluate the equations
EVALUATE JACOBIAN
Evaluate the Jacobian
EVALUATE OBJECTIVE HESSIAN Display the diagonal of the Hessian

EVALUATE OBJECTIVE
Evaluate and display the value
EVALUATE OBJECTIVE
DERIVATIVE
Evaluate and display the derivative
EVALUATE RESIDUALS
Evaluate the equations
EXCLUDE BLOCKS
Exclude a block
EXPOSE PORT
Expose a port contained within the current scope to the block which
FIND BLOCK
Search the block hierarchy for a block
FIX STREAMS
Fix the named streams
FLUSH
Flush all the indicated devices
FREE PROP DATA
Initialize Aspen Properties and free an aprpdf file
FREE STREAMS
Free the named streams
HOMOTOPY PARAMETERS
Show or Set the list of variables, the appropriate target values, and, if
necessary, the appropriate initial values that should be used as
parameters, parameter targets, and parameter initial values by the
parsity solver.
IDENTIFY LIBRARY
Ask a loaded library to give its version
INACTIVATE VARIABLE
PROFILE
Inactivate a variable profile
10
1 Script Commands
Command
Purpose
INCLUDE BLOCKS
Reactivate an excluded block
INITIALIZE BLOCKS
Invoke the closed form initialization on the block(s)
INITIALIZE PORT
Initialize a port from another port
INVOKE
Execute commands in a file or a script attached to a block
LINEAR OBJECTIVE
Define an objective function
LOAD BLOCK
Load the block in a specified binary file into the current simulation
LOAD LIBRARY
Dynamically load a shared library
LOAD PROP DATA
Initialize Aspen Properties and load an aprpdf file
LOAD SNAPSHOT
Load a specified snapshot
MEASUREMENTS
Show or define the set of measured variables
OPEN SIMULATION
Open a simulation from a specified binary file
OPENSOLVER LOAD
Dynamically load an Open Solver DLL
OPENSOLVER UNLOAD
Unload a previously loaded Open Solver DLL
PAUSE
Pause a running dynamic simulation and enter dynamic interactive

mode
POP SCOPE
Return the scope stack to the previous scope
PRINT ACTIVE_BOUNDS
Print a report for variables showing shadow prices and active bounds
PRINT ACTIVE_BOUNDS SSI
Print a report for variables showing SSI shadow prices and active
bounds
PRINT ALIAS VARIABLES
Print the alias names referencing the specified variables
PRINT ALIASES
Report variable attributes for all aliases
PRINT ALL BLOCKS
Print all blocks in the current scope including those in child containers
PRINT BLOCK ATTRIBUTES
Print the list of attributes for a specified block
PRINT BLOCK ATTRIBUTES

DETAILED
Print the list of attributes in detail for a specified block
PRINT BLOCK CONVERGENCE
Print convergence summary by block
PRINT BLOCK HIERARCHY
Show all blocks in the block hierarchy
PRINT BLOCK PARAMETERS
Print the list of attributes for a specified block
PRINT BLOCK PORTS DETAILED Print detailed port information for a specified list of blocks
PRINT BLOCK PORTS
Print the list of ports for a specified block
PRINT BLOCK STATISTICS FULL Print block statistics (with indices) for all or listed blocks
PRINT BLOCK STATISTICS
Print block statistics for all or listed blocks
PRINT CONNECTION GROUPS
Print the connection group or groups associated with specified blocks

or variables.
PRINT CONNECTION VARIABLES Print the connection name that references the specified variables
PRINT CONNECTIONS DETAILED Print a detailed report for each connection named in the supplied list.
PRINT CONNECTIONS
Print any connection whose name matches a list of name expressions.
PRINT CONVERGENCE SUMMARY Summarize the convergence

PRINT EQUATIONS
Print a report for equations
PRINT EXCLUDED BLOCKS
Print all blocks in the current scope and child containers that are
currently excluded
PRINT FIXED
Print a report for fixed variables
PRINT FLUSHING
Show the flushing level of an output device
PRINT FORMATTED
Write formatted information to the report device
1 Script Commands
11
Command
Purpose
PRINT INACTIVE CONNECTIONS Print any inactive connection whose name matches a list of name
expressions.
PRINT INACTIVE SPECIFICATION Print any inactive specification group whose name matches a list of
GROUPS
name expressions.
PRINT INCLUDED BLOCKS
Print all blocks in the current scope and child containers that are
currently included
PRINT INCOMPLETE
CONNECTIONS
Print the list of connections that are incomplete. Incomplete

connections
PRINT JACOBIAN
Print the Jacobian (matrix for first derivatives)
PRINT JACOBIAN EQUATIONS
Print the Jacobian for certain equations
PRINT JACOBIAN VARIABLES
Print the Jacobian for certain variables
PRINT LARGEST EQUATION

SCALED_SHADOW_PRICES
Show the largest equation shadow prices

SHADOW_PRICES
Show the largest equation shadow prices
PRINT LARGEST EQUATIONS
Show the largest residuals
PRINT LARGEST RESIDUAL

Show the largest residual shadow prices

SHADOW_PRICES
Show the largest residual shadow prices
PRINT LARGEST RESIDUALS
Show the largest residuals
PRINT LARGEST VARIABLE

SHADOW_PRICES SSI
Show the largest variable shadow prices in scaled SI

SHADOW_PRICES
Show the largest variable shadow prices in user units
PRINT MEASUREMENTS
Report on all or specified variable measurements.
PRINT MEASUREMENTS
VARIABLES
Report the measurements that reference the specified variables
PRINT OBJECTIVE
Display an objective function
PRINT QUERY
Print the attributes of variables that satisfy a query string.
PRINT RESIDUALS
Print a report for equations
PRINT SCOPE
Output the scope stack
PRINT SOLVERS
List the currently loaded solvers
PRINT SPECIFICATION GROUP
Print any specification group whose name matches a list of name

expressions.

VARIABLES
Print the specification group name that references the specified

variables
PRINT SPECIFICATIONS
List variables that have a spec type other than Calc
PRINT SUMMARY
Summarize the state of the kernel
PRINT TIMER
Print the timer
PRINT VARIABLES
Print a report for variables
PRINT VARIABLES
CONNECTIONS
Print a report for variable connections
PRINT VARIABLE HISTORY
Compute a variables history and print it
PRINT VARIABLE PROFILE
Print a variable profile
PRINT VARIABLES SSI
Print a report for variables in scaled SI
12
1 Script Commands
Command
Purpose
PROCESS VARIABLE QUALITY
Process spec flipping logic to the &BAD_STATUS_LIST
PUSH SCOPE
Change the scripting scope to that of the named block
READ BLOCK
Load a block from the specified XML file into the current simulation
READ BLOCK ATTRIBUTES
Read the list of block attributes from a specified file
READ SIMULATION
Open a simulation from the specified XML file
READ VARFILE
Read a database of variable information
READ VARFILE EXCEPT
Read a database of variable information
READ VARFILE QUERY
Read a database of variable information and update the simulation

based upon the query
REINITIALIZE
Reinitialize a dynamic simulation
REMOVE CONNECTIONS
Remove any connection whose name matches a list of name

expressions.
REMOVE SPECIFICATION
GROUPS
Remove any specification group whose name matches a list of name

expressions.
REPORT BLOCKS
Print block reports
REPORT OBJECTIVE
Display an objective function
RESET SCOPE
Remove all of the pushed scopes
RESET VARIABLES
Reset the variable values to their state before the solve command
was issued
RESTART TIMER
Restart the timer
RESTORE FREE VARIABLES

EXCEPT
Restore attributes for free variables in current MODE from a binary

file
RESTORE FREE VARIABLES
Restore attributes for free variables in current MODE from a binary

file
RESTORE VARIABLES EXCEPT
Restore variable attributes from a binary file
RESTORE VARIABLES
Restore variable attributes from a binary file
RUN
Run to the final time point in a dynamic simulation
SAVE BLOCK
Save the specified block to the named binary file
SAVE SIMULATION
Save a simulation to a specified binary file
SAVE VARIABLES
Store variable attributes in a binary file
SAVE SNAPSHOT
Save a snapshot with a specified name
SCOPE INVOKE
Execute a block method for a block hierarchy
SENSITIVITY
Performs a sensitivity analysis
SHOW DECOMPOSITION
Show the details of the groups in the current decomposition of the

Non-Linear Algebraic Equation System. This is applicable only if you
are using a solver that decomposes the current problem into smaller
groups before the solve.
SHOW TASKS
Print the list of tasks that are currently loaded
SNAPSHOTS
Print the list of snapshots in the current scope to the current output
device
SOLVE
Solve the current problem
SOLVER SETTINGS
Set or show the current solver settings
SOLVER
Set or show the current solver
START TIMER
Start the timer
STEP
Step to the next communication time point in a dynamic simulation
1 Script Commands
13
Command
Purpose
STOP
Stop the dynamic simulation and exit dynamic interactive mode
STOP TIMER
Stop the timer
SUM SQUARES OBJECTIVE
SWAP PROPERTY
Swap the Aspen Properties property method or option set
SYMBOLIC OBJECTIVE
SYSTEM
Have the operating system execute a command
TOGGLE SOLVE SCOPE
Changes the status of any connections and spec groups that cross the
current scope boundary
UNLOAD LIBRARY
Unload a previously loaded library
UNPROCESS VARIABLE QUALITY Undo the effect of &BAD_STATUS_LIST and measurement

UNSET
Undefine a set of parameters
UPDATE VARIABLES
Update binary variable file from the current variable vector
WRITE BLOCK
Save the specified block to the named XML file
WRITE BLOCK ATTRIBUTES
Write the list of block attributes to a specified file
WRITE SIMULATION
Save the simulation to the specified XML file
WRITE SNAPSHOT
Write the list of block attributes and variables to a specified file
WRITE VARFILE
Write a database of variable information
WRITE VARFILE EXCEPT
Write a database of variable information
See Also
Aspen Plus Extensions - Command Summary
Aspen Custom Modeler Extensions - Adding an ACM Model to OOMF
Aspen HYSYS Refining Extensions - Command Summary
For these commands, arguments should be separated by commas. Many of
these commands support output redirection by adding TO followed by an
output device specification. Additional help may be available for these
commands by typing help followed by the commands full name.
Commands above that support regular expressions can understand GLOB or
REGEXP style regular expressions. Commands listed below (except
assignment) do not support GLOB.
Additional Commands
ADD UOM {uom1} = (multiplier * ){uom2} ([+ | -] offset)
BREAK
CONTINUE
EXIT
IF, FOR, and WHILE blocks
HELP [command name]
PRINT uom(s) [ list_of_uom_specs | for list_of_physical_types]
QUIT
SET paramname = expression
LOCAL paramname [= expression] [, paramname ]
RETURN [expression]
14
1 Script Commands
Assignments
variableId[.lower | .upper | .step | .scale | .bound | .spec | .sbweight] = expression
variableId(.uom) = { uom }
variableId(.spec) = const | calc | meas | param | optim | recon | indep(endent) | fixed
| free
variableId(.bound) = hard | relaxed | soft
blockId(.deriv_method) = analytic | numeric | update_numeric | update_analytic
blockId(.nlratiodev) = real
blockId(.zerotol) = real
blockId(.move) = TRUE | FALSE
blockId(.moveamount) = real
blockId(.pert) = real
blockId(.included) = expression
blockId.streamId.str.spec = const | calc | meas | param | optim | recon |
indep(endent) | fixed | free
blockId.streamId.str.phase = unknown | liquid | vapor | vl | vlf
objId.direction = MAXIMIZE | MINIMIZE
objId.scale = expression
objId.uom = { uom }
equationId(.included) = TRUE | FALSE |
parsit expression
regexp = expression
Syntax for Command Descriptions Above

[]
Indicates that the command within is optional.
<>
Indicates that you must choose one of the keywords within. For example,
list_of_< parsit variableId> indicates you must enter a list of alias
names or variable names.
Used to separate command options. For example, str(ea)m(s) all |

none indicates that you may type streams all or streams none.
variableId
Name of a variable.
aliasId
Name of a alias.
equationId
Name of an equation.
uom
Units of measure. When you enter the units of measure for a variable,
you must place it within braces, { }.
list_of_
Indicates a list of names. The names are separated by blanks.
regex
Indicates the use of regular expression matching. This is a form of

wildcarding which is discussed in the section titled Regular Expression
Matching.
expression
An expression. This is discussed further in the section titled Expressions

and Conditionals.
condition
A TRUE/FALSE condition. This is discussed further in the section titled

Expressions and Conditionals.
Notes
expression may be any of:
1 Script Commands
number
15
"a quoted string"
regexp
TRUE, FALSE, ON, or OFF
identifier
&identifier
variable_attribute
expression + expression
expression expression
expression * expression
expression / expression
expression ^ expression
expression OR expression
expression AND expression
expression . expression
expression relop expression
( expression )
op ( expression )
expression
NOT expression
number is any of the following:
integer
real
integer { uom }
real { uom }
integer { $ / uom }
real { $ / uom }
real {si}
real {ssi}
real {*}
where uom is a valid unit (see section on Unit of Measure and Physical Types)
num_or_param is one of:
number
&identifier
relop is any of these relational operators: < > = <> <= >=
vmaskElem is any of:
name
physical_type
lower
value
upper
scale
units
spec
step
sbweight
shadow
active
vmask is [ list_of_vmaskElem ]
op is any of:
16
1 Script Commands
abs
loge
log10
cos
sin
tan
exp
defined
head
tail
string2id
id2string
OpenFile
OpenBinary
DeviceInfo
OpenTee
ToLower
ToUpper
BlockVars
QueryVars
Int
Val
TypeOf
AliasesByVar
ConnectionsByVar
MeasurementsByVar
SpecGroupsByVar
ActiveConn
InActiveConn
ActiveSpecGroup
InActiveSpecGroup
ActiveMeas
InActiveMeas
BlockAttrs
regexp is % regular_expression %
You can use echo to examine the value of block attributes, equation residuals
and attributes, and variable values and attributes. For example:
echo blkname.deriv_method
echo variable_name.spec
Syntax of If, For, and While blocks

IF ( expression ) THEN
list_of_command
[ ELSEIF ( expression ) THEN
list_of_command ]
[ ELSE
list_of_command ]
ENDIF
FOR <indexvar> IN <list expression> DO
list_commands
ENDFOR
WHILE <expression> DO
list_commands
ENDWHILE
Read-Only Block Attributes
blkname.model
blkname.sparsity_file
blkname.sparsity_type
blkname.sparsity_gen
1 Script Commands
17
Predefined Script Parameters

Parameter
Description
BLOCKS
List of blocks in the current scope (read-only)
BUILD_DATE
Build date of the software (read-only)
BUILD_NUMBER
Build number of the software (read-only)
CHECK_UOM
If true, do not allow assignment of untyped numbers to

variables
CONVERGED
If true, the last solve converged (read-only)
DATE
The date and time of day as a string (read-only)
DEFAULT_FLUSHING
Control the flushing level of new files
DIAG_LEVEL
Diagnostic level controls debug printing
DYN_RUN_TO
Time to which a dynamic simulation should run to.
DYN_INTERVAL
Reporting or communication interval for a dynamic simulation.
FLANGE_PHASE
Default phase when linking PML and AspenPlus streams
HISTORY_DEVICE
Where to send status messages and errors
JOURNAL_DEVICE
Where to journal commands
JOURNAL_LEVEL
How many levels of invoke commands are expanded
MAJOR_VERSION
Major version of the software (read-only)
MEAS_CAPACITY
Initial capacity (number of measurements) for measurement

blocks
MEAS_DESC_WIDTH
Number of characters used to display the measurement

description
MEAS_NUMBER_WIDTH Number of characters used to display the measurement values

MEAS_TAG_WIDTH
18
Number of characters used to display the measurement

tagname
MEAS_UOM_WIDTH
Number of characters used to display the measurement UOM
MINOR_VERSION
Minor version of the software (read-only)
MODE
Calculation mode
(Legal values are: SIM, PAR, REC, OPT; default: SIM)
NAME_WIDTH
Number of characters used to display variable/equation names
NUMBER_WIDTH
Number of characters used to display real (floating point)

values
OBJECTIVE
The current objective function using by SOLVE
ONLINE
True/false; indicates the program is running on/off-line (readonly)
P_AMB
Ambient pressure for converting to/from gauge pressure
PAGE_WIDTH
Number of characters per line
PRINT_VAR_MASK
List of variable attributes to be displayed in a print variable

command
PROBID
Current problem as identifier (read-only)
PROBNAME
Current problem as string (read-only)
PROMPT
Command line prompt
READ_VARFILE_MASK
List of variable attributes to be read in a read varfile command
RELAX_TOL
Relaxed-bound tolerance
REPORT_DEVICE
Where to direct output from commands
1 Script Commands
Parameter
Description
REUSE_SOLVER
True/false, used with decomposition solvers (DECOMP DMO,

DECOMP LSSQP, and DECOMP SPARSE) only. When TRUE, the
decomposition created during the first solve pass may be used
in subsequent passes. This is automatically set to FALSE when
the model is changed in a way that requires the block
decomposition to be recreated.
RUN_MODE
Run mode for a simulation. The options are SS (for steadystate simulations), INIT (for initialization simulations) and DYN
(for dynamic simulations). The default value is SS. (The INIT
and DYN run modes are relevant only to dynamic models.)
SOFT_BOUND
True/false; indicates soft-bounds are active/inactive
STEP_BOUND
True/false; indicates step-bounds are active/inactive
UOM_WIDTH
Number of characters used to display the UOM
WRITE_VARFILE_MASK List of variable attributes to be written in a write varfile

command
User Definable Script Parameter

SCRIPT_PATH
Semicolon-separated list of directories which are searched

left to right if a specified script cannot be found
The following chapters describe the script commands in detail, grouped by

functionality.
1 Script Commands
19
20
1 Script Commands
2 OOMF Script Language

Basics
This chapter describes language elements and general commands of the

OOMF Script language.
Redirecting Output and

Journaling
These commands allow you to redirect the output from any command to an
external file, determine where reports and history information is sent, and
allows you to journal all your script commands.
Redirecting the Output of a Command

Many commands can have their output redirected to another device by
placing TO at the end of the command followed by the desired device. This is
similar to the DOS and VMS use of the greater than sign (>).
Input Language
command TO device
2 OOMF Script Language Basics
21
Input Language Description

device
Device to which output is to be directed:
device defaults to TERMINAL but may be any of the following:

TERMINAL
Redirects output to the console.
NOWHERE
Redirects output to nowhere (nothing is printed).
"file"
Name of a file enclosed in double quotation marks.
OPENFILE
Redirects output to the specified ASCII file. To simply open the file,
enter:
OPENFILE( "file" )
The name of the file is enclosed in double quotation marks. To open
the file with an option, enter:
OPENFILE( [ "file", option ] )
Note the use of the brackets. option is one of the following:
READ
Open file for reading only.
WRITE Open file for writing only.

APPEND Open file for writing. Any data written will be appended to
the end of the file.
OPENBINARY
Redirects output to the specified binary file. To simply open the file,
enter:
OPENBINARY( "file" )
OPENBINARY( [ "file", option ] )
BINARY_READ Open file for binary reading only.
BINARY_WRITE Open file for binary writing only.
BINARY_APPEND Open file for binary writing. Any data written will
be appended to the end of the file.
OPENTEE
Redirects output to a series of destinations:

OPENTEE( [ list ] )
list is a comma-separated list of destinations enclosed in brackets. It
may include TERMINAL and OPENFILE.
22
Changing the Report Device

The output device for most commands (except ANALYZE VARIABLES,
ANALYZE EQUATIONS and SENSITIVITY) can be changed by changing the
system parameter REPORT_DEVICE using the SET command.
Input Language
SET REPORT_DEVICE = device

device
device may be any of the following:

TERMINAL
NOWHERE
OPENFILE
OPENTEE
See the section Redirecting the Output of a Command for details on these
options.
Changing the History Device

The output device for the ANALYZE VARIABLES, ANALYZE EQUATIONS
and SENSITIVITY commands can be changed by changing the system
parameter HISTORY_DEVICE using the SET command.
Input Language
SET HISTORY_DEVICE = device

device
device may be any of the following:

TERMINAL
NOWHERE
OPENFILE
OPENTEE
options.
23
Flushing the Devices

The flushing level determines how frequently the program will force any
buffered data to be written to the output device. For normal batch operation,
you do not need to worry about flushing. When a device is opened, the
DEFAULT_FLUSHING script parameter is used to set the flushing.
Input Language
FLUSH
PRINT FLUSHING device
CHANGE FLUSHING device, level

device
Device to flush.
level
Flushing level. This determines how frequently the program will force any
buffered data to be written to the output device. The default is set to script
parameter DEFAULT_FLUSHING.
NEVER
Never flush
PER_LINE
Flush after each line
PER_WRITE
Flush after each write command
Journaling
A parameter is available to create a journal of all the commands you type at
the console or are invoked in script files. This parameter is called
JOURNAL_DEVICE and may be displayed with the ECHO command and
changed with the SET command. This output can be directed to a file and/or
the terminal. You turn it off by directing it NOWHERE.
A parameter is available to control the level of invoke commands that will be
journaled. This parameter is called JOURNAL_LEVEL and may be displayed
with the ECHO command and changed with the SET command. A value of 0
will journal only the topmost level of commands. A value of 1 will journal the
top two levels of commands. A value of 99999 will journal all levels.
The journal file starts with a comment (using //) indicating the build number
and build date of the executable being run followed by the current date, time
and journal status. Each command executed is added to the journal file
followed by a time-stamp comment. The journal file is designed so that it may
be run like any other script file, i.e. with the INVOKE command.
24
Input Language
SET JOURNAL_DEVICE = device
SET JOURNAL_LEVEL = level

device
level
Journaling level. This controls the level of invoke commands that will be
journaled. A value of 0 will journal only the topmost level of commands. A
value of 1 will journal the top two levels of commands. A value of 99999 will
journal all levels.
device defaults to NOWHERE but may be any of the following:

TERMINAL
NOWHERE
OPENFILE
OPENTEE
options.
Examining the Output Devices

The value of the report, history and journal devices can be examined using
the ECHO command.
Input Language
ECHO &REPORT_DEVICE
ECHO &HISTORY_DEVICE
ECHO &JOURNAL_DEVICE
Examples of Redirecting Output

To change the report device to file COLUMN.REP enter:
SET REPORT_DEVICE = OPENFILE( "COLUMN.REP" )
To have the report sent to both the terminal and file COLUMN.REP enter:
SET REPORT_DEVICE = OPENTEE( [ TERMINAL, OPENFILE( "COLUMN.REP" ) ] )
To change the report device to file COLUMN.REP and open it with the
appending option enter:
SET REPORT_DEVICE = OPENFILE( [ "COLUMN.REP", APPEND ] )
25
Script Parameters
Script parameters are quantities that are local to the scripting language. You
may define your own script parameters to perform a variety of tasks:
Define a character string.
Define a format for formatted printing.
Control the behavior of OOMF through pre-defined script parameters.
Script parameters have the following naming convention:
Names are limited to 128 characters.
Names must start with a letter (A-Z) and only contain letters, numbers,
and underscores (A-Z 0-9 _ ).
Script parameters may be strings, numeric quantities or identifiers. Like

variables, numeric values are always stored in SI units and have units
attributes. The values of script parameters may be set with the SET (for
global script parameters) or LOCAL (for local script parameters) commands
and viewed with the ECHO command.
The commands for working with script parameters can also be used with
variables defined by models. Names of these variables may contain other
characters, which may need to be quoted, as specified below:
All names must begin with a letter (A-Z), digit (0-9) or a dollar sign ($).
The following characters can appear in a name without any special

treatment:
A-Z 0-9 $ : + - _ .
The following characters can appear in a name, but when they do, the
whole name must be delimited by single quotation marks:
(blank) ; / = * , () [] {} <>
The ampersand (&), percent sign (%) and the pound sign (#) are not
valid characters.
Global Script Parameters

Script parameters defined with the SET command are global by default. A
global script parameter is available anywhere regardless of where it is
defined. All built-in script parameters are global. Global script parameters are
defined with the SET command. See Setting Script Parameter Values.
26
Local Script Parameters

A local script parameter is available only within the script file or block script
method where it is defined. Its value is not available outside of the defining
script. This also means that it is not available to a script invoked by the
defining script.
If a local script parameter has the same name as a global script parameter,
then the global script parameter value is re-defined.
Local script parameters are defined with the LOCAL command. See Setting
Script Parameter Values.
Built-In Script Parameters

OOMF uses pre-defined script parameters that provide information on OOMF
and control operation:
Script Parameter
Description
BLOCKS
List of blocks in the current scope (read only).
BUILD_DATE
Build date of the OOMF software. (read only) The format is

DAY MON DATE HRS:MIN:SEC YEAR
BUILD_NUMBER
Build number of the OOMF software (read only)
CONVERGED
Indicates if the last solve converged (read only)
CHECK_UOM
Indicates if the user is required to enter the units of measure for every value
entered (default = FALSE)
DATE
The date and time of day as a string. (read only) The format is
DAY, MON DATE, YEAR, HRS:MIN.
DEFAULT_FLUSHING
Default flushing level for new files. NEVER is recommended for VMS
systems.
DIAG_LEVEL
NEVER
Never flush
PER_LINE
Flush after each line (default)
PER_WRITE
Flush after each write command
Diagnostic level to control debug printing (default = 4).
DYN_INTERVAL
Reporting or communication interval for a dynamic simulation.
DYN_RUN_TO
Time to which a dynamic simulation should run to.
FLANGE_PHASE
Used as a default phase for a stream connection from a mole flow stream to
a mole fraction stream. This determines the type of flash to be performed:
HISTORY_DEVICE
VL
Mixed vapor and liquid phases (flash required)
VLF
Mixed vapor, liquid and free water phases (flash with free
water required)
UNKNOWN
Unknown phase (default).
Destination where history information is to be output. Use ECHO

&HISTORY_DEVICE to examine the current value.
TERMINAL
NOWHERE
OPENFILE
OPENTEE
See the section Redirecting the Output of a Command for details on

these options.
27
Script Parameter
Description
JOURNAL_DEVICE
Destination where journaling output is to be directed. Use ECHO

&JOURNAL_DEVICE to examine the current value.
TERMINAL
NOWHERE
OPENFILE
OPENTEE

these options.
JOURNAL_LEVEL
How many levels of invoke commands are journaled. A value of 0 will journal
only the topmost level of commands. A value of 1 will journal the top two
levels of commands. A value of 99999 will journal all levels.
MAJOR_VERSION
Major version of the OOMF software (read only)
MEAS_CAPACITY
Initial capacity for measurement blocks (default = 50)
MINOR_VERSION
Minor version of the OOMF software (read only)
MODE
Operating mode (default = INI)
NAME_WIDTH
Width of the name field in the PRINT commands, such as PRINT

VARIABLES, PRINT ALIAS, PRINT FIXED, PRINT MEASUREMENTS,
PRINT EQUATIONS, PRINT LARGEST EQUATIONS, and PRINT
JACOBIAN
(default = 40)
NUMBER_WIDTH
Width of the number field in some output commands, such as WRITE

VARFILE, and WRITE VARFILE EXCEPT (default = 12)
OBJECTIVE
The name of the objective function to be used during the solution (default =
NONE)
ONLINE
Indicates if the program is running on-line or off-line (read only)
P_AMB
Ambient pressure for converting to/from gauge pressure. In online

situations, this can be set to the actual ambient pressure (default = 1
{atm})
PAGE_WIDTH
Width of the page for some output commands, such as WRITE VARFILE,
and WRITE VARFILE EXCEPT (default = 131)
PRINT_VAR_MASK
Default variable mask used for the PRINT VARIABLES, PRINT FIXED,
PRINT QUERY, PRINT ALIAS, and PRINT ACTIVE_BOUNDS commands
(default = [NAME, LOWER, VALUE, UPPER, UNITS, SPEC]).
PROBID
Current problem name as identifier (read-only)
PROBNAME
Current problem name as string (read-only)
PROMPT
Command line prompt (default = OOMF>)
READ_VARFILE_MASK
Default variable mask used for the READ VARFILE command

(default = [NAME, UNITS, VALUE, INIT, CHANGE, LOWER, UPPER,
STEP, BOUND, SPEC, SSPEC, SCALE, SBWEIGHT, RLOWER, RUPPER]).
RELAX_TOL
Relaxed-bound tolerance (default = 0)
REPORT_DEVICE
Destination where output from the PRINT and REPORT commands are to
be directed. Use ECHO &REPORT_DEVICE to examine the current value.
TERMINAL
NOWHERE
OPENFILE
OPENTEE

these options.
RESTORE_STATE
Indicates whether or not to restore variable state for existing

user blocks that are re-initialized when a new block is added to the problem
matrix. Only blocks that have a matrix precedence higher than the
block being added are affected by this parameter (default = FALSE).
28
Script Parameter
Description
RUN_MODE
Run mode for a simulation. The options are SS (for steady-state

simulations), INIT (for initialization simulations) and DYN (for dynamic
simulations). The default value is SS. (The INT and DYN run modes are only
relevant to dynamic models.).
SCRIPT_PATH
Semicolon separated list of directories that are searched left to right if a

specified script cannot be found. (default = undefined).
SOFT_BOUND
Flag for soft bounds (default = TRUE).
STEP_BOUND
Flag for step bounds (default = TRUE).
UOM_WIDTH
Width of the name field in the PRINT commands, such as PRINT

VARIABLES, PRINT ALIAS, PRINT FIXED and WRITE VARFILE (default
= 8).
WRITE_VARFILE_MASK
Default variable mask used for the WRITE VARFILE command (default =
[NAME, UNITS, VALUE, INIT, CHANGE, LOWER, UPPER, STEP,
BOUND, SPEC, SSPEC, SCALE, SBWEIGHT, RLOWER, RUPPER])
Setting Script Parameter Values

The value of any global script parameter may be defined with the SET
command. The value of any local script parameter may be defined with the
LOCAL command.
Input Language
SET parameter = expression
LOCAL parameter = expression

parameter
Name of the parameter. The name may be constructed by string

concatenation and use the STRING2ID function. If no parameter is
entered, SET and LOCAL return a list of all defined parameters.
expression
An expression to define the parameter value. This may be a string in

double quotes or a mathematical expression. A mathematical expression
may include the operators:
+, -, *, /, ^, .
and the relational operators:
<, >, =, <>, <=, >=
as well as the functions:
ABS, LOGE, LOG10, COS, SIN, TAN, EXP, SQRT, INT,
STRING2ID, ID2STRING, TOUPPER, TOLOWER, LENGTH, SUBSTR,
INDEX, INSERTSTR, REMOVESTR, OPENFILE, OPENBINARY,
DEVICEINFO, OPENTEE, VAL, TYPEOF, DEFINED, HEAD, TAIL,
BLOCKVARS, BLOCKATTRS, QUERYVARS, ALIASESBYVAR,
CONNECTIONSBYVAR, MEASUREMENTSBYVAR, SPECGROUPSBYVAR
Expressions are discussed further in the section titled Expressions and
Conditionals.
29
Unsetting Script Parameters

The value of any script parameter may be set to undefined with the UNSET
command.
Input Language
UNSET parameter

parameter
Name of the parameter. The name may be constructed by string

concatenation and use the STRING2ID function.
Accessing Parameter Values

The value of any script parameter may be accessed using the & character.
See the following examples.
Examples of Script Parameters

To print the value of the CONVERGED parameter to the report device we
enter:
ECHO &CONVERGED
We could use this parameter value in an IF-THEN-ELSE construct to control
whether we save our variable values at the completion of the problem:
IF (&CONVERGED) THEN
SAVE VARIABLES [VALUE] TO "COLUMN_SIM.X"
ENDIF
To set the mode to SIM we enter:
SET MODE = SIM
To define a numeric parameter called TEMP the value of 30 C, enter:
SET TEMP = 30.{C}
To define a string parameter called FILENAME the value of COLUMN.VBL we
enter:
SET FILENAME = "COLUMN.VBL"
We can then use this file name as the report device:
SET REPORT_DEVICE = OPENFILE(&FILENAME)
We can use string concatenation to define the name of the parameter we wish
to set:
EO> SET STRING2ID("P" . "1") = 10
EO> ECHO &P1
10
Note the use of the STRING2ID function. This converts the resultant string
P1 into an identifier, which is required for the SET command.
30
We can build up this name from two script parameters:

EO> SET NAME = "P"
EO> SET NUM = "1"
EO> SET STRING2ID( &NAME . &NUM ) = 10.
EO> ECHO &P1
10 {*}
However, the scripting language will automatically perform the STRING2ID
function is some cases. So here, we can also write:
EO> SET NAME = "P"
EO> SET NUM = "1"
EO> SET &NAME&NUM = 10.
EO> ECHO &P1
10 {*}
Note that we do not put any blanks between the two parameter references.
We can also build the name from a parameter and another string:
EO> SET NAME = "P"
EO> SET &<NAME>1 = 10.
EO> ECHO &P1
10 {*}
Note that we place NAME in angled brackets (<>) to avoid ambiguity.
You can set a script parameter to a variable with this command:
EO> SET VAR = C2S.D.STR.C2H6
EO> ECHO &VAR
0.0001 {UNITLES}
However, when you do this, it is the variable ID that is transferred to the
script parameter, not the value. So when you change the variable value, the
script parameter also changes. You can verify this with the TYPEOF function:
EO> C2S.D.STR.C2H6 = 0.0002
EO> ECHO &VAR
0.0002 {UNITLES}
EO> ECHO TYPEOF(&VAR)
VARIABLE
If this is not the desired effect, use the VAL function. This ensures that only
the value of the variable, not the ID, is transferred to the script parameter:
EO> SET VAR = VAL(C2S.D.STR.C2H6)
EO> ECHO &VAR
0.0001 {UNITLES}
EO> C2S.D.STR.C2H6 = 0.0002
EO> ECHO &VAR
0.0001 {UNITLES}
REAL
31
Invoke Commands
These commands allow you to call, or invoke, other scripts. These may be
scripts that have been entered in external files.
Invoking an External File

An external script file may be invoked with this command.
You may pass arguments to the invoked script file and get a returned value.
Note: If the file argument is the same as a block ID, problem ID, or the word
PLANT, then the command may be interpreted as an attempt to invoke a
block script or plant-level script. To avoid this, use names for external files
that do not conflict with these IDs.
Input Language
INVOKE file, arg1, arg2,

file
Name of an external script file to execute. The default extension is EBS.
arg1,
arg2
Optional list of arguments passed to the script file. This may be referenced in
the invoked script as &ARG1, &ARG2 etc. These are local script parameters
and thus only available within the invoked script. The total number of
arguments passed to the script file is available as &ARGC. The value returned
to the invoking script is available as &RET_VALUE.
Invoking a Block Script

Any method in a block script can be invoked with this command. When the
INVOKE is executed, the scope is implicitly changed to the blocks level.
You may pass arguments to the invoked script and get a returned value.
Input Language
INVOKE blockid, method, arg1, arg2,
32
blockid
Name of the block script to execute.
method
Name of the script method to execute.
arg1,
arg2
Optional list of arguments passed to the script. This may be referenced in the
invoked script as &ARG1, &ARG2 etc. These are local script parameters and
thus only available within the invoked script. The total number of arguments
passed to the script file is available as &ARGC. The value returned to the
invoking script is available as &RET_VALUE.
Invoking Scripts Within a Scope

A group of block scripts within a scope can be executed with the SCOPE
INVOKE command. This command executes the block scripts in a
predetermined order.
When hierarchies are present, the SCOPE INVOKE command executes all the
blocks in the hierarchies first, then the hierarchy scripts. It effectively works
its way up the directory tree of the flowsheet. As each INVOKE is executed,
the scope is implicitly changed to the blocks level.
Input Language
SCOPE INVOKE blockid, method

blockid
Name of the scope to execute. SELF refers to the name of the current scope.
method
Name of the script method to execute.
See Also
Aspen Plus Extensions - Invoke Commands
Script Arguments
Scripts may have arguments passed to them and may return a single
argument. The arguments are passed with the INVOKE command:
INVOKE file, arg1, arg2,
These may be referenced in the invoked script as &ARG1, &ARG2 etc. These
are local script parameters and thus only available within the invoked script.
The total number of arguments passed to the script file is available as
&ARGC.
The script file may define a return value using the RETURN command:
RETURN value
This command terminates execution of the script.
The invoking script may reference the returned value as &RET_VALUE. This
is a local script parameter.
Examples of Invoke Commands

To invoke a script file called SETINDEP.EBS, enter:
INVOKE SETINDEP
The file extension is not necessary.
To invoke a method INIT in block C2S, enter:
INVOKE C2S, INIT
Consider the flowsheet structure:
33
PLANT
S1
B1
B2
S2
B3
B6
S3
B4
B5
To invoke all the PRESOLVE methods in scope S2, enter:

SCOPE INVOKE S2, PRESOLVE
The scripts would be executed in this order: B4, B5, S3, B6, S2.
Program Flow Control

These commands allow you to perform advanced programming functions such
as IF-THEN-ELSE, FOR-DO and WHILE-DO.
IF-THEN-ELSE Command
This command can be used to define conditionals to control program
execution.
Input Language
IF ( condition ) THEN
ELSEIF ( condition ) THEN
ELSE
ENDIF
34

condition
A TRUE/FALSE condition. This may include the operators:

+, -, *, /, ^, .
<, >, =, <>, <=, >=
STRING2ID, ID2STRING, TOUPPER, TOLOWER, LENGTH,
SUBSTR, INDEX, INSERTSTR, REMOVESTR, OPENFILE,
OPENBINARY, DEVICEINFO, OPENTEE, VAL, TYPEOF, DEFINED,
HEAD, TAIL, BLOCKVARS, BLOCKATTRS, QUERYVARS,
ALIASESBYVAR, CONNECTIONSBYVAR, MEASUREMENTSBYVAR,
SPECGROUPSBYVAR
Logical operators are also allowed:
OR, AND, NOT
Conditions are discussed further in the section titled Expressions
and Conditionals.
FOR-DO Command
This command can be used to define an execution loop.
Input Language
FOR index IN list DO
BREAK
CONTINUE
ENDFOR

index
Index in the defined list. If the index is defined before the FOR-DO loop
executes, its original value will be restored after the loop terminates. If
the index is undefined before the loop executes, it will be undefined after
the loop terminates.
list
List of quantities that define the FOR-DO loop. The list is separated by
commas and enclosed in brackets.
BREAK
Used to break out of the FOR-DO loop.
CONTINUE
Used to skip to the next index in the FOR-DO loop.
35
WHILE-DO Command
This command can be used to define an execution loop.
Input Language
WHILE ( condition ) DO
BREAK
CONTINUE
ENDWHILE

condition
A TRUE/FALSE condition. This may include the operators:

+, -, *, /, ^, .
<, >, =, <>, <=, >=
STRING2ID, ID2STRING, TOUPPER, TOLOWER, LENGTH, SUBSTR,
INDEX, INSERTSTR, REMOVESTR, OPENFILE, OPENBINARY,
DEVICEINFO, OPENTEE, VAL, TYPEOF, DEFINED, HEAD, TAIL,
BLOCKVARS, BLOCKATTRS, QUERYVARS, ALIASESBYVAR,
CONNECTIONSBYVAR, MEASUREMENTSBYVAR, SPECGROUPSBYVAR
Logical operators are also allowed:
OR, AND, NOT
Conditions are discussed further in the section titled Expressions and
Conditionals.
BREAK
Used to break out of the WHILE-DO loop.
CONTINUE
Used to skip to the next index in the WHILE -DO loop.
Examples of Program Flow Control

This is an example of using the IF-THEN-ELSE block to check the convergence
of a problem and save the variable values to a binary file if converged:
IF (&CONVERGED) THEN
ECHO "The problem was successful."
SAVE VARIABLES [VALUE] TO "COLUMN.XSM"
ELSE
ECHO "The problem failed."
ENDIF
We can also use the IF-THEN-ELSE to check the values of variables:
IF (B1.BLK.TEMP > 50 {F}) THEN
ECHO "TEMP TOO HIGH"
ELSE
ECHO "TEMP OK"
36
ENDIF
This is an example of a FOR-DO loop:
FOR I IN [1, 2, 4] DO
ECHO &I
ENDFOR
This will cause the following lines to be output to the report device:
1
2
4
A more pertinent example would be to define a script parameter that holds
certain blocks in a problem and then use the list in a FOR-DO loop:
SET BLOCKLIST = [ F,
C2S,
CIN,
CDEF,
CVAP,
CONDUA
FOR I IN &BLOCKLIST DO
REPORT BLOCK &I
ENDFOR
\
\
\
\
\
]
This will cause each block to be reported in the ordered set in the script
parameter.
A more complex example would be to create a list of script parameters and to
refer to them in a FOR-DO loop:
SET
SET
SET
FOR
TEST1 = 100
TEST2 = 200
VARNAME = [ TEST1, TEST2 ]
I IN &VARNAME DO
ECHO &&I
ENDFOR
Note the use of &&I to indicate a double parameter reference. This will result
in the following output:
100
200
37
Expressions and Conditionals

The scripting language has an ability to evaluate complex expressions.
Expressions can be used to set variable attributes, define an objective
function, set script parameters, etc.
Input Language
expression
(expression) # {uom}

If you wish to assign units to an expression, enclose the expression in
parenthesis and use the pound sign # and the standard braces {} to enter
the units.
The following is a list of the available functions that can be used in
expressions:
Mathematical Functions:
38
Addition
Subtraction
Multiplication
Division
Power
ABS
Absolute value
LOGE
Natural logarithm
LOG10
Logarithm
COS
Cosine
SIN
Sine
TAN
Tangent
EXP
Exponentiation
SQRT
Square root
INT
Nearest integer
String Functions:
.
String concatenation
STRING2ID
Converts string to an ID
ID2STRING
Converts ID to a string
TOUPPER
Converts string to uppercase
TOLOWER
Converts string to lowercase
LENGTH
Length of string
SUBSTR
Returns a substring from a given string. It may be used as

SUBSTR( string, position, length )
Or
SUBSTR( string, position )
string
Source string.
positionStarting position of returned substring. A position of 1 is the

first character. A negative value indicates a backwards count
from the end.
length Optional length. If omitted, the indicated position to the end
of the string is returned.
INDEX
Returns the index of a substring within another string. A return value of

zero indicates that the substring was not found. It may be used as
INDEX( string, substring, position )
Or
INDEX( string, substring ).
string
Source string.
substring
Substring to search the string for.
positionOptional starting location to begin search. If omitted, the

search begins at position 1. This must be positive.
INSERTSTR
Inserts a substring into a string at the specified position.

INSERTSTR( string, substring, position )
string
Source string.
substring
Substring to insert.
positionPosition to insert substring. A position of 1 is the first

character. A negative value indicates a backwards count from
the end.
REMOVESTR
Removes a substring of specified length from a string at a specified

position.
REMOVESTR( string, position, length )
string
Source string.
positionPosition to remove substring. A position of 1 is the first

character. A negative value indicates a backwards count from
the end.
length Length of substring to remove.
39
Relational Functions:
<
Less than
<=
Less than or equal to
Equal to
<>
Not equal to
>
Greater than
>=
Greater than or equal to
Logical Functions:
AND
Logical AND
OR
Logical OR
NOT
Logical NOT
File Functions:
OPENFILE
Redirects output to the specified ASCII file. To simply open the file,
enter:
OPENFILE( "file" )
OPENFILE( [ "file", option ] )
OPENBINARY
READ
Open file for reading only.
WRITE
Open file for writing only.
APPEND
Open file for writing. Any data written will be

appended to the end of the file.
Redirects output to the specified binary file. To simply open the file,
enter:
OPENBINARY( "file" )
OPENBINARY( [ "file", option ] )
OPENTEE
BINARY_READ
Open file for binary reading only.
BINARY_WRITE
Open file for binary writing only.
BINARY_APPEND
Open file for binary writing. Any data written

will be appended to the end of the file.
Redirects output to a series of destinations:

OPENTEE( [ list ] )
list is a comma-separated list of destinations enclosed in brackets. It
may include TERMINAL and OPENFILE.
DEVICEINFO
40
Returns information about the specified device. This function should

be used in PRINT FORMATTED and IF-THEN-ELSE commands.
List Functions:
.
Concatenate two lists
ELEM
A specific element in a list.

Usage set Parameter_name = ELEM(&List_name, Location)
HEAD
First element in a list
NUM
Number of elements in a list.
REPLELEM
Replace a specific element in a list

set New_List_name = REPLELEM(&List_name, Location, Value)
TAIL
List with the first element removed
Query Functions:
BLOCKVARS
Returns list of variables in the specified block
BLOCKATTRS
Returns list of attributes in the specified block
QUERYVARS
Returns list of variables using the specified query string
ALIASBYVAR
Returns list of aliases matching the specified variable.

Wildcards may be used for the variable name.
CONNECTIONSBYVAR
Returns list of connections matching the specified variable.

MEASUREMENTSBYVAR
Returns list of measurement names (as

blockid.tagid_description) matching the specified variable.
SPECGROUPSBYVAR
Returns list of Specification Groups matching the specified

variable. Wildcards may be used for the variable name.
Miscellaneous Functions:
VAL
Returns the value of the quantity, rather than a reference to the ID.
TYPEOF
Returns the argument type.
DEFINED
Logical function indicating if the parameter argument has been given value.
Examples of Math Functions

Lets set a parameter, called FLOW, to the value of a variable:
SET FLOW = C2S.BLK.DISTILLATE_MASS
We can use a simple mathematical expression in this statement:
SET FLOW = C2S.BLK.DISTILLATE_MASS + 5000. {KG/HR}
We can do likewise with variables:
C2S.BLK.DISTILLATE_MASS = C2S.BLK.DISTILLATE_MASS + 5000. {KG/HR}
Or even apply your own version of step bounds:
C2S.BLK.DISTILLATE_MASS.LOWER = C2S.BLK.DISTILLATE_MASS - 5000.
{KG/HR}
C2S.BLK.DISTILLATE_MASS.UPPER = C2S.BLK.DISTILLATE_MASS + 5000.
{KG/HR}
41
Examples of String Functions

Heres a common use of string concatenation to create a file name:
SET FILENAME = &PROBID . "_" . &MODE . "VBL"
SET REPORT_DEVICE = OPENFILE(&FILENAME)
PRINT VARIABLES
SET REPORT_DEVICE = TERMINAL
We could also do this with the TO option:
PRINT VARIABLES TO &PROBID . "_" . &MODE . "VBL"
If the problem ID is COLUMN and the mode is SIM, this will write all the
variables to file COLUMN_SIM.VBL. We can force the file name to lower case
with:
PRINT VARIABLES TO TOLOWER( &PROBID . "_" . &MODE . "VBL" )
To construct an identifier from a string, we use the STRING2ID function. In
the following example, we make a parameter by concatenating two strings.
EO> STRING2ID("P" . "1") = 10
EO> ECHO &P1
10
We can build up this name from two script parameters:
EO> SET NAME = "P"
EO> SET NUM = "1"
EO> SET STRING2ID( &NAME . &NUM ) = 10.
EO> ECHO &P1
10 {*}
However, the scripting language will automatically perform the STRING2ID
function is some cases. So here, we can also write:
EO> SET NAME = "P"
EO> SET NUM = "1"
EO> SET &NAME&NUM = 10.
EO> ECHO &P1
10 {*}
Note that we do not put any blanks between the two parameter references.
We can also build the name from a parameter and another string:
EO> SET NAME = "P"
EO> SET &<NAME>1 = 10.
EO> ECHO &P1
10 {*}
Note that we place NAME in angled brackets (<>) to avoid ambiguity.
Here are some examples of the SUBSTR, INDEX and LENGTH functions.
EO>
EO>
EO>
23
EO>
EO>
45
42
SET STR = "12345"

SET STR1 = SUBSTR(&STR,2,2)
ECHO &STR1
SET STR2 = SUBSTR(&STR,-2,2)
ECHO &STR2
EO> ECHO INDEX(&STR,&STR1)

2
EO> ECHO LENGTH(&STR)
5
Here is an example of INSERTSTR and REMOVESTR.
EO> SET STR1 = "12345"
EO> SET STR2 = "ABC"
EO> SET STR = INSERTSTR(&STR1,&STR2,2)
EO> ECHO &STR
1ABC2345
EO> SET STR = REMOVESTR(&STR,2,3)
EO> ECHO &STR
12345
Examples of Relational and Logical

Functions
Heres an example of a conditional in an IF-THEN-ELSE construct using the
relational operator for less than:
IF (C2S.BLK.TEMP_1 > 50 {F}) THEN
ECHO "TEMP TOO HIGH"
ELSE
ECHO "TEMP OK"
ENDIF
Note that it is necessary to enter the units of measure for the test
temperature.
An example of the AND logical follows:
IF ( C2S.BLK.TEMP_1 < 0 {C} AND C2S.BLK.TEMP_1 > -50 {C} ) THEN
ECHO "TEMP OK"
ENDIF
Examples of File Functions

To change the report device to file COLUMN.REP we need to change the script
parameter REPORT_DEVICE and use the OPENFILE function:
SET REPORT_DEVICE = OPENFILE( "COLUMN.REP" )
To have the report sent to both the terminal and file COLUMN.REP we use the
OPENTEE function:
SET REPORT_DEVICE = OPENTEE( [ TERMINAL, OPENFILE( "COLUMN.REP" )
] )
Note the use of the additional brackets.
To change the report device to file COLUMN.REP and open it with the
appending option enter:
SET REPORT_DEVICE = OPENFILE( [ "COLUMN.REP", APPEND ] )
43
Examples of List Functions

Script parameters can be set to lists of objects, such as blocks. Here is an
example of an interactive session and the use of the HEAD, TAIL and list
concatenation functions:
EO> SET LIST = [A, B, C]
EO> ECHO &LIST
[ A , B , C ]
EO> ECHO HEAD(&LIST)
A
EO> ECHO TAIL(&LIST)
[ B , C ]
EO> SET LIST = &LIST . [D]
EO> ECHO &LIST
[ A , B , C , D ]
Examples of Query Functions

These query functions can be used to return lists of variables or other objects.
For example, to get a list of variables in block C2S, enter:
SET VARLIST = BLOCKVARS( C2S )
You may use the QUERYVARS function to enter a query. For example, to get
a list of variables whose names begin with CVAP and whose values are less
than zero, you may enter:
SET VARLIST = QUERYVARS("NAME=CIN* AND VALUE<0")
The other query functions return lists of objects given the name of a variable.
For example, to get the measurements in block C2S enter:
SET VARLIST = MEASUREMENTSBYVAR( C2S.* )
Note that a wildcard may be used.
To get the list of attributes in block B1 and then print it to the screen, enter
the following commands:
SET ATTRLIST = BLOCKATTRS( B1)
ECHO &ATTRLIST
Examples of Miscellaneous Functions

You can set a script parameter to a variable with this command:
EO> SET VAR = C2S.D.STR.C2H6
EO> ECHO &VAR
0.0001 {UNITLES}
However, when you do this, it is the variable ID that is transferred to the
script parameter, not the value. So when you change the variable value, the
script parameter also changes. You can verify this with the TYPEOF function:
44
EO> C2S.D.STR.C2H6 = 0.0002

EO> ECHO &VAR
0.0002 {UNITLES}
VARIABLE
If this is not the desired effect, use the VAL function. This ensures that only
the value of the variable, not the ID, is transferred to the script parameter:
EO> SET VAR = VAL(C2S.D.STR.C2H6)
EO> ECHO &VAR
0.0001 {UNITLES}
EO> C2S.D.STR.C2H6 = 0.0002
EO> ECHO &VAR
0.0001 {UNITLES}
REAL
Examples of Effects of Units of Measure

Some care must be taken when computing expressions for values that have
units of measure. Consider this simple example below where we wish to
compute the sum of two flows, each in Kg/hr:
EO> SET FLOW = 30. + 15.
EO> ECHO &FLOW
45. {*}
In this case, parameter FLOW is unitless since we did not declare its units. So
we enter:
EO> SET FLOW = (30. + 15.) # {KG/HR}
EO> ECHO &FLOW
162000 {KG/HR}
In this case, the constants 30. and 15. were interpreted in SI units, Kg/sec.
To clarify, we enter:
EO> SET FLOW = 30.{KG/HR} + 15.{KG/HR}
EO> ECHO &FLOW
45. {KG/HR}
Here, the kernel assigned the units of Kg/hr. We can force a change in units
with:
EO> SET FLOW = (30.{KG/HR} + 15.{KG/HR}) # {KG/SEC}
EO> ECHO &FLOW
0.0125 {KG/SEC}
This operation is a little more complex with temperatures and pressures
because of the presence of an offset in their units. In this case, it is not
possible to add two values in units of C. One must be in units of Delta-C:
EO> SET TEMP = 30.{C} + 15.{DELTA-C)
EO> ECHO &TEMP
45. {C}
45
Subtracting temperatures is allowed, the resulting value having units of

Delta-C. We can use this to compute an average of two temperatures:
EO> SET TEMP = 30.{C} + (30.{C} -15.{C)) / 2
EO> ECHO &TEMP
22.5 {C}
Units of measure can be removed if necessary by dividing by one unit as
follows:
EO> SET TEMP = SQRT( C2S.BLK.TEMP_1 / 1.0 {K} )
EO> ECHO &TEMP
15.6191 {UNITLES}
Without the removal of the units of measure, the SQRT function would not
work.
Examples Using String Functions to Create

Variable Names
A common use of script parameters is to use them in conjunction with the
string functions to create variable names so that many variable attributes can
be changed easily.
In this example, we use a FOR-DO loop to define a list of variable names. We
then use a PRINT FORMATTED command to write a table of these variable
attributes:
SET NAME = C2S.BLK.TEMP_
SET LIST = []
FOR I IN [ 1, 2, 60, 61, 99, 100 ] DO
SET LIST = &LIST . [ &NAME&I ]
ENDFOR
PRINT FORMATTED "\n"
PRINT FORMATTED "
TRAY TEMPERATURES \n"
PRINT FORMATTED "
----------------- \n"
PRINT FORMATTED "Name
Low
Value
PRINT FORMATTED "---------SET FMT = "%-20s %-12.7g %-12.7g %-12.7g \n"
FOR VAR IN &LIST DO
PRINT FORMATTED &FMT , ID2STRING(&VAR), \
&VAR.LOWER,
\
&VAR,
\
&VAR.UPPER
ENDFOR
This script will give use the following output:
TRAY TEMPERATURES
---- -----------Name
Low
Value
Upper
-------------C2S.BLK.TEMP_1
-1e+20
-29.19481
1e+20
C2S.BLK.TEMP_2
-150.7233
-28.29885
94.13006
C2S.BLK.TEMP_60
-148.3372
-23.87614
101.2884
C2S.BLK.TEMP_61
-148.3081
-23.85514
101.3758
C2S.BLK.TEMP_99
-139.0004
-5.433002
129.2988
C2S.BLK.TEMP_100
-1e+20
-5.228761
1e+20
46
Upper \n"
----- \n"
Wildcards
There are two wildcard capabilities in OOMF: glob-style and regular
expression matching. The former is the simplest and meets most user needs.
The latter is more complex but is more powerful.
Glob-Style Wildcards
Glob-style wildcards are a simple way to refer to a group of objects so you
can access them in one statement, rather than having to repeat a similar
command again. Not all commands in the script language support glob
wildcards.

Glob wildcards use these special characters to provide the matching
functions:
*
Matches one or more characters
Matches a single character
Regular Expression Matching

Regular expression matching is a powerful form of wildcards. It is mostly used
to refer to a group of variables so you can access their attributes in one
statement, rather than having to repeat a similar command again.
Although powerful, regular expression matching is rather complex.

Regular expression matching uses special characters to provide the matching
functions. The string to be matched is enclosed in percent signs (%). Regular
expression matching processes the string enclosed in percent signs, searching
for these special characters:
.
Matches any single character other than a new line.
Matches zero or more of the character- or parenthesis-delimited group

appearing immediately to the left of the *.
Matches one or more of the character- or parenthesis-delimited group

appearing immediately to the left of the +. x+ is equivalent to xx*.
This makes the character- or parenthesis-delimited group appearing

immediately to the left of the ? optional.
Matches the beginning of the string exactly as typed.
Matches the end of the string exactly as typed.
Matches what appears to the left of the bar or the right of the bar. This
operator has the lowest preference.
()
Used to indicate grouping and to override the normal precedence of

operators. Parentheses match no character themselves.
Used to take away the special treatment of a special character. \. Matches a

period; \| matches a bar character; \\ matches a backslash.
47
[]
Used to define a set of characters. This will match a single character in the
brackets. The range [ab] will match a single a or b. The range [^ab] will
match any character other than a or b. You can indicate a group of characters
using the hyphen. [a-z] will match any character in the alphabet.
There is an implied wildcard at the beginning and end of the string in percent
signs. The ^ and $ special characters allow you to override this implied
wildcard.
When using regular expression to match variable names, you must include
the entire variable name within the percent signs. That is, some parts of the
variable name cannot lie outside the percent signs. The attribute you are
changing may lie outside the percent signs.
Examples of Wildcards
To enter a lower limit of zero for all flows in the flowsheet with glob style
wildcards enter:
*.FLOW.LOWER = 0.0 {KMOL/HR}
To enter a lower limit of zero for all the flows in block C2S:
C2S.*.FLOW.LOWER = 0.0 {KMOL/HR}
Consider the following regular expression:
%FLOW\.LOWER% = 0.0
In simple wildcard jargon, this is equivalent to
*FLOW.LOWER* = 0.0
This is because of the implied wildcard of the percent signs. This would place
lower bounds on all variables that have FLOW in them, i.e., both mass and
molar flows. Note the use of the \ to treat the . as a literal. We do not enter
the units of measure so that we apply the zero as Kmol/Hr for mole flows and
Kg/Hr for mass flows.
If we write
%\.FLOW\.LOWER% = 0.0 {KMOL/HR}
This is equivalent to
*.FLOW.LOWER* = 0.0 {KMOL/HR}
In this case the \ makes the . a literal character. Thus, we only change mole
flows and we can enter the units if we want to. Entering
%.FLOW\.LOWER% = 0.0 {KMOL/HR}
is equivalent to
%FLOW\.LOWER% = 0.0 {KMOL/HR}
because the . is a single-character wildcard and the beginning of the string is
a multicharacter wildcard.
If we wanted to access only stream component molar flows, we enter:
%STR\..*\.FLOW\.LOWER% = 0.0 {KMOL/HR}
This is equivalent to:
48
*STR.*.FLOW.LOWER* = 0.0 {KMOL/HR}

If we wish to change the lower bounds on all the molar flows in unit C2S, we
enter:
%^C2S\..*\.FLOW\.LOWER% = 0.0 {KMOL/HR}
Note that we must put the unit name inside the percent signs. We must use
the ^ to remove the implied wildcard at the beginning of the string. We use
the \. three times to treat the . as a literal. Finally, the .* acts as a
multicharacter wildcard. So this is equivalent to:
C2S.*.FLOW.LOWER* = 0.0 {KMOL/HR}
We can use the $ character to suppress the implied wildcard at the end of the
string. Consider:
%^C2S\..*\.FLOW\.LOWER$% = 0.0 {KMOL/HR}
This is equivalent to
Lets look at an example of using the [] characters:
%^C2S[BD]DEF\..*\.FLOW.LOWER$% = 0.0 {KMOL/HR}
This is equivalent to:
C2SBDEF.*.FLOW.LOWER = 0.0 {KMOL/HR}
C2SDDEF.*.FLOW.LOWER = 0.0 {KMOL/HR}
The [BD] acts as an OR function on the characters B and D.
Finally, here is an even more complex example:
%^C2S([BD]DEF)?\..*\.FLOW.LOWER$% = 0.0 {KMOL/HR}
The ()? Indicates that everything in the parenthesis is optional. So this is
equivalent to:
C2SBDEF.*.FLOW.LOWER = 0.0 {KMOL/HR}
C2SDDEF.*.FLOW.LOWER = 0.0 {KMOL/HR}
General Commands
These general commands include a powerful help facility, a timer for tracking
execution times and other useful functions.
Getting Help
This command provides on-line help.
Input Language
HELP command
49

command
Name of command to get help on. If a keyword is entered, a list of

all commands containing that keyword is printed. If no command is
entered, then a summary of all the commands is printed as shown
at the beginning of this chapter.
Exiting the System

These commands are used to leave the EO strategy in an IAP session and
return to the A+ prompt. They have no effect while in the Aspen Plus user
interface.
Input Language
QUIT
EXIT
Executing System Commands

This command allows you to enter an operating system command when you
are in OOMF. Note that the command is enclosed in double quotation marks.
Input Language
SYSTEM " command "
Timer
A timer that tracks CPU usage is available.
Input Language
START TIMER
STOP TIMER
RESTART TIMER
PRINT TIMER
50
START TIMER
Starts the timer at zero.
STOP TIMER
Stops the timer.
RESTART TIMER
Restarts the timer at the current value.
PRINT TIMER
Prints the timer to the report device.
OOMF Model Adapters

OOMF loadable models are compiled and placed into a DLL library. You can
write model adapters to load various types of models into OOMF:
Models exported from Aspen Custom Modeler may be loaded into OOMF
using the OOMF loadable DLL named acmexp.
Aspen Plus equation oriented models may be loaded into OOMF using the
OOMF loadable DLLs named rtoblk and pmlbridge.
Aspen HYSYS Refining reactor models may be loaded into OOMF using
OOMF loadable DLLs named usrdmo and refpmlbridge.
The example model called pltcon that is delivered with OOMF may be
loaded into OOMF using the OOMF loadable DLL named pltcon.
Custom user models written in C++ or other programming languages may

be loaded into OOMF using the OOMF loadable DLL named CMF. Aspen
PIMS and Aspen Advisor models are loaded into OOMF via CMF.
Aspen PIMS sub-model calculator models, short cut distillation models,

and models described by MPS format files may be loaded into OOMF using
the OOMF loadable DLL named xlpadap.
The appropriate library is loaded to instantiate these models in OOMF. The

following commands load, unload, and inquire about these libraries.
Input Language
IDENTIFY LIBRARY dll_name
LOAD LIBRARY dll_name
UNLOAD LIBRARY dll_name

IDENTIFY LIBRARY
Returns the version number of the specified DLL
LOAD LIBRARY
Loads the specified DLL
UNLOAD LIBRARY
Unloads a previously loaded DLL
51
52
3 Hierarchies, Blocks,
Variables and Equations
This chapter describes the OOMF Script commands used to manipulate

hierarchies, blocks, variables and equations.
Hierarchies
Hierarchies are blocks that are used to contain parts of a flowsheet. This
allows you to organize your flowsheet into manageable sections that may be
solved separately.
See Also
Aspen Plus Extensions - Hierarchies
What are Hierarchies?

Hierarchies are convenient ways of organizing very large flowsheets or
creating large flowsheets from a collection of smaller flowsheets.
A hierarchy is a collection of blocks that are treated as a single block. The
names of all the variables and equations within the hierarchy have their
names prefixed with the hierarchy name. For example, if you have a variable
named C2S.BLK.TEMP_1 and this block is placed in a hierarchy called T1, then
the new name will be T1.C2S.BLK.TEMP_1.
The hierarchy becomes a simple way of grouping blocks together. This makes
it easy to exclude a group of blocks from a flowsheet with a single command.
Hierarchies may contain other hierarchies.
3 Hierarchies, Blocks, Variables and Equations
53
How are Hierarchies Created?

Hierarchies are usually created through the product such as Aspen Pluss user
interface or input language by placing a hierarchy block onto the flowsheet.
See Also
If you are using standalone OOMF, then a hierarchy may be created by
invoking the following set of commands in a script file:
load lib "pltcon"
set num_blocks_in_hierarchy = 2
DEFINE SUPERPLANT small_hierarchy
METHOD setup BEGIN
BLOCKS NONE
SET small_group_iter = 1
WHILE (&small_group_iter <= &num_blocks_in_hierarchy) DO
echo "add block pltcon"
ADD BLOCK b&small_group_iter AS pltcon
SET small_group_iter = &small_group_iter + 1
ENDWHILE
END setup
METHOD alias BEGIN
ALIAS [ key_var, b1.blk.var_150 ]
END alias
METHOD connect BEGIN
CONNECTIONS NONE
SET small_group_iter = 1
WHILE (&small_group_iter < &num_blocks_in_hierarchy) DO
SET small_group_iter_next = &small_group_iter + 1
echo "add conn"
ADD CONNECTION [ b&small_group_iter.blk.var_1 , \
b&small_group_iter_next.blk.var_1 ]
SET small_group_iter = &small_group_iter_next
ENDWHILE
END connect
METHOD measurement BEGIN
MEASURE key_var
END measurement
METHOD setvar BEGIN
key_var.sbweight = 1.5e5 {*}
key_var.step = 150.0 {*}
END setvar
END small_hierarchy
add block C2HIER as small_hierarchy
54
Hierarchy Input
Hierarchies have sets of input that are similar to what can be defined for an
entire flowsheet.
In standalone OOMF the inputs include:
Streams.
Blocks.
Convergence options, such as solver parameters.
Flowsheeting Options, such as measurement blocks.
Objective functions, Spec Groups, and Connections.
The type of input that may be entered for an EO configuration item is limited
by the scope.
See Also
What is the Scope?

When a flowsheet contains a collection of hierarchies, a tree structure similar
to a conventional directory structure is used to organize the hierarchies. The
scope determines what parts of the tree are visible at any given time. You
may use the scope combo box on the Control Panel or the SCOPE commands
to move around this tree. For example, what you see when you execute
PRINT BLOCK STATISTICS will depend upon the current scope. See also:
Defining the Scope
Printing the Block Hierarchy
Finding a Block
At the top of the tree, when the scope is the CONTROLLING KERNEL, the
entire problem is visible to the kernel. At this level, hierarchies appear as
single blocks.
When you move down the tree into a hierarchy by pushing the scope, the
scope becomes the name of the hierarchy. At this scope, all the blocks within
the hierarchy, the user connections and the measurements become visible.
Understanding how the scope works is very important. Consider the example:
55
Flowsheet Level
S1
B1
B2
S2
B3
B6
S3
B4
B5
The flowsheet consists of two hierarchies S1 and S2. Hierarchy S1 is made up

of blocks B1, B2 and B3. Hierarchy S2 is made up of block B6 and hierarchy
S3, which is in turn made up of blocks B4 and B5.
When the scope is at the controlling kernel, we can only see hierarchies S1
and S2. If you push the scope into S1, you can see blocks B1, B2 and B3.
EO input attached to any block or hierarchy is limited to the scope of the
block to which it is attached. For example, to make a user connection
between block B6 and B3, you must do it in hierarchy PLANT. You cannot
define the connection in hierarchy S1, since block B6 is outside its scope. Nor
can you define it in hierarchy S2, since block B1 is outside of its scope. If you
wish to connect blocks B2 and B3, you can do so in hierarchy S1 or at the
flowsheet level.
56
How Hierarchies are Built

The lowest level hierarchy blocks are completely constructed first, followed by
the next higher level. In other words, the tree structure is built up from the
bottom to the top.
Each hierarchy is built in this order:
Blocks are instantiated. As each block is instantiated, the following is

executed:
o
INIT scripts are invoked.
EO Input form is executed.
The flowsheet level EO Input is executed.
Measurements are instantiated.
Spec Groups are processed.
Product specific stream connections are built.
User connections are built.
Measurement connections are built.
Only after each hierarchy is completely built is execution passed to the next
hierarchy.
Defining the Scope

The scope determines what blocks are visible. The problem may be thought of
as a tree structure, not unlike a directory. By moving up and down the tree,
that is, by changing the scope, different parts of the problem become visible.
At the top of the tree, when the scope is the CONTROLLING KERNEL, the
entire problem is visible to the kernel. At this level, hierarchies appear as
single blocks. When you move down the tree into a hierarchy, the scope
becomes the name of the hierarchy and all the blocks within the hierarchy
become visible. You can view the layout of all the blocks in the flowsheet with
the PRINT BLOCK HIERARCHY command.
A note of caution: if you use these scope commands from within products that
embed OOMF, you may get into situations where OOMF is out of sync with
that products user interface. Therefore, care should be exercised when using
these commands in the products user interface.
57
Input Language
PUSH SCOPE blockid
CHANGE SCOPE blockid
POP SCOPE
RESET SCOPE
PRINT SCOPE

PUSH SCOPE
Pushes the scope down the tree into the specified hierarchy.
CHANGE SCOPE Resets the scope and then pushes the scope down the tree into the
specified hierarchy.
POP SCOPE
Pops the scope up the tree one level.
RESET SCOPE
Pops the scope up to the top of the tree.
PRINT SCOPE
Prints the current scope.
Printing the Block Hierarchy

This command is used to print the complete block hierarchy for the flowsheet
from the current scope on downward. This is useful to locate the position of a
block in a complex flowsheet structure.
Input Language
PRINT BLOCK HIERARCHY
Finding a Block
This command is used to find a block within a flowsheet. It searches within
the current scope and, if the block is not found, continues the search from the
global scope.
Input Language
FIND BLOCK blockid

blockid
58
Name of block to find.
Solving at a Scope
A scope may be solved separately from the rest of the flowsheet. This may be
done by changing the scope to the desired level, which may be done through
the products user interface or with the PUSH SCOPE command. The scope
may then be solved either through the products user interface or with the
SOLVE command.
A complication arises when connections and specification groups cross the
scope boundary. When this occurs, the scope may be non-square. (You may
use the ANALYZE DOF command to check.) Specification Management
automatically inactivates these objects when the SOLVE is executed. This
keeps the problem well defined at any scope level. It is therefore very
straightforward to solve your problem at any scope.
The inactivation of these objects occurs at the instant the SOLVE command is
issued and reactivated immediately afterwards. Therefore, when you examine
your reduced scope problem, what you see is not what the solver is seeing.
You may use the TOGGLE SOLVE SCOPE command to inactivate any
connections and specification groups that cross the scope boundary. If you
issue the command again, the connections and specification groups are reactivated.
Input Language
TOGGLE SOLVE SCOPE
Examples of Hierarchy
The following interactive session shows a flowsheet with two hierarchies
called C2HIER and C3HIER and a normal block. First, the block statistics are
printed and the hierarchies appear as any other block. When the scope is
pushed into one of the hierarchies, the blocks within the hierarchy appear.
Within the hierarchy the problem is non-square due to streams, connections
and specification groups that cross the hierarchy boundary. When the
TOGGLE SOLVE SCOPE command is issued the problem becomes square.
The SOLVE command solves the reduced scope problem.
EO> PRINT BLOCK STATISTICS
---Block-- -Nvar- -Neqn- -NfixC2HIER
1369
1324
24
C3HIER
79
64
7
CONDUA
12
5
3
---------- ------ ------ -----Total
1460
1393
34
EO> PUSH SCOPE C3HIER
EO> PRINT BLOCK STATISTICS
---Block-- -Nvar- -Neqn- -NfixCVAP
41
33
3
CIN
35
30
3
C3MEAS
3
1
1
---------- ------ ------ -----Total
79
64
7
Nexcld -Ndof- NfreeI --Nnz- --Nz%0

0
7
6808
0.38
0
0
1
183
4
0
0
0
15
33
------ ------ ------ ------ -----0
0
8
7006
Nexcld -Ndof- NfreeI --Nnz- --Nz%0

0
1
96
7.7
0
0
0
85
8.9
0
0
0
2 1e+002
------ ------ ------ ------ -----0
0
1
183
59
EO> ANALYZE DOF

Problem has 1 degrees of freedom
EO> TOGGLE SOLVE SCOPE
EO> ANALYZE DOF
Problem is square
EO> SOLVE
Residual
Objective
Objective
Overall
Model
Convergence Convergence Function Nonlinearity Nonlinearity Worst
Iteration
Function
Function
Value
Ratio
Ratio
Model
--------- ----------- ----------- ---------- ------------ ------------ ------0
2.834D-01
0.000D+00 0.000D+00
1.000D+00
1.000D+00 CVAP
1
4.147D-06
0.000D+00 0.000D+00
1.000D+00
1.000D+00 CVAP
2
0.000D+00
0.000D+00 0.000D+00
Successful solution.
Optimization Timing Statistics

================================
Time
========
MODEL computations
DMO computations
Miscellaneous
-------------------------------Total Optimization Time
0.02 secs
0.00 secs
0.14 secs
--------0.16 secs
Percent
=======
12.50 %
0.00 %
87.50 %
------100.00 %
Problem converged
EO> ANALYZE DOF
Problem is square
EO> TOGGLE SOLVE SCOPE
EO> ANALYZE DOF
Problem has 1 degrees of freedom
EO> RESET SCOPE
EO> ANALYZE DOF
Problem is square
EO>
60
Block Commands
The block commands are used to control the blocks that are to be included in
the OOMF solution.
Listing Blocks
The BLOCKS command is used to show the list of instantiated blocks in the
current scope. This command does not list blocks in child containers.
Input Language
BLOCKS
The PRINT ALL BLOCKS command is used to list all the blocks in the current
scope, including child containers. The blocks are listed by their full qualified
names.
Input Language
PRINT ALL BLOCKS
The PRINT EXCLUDED BLOCKS command is used to list all blocks in the
current scope, including child containers, that are currently excluded. The
blocks are listed by their full qualified names.
Input Language
PRINT EXCLUDED BLOCKS
The PRINT INCLUDED BLOCKS command is used to list all blocks in the
current scope, including child containers, that are currently included. The
blocks are listed by their full qualified names.
Input Language
PRINT INCLUDED BLOCKS
Excluding Blocks
These commands can be used to exclude blocks from the problem. Excluding
a block removes all its equations and variables from the flowsheet.
When a block is excluded, Spec Management automatically reprocesses all the
Connections and Spec Groups to ensure that the problem remains square.
61
Connections and Spec Groups that contain references to the excluded block
become Inactive. (The Status on the GUI is not updated until an Incremental
Build or Solve is performed.) Variables that are connected from an excluded
block return to their pre-connected specifications, usually Constant.
When a block is excluded, it still appears in the list of blocks. If you display
the block with PRINT BLOCK STATISTICS, the block name will appear in
parentheses. Equation residuals and Jacobian values are not calculated for
excluded blocks.
Input Language
EXCLUDE BLOCKS block_list

block_list
Comma-separated list of the blocks to exclude.
Including Blocks
This command can be used to include blocks that have been previously
excluded. This procedure works in a similar manner to the EXCLUDE
BLOCKS command (see previous section).
Input Language
INCLUDE BLOCKS block_list

block_list
Comma-separated list of the blocks to include.
Listing Block Scripts

This command can be used to create a tree-structured list of all the script
methods that are attached to the specified blocks.
Input Language
BLOCK SCRIPTS block_list

block_list
62
Comma-separated list of the blocks whose script methods

are to be printed to the report device. If no list is entered,
then the list is produced for all the blocks.
Printing Block Convergence

This command is used to print the norm of the residuals for the specified
blocks.
Input Language
PRINT BLOCK CONVERGENCE block_list

block_list
Comma-separated list of blocks to print. If not entered, all

blocks are printed.
Printing Block Statistics

Prints summary information for the indicated blocks. These include the
number of variables, the number of equations, the number of fixed variables,
the number of excluded equations, the number of degrees of freedom, the
number of independent variables, the number of nonzero Jacobian elements
and the Jacobian matrix density.
Input Language
PRINT BLOCK STATISTICS block_list
PRINT BLOCK STATISTICS FULL block_list

block_list
Comma-separated list of blocks to print. If not entered,

all blocks are printed.
PRINT BLOCK STATISTICS FULL also includes the starting indices of the
variables, equations and non-zeroes for each block. A description of each
column heading follows:
Column
Description
Block
Name of block. Excluded blocks appear in parenthesis.
Nvar
Number of variables. Excluded blocks have zero variables.
Neqn
Number of equations.
Nfix
Number of fixed variables in the current mode.
Nexcld
Number of excluded equations.
Ndof
Number of degrees of freedom. If positive, the block is underspecified; if

negative, the block is over specified. This includes declared degrees of
freedom variables with specifications of OPTIM, RECON and INDEP.
NfreeI
Number of variables that were freed as a result of stream connection

equations.
Nnz
Number of non-zeroes. Excluded blocks have no non-zeroes.
Nnz%
Density of non-zeroes in the Jacobian.
63
Changing Block Attributes

Block attributes may be changed with this command. Block attributes may be
viewed either with the PRINT BLOCK ATTRIBUTES command or the ECHO
command.
Input Language
blockid.attribute = value

blockid
Name of the block.
attribute
Attribute to be changed.
value
Value of the attribute.
Block Attributes
INCLUDED
Flag indicting if the block is in the included state.
NLRATIODEV
Allowable deviation of the blocks non-linearity ratio when using

Schubert updating. If the non-linearity ratio is greater than this value,
the blocks Jacobian is re-computed. (default = 0.01)
DERIV_METHODDerivative method.
PERT
ANALYTIC
Derivatives are set by the model subroutine.
NUMERIC
Derivatives are computed numerically. The

perturbation size may be specified with the PERT block
attribute.
Perturbation size to use for the computation of numerical derivatives

for the specified block. (default = 1.0E-6).
ZEROTOL
Zero tolerance for numeric sparsity detection. (default = 1.0D-12)
MOVE
Flag indicating if variables with zero value should be moved during

numeric sparsity detection. (default = TRUE)
MOVEAMOUNT Amount to move variables with zero value during numeric sparsity
detection. (default = 0.01)
For a list the block attributes that are supported by the exported Aspen
Custom Modeler models but not the base OOMF models attributes, see ACM
Block Attributes
Printing Block Attributes

Prints a list of all the block attributes.
Input Language
PRINT BLOCK ATTRIBUTES block_list

block_list
64

the attributes of all blocks are printed.
Printing Block Attributes in Detail

Prints a list of all the block attributes in detail.
Input Language
PRINT BLOCK ATTRIBUTES DETAILED block_list

block_list

Printing Block Parameters

Prints a list of all the block attributes.
Input Language
PRINT BLOCK PARAMETERS block_list

block_list

Example of Block Commands

In the following example, we print the list of blocks, then exclude a block and
print the list again. In this example, there is a Spec Group, C3RVFRAC, which
has a spec change between the excluded block, CVAP, and another block,
C2MEAS. When the block is excluded, the size of the problem is reduced.
Also, the excluded block caused the Spec Group C3RVFRAC to become
inactive, leaving the problem square.
65
EO> PRINT BLOCK STAT

---Block-- -Nvar- -Neqn- -Nfix- Nexcld -Ndof- NfreeI --Nnz- --Nz%C2S
1256
1244
5
0
0
7
6560
0.42
DDEF
45
36
2
0
0
0
131
8.5
CVAP
41
33
2
0
-1
1
97
7.5
CONDUA
12
5
2
0
0
0
16
32
CIN
35
30
4
0
0
0
72
7.7
F
41
35
4
0
0
0
104
8
C2MEAS
24
8
12
0
1
0
12
13
---------- ------ ------ ------ ------ ------ ------ ------ -----Total
1454
1391
31
0
0
8
6992
EO> PRINT SPEC GROUP C3RVFRAC
<< Specification group C3RVFRAC, enabled, and active >>
[CVAP.BLK.COUT_VAPOR_FRACTION,Const]
[C2MEAS.BLK.C3R_PLANT,Meas]
[C2MEAS.BLK.C3R_OFFSET,Param]
1 specification group found.
EO> EXCLUDE BLOCK CVAP
1256
1244
5
0
0
7
6560
0.42
DDEF
45
36
2
0
0
0
131
8.5
(CVAP
)
0
33
0
33
0
0
0
0
CONDUA
12
5
4
0
0
0
12
30
CIN
35
30
4
0
0
0
72
7.7
F
41
35
4
0
0
0
104
8
C2MEAS
24
8
13
0
0
0
11
13
---------- ------ ------ ------ ------ ------ ------ ------ -----Total
1413
1391
32
33
0
7
6890
EO> PRINT SPEC GROUP C3RVFRAC
<< Specification group C3RVFRAC, enabled, and inactive >>
[CVAP.BLK.COUT_VAPOR_FRACTION,Const]
To print the list of parameters for all the blocks in the current scope, enter:
PRINT BLOCK PARAMETERS
To print the list of attributes for block B1 in detail, enter:
PRINT BLOCK ATTRIBUTES DETAILED B1
66
Variable Commands
These commands may be used to change and print variable attributes.
Variable Attributes
The following table shows the variable attributes along with allowable values.
Attribute
Description
NAME
Name.
VALUE
Value. (also VAL, VALUES)
INITIAL
Initial value.
CHANGE
Change in value. If a value is entered for this attribute, the INIT

attribute is also changed automatically.
LOWER
Lower bound. (also LB)
UPPER
Upper bound. (also UB)
STEP
Step bound (also SB)
BOUND
Bound type:
HARD Hard bound.
RELAXED
Relaxed bound.
SOFT Soft bound. If the initial value of the variable is outside

its bounds, the appropriate variable bound is relaxed to this
initial value.
SOFT2 Special case of the soft bound that allows the variable
value to vary between -1e+35 and 1e+35. The UPPER and
LOWER attributes are ignored.
SBWEIGHT
Soft bound weight.
SCALE
Scale factor.
INTSCALE
Internal scale factor.
RLOWER
Resolved lower bound.
RUPPER
Resolved upper bound.
PHYSICAL_TYPE
Physical type. Changing the physical type is not recommended,

but when you do so, use a string such as PDROP.
In PRINT commands, this is an integer value corresponding to
the physical type. See the section Physical Types for options
and integer values.
UNITS
Units of measure string.
SPEC
The specification of the variable. (also SPECS) This is a string

that sets the specification in each mode. See table below.
During the run of any particular mode, only the specification for
that mode is known to the OOMF system.
SSPEC
Specification in the current mode
SHADOW_PRICE
Shadow price (also SP)
ACTIVE_BOUND
Active bound (also AB)
67
Attribute
Description
QUALITY
Quality of variable value:

GOOD The quality of the measured or parameterized variable is
good.
BAD
The quality of the measured variable is bad.
OVERRIDE
overridden.
The quality of the parameterized variable is to be
BADIGNORE The quality of the measured variable is bad but it

may be ignored.
BASEUOM
Internal units of measure (string). Changing this attribute is not

recommended.
THRESHOLD
Threshold value.
RAMPED
TRUE if the variable is ramped, else FALSE. This attribute is

only used in dynamic simulations.
CONN_TYPE
Connection type. See the section Connection Types for the list
of supported connection types.
Specifications in Each Mode

SPEC
SIM
PAR
REC
OPT
CONST
Fixed
Fixed
Fixed
Fixed
CALC
Free
Free
Free
Free
MEAS
Free
Fixed
Fixed
Free
PARAM
Fixed
Free
Free
Fixed
OPTIM
Fixed
Fixed
Fixed
DOF
RECON
Fixed
Fixed
DOF
Fixed
INDEP
Fixed
Fixed
DOF
DOF
Changing Variable Attributes

These commands are used to change variable attributes such as the initial
value, the bounds and the specification.
Input Language
variableid.attribute = value
aliasid.attribute = value
...

Variable attributes can be changed by referring to the variable by name or its
alias along with its attribute. If the attribute is omitted, the VALUE is
changed. The changeable attributes are:
68
VALUE
INITIAL
CHANGE
LOWER
UPPER
STEP
BOUND
SBWEIGHT
SPEC
UNITS
SCALE
PHYSICAL_TYPE
QUALITY
BASEUOM
When a value is entered, you may also enter the units of measure enclosed in
braces, {}. If no units of measure are entered, the value is assumed to be in
the units of measure of the variable. This functionality can be controlled by
the script parameter CHECK_UOM. When CHECK_UOM is FALSE (the
default), the units of measure may be omitted. When CHECK_UOM is TRUE,
the units of measure must be entered with every value.
Printing Variables
Prints to the report device selected information about the listed variables.
The set of attributes to print for each variable is determined by the variable
masking, which is a list of variable attributes enclosed by parentheses.
For PRINT VARIABLES, values are given in the variables units of measure;
for PRINT VARIABLES SSI, values are given in scaled SI units.
The list of variables can be specified by variable index, variable name or a list
of block names.
The format of the output is affected by script parameter NAME_WIDTH.
Input Language
PRINT VARIABLES [ vmask ], list
PRINT VARIABLES SSI [ vmask ], list

vmask
Optional list of variable attributes to print, separated by commas. Note that

this list is enclosed in brackets.
If no list is given, then the script parameter PRINT_VAR_MASK is used as
the list of attributes to print. This default list includes the name, lower, value,
upper, units and specification.
list
A comma separated list of block names, variable names, stream names or

variable indices. If omitted, all variables are printed. A range of indices may
be printed by using a colon with spaces on either side ( : ) between the
indices.
These attributes can be printed:

VALUE
INITIAL
CHANGE
LOWER
UPPER
STEP
BOUND
SBWEIGHT
SPEC
UNITS
SCALE
PHYSICAL_TYPE
QUALITY
BASEUOM
SHADOW_PRICE
ACTIVE_BOUND
NAME
Printing Variables Fixed in the Current

Mode
This command prints the variables that are fixed in the current mode to the
report device.
69
Numerical values are given in the variables units of measure.
of block names.
The format of the output is affected by script parameters NAME_WIDTH and
UOM_WIDTH.
Input Language
PRINT FIXED [ vmask ], list

vmask
Optional list of variable attributes to print. This list is separated by spaces and
enclosed in brackets.
If no list is given, then the script parameter PRINT_VAR_MASK is used as
the list of attributes to print. This default list includes the name, lower, value,
list

variable indices. If omitted, all variables are printed.

VALUE
INITIAL
CHANGE
LOWER
UPPER
STEP
BOUND
SBWEIGHT
SPEC
UNITS
SCALE
PHYSICAL_TYPE
QUALITY
BASEUOM
SHADOW_PRICE
ACTIVE_BOUND
NAME
Printing Variables Fixed in Other Modes

The PRINT SPECIFICATIONS command is used to search for variables
whose specifications are not CALC. The values for these variables are printed
to the report device.
Input Language
PRINT SPECIFICATIONS block_list

block_list
A comma separated list of block names. If omitted, all blocks are

scanned.
Printing Variables with Active Bounds

Prints to the report device selected information about variables with active
bounds. This is particularly useful after an optimization solution to determine
the active bound set.
70
For PRINT ACTIVE_BOUNDS, values are given in the variables units of

measure; for PRINT ACTIVE_BOUNDS SSI, values are given in scaled SI
units.
of block names.
UOM_WIDTH.
Input Language
PRINT ACTIVE_BOUNDS [ vmask ], list
PRINT ACTIVE_BOUNDS SSI [ vmask ], list

vmask
Optional list of variable attributes to print, separated by commas. Note that

this list is enclosed in brackets.
If no list is given, then the script parameter PRINT_VAR_MASK is used as the
list of attributes to print. This default list includes the name, lower, value,
list

variable indices. If omitted, all variables are printed. A range of indices may
indices.

VALUE
INITIAL
CHANGE
LOWER
UPPER
STEP
BOUND
SBWEIGHT
SPEC
UNITS
SCALE
PHYSICAL_TYPE
QUALITY
BASEUOM
SHADOW_PRICE
ACTIVE_BOUND
NAME
Printing Largest Variable Shadow Prices

This command prints the largest variable shadow prices (in decreasing
magnitude) to the report device. These may be listed in user units or scaled
SI units. Only variables that are fixed or are at an active bound will have nonzero shadow prices.
The variable shadow prices are not calculated by this command. This should
be done with a SOLVE command. (The EVALUATE RESIDUALS command
will not compute the shadow prices.)
of block names.
UOM_WIDTH.
Input Language
PRINT LARGEST VARIABLE SHADOW_PRICES integer, list
71
PRINT LARGEST VARIABLE SHADOW_PRICES SSI integer, list

integer
Optional length of largest shadow price list (default = 10)
list

variable indices. If omitted, all variables are searched. A range of indices may
indices.
Printing Variables Using a Query

Prints to the report device selected information about variables using a query
string.
UOM_WIDTH.
Input Language
PRINT QUERY [ vmask ], block_list, query

vmask
Optional list of variable attributes to print, separated by commas. Note

that this list is enclosed in brackets.
If no list is given, then the script parameter PRINT_VAR_MASK is used
as the list of attributes to print. This default list includes the name, lower,
value, upper, units and specification.
block_list
A comma separated list of block names. If omitted, all blocks are queried.
query
A string containing the query enclosed in double quotation marks. Usually

of the form: "attribute = value"
These attributes can be printed by PRINT QUERY:

VALUE
INITIAL
CHANGE
LOWER
UPPER
STEP
BOUND
SBWEIGHT
SPEC
UNITS
SCALE
PHYSICAL_TYPE
QUALITY
BASEUOM
SHADOW_PRICE
ACTIVE_BOUND
NAME
72
These attributes can appear in the query of PRINT QUERY:

VALUE
INITIAL
CHANGE
LOWER
UPPER
STEP
BOUND
SBWEIGHT
SPEC
UNITS
SCALE
PHYSICAL_TYPE
QUALITY
BASEUOM
SHADOW_PRICE
ACTIVE_BOUND
NAME
The query can also use logical operands:

AND
Logical and operator
OR
Logical or operator
NOT
Logical not operator
Other functions are also available:

INOBJECTIVE()
Indicates whether the variable is in the specified objective

function.
ISMODIFIED()
Indicates whether the specified attribute has been modified. The

attribute may be one of VALUE, SPEC, LOWER, UPPER, STEP,
SCALE, SBWEIGHT and BOUND.
ISALIAS()
Allows variables to be filtered using their alias names.
Examples of Variable Commands

To set the lower bound of variable C2S.BLK.TEMP_10 to -50C:
C2S.BLK.TEMP_10.LOWER = -50. {C}
Note: The equal sign is surrounded by blanks.
To make variable C2S.D.STR.C2H6 an independent and provide an initial
value and bounds, enter:
C2SD.D.STR.C2H6
C2SD.D.STR.C2H6.LOWER
C2SD.D.STR.C2H6.UPPER
C2SD.D.STR.C2H6.SPEC
=
=
=
=
0.0001
0.00001
0.0002
INDEP
To print the variables in block C2S enter:

PRINT VARIABLES C2S
To print only the value and specification attributes, enter:
PRINT VARIABLES [VALUE, SPEC], C2S
To print the values of the fixed variables in this block, enter:
PRINT SPECIFICATIONS [VALUE], C2S
To print the variables in stream F in block C2S, enter:
PRINT VARIABLES C2S.F.STR
To print the variables with indices 30 to 40, enter:
PRINT VARIABLES 30 : 40
Note: The colon is surrounded by blanks.
To print the variables with specification of Optimized, enter:
73
PRINT QUERY "SPEC = OPTIM"

To print the variables with specification of Optimized or which are in objective
function PROFIT, enter:
PRINT QUERY "SPEC = OPTIM OR INOBJECTIVE(PROFIT)"
To print all variables whose alias matches FLOW*, enter:
PRINT QUERY(ISALIAS(FLOW*))
To print all variables for which aliases have been defined, enter:
PRINT QUERY(ISALIAS(*))
To print the description attribute of all variables whose alias matches FLOW*,
enter:
PRINT QUERY [description], ("ISALIAS(FLOW*)")
Alias Commands
Aliases are user-defined alternate names for variables. The alias may be used
to refer to a variable in other script language commands. This is useful to
avoid typing long variable names.
Printing Aliases
This command lists the alias definitions for the current scope.
Input Language
ALIAS
Printing Alias Values

Prints a list of alias values to the report device.
The set of attributes to print for each alias is determined by the variable
Numerical values are given in the variables units of measure.
The width of the name field in the report may be controlled with script
parameter NAME_WIDTH.
Input Language
PRINT ALIAS name [ vmask ]
74

name
Optional alias name or partial alias name. If specified, only

aliases matching the name will be printed. Wildcards may be
used in the name.
vmask
Optional list of variable attributes to print. This list is separated

by commas and enclosed in brackets.
If no list is given, then the script parameter PRINT_VAR_MASK
is used as the list of attributes to print. This default list includes
the name, lower, value, upper, units and specification.
These attributes can be used. (See the Variable Commands section for
descriptions.)
VALUE
INITIAL
CHANGE
LOWER
UPPER
STEP
BOUND
SBWEIGHT
SPEC
UNITS
SCALE
PHYSICAL_TYPE
QUALITY
BASEUOM
SHADOW_PRICE
ACTIVE_BOUND
Printing Alias Variables

Prints a list of aliases corresponding to the specified variables to the report
device.
Input Language
PRINT ALIAS VARIABLES var_list

var_list
Optional comma-separated list of variable names. If no list is given,

then all alias definitions for the current scope are printed.
75
Equation Commands
The equation commands are used to include or exclude equations from the
OOMF solution.
Excluding Equations
This command may be used to exclude, or remove, equations from the
problem. This may change the number of degrees of freedom, depending on
the variable specifications.
Input Language
equationid.INCLUDED = FALSE

equationid
Equation name.
Including Equations
This command may be used to include equations that have been previously
excluded.
Input Language
equationid.INCLUDED = TRUE

equationid
Equation name.
Evaluating Equations
Equations may be evaluated with either of the following commands. Equations
in excluded blocks are not evaluated.
Input Language
EVALUATE EQUATIONS
EVALUATE RESIDUALS
76
Printing Equations
Prints the listed equation names and attributes to the report device.
The list can be generated by block, equation index or equation name. If no
argument is given, all the problem equations are printed.
The residual equations are not evaluated by this command. To evaluate the
equations use EVALUATE RESIDUALS or EVALUATE EQUATIONS.
Input Language
PRINT EQUATIONS list
PRINT RESIDUALS list

list
A comma separated list of block names, equation names, and

equation indices. If omitted, all equations are printed.
Printing Largest Residuals

This command prints the largest residuals (in decreasing size) from the listed
set of blocks to the report device. Only those residuals that are included in
the current problem are printed.
The residuals are not calculated by this command. To calculate residuals use
EVALUATE RESIDUALS.
Input Language
PRINT LARGEST RESIDUALS integer, block_list
PRINT LARGEST EQUATIONS integer, block_list

integer
Optional length of largest residual list (default = 10)
block_list
Optional comma separated list of blocks. The largest residuals in each block
will be printed. If omitted, the largest residuals in the problem are printed.
77
Printing Largest Residual Shadow Prices

This command prints the largest residual shadow prices (in decreasing size)
from the listed set of blocks to the report device. These may be listed as
scaled or unscaled.
The residuals and their shadow prices are not calculated by this command.
This should be done with a SOLVE command. (The EVALUATE RESIDUALS
command will not compute the shadow prices.)
Input Language
PRINT LARGEST RESIDUAL SHADOW_PRICES integer, block_list
PRINT LARGEST EQUATIONS SHADOW_PRICES integer, block_list
PRINT LARGEST RESIDUAL SCALED_SHADOW_PRICES integer,
block_list
PRINT LARGEST EQUATION SCALED_SHADOW_PRICES integer,
block_list
78
integer
Optional length of largest shadow price list (default = 10)
block_list
Optional comma separated list of blocks. The largest residual shadow

prices in each block will be printed. If omitted, the largest residuals in the
problem are printed.
4 Specification Groups and

Connections

specification groups, streams, and connections.
Specification Group Commands

These commands are used to control Specification Groups.
Removing Specification Groups

This command is used to remove Spec Groups, completely eliminating them
from the EO Strategy. The product specific user interface input, of course, is
not affected.
When a Spec Group is removed, Spec Management automatically reprocesses
all the Connections and Spec Groups to ensure that the problem remains
square. The removed Spec Group will not appear in any PRINT command, and
will have an Inactive status in the GUI, if defined there. (The Status on the
GUI is not updated until an Incremental Build or Solve is performed.)
Note that any Spec Groups defined in the product specific user interface that
are removed with this command are recreated if the EO Strategy is
reinitialized either from SM Results or from a complete rebuild.
Input Language
REMOVE SPECIFICATION GROUP spec_list

spec_list
A comma-separated list of names. If no name is entered, all

Spec Groups within the current scope are removed. Wildcards
may be used in the names.
4 Specification Groups and Connections
79
Disabling Specification Groups

This command is used to disable a specific Spec Group.
When a Spec Group is disabled, Spec Management automatically reprocesses
square. (The Status on the GUI is not updated until an Incremental Build or
Solve is performed.)
Input Language
DISABLE SPECIFICATION GROUP spec_list

spec_list

Spec Groups within the current scope are disabled. Wildcards
Enabling Specification Groups

This command is used to enable a specific Spec Group. It does the reverse of
the DISABLE SPECIFICATION GROUP command discussed in the previous
section.
Input Language
ENABLE SPECIFICATION GROUP spec_list

spec_list

Spec Groups within the current scope are enabled. Wildcards
Printing Specification Groups

This command prints the Specification Groups in the current scope.
Input Language
PRINT SPECIFICATION GROUP spec_list

spec_list
A comma-separated list of names. If no name is entered, all Spec

Groups within the current scope are printed. Wildcards may be used
in the names.
Printing Inactive Specification Groups

This command is used to print inactive Specification Groups in the current
scope. These may become inactive because it was disabled or the group is
non-square.
80
Input Language
PRINT INACTIVE SPECIFICATION GROUPS spec_list

spec_list
A comma-separated list of names. If no name is entered, all inactive

Spec Groups within the current scope are printed. Wildcards may be
used in the names.
Printing Specification Group Variables

This command is used to locate variable references in Specification Groups in
the current scope.
Input Language
PRINT SPECIFCATION GROUP VARIABLES var_list

var_list
A comma-separated list of variable names to search. If no name is

entered, all connections within the current scope are printed.
Wildcards may be used in the names.
Examples of Specification Group Commands

In the following example session, a Spec Group called DOG is disabled and
then enabled:
EO> PRINT SPEC GROUP DOG

<< Specification group DOG, enabled, and active >>
[CIN.BLK.C3H6_MOLE_FRAC,Calc]
[CIN.BLK.SUM_MOLE_FRAC,Const]
EO> DISABLE SPEC GROUP DOG
1 specification group disabled.
<< Specification group DOG, disabled, and inactive >>
EO> ENABLE SPEC GROUP DOG
1 specification group enabled.
<< Specification group DOG, enabled, and active >>
81
Stream Commands
These commands are used to change stream or port attributes such as the
specification and the phase.
Printing Block Ports

The ports associated with a block may be printed with these commands.
PRINT BLOCK PORTS will list the following:
Name.
Type.
Direction.
Phase.
Attached stream.
PRINT BLOCK PORTS DETAILED will list the above along with:
Number of variables.
Number of components.
Variable indices and names.
Components (for material ports).
Input Language
PRINT BLOCK PORTS block_list
PRINT BLOCK PORTS DETAILED block_list

block_list
A comma-separated list of names. If no name is entered, all ports at

the current scope level only are printed. Wildcards may be used in
the names.
Printing Stream Values

The variables in a stream may be viewed with the PRINT VARIABLES
command. More on this command may be found in the section titled Printing
Variables.
Input Language
PRINT VARIABLES blockid.streamid.STR
82
blockid
Name of the block the stream is associated with. Note that a stream
connected between two blocks will have variables associated with it in both
blocks. A connection equation ensures that at the solution, these values will
be the same.
streamid
Name of the stream.
Changing Stream Attributes

This command allows various attributes of the stream to be changed, such as
the phase, type and the specifications of all the variables within the stream.
The stream attributes may be viewed with the ECHO command.
Input Language
blockid.streamid.STR.attribute = value

Stream attributes can be changed by referring to the stream by name along
with its attribute. If the attribute is left out, the value is changed. The allowed
attributes are:
SPEC
The specification of the stream. This is a string that sets the specification in
each mode. (See table below.)
During the run of any particular mode, only the specification for that mode is
known to the OOMF system.
PHASE
TYPE
Phase of the stream. This is used for connection processing when connecting
a mole-based stream to a mole fraction-based stream to determine if a flash
is necessary.
VAPOR
Vapor phase
LIQUID
Liquid phase
VL
Mixed vapor and liquid phases (flash required)
VLF
water
Mixed vapor, liquid and free water phases (flash with free
required)
UNKNOWN
Unknown phase (flash or flash with free water required; you

may set the script parameter FLANGE_PHASE to VL or VLF
to control the type of flash).
The type of stream. This is used for connection processing to determine if

there is a stream type change.
MATERIAL_MOLE_FLOW A material stream using the mole flow structure
MATERIAL_MOLE_FRAC A material stream using the mole fraction structure
INFORMATION
An information stream
UNDEFINED
The stream type has not been defined
Stream Specifications
SPEC
SIM
PAR
REC
OPT
CONST
Fixed
Fixed
Fixed
Fixed
CALC
Free
Free
Free
Free
MEAS
Free
Fixed
Fixed
Free
PARAM
Fixed
Free
Free
Fixed
OPTIM
Fixed
Fixed
Fixed
DOF
RECON
Fixed
Fixed
DOF
Fixed
INDEP
Fixed
Fixed
DOF
DOF
See Also
Aspen Plus Extensions - Stream Commands
83
Connection Commands
These commands are used to control connections between variables.
Connections create an equation equivalencing two variables. When
connections are processed, OOMF checks the specification of each variable in
the current mode.
The rules for connection processing specification changes are simple. If only
one variable in the connection is specified in all four modes (type CONST,
OPTIM, RECON or INDEP), then this variable will become free (type CALC) by
the connection processing. If both variables are a specified type, then the
variable listed first, the destination variable, will become free.
The following table shows the connection rules for the seven specification
types. The rows are the destination variables (the variable listed first in the
connection); the columns are the source variables (the variable listed second
in the connection).
CONST
CALC
MEAS
PARAM
OPTIM
CONST= CALC=CONST CALC=CALC CALC=MEAS CALC=PARAM CALC=OPTIM
RECON
INDEP
CALC=RECON CALC=INDEP
CALC =
CALC=CALC
N/A
N/A
N/A
CALC=CALC
CALC=CALC
CALC=CALC
MEAS =
MEAS=CALC
N/A
N/A
CALC=CALC
MEAS=CALC
MEAS=CALC
MEAS=CALC
PARAM= PARAM=CALC N/A
CALC=CALC N/A
PARAM=CALC PARAM=CALC PARAM=CALC
CALC=CONST CALC=CALC CALC=MEAS CALC=PARAM CALC=OPTIM
RECON= CALC=CONST CALC=CALC CALC=MEAS CALC=PARAM CALC=OPTIM
CALC=CONST CALC=CALC CALC=MEAS CALC=PARAM CALC=OPTIM
OPTIM=
INDEP=
For example, if the connection CONST=PARAM is made, we get CALC=PARAM

for the result. Therefore, the first variable goes from a CONST type to a CALC
type.
Connections will change the number of equations in the problem but not
change the number of degrees of freedom since a specification is always lost.
Adding Connections
This command is used to add connections either between one or more pairs of
variables or between one or more pairs of ports.
Input Language
ADD CONNECTION cxn_name, cxn_list
84

cxn_name
An optional connection name.
cxn_list
A list of connection definitions. Each connection definition is a list

of 2-4 elements. The first two elements specify the variables or
ports to be connected. If the first element elements are variable
names, you can supply a optional multiplier and offset. If not
specified, the multiplier defaults to 1 and the offset to 0.
Adding Custom Connections

This command is used to add a custom connection between a pair of ports.
For custom connections, the ports being connected may have different
numbers of variables and their own variable ordering.
Input Language
ADD CUSTOM CONNECTION cxn_name, cxn ports, cxn_types

cxn_name
An optional connection name.
cxn_ports
A pair of ports to be connected.
cxn_types
An optional list of connection types
Removing Connections
This command is used to remove Connections and Spec Groups, completely
eliminating them from the EO Strategy. The product specific user interface
input, of course, is not affected.
When a Connection is removed, Spec Management automatically reprocesses
square. The removed Connections and Spec Groups will not appear in any
PRINT command, and will have an Inactive status in the GUI, if defined
there. (The Status on the GUI is not updated until an Incremental Build or
If you use these commands from within products that embed OOMF, note that
any Connections defined in the products user interface that are removed with
this command are recreated if the EO Strategy is reinitialized either from SM
Results or from a complete rebuild.
This command will not remove product specific connections such as
Aspen Plus stream connections (Use STREAMS NONE instead).
Aspen Plus HXFlux connections (use DISABLE HXFLUX instead).
Input Language
REMOVE CONNECTION cxn_list
85

cxn_list

Connections and Spec Groups within the current scope are
removed. Wildcards may be used in the names.
Disabling Connections
This command is used to disable a specific Connection or Spec Group. For a
Connection, this excludes the connection equation from the problem. For a
Spec Group, this disables the group.
When a connection is disabled, Spec Management automatically reprocesses
square. (The Status on the GUI is not updated until an Incremental Build or
Input Language
DISABLE CONNECTION cxn_list

cxn_list

disabled. Wildcards may be used in the names.
Enabling Connections
This command is used to enable a specific Connection or Spec Group. It does
the reverse of the DISABLE CONNECTION command discussed in the
previous section.
Input Language
ENABLE CONNECTION cxn_list

cxn_list
86

enabled. Wildcards may be used in the names.
Checking Connections
This command is used to check the integrity of all flowsheet connections.
Input Language
CHECK CONNECTIONS
Printing Connections
The CONNECTIONS command prints from the current scope level only:
Spec Groups.
User connections.
The PRINT CONNECTIONS and PRINT CONNECTIONS DETAILED

commands print from the current scope:
Spec Groups.
User connections.
Product specific connections such as

Aspen Plus stream connections.
Aspen Plus HXFlux connections.
PRINT CONNECTIONS DETAILED will show a detailed report for all

connections.
The PRINT VARIABLES CONNECTIONS command prints for the current
scope all the User connections. This will show the source and destination
variables as well as their indices, and the connection multiplier and offset.
The PRINT MEASUREMENT CONNECTIONS and PRINT MEASUREMENT
CONNECTIONS DETAILED commands print, for the current scope, all the
measurement connections. When a measurement is defined for a simulation,
a measurement connection is created between a measurement variable and a
model variable. See the chapter on Measurements for more information on
creating and configuring measurements.
Input Language
CONNECTIONS
PRINT CONNECTIONS cxn_list
PRINT CONNECTIONS DETAILED cxn_list
PRINT VARIABLES CONNECTIONS
PRINT MEASUREMENT CONNECTIONS cxn_list
PRINT MEASUREMENT CONNECTIONS DETAILED cxn_list

cxn_list

connections within the current scope are printed. Wildcards may
be used in the names.
87
Printing Inactive Connections

This command is used to print the following items that are inactive:
User connections.

These may become inactive because the connection was disabled through the
products user interface or because a block involved in the connection has
been excluded.
The PRINT INACTIVE MEASUREMENT CONNECTIONS command is used
to print measurement connections that are inactive.
Input Language
PRINT INACTIVE CONNECTIONS cxn_list
PRINT INACTIVE MEASUREMENT CONNECTIONS cxn_list

cxn_list

inactive connections within the current scope are printed.
Printing Incomplete Connections

This command is used to print the following items that are incomplete:
Spec Groups.
User connections.

These may be incomplete due to an input error, such as a bad variable name
or an improper specification.
Input Language
PRINT INCOMPLETE CONNECTIONS cxn_list

cxn_list
88

incomplete connections within the current scope are printed.
Printing Connection Variables

This command is used to locate variable references in the following:
Spec Groups.
User connections.

Input Language
PRINT CONNECTION VARIABLES var_list

var_list
A comma-separated list of variable names to search. If no name

is entered, all connections within the current scope are printed.
See Also
Aspen Plus Extensions - Stream Commands
Aspen Plus Extensions - HXFlux Commands
Examples of Connection Commands

The following example depicts how to create a connection between two
variables:
ADD CONNECTION CONN1, [B1.VAR1, B2.VAR2, 3.0, 5.0]
This command creates the equivalent of B1.VAR1 = B2.VAR2 * 3.0 5.0.
The following examples depict how to create custom connections between
ports:
ADD CUSTOM CONNECTIONS CONN1, [port1, port2], [TEMPERATURE]
This command creates a connection of type TEMPERATURE between the
variables in port1 and port2. The first variable in port1 that has a connection
type of TEMPERATURE will be connected to the first variable in port2 that has
a connection type of temperature. If either of the ports does not hold a
variable with a connection type of TEMPERATURE, the connection will not be
created.
ADD CUSTOM CONNECTIONS [port1, port2]
This creates connections between port1 and port2. Since no connection types
have been explicitly specified, the first variable in port1 will be connected to
the first variable in port2 that has the same connection type, and so on.
In the following example session, a connection called THIN is disabled and
then enabled. When the connection is disabled, the destination variable
specifications becomes Constant, reverting back to Calculated when the
connection is enabled again.
89
EO> PRINT VAR CONDUA.BLK.H_IN_TEMP

-index- ------variable------ -----lower---- ---value---- ----upper----- -----uom ------ -spec1430 CONDUA.BLK.H_IN_TEMP
-1e+020
-20
1e+020
C
Calc
EO> DISABLE CONNECTION THIN
1 connection disabled.
EO> PRINT CONNECTION THIN
<< Variable Connection THIN, disabled and inactive >>
CONDUA.BLK.H_IN_TEMP = C2HIER.C2S.BLK.TEMP_2
1 connection found.
-1e+020
-20
1e+020
C
Const
EO> ENABLE CONNECTION THIN
1 connection enabled.
EO> PRINT CONNECTION THIN
<< Variable Connection THIN, enabled and active >>
CONDUA.BLK.H_IN_TEMP = C2HIER.C2S.BLK.TEMP_2
1 connection found.
-1e+020
-20
1e+020
C
Calc
90
5 Measurements

measurements and measurement qualities.
Measurement Commands
Measurements are used to associate model variables with actual plant
measurements. Measurements are typically configured through the products
user interface. If you are using standalone OOMF, measurements may be
added using the add measurements command. Do not use the add
measurements command from within the Aspen Plus user interface. These
commands allow you to control the status of your measurements.
Checking Measurements
This command is used to verify that the measurements for the problem are
properly defined. This will check for the following
Source variables that are not calculated.
Model variables that are not calculated.
Inactive measurement connections.
This command is automatically issued at the end of the Synchronization step.

If all the connections are properly defined, this command will return the
message All measurements are correctly specified. Otherwise, this command
will return a table of improperly specified measurements. This output is sent
to the Report Device.
Input Language
CHECK MEASUREMENTS
5 Measurements
91
Disabling Measurements
This command is used to disable a specific measurement. This excludes the
measurement from the problem: the measurement connection is broken, the
variables are removed, and the offset equation is excluded.
When a measurement is disabled, Spec Management automatically
reprocesses all the Connections and Spec Groups to ensure that the problem
remains square. Connections and Spec Groups that contain references to the
disabled measurement become Inactive. (The Status on the GUI is not
updated until an Incremental Build or Solve is performed.)
Input Language
DISABLE MEASUREMENT meas_list

meas_list

measurements within the current scope are disabled. The names are
written in the format blockid.tagid_descr, where blockid is the name
of the measurement block, tagid is the name of tag, and descr is the
measurement description. Wildcards may be used in the names.
Enabling Measurements
This command is used to enable a specific measurement. It does the reverse
of the DISABLE MEASUREMENT command discussed in the previous
section.
Input Language
ENABLE MEASUREMENT meas_list

meas_list
92

measurements within the current scope are enabled. The names
are written in the format blockid.tagid_descr, where blockid is
the name of the measurement block, tagid is the name of tag,
and descr is the measurement description. Wildcards may be
used in the names.
5 Measurements
Printing Measurements
Prints a list of measurements to the report device.
Input Language
PRINT MEASUREMENTS meas_list

meas_list
Optional comma-separated list of measurement names. The

measurement names are written in the format
blockid.tagid_descr, where blockid is the name of the
measurement block, tagid is the name of tag, and descr is the
measurement description. Wildcards are not allowed. If no list is
given, then all measurements for the current scope are printed.
Printing Measurement Variables

Prints a list of measurements associated with the specified variables to the
report device.
Input Language
PRINT MEASUREMENTS VARIABLES var_list

var_list
Optional comma-separated list of variable names. If no list is

given, then all measurements for the current scope are printed.
Examples of Measurement Commands

To check measurements enter:
EO> CHECK MEASUREMENTS
The specifications for these measurements are not as expected:
Measurement -Connected?- -Model- -SourceC2MEAS.XB
Yes
Calc
Optim
C2MEAS.XD
Yes
Calc
Optim
C2MEAS.XF
Yes
Calc
Const
C2MEAS.F
Yes
Calc
Const
The table shows the list of bad measurements. The column labeled
Connected? shows the status of the measurement connections. All entries in
this column should be Yes. The last two columns, labeled Model and Source,
show the specifications of the Model and Source variables, respectively. All
entries in these two columns should be Calc.
In the following example, measurement C2MEAS.C3R is disabled. Since the
measurement does not appear in any Spec Groups, no Spec Groups become
Inactive as a result of this change:
5 Measurements
93

1256
1244
5
0
2
7
6560
0.42
DDEF
45
36
2
0
0
0
131
8.5
CVAP
41
33
2
0
-1
1
97
7.5
CONDUA
12
5
2
0
0
0
16
32
CIN
35
30
4
0
1
0
72
7.7
F
41
35
4
0
2
0
103
8
C2MEAS
24
8
12
0
-4
0
12
13
---------- ------ ------ ------ ------ ------ ------ ------ -----Total
1454
1391
31
0
0
8
6991
EO> PRINT MEASUREMENTS
Current scope
Msmt ID Tagname Description
Inc UOM
Plant
Model
Offset
-------- -------- ---------------- --- -------- --------- --------- --------C2MEAS
F
F.BLK.MASS
Y KG/HR
49000.000 50000.000
0.0
C2MEAS
XF
F.BLK.C2H6_MOLE| Y UNITLESS
0.200
0.200
0.0
C2MEAS
D
C2S.BLK.DISTILL| Y KG/HR
41000.000 39000.493
0.0
C2MEAS
B
C2S.BLK.BOTTOMS| Y KG/HR
12000.000 11000.000
0.0
C2MEAS
RR
C2S.BLK.REFL_RA| Y UNITLESS
4.300
4.000
0.0
C2MEAS
XD
C2S.D.STR.C2H6
Y FRACTION 1.0000e-4 2.1613e-4
0.0
C2MEAS
XB
C2S.B.STR.C2H4
Y FRACTION 1.5000e-2 4.2976e-2
0.0
C2MEAS
C3R
CIN.BLK.MASS
Y KG/HR
140000.
150000.
0.0
Pspec
----Const
Const
Meas
Meas
Meas
Optim
Optim
Meas
Ospec
----Const
Const
Param
Param
Param
Const
Const
Param
Pspec
----Const
Const
Meas
Meas
Meas
Optim
Optim
Meas
Ospec
----Const
Const
Param
Param
Param
Const
Const
Param

All measurements are correctly specified.
EO> DISABLE MEASUREMENT C2MEAS.C3R
1 measurement disabled.
1256
1244
5
0
2
7
6560
0.42
DDEF
45
36
2
0
0
0
131
8.5
CVAP
41
33
2
0
-1
1
97
7.5
CONDUA
12
5
2
0
0
0
16
32
CIN
35
30
4
0
1
0
72
7.7
F
41
35
4
0
2
0
103
8
C2MEAS
21
8
11
1
-4
0
10
14
---------- ------ ------ ------ ------ ------ ------ ------ -----Total
1451
1391
30
1
0
8
6989
Current scope
Inc UOM
Plant
Model
Offset
-------- -------- ---------------- --- -------- --------- --------- --------C2MEAS
F
F.BLK.MASS
Y KG/HR
49000.000 50000.000
0.0
C2MEAS
XF
0.200
0.200
0.0
C2MEAS
D
41000.000 39000.493
0.0
C2MEAS
B
12000.000 11000.000
0.0
C2MEAS
RR
4.300
4.000
0.0
C2MEAS
XD
C2S.D.STR.C2H6
Y FRACTION 1.0000e-4 2.1613e-4
0.0
C2MEAS
XB
C2S.B.STR.C2H4
Y FRACTION 1.5000e-2 4.2976e-2
0.0
C2MEAS
C3R
CIN.BLK.MASS
N KG/HR
140000.
150000.
0.0
EO> PRINT INACTIVE SPEC GROUPS
0 inactive specification groups found.
Note the reduction in size of the measurement block, C2MEAS, and that it
now contains an excluded equation.
In this next example, we repeat the above except that measurement
C2MEAS.XD is disabled. This measurement appears in Spec Group C2MEAS,
causing it to become Inactive. Since this Spec Group is used to ensure proper
configuration of all the measurements, once it becomes Inactive, a number of
94
5 Measurements
bad measurements appear when the CHECK MEASUREMENTS command is

issued:
EO> DISABLE MEASUREMENT C2MEAS.XD
1 measurement disabled.
1256
1244
7
0
0
7
6558
0.42
DDEF
45
36
2
0
0
0
131
8.5
CVAP
41
33
2
0
-1
1
97
7.5
CONDUA
12
5
2
0
0
0
16
32
CIN
35
30
4
0
1
0
72
7.7
F
41
35
6
0
0
0
100
8.2
C2MEAS
21
8
7
1
0
0
14
14
---------- ------ ------ ------ ------ ------ ------ ------ -----Total
1451
1391
30
1
0
8
6988
Current scope
Inc UOM
Plant
Model
Offset
-------- -------- ---------------- --- -------- --------- --------- --------C2MEAS
F
F.BLK.MASS
Y KG/HR
49000.000 50000.000
0.0
C2MEAS
XF
0.200
0.200
0.0
C2MEAS
D
41000.000 39000.493
0.0
C2MEAS
B
12000.000 11000.000
0.0
C2MEAS
RR
4.300
4.000
0.0
C2MEAS
XD
C2S.D.STR.C2H6
N FRACTION 1.0000e-4 2.1613e-4
0.0
C2MEAS
XB
C2S.B.STR.C2H4
Y FRACTION 1.5000e-2 4.2976e-2
0.0
C2MEAS
C3R
CIN.BLK.MASS
Y KG/HR
140000.
150000.
0.0
Pspec
----Const
Const
Const
Const
Const
Const
Const
Const
Ospec
----Calc
Calc
Calc
Calc
Calc
Calc
Calc
Calc

The specifications for these measurements are not as expected:
Measurement -Connected?- -Model- -SourceC2MEAS.XB
Yes
Calc
Optim
C2MEAS.XF
Yes
Calc
Const
C2MEAS.F
Yes
Calc
Const
<< Specification group C2MEAS, enabled, and inactive >>
[C2MEAS.BLK.F_PLANT,Const]
[C2MEAS.BLK.F_OFFSET,Const]
[C2MEAS.BLK.XF_PLANT,Const]
[C2MEAS.BLK.XF_OFFSET,Const]
[C2MEAS.BLK.D_PLANT,Meas]
[C2MEAS.BLK.D_OFFSET,Param]
[C2MEAS.BLK.B_PLANT,Meas]
[C2MEAS.BLK.B_OFFSET,Param]
[C2MEAS.BLK.RR_PLANT,Meas]
[C2MEAS.BLK.RR_OFFSET,Param]
[C2MEAS.BLK.XD_PLANT,Optim]
[C2MEAS.BLK.XD_OFFSET,Const]
[C2MEAS.BLK.XB_PLANT,Optim]
[C2MEAS.BLK.XB_OFFSET,Const]
[C2S.D.STR.C2H6,Calc]
[C2S.B.STR.C2H4,Calc]
[C2S.BLK.DISTILLATE_MASS,Calc]
[C2S.BLK.REFL_RATIO_MASS,Calc]
[F.BLK.MASS,Calc]
[F.BLK.C2H6_MOLE_FRAC,Calc]
[CIN.BLK.MASS,Calc]
1 inactive specification group found.
At this point, we enable measurement C2MEAS.XD. This brings us back to the

original state of the system:
EO> ENABLE MEASUREMENT C2MEAS.XD
1 measurement enabled.
5 Measurements
95

1256
1244
5
0
2
7
6560
0.42
DDEF
45
36
2
0
0
0
131
8.5
CVAP
41
33
2
0
-1
1
97
7.5
CONDUA
12
5
2
0
0
0
16
32
CIN
35
30
4
0
1
0
72
7.7
F
41
35
4
0
2
0
103
8
C2MEAS
24
8
12
0
-4
0
12
13
---------- ------ ------ ------ ------ ------ ------ ------ -----Total
1454
1391
31
0
0
8
6991
Current scope
Inc UOM
Plant
Model
Offset
-------- -------- ---------------- --- -------- --------- --------- --------C2MEAS
F
F.BLK.MASS
Y KG/HR
49000.000 50000.000
0.0
C2MEAS
XF
0.200
0.200
0.0
C2MEAS
D
41000.000 39000.493
0.0
C2MEAS
B
12000.000 11000.000
0.0
C2MEAS
RR
4.300
4.000
0.0
C2MEAS
XD
C2S.D.STR.C2H6
Y FRACTION 1.0000e-4 2.1613e-4
0.0
C2MEAS
XB
C2S.B.STR.C2H4
Y FRACTION 1.5000e-2 4.2976e-2
0.0
C2MEAS
C3R
CIN.BLK.MASS
Y KG/HR
140000.
150000.
0.0
Pspec
----Const
Const
Meas
Meas
Meas
Optim
Optim
Meas
Ospec
----Const
Const
Param
Param
Param
Const
Const
Param

0 inactive specification groups found.
Measurement Qualities
The quality of a variable may be used to change problem specifications. The
Variable Quality capability allows you to:
Disable a Measured-Parameterized pair between a measurement block

Plant and Offset variable.
Disable all Measured-Parameterized pairs within a defined list of

Specification Groups.
Enable a disabled Specification Group.
Each of these capabilities will be discussed in turn.

There are two tools you must use for the Variable Quality capability:
The QUALITY variable attribute.
The script parameter BAD_STATUS_LIST.
Every variable has a QUALITY attribute. The quality may be set with the
following script command:
variableid.QUALITY = status
Where status is one of the following:
GOOD
The quality of the measured or parameterized variable is good.
BAD
The quality of the measured variable is bad.
OVERRIDE
The quality of the parameterized variable is to be overridden.
Normally, only Measured variables are given a quality of BAD; only

Parameterized variables are given a status of OVERRIDE.
96
5 Measurements
The BAD_STATUS_LIST contains a list of Specification Groups and VariableSpecification Group pairs used by the Variable Quality capability. This script
parameter may be defined with the SET script command:
SET BAD_STATUS_LIST =[ specid1, specid2, ...
[ variableid1, specid1 ], \
[ variableid2, specid2 ], ... ]
The following sections discuss the use of the Variable Quality capability.
Disabling Simple Measured-Parameterized

Pairs
The simplest type of Measured-Parameterized pairing occurs between the
Plant and Offset variables within a Measurement block. In this case, during a
tuning mode, such as Parameter Estimation, the value of the Plant variable is
used to update its corresponding Offset variable, thus provided an indication
of plant-model mismatch.
However, if the quality of the Plant variable becomes bad, then it is not
desirable to keep these specifications, but rather to set the Plant variable to
Calculated and the Offset to Constant.
The PROCESS VARIABLE QUALITY command automatically handles this
situation: If a Plant variable with a Measured specification is BAD, and its
corresponding Offset variable is Parameterized, then the specifications are
changed to Calculated and Constant, respectively. This allows simple
Measured-Parameterized pairs to be disabled with minimal user input.
Disabling Measured-Parameterized Pairs in

Specification Groups
It is often the case that a particular Plant variable is paired with a parameter
other than its corresponding Offset. For example, in a distillation column the
reflux ratio may be used to as a measurement to update the Murphree
efficiency. In this case, the reflux ratio variable has a specification of
Measured and the efficiency a specification of Parameterized. If the quality of
the reflux ratio becomes bad, then it is not desirable to keep these
specifications, but rather to set the reflux ratio to Calculated and the
efficiency to Constant.
To accomplish this, BAD_STATUS_LIST is set to a list of Specification Groups
to be processed. This may be done with the SET script command:
SET BAD_STATUS_LIST = [ specid1, specid2 ], ...
If a variable has a Measured specification with a BAD quality or a
Parameterized specification with an OVERRIDE quality, then all Specification
Groups listed in BAD_STATUS_LIST are searched for the variable. If found,
then all Measured variables within the Specification Group are changed to
Calculated and all Parameterized variables are changed to Constant.
This effectively breaks all the Measured-Parameterized pairs involving the bad
variable. For this to work correctly, the Specification Groups should have an
5 Measurements
97
equal number of Measured and Parameterized variables, otherwise they would

become non-square and inactive.
Enabling Specification Groups

Often, the above logic is inadequate in more complicated situations.
Sometimes when a variable is no longer good, a number of specification
changes must be made. To assist in this, it is possible to associate a variable
with a Specification Group. When the variable quality is BAD, then the
Specification Group is changed from Disabled to Enabled. In this way, you can
enter the desired specification changes in a Specification Group whose default
status is Disabled. The Specification Group would only be processed when a
key variable quality is no longer good.
To do this, you need only add a Variable-Specification Group pair to the script
parameter BAD_STATUS_LIST. This may be done with the SET script
command:
SET BAD_STATUS_LIST =[ [ variableid1, specid1 ], \
[ variableid2, specid2 ], ...]
Executing the Variable Quality Capability

The variable qualities may be processed with the PROCESS VARIABLE
QUALITY command. This can be undone with the UNPROCESS VARIABLE
QUALITY command.
Input Language
UNPROCESS VARIABLE QUALITY
Examples of Measurement Qualities

In the following example, a reflux ratio measurement in a tower is given a
bad quality. A Specification Group associated with the variable, PARMODE, is
entered in the script parameter BAD_STATUS_LIST. When the variable
qualities are processed, a new Specification Group is automatically created to
change all the Measured specifications to Calculated and all the Parameterized
specifications to Constant.
EO> C2HIER.C2MEAS.BLK.RR_PLANT.QUALITY = BAD
EO> SET BAD_STATUS_LIST = [PARMODE]
EO> PROCESS VARIABLE QUALITY
Creating bad spec group AS__PARMODE:
C2MEAS.BLK.F_OFFSET (Param -> Const)
C2MEAS.BLK.XF_OFFSET (Param -> Const)
C2HIER.C2MEAS.BLK.D_PLANT (Meas -> Calc)
C2HIER.C2MEAS.BLK.B_PLANT (Meas -> Calc)
C2HIER.C2MEAS.BLK.RR_PLANT (Meas -> Calc)
C2HIER.C2S.BLK.EFF_1 (Param -> Const)
EO>
98
5 Measurements
If we reset the quality to GOOD and process again, the new Specification
Group is removed:
EO> C2HIER.C2MEAS.BLK.RR_PLANT.QUALITY = GOOD
Remove bad spec group AS__PARMODE
EO>
In this example, we first disable Specification Group PARMODE and associate
it with the reflux ratio variable. When the variables quality goes BAD,
Specification Group PARMODE is enabled.
EO> DISABLE SPEC GROUP PARMODE
1 specification group disabled.
EO> SET BAD_STATUS_LIST = [[C2HIER.C2MEAS.BLK.RR_PLANT,PARMODE]]
EO> C2HIER.C2MEAS.BLK.RR_PLANT.QUALITY = BAD
Enable spec group PARMODE
EO>
5 Measurements
99
100
5 Measurements
6 Saving and Restoring
This chapter describes the OOMF Script commands used for saving and
restoring variable and block data to and from binary and ASCII files. It also
describes how simulation and block data can be persisted in compound
storage (binary) files and XML files.
Commands for Saving and

Restoring Variable and Block
Data
Variable and block attributes may be saved to binary and ASCII files so that
they may be read to initialize future runs.
Saving Variables To a Binary File

This command is used to save variable attributes to a binary file.
Input Language
SAVE VARIABLES [ vmask ], list TO "file"

vmask
Optional list of variable attributes to save, separated by commas. If omitted,

value, lower, upper, scale, units, physical type and specification are saved.
Note that this list is enclosed in brackets and followed by a comma. Variable
names are always saved.
list
Optional list of block names, variable names, stream names, or port names.
The list is separated by commas. If no list is given, then all variables in the
current scope are saved.
file
Name of file. The name must be in double quotation marks.
101
descriptions.)
VALUE
INITIAL
LOWER
UPPER
STEP
UNITS
BOUND
SBWEIGHT
SPEC
SCALE
QUALITY
PHYSICAL_TYPE
BASEUOM
Restoring Variables From a Binary File

This command is used to restore variable attributes from a binary file.
Normally, only variable values are restored. Particular care should be
exercised when restoring variable specifications, as this could corrupt
Specification Management and lead to non-square problems.
Input Language
RESTORE VARIABLES [ vmask ], list FROM "file"
RESTORE VARIABLES EXCEPT [ vmask ], list FROM "file"

vmask
Optional list of variable attributes to restore, separated by commas. If

omitted, all the variable attributes in the file are restored. Note that this list is
enclosed in brackets and followed by a comma. Variable names are never
restored.
list
The list is separated by commas. For RESTORE VARIABLES, list is the list of
objects to restore. For RESTORE VARIABLES EXCEPT, list is the list of
objects not to restore. In either case, if no list is given, then all variables in
the current scope are restored.
file
These attributes can be used. (See the Variable Commands section.)

VALUE
INITIAL
LOWER
UPPER
STEP
BOUND
SBWEIGHT
SPEC
UNITS
SCALE
QUALITY
PHYSICAL_TYPE
BASEUOM
102
Restoring Free Variables From a Binary File

This command is used to restore variable attributes from a binary file. Unlike
RESTORE VARIABLES, this command only restores variables that are free in
the current mode. This is useful for loading solutions at similar operating
conditions without changing the values of fixed variables.
Input Language
RESTORE FREE VARIABLES [ vmask ], list FROM "file"
RESTORE FREE VARIABLES EXCEPT [ vmask ], list FROM "file"

vmask
Optional list of variable attributes to restore, separated by commas. If

omitted, the values and units of measure are restored. Note that this list is
enclosed in brackets and followed by a comma. Variable names are never
restored.
list
The list is separated by commas. For RESTORE FREE VARIABLES, list is the
list of objects to restore. For RESTORE FREE VARIABLES EXCEPT, list is
the list of objects not to restore. In either case, if no list is given, then all
variables in the current scope are restored.
file
These attributes can be used. (See the Variable Commands section.)

VALUE
INITIAL
LOWER
UPPER
STEP
UNITS
BOUND
SBWEIGHT
SPEC
SCALE
QUALITY
PHYSICAL_TYPE
BASEUOM
Updating Variables In a Binary File

This command is used to update variables that have already been saved to a
binary file.
Input Language
UPDATE VARIABLES [ vmask ] TO "file"

vmask
Optional list of variable attributes to save, separated by commas. If omitted,

value, lower, upper, scale, units, physical type and specification are saved.
Note that this list is enclosed in brackets and followed by a comma. Variable
names are always saved.
file
103
descriptions.)
VALUE
STEP
SCALE
SPEC
LOWER
SBWEIGHT
UNITS
PHYSICAL_TYPE
UPPER
Saving Variables To an ASCII File

These commands are used to write variable attributes to an ASCII file. The
format of this file is affected by script parameters NAME_WIDTH,
PAGE_WIDTH and NUMBER_WIDTH.
Input Language
WRITE VARFILE [ vmask ], list TO "file"
WRITE VARFILE EXCEPT [ vmask ], list TO "file"

vmask
Optional list of variable attributes to save, separated by commas. Note that

this list is enclosed in brackets and followed by a comma. Variable names are
always saved. If no list is given, then the script parameter
WRITE_VARFILE_MASK is used as the list of attributes to print. This
default list includes all the available attributes.
list
Optional list of block names, variable names, variable indices, stream names,
or port names. The list is separated by commas. For WRITE VARFILE, list is
the list of objects to write. For WRITE VARFILE EXCEPT, list is the list of
objects not to write. In either case, if no list is given, then all variables in the
current scope are written. (The name of the current hierarchy, if any, is not
added to the variable name prefix.)
file
descriptions.)
VALUE
INITIAL
CHANGE
LOWER
UPPER
STEP
BOUND
SBWEIGHT
SPEC
UNITS
SCALE
PHYSICAL_TYPE
QUALITY
BASEUOM
SHADOW_PRICE
ACTIVE_BOUND
NAME
SSPEC
RLOWER
RUPPER
Restoring Variables From an ASCII File

This command is used to read variable attributes from an ASCII file. The
format of this file is affected by script parameters NAME_WIDTH,
PAGE_WIDTH, UOM_WIDTH and NUMBER_WIDTH.
104
Input Language
READ VARFILE [ vmask ], list FROM "file"
READ VARFILE EXCEPT [ vmask ], list FROM "file"
READ VARFILE QUERY [QUERY], [ vmask ], list FROM "file"

vmask
Optional list of variable attributes to restore, separated by commas. Note that

never restored. If no list is given, then the script parameter
READ_VARFILE_MASK is used as the list of attributes to print. This default
list includes all the above attributes.
list
or port names. The list is separated by commas. For READ VARFILE, the list
is the list of objects to read. For READ VARFILE EXCEPT, the list is the list
of objects not to read. In either case, if no list is given, then all variables
within the current scope are read.
file
query
A string containing the query enclosed in double quotation marks. Usually of

the form: "attribute = value"
descriptions.)
VALUE
INITIAL
CHANGE
LOWER
UPPER
STEP
BOUND
SBWEIGHT
SPEC
UNITS
SCALE
PHYSICAL_TYPE
QUALITY
BASEUOM
Comparing Variables With an ASCII File

This command is used to compare variable attributes in OOMF with an ASCII
file. The comparison for values is done in user units of measure.
Input Language
COMPARE VARFILE [ vmask ], list FROM "file"

vmask
Optional list of variable attributes to compare, separated by commas. If

omitted, all variable attributes in the file are compared. This list is enclosed in
brackets and followed by a comma. Variable names are never compared.
list
or port names. The list is separated by commas. If no list is given, then all
variables within the current scope are compared.
file
descriptions.)
UNITS
LOWER
BOUND
SCALE
VALUE
UPPER
SPEC
SBWEIGHT
INITIAL
STEP
105
Saving Variables and Block Attributes to an

ASCII File
This command is used to write both variables and block attributes to an ASCII
file.
Input Language
WRITE SNAPSHOT [ vmask ], list TO file
Examples:
WRITE SNAPSHOT TO "file.snp"
WRITE SNAPSHOT [ units, value, lower, upper ] TO "file.txt"
WRITE SNAPSHOT [ units, value, spec ], a, b* TO &history_device

vmask
Optional list of variable attributes to save, separated by commas. Note that

always saved. If no list is given, then the script parameter
WRITE_VARFILE_MASK is used as the list of attributes to print. This
default list includes all the available attributes.
list
or port names. The list is separated by commas. For WRITE VARFILE, list is
the list of objects to write. For WRITE VARFILE EXCEPT, list is the list of
objects not to write. In either case, if no list is given, then all variables in the
current scope are written. (The name of the current hierarchy, if any, is not
added to the variable name prefix.)
file
descriptions.)
VALUE
INITIAL
CHANGE
LOWER
UPPER
STEP
BOUND
SBWEIGHT
SPEC
UNITS
SCALE
PHYSICAL_TYPE
QUALITY
BASEUOM
SHADOW_PRICE
ACTIVE_BOUND
NAME
SSPEC
RLOWER
RUPPER
Reading Variables and Block Attributes

from an ASCII File
This command is used to restore both variables and block attributes from an
ASCII file.
READ SNAPSHOT [ vmask ], list FROM file
Examples:
READ SNAPSHOT FROM "file.snp"
READ SNAPSHOT [ units, value, lower, upper ] FROM "file.txt"
READ SNAPSHOT [ units, value, spec ], a, b* FROM "test.out"
106

vmask
Optional list of variable attributes to restore, separated by commas. Note that

never restored. If no list is given, then the script parameter
READ_VARFILE_MASK is used as the list of attributes to print. This default
list includes all the above attributes.
list
or port names. The list is separated by commas. For READ VARFILE, the list
is the list of objects to read. For READ VARFILE EXCEPT, the list is the list
of objects not to read. In either case, if no list is given, then all variables
within the current scope are read.
file
query
A string containing the query enclosed in double quotation marks. Usually of

the form: "attribute = value"
descriptions.)
VALUE
INITIAL
CHANGE
LOWER
UPPER
STEP
BOUND
SBWEIGHT
SPEC
UNITS
SCALE
PHYSICAL_TYPE
QUALITY
BASEUOM
Examples of Commands to Save and

Restore Variable Data
To save all the variables in the problem to binary file COLUMN.X enter:
SAVE VARIABLES TO "COLUMN.X"
To restore the variable values, upper and lower bounds from this file enter:
RESTORE VARIABLES [VALUE, UPPER, LOWER], FROM "COLUMN.X"
To save just the variable values in blocks C2S, C2SDDEF and
C2SBDEF to this file enter:
SAVE VARIABLES [VALUE], C2S, C2SDDEF, C2SBDEF FROM "COLUMN.X"
Persisting Simulation and Block

Data in Compound Storage
(Binary) Files
OOMF allows the persistence of simulation and block data in compound
storage files. A compound storage file is a binary file whose contents can be
written and read via the standard COM interfaces, IStorage and IStream,
OOMF currently supports the creation of files with two different storage
structures, one for the storage of simulation data and the other for the
storage of block data.
107
The following information is persisted in the simulation storage files:

1) Global parameters
2) Names of loaded block libraries
3) Names of loaded solver libraries
4) Current solver and solver settings
5) Tags
6) Objective functions
7) Variable list
8) Equation list
9) Jacobian
10)Blocks
11)Ports
12)Connections
13)Measurements
Block storage files are used to persist block-specific information.
Saving a Simulation to a Compound Storage

File
This command is used to save a simulation to a simulation storage file.
Input Language
SAVE SIMULATION TO "file"

file
Name of the file to which the simulation is to be saved.
Opening a Simulation from a Compound

Storage File
This command is used to load a simulation from a compound storage file.
This command can only be used on either simulation storage or block storage
files.
Input Language
OPEN SIMULATION FROM "file"

file
108
Name of the file from which the simulation is to be loaded.
Adding all the Blocks in a Compound

Storage File to a Simulation
This command is used to add all the blocks in a compound storage file to the
current simulation.
This command can only be used on either simulation storage or block storage
files.
Input Language
ADD SIMULATION FROM "file"

file
Name of the file from which the blocks are to be loaded.
Saving a Block to a Compound Storage File

This command is used to save a specified block in the current simulation to a
block storage file.
Input Language
SAVE BLOCK blk_name TO "file"

blk_nameName of the block to be saved.
file
Name of the file to which the block is to be saved.
Loading a Block from a Compound Storage

File
This command is used to load the block contained in a specified storage file
into the current simulation.
This command can only be used on block storage files.
Input Language
LOAD BLOCK FROM "file"

file
Name of file from which the block is to be loaded.
Examples of Binary Persistence Commands

To save a simulation to a file called MyPlant.sim, enter:
SAVE SIMULATION TO "MyPlant.sim"
109
To open a simulation from the file MyPlant.sim, enter:

OPEN SIMULATION FROM MyPlant.sim
To add all the blocks from the file MyPlant.sim to the current simulation,
enter:
ADD SIMULATION FROM MyPlant.sim
To save the block B1 to a file called MyBlock.blk, enter:
SAVE BLOCK B1 TO MyBlock.blk
To load the block in the file MyBlock.blk, enter:
LOAD BLOCK FROM MyBlock.blk
Persisting Simulation and Block

Data in XML Files
OOMF allows the persistence of simulation and block data in XML files.
All of the following information may be persisted in XML files:
1) Global parameters
2) Names of loaded block libraries
3) Names of loaded solver libraries
4) Current solver and solver settings
5) Tags
6) Objective functions
7) Variable list
8) Equation list
9) Jacobian
10)Blocks
11)Ports
12)Connections
13)Measurements
XML Schema for Simulation Persistence

The full XML schema for the persistence of OOMF simulations is presented
below.
<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="oomf" type="oomfType"/>
<xs:complexType name="oomfType">
<xs:all>
110
<xs:element name="simulation" type="simulationType"

minOccurs="1" maxOccurs="1"/>
</xs:all>
<xs:attribute name="majorVersion" use="required"/>
<xs:attribute name="minorVersion" use="required"/>
</xs:complexType>
<xs:complexType name="simulationType">
<xs:all>
<xs:element name="simulationHeader"
type="simulationHeaderType" minOccurs="0" maxOccurs="1"/>
<xs:element name="globalParameters"
type="globalParametersType" minOccurs="0" maxOccurs="1"/>
<xs:element name="modules" type="modulesType" minOccurs="0"
maxOccurs="1"/>
<xs:element name="blocks" type="blocksType" minOccurs="0"
maxOccurs="1"/>
<xs:element name="variables" type="variablesType"
<xs:element name="equations" type="equationsType"
<xs:element name="objectiveFunctions"
type="objectiveFunctionsType" minOccurs="0" maxOccurs="1"/>
<xs:element name="tags" type="tagsType" minOccurs="0"
maxOccurs="1"/>
<xs:element name="solver" type="solverType" minOccurs="0"
maxOccurs="1"/>
</xs:all>
</xs:complexType>
<xs:complexType name="simulationHeaderType">
<xs:sequence>
<xs:element name="revisionHistory"
type="revisionHistoryType" minOccurs="0" maxOccurs="1"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="revisionHistoryType">
<xs:sequence>
<xs:element name="revision" type="revisionType"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="revisionType">
<xs:attribute name="revisionDate" use="required"/>
<xs:attribute name="user" use="required"/>
<xs:attribute name="description" use="required"/>
<xs:attribute name="OOMFVersion" use="required"/>
<xs:attribute name="CMEVEVersion" use="required"/>
</xs:complexType>
<xs:complexType name="globalParametersType">
<xs:sequence>
<xs:element name="globalParameter"
type="globalParameterType" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="globalParameterType">
<xs:attribute name="name" use="required"/>
<xs:attribute name="type" use="required"/>
<xs:attribute name="value" use="required"/>
111
</xs:complexType>
<xs:complexType name="modulesType">
<xs:sequence>
<xs:element name="module" type="moduleType" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="moduleType">
</xs:complexType>
<xs:complexType name="blocksType">
<xs:sequence>
<xs:element name="block" type="blockType" minOccurs="0"
</xs:sequence>
</xs:complexType>
<xs:complexType name="blockType">
<xs:all>
<xs:element name="blocks" type="blocksType" minOccurs="0"
maxOccurs="1"/>
<xs:element name="blockAttributes"
type="blockAttributesType" minOccurs="0" maxOccurs="1"/>
<xs:element name="blockPorts" type="blockPortsType"
<xs:element name="connections" type="connectionsType"
<xs:element name="blockSpecificData" minOccurs="0"
maxOccurs="1"/>
</xs:all>
<xs:attribute name="modid" use="required"/>
<xs:attribute name="subid" use="optional"/>
<xs:attribute name="included" use="optional"/>
<xs:attribute name="category" use="optional"/>
<xs:attribute name="parent" use="optional"/>
</xs:complexType>
<xs:complexType name="blockAttributesType">
<xs:sequence>
<xs:element name="blockAttribute" type="blockAttributeType"
</xs:sequence>
</xs:complexType>
<xs:complexType name="blockPortsType">
<xs:sequence>
<xs:element name="blockPort" type="blockPortType"
</xs:sequence>
</xs:complexType>
<xs:complexType name="blockAttributeType">
<xs:attribute name="readOnly" use="required"/>
<xs:attribute name="modified" use="required"/>
<xs:attribute name="baseType" use="required"/>
</xs:complexType>
112
<xs:complexType name="blockPortType">
<xs:sequence>
<xs:element name="variables" type="portVariablesType"
</xs:sequence>
<xs:attribute name="direction" use="optional"/>
<xs:attribute name="type" use="optional"/>
<xs:attribute name="sosType" use="optional"/>
<xs:attribute name="basis" use="optional"/>
<xs:attribute name="defaultPhase" use="optional"/>
<xs:attribute name="phase" use="optional"/>
<xs:attribute name="portPhase" use="optional"/>
<xs:attribute name="portSpec" use="optional"/>
<xs:attribute name="portStream" use="optional"/>
<xs:attribute name="portType" use="optional"/>
</xs:complexType>
<xs:complexType name="portVariablesType">
<xs:sequence>
<xs:element name="variable" type="portVariableType"
</xs:sequence>
</xs:complexType>
<xs:complexType name="portVariableType">
<xs:attribute name="index" use="required"/>
</xs:complexType>
<xs:complexType name="connectionsType">
<xs:sequence>
<xs:element name="connection" type="connectionType"
</xs:sequence>
</xs:complexType>
<xs:complexType name="connectionType">
<xs:attribute name="connType" use="required"/>
<xs:attribute name="destID" use="required"/>
<xs:attribute name="sourceID" use="required"/>
<xs:attribute name="multiplier" use="required"/>
<xs:attribute name="offset" use="required"/>
<xs:attribute name="enabled" use="required"/>
</xs:complexType>
<xs:complexType name="variablesType">
<xs:sequence>
<xs:element name="variable" type="variableType"
</xs:sequence>
</xs:complexType>
<xs:complexType name="variableType">
<xs:attribute name="value" use="optional"/>
<xs:attribute name="uomID" use="optional"/>
<xs:attribute name="baseUOM" use="optional"/>
<xs:attribute name="initial" use="optional"/>
<xs:attribute name="lowerBound" use="optional"/>
<xs:attribute name="upperBound" use="optional"/>
113
<xs:attribute name="sbWeight" use="optional"/>

<xs:attribute name="status" use="optional"/>
<xs:attribute name="stepBound" use="optional"/>
<xs:attribute name="solverScale" use="optional"/>
<xs:attribute name="connType" use="optional"/>
<xs:attribute name="description" use="optional"/>
</xs:complexType>
<xs:complexType name="equationsType">
<xs:sequence>
<xs:element name="equation" type="equationType"
</xs:sequence>
</xs:complexType>
<xs:complexType name="equationType">
<xs:attribute name="scale" use="optional"/>
<xs:attribute name="shadowPrice" use="optional"/>
<xs:attribute name="status" use="optional"/>
<xs:attribute name="procVar" use="optional"/>
</xs:complexType>
<xs:complexType name="objectiveFunctionsType">
<xs:sequence>
<xs:element name="objectiveFunction"
type="objectiveFunctionType" minOccurs="0"
</xs:sequence>
<xs:attribute name="current" use="optional"/>
</xs:complexType>
<xs:complexType name="objectiveFunctionType">
<xs:all>
<xs:element name="terms" type="termsType" minOccurs="0"
maxOccurs="1"/>
</xs:all>
<xs:attribute name="physicalType" use="required"/>
<xs:attribute name="uomSet" use="required"/>
<xs:attribute name="direction" use="required"/>
<xs:attribute name="scale" use="required"/>
<xs:attribute name="expression" use="optional"/>
</xs:complexType>
<xs:complexType name="termsType">
<xs:sequence>
<xs:element name="term" type="termType" minOccurs="1"
</xs:sequence>
</xs:complexType>
<xs:complexType name="termType">
<xs:attribute name="varName" use="required"/>
<xs:attribute name="coefType" use="optional"/>
<xs:attribute name="coefValue" use="optional"/>
<xs:attribute name="coefUOMIndex" use="optional"/>
<xs:attribute name="coefDimension" use="optional"/>
<xs:attribute name="biasType" use="optional"/>
114
<xs:attribute name="biasValue" use="optional"/>

<xs:attribute name="biasUOMIndex" use="optional"/>
<xs:attribute name="biasDimension" use="optional"/>
<xs:attribute name="sigmaType" use="optional"/>
<xs:attribute name="sigmaValue" use="optional"/>
<xs:attribute name="sigmaUOMIndex" use="optional"/>
<xs:attribute name="sigmaDimension" use="optional"/>
</xs:complexType>
<xs:complexType name="tagsType">
<xs:sequence>
<xs:element name="tag" type="tagType" minOccurs="0"
</xs:sequence>
</xs:complexType>
<xs:complexType name="tagType">
</xs:complexType>
<xs:complexType name="solverType">
<xs:sequence>
<xs:element name="solverSetting" type="solverSettingType"
</xs:sequence>
</xs:complexType>
<xs:complexType name="solverSettingType">
</xs:complexType>
</xs:schema>
Writing a Simulation to a XML File

This command is used to write a simulation to a XML file.
Input Language
WRITE SIMULATION TO "file"

file
Name of the file to which the simulation is to be saved.
Reading a Simulation from a XML File

This command is used to read a simulation from a XML file.
Input Language
READ SIMULATION FROM "file"

file
Name of the file from which the simulation is to be loaded.
115
Appending all the Blocks in a XML File to a

Simulation
This command is used to append all the blocks in a XML file to the current
simulation.
Input Language
APPEND BLOCKS FROM "file"

file
Name of file from which the blocks are to be loaded.
Writing a Block to a XML File

This command is used to save a specified block in the current simulation to a
XML file.
Input Language
WRITE BLOCK blk_name TO "file"

blk_nameName of the block to be saved.
file
Name of the file to which the block is to be saved.
Reading a Block from a XML File

This command is used to load a specified block contained in the XML file into
the current simulation.
Input Language
READ BLOCK blk_name FROM "file"

blk_nameName of the block to be loaded.
file
Name of the file from which the block is to be loaded.
Examples of XML Persistence Commands

To write a simulation to a file called MyPlant.xml, enter:
WRITE SIMULATION TO "MyPlant.xml"
To read a simulation from the file MyPlant.xml, enter:
READ SIMULATION FROM MyPlant.xml
To append all the blocks from the file MyPlant.xml to the current simulation,
enter:
116
APPEND BLOCKS FROM MyPlant.xml

To save the block B1 to a file called MyBlock.xml, enter:
WRITE BLOCK B1 TO MyBlock.xml
To load the block B1 in the file MyPlant.xml into the current simulation,
enter:
READ BLOCK B1 FROM MyPlant.xml
117
118
7 Objective Functions
This chapter describes the OOMF Script commands for manipulating objective
functions, Jacobians, and derivatives.
There are three types of objective functions available: linear, sum of squares
and symbolic. The coefficient of a term in a linear objective function may have
a constant numeric value with units or another variables name. In the latter
case the objective term is either bi-linear or quadratic. You can define as
many objective functions as you want. In this way, you can keep track of all
your objective function values during any particular run. The objective
function you wish to solve is determined by the setting of script parameter
OBJECTIVE.
Note that variables are stored internally in OOMF in the units in which model
residuals are evaluated (model base units). Some models may be in SI units
while others may be in metric units. Hence, SI units are used during the
evaluation of a custom objective function in order to have a common basis for
evaluation in the overall flowsheet.
Objective Function Commands

Changing Objective Function Attributes
This command allows various attributes of the objective function to be
changed, such as the scale and the direction.
The objective function attributes may be viewed with the ECHO command.
Input Language
objid.attribute = value
119

Objective function attributes can be changed by referring to the objective
function by name along with its attribute. The allowed attributes are:
VALUE
DIRECTION
Value of the objective function. If you do not enter the units of measure,
SI units are assumed.
Direction for the optimization.
MAXIMIZE
Maximize value
MINIMIZE
Minimize value
SCALE
Scale factor. This is a multiplicative factor.
UOM
Units of measure.
Evaluating the Objective Function

This command evaluates the objective function value and prints it to the
report device.
Input Language
EVALUATE OBJECTIVE objid

objid
Name of the objective function
Evaluating the Objective Functions

Derivatives
This command evaluates the objective function derivatives with respect to all
the variables in the objective function and prints them to the report device.
Input Language
EVALUATE OBJECTIVE DERIVATIVE objid

objid
Evaluating the Objective Functions Hessian

This command evaluates the objective function Hessian (second derivatives)
with respect to all the variables in the objective function and prints them to
the report device.
Input Language
EVALUATE OBJECTIVE HESSIAN objid
120

objid
Printing the Objective Function

This command prints all terms in the objective function.
Input Language
PRINT OBJECTIVE objid

objid
Name of the objective function to print.
Jacobian and Derivative

Commands
These commands allow you to analyze the Jacobian and change the manner
in which numerical derivatives are computed.
Analyzing the Jacobian

This command compares the analytical Jacobian values against the values
computed numerically. You may specify the blocks for which the analysis is to
be done.
Input Language
ANALYZE JACOBIAN reltol, pertsize, block_list

reltol
Relative error tolerance. If the relative error is greater than this value, the
analytical and numerical derivatives are reported for each term in error.
pertsize
Optional value of the perturbation size for the numerical derivative

evaluation. (default = 1.0E-6).
block_list
Optional list of blocks in which to analyze the Jacobian. The list entries are
separated by commas. All the blocks in the list must be within the current
scope.
Analyzing the Jacobian Sparsity

This command compares the analytical and numerical Jacobian sparsity
patterns. You may specify the blocks for which the analysis is to be done.
Input Language
ANALYZE SPARSITY zerotol, pertsize, block_list
121

zerotol
Zero tolerance. If the numerical value of the Jacobian element is less than
this tolerance, then the element is considered zero. (default = 1.0E-12)
pertsize
Optional value of the perturbation size for the numerical derivative

evaluation. (default = 1.0E-6)
block_list
Optional list of blocks in which to analyze the Jacobian. The list entries are
separated by commas. All the blocks in the list must be within the current
scope.
Evaluating the Jacobian

This command evaluates the Jacobian. The Jacobian for excluded blocks are
not evaluated.
Input Language
EVALUATE JACOBIAN
Printing the Jacobian

Prints the scaled Jacobian values for the selected blocks or Jacobian element
index to the report device.
The Jacobian is not calculated by this command. To calculate the Jacobian,
use EVALUATE JACOBIAN.
The width of the variable and equation name fields in the report may be set
with script parameter NAME_WIDTH.
Input Language
PRINT JACOBIAN list

list
Optional list of block names or nonzero element indices. If

omitted, the entire Jacobian is printed.
Printing Jacobian Variables

Print to the report device all Jacobian entries corresponding to the selected
list of variables, which can be specified using variable names or regular
expression matching. Each variable is associated with a column in the
Jacobian matrix.
Input Language
PRINT JACOBIAN VARIABLES list
122

list
List of variable names of indices that appear in the Jacobian.
Printing Jacobian Equations

Prints to the report device all Jacobian entries corresponding to the selected
list of equations, which can be specified using equation name or regular
expression matching. Each equation is associated with a row in the Jacobian
matrix.
Input Language
PRINT JACOBIAN EQUATIONS list

list
List of equation names or indices that appear in the Jacobian.
Printing Block Derivative Methods

This command prints a table of block names in the current scope level only
with their derivative methods, perturbation sizes (if computed numerically),
and other block information.
Block attributes associated with the derivative method may be changed. See
Changing Block Attributes.
Input Language
DERIVATIVE
Examples Of Derivative Commands

To print the Jacobian for equation FDEF.STREQN.COMPBAL_C2H4 enter:
PRINT JACOBIAN EQUATION FDEF.STREQN.COMPBAL_C2H4
To print the Jacobian for entire block FDEF enter:
PRINT JACOBIAN FDEF
To print the Jacobian for nonzero number 30 enter:
PRINT JACOBIAN 30
To print the Jacobian for nonzero number 30 to 40 enter:
PRINT JACOBIAN 30 : 40
Note that the colon is surrounded by blanks.
123
Lets interactively query the derivatives for a small flowsheet and then change
one of the blocks to use numerical derivatives with a perturbation size of
1.0E-7.
EO> DERIVATIVE
--block- --deriv- --pert size- --when update fails- --nonlinearity r. deviation
DDEF analytic
C2S analytic
F analytic
C2MEAS analytic
EO> DDEF.DERIV_METHOD = NUMERIC
EO> DDEF.PERT = 1.0D-7
EO> DERIVATIVE
--block- --deriv- --pert size- --when update fails- --nonlinearity r. deviation
DDEF numeric 1e-007
C2S analytic
F analytic
C2MEAS analytic
Lets interactively analyze the Jacobian for block C2S and report errors for
any derivatives with relative errors greater than 0.1 using a perturbation size
of 1.0E-6.
EO> ANALYZE JACOBIAN 1.0, 1.0D-6, C2S
Analyzing C2S
Found 5 significant differences out of 6858 non-zeros
---i--- ----------equation---------- ----------variable---------- --analytic-- ---numeric-148 C2S.BLKEQN_PHSEQBL_1_C2H4
C2S.BLK.CVAP_1.C2H6
-0.4405
-447.5
254 C2S.BLKEQN_PHSEQBL_3_C2H4
C2S.BLK.CVAP_3.C2H6
-1.969e-006
4.254e-007
C2S.F.STR.MOLES
0.002919
-0.001528
C2S.BLK.F.C2H4.FL_VMFRC
0.001769
0.0233
C2S.BLK.EFF_1
-0.09316
0.01107
124
8 Analysis
This chapter describes the OOMF Script commands used for analysis and
controlling the solver.
Analysis Commands
These commands help you analyze your problem and can assist in debugging.
Checking Degrees of Freedom

This command prints the degrees of freedom for the problem. If no degrees of
freedom exist, then it will report that the problem is square. If there are too
many fixed variables, the problem is structurally singular and an equation
name is listed. If the listed equation were to be dropped, then the problem
would become square. If not enough fixed variables are assigned, then this
command will report the number of required specifications to completely
determine the problem. If variables are specified as independent, ANALYZE
DOF will not count them as fixed variables and will report the number of
required specifications, including any independent variables.
Input Language
ANALYZE DOF
Sensitivity Analysis
This command computes the sensitivity between a set of independent and
dependent variables. The sensitivity is the derivative or gain between the
variables. This can be very useful for analyzing flowsheet behavior or in
control system design. This output is sent to the HISTORY_DEVICE.
Input Language
SENSITIVITY obj [ depend ], [ indep ]

obj
8 Analysis
Name of the objective function to compute sensitivity for. If omitted, the
125
current objective function is used.

depend
Comma separated list of dependent variables. These variables must be

calculated in the current mode.
indep
Comma separated list of independent variables. These variables must be

fixed or independent in the current mode.
Analyzing Variables
This command analyzes the structure of the problem and divides the variables
into a set of observable and unobservable variables and redundant and
nonredundant measurements. A variable is defined as observable or
determinable if there are sufficient measurements or fixed variables that will
allow it to be determined through the model. A measurement is defined as
redundant if the variable associated with it can be determined or estimated
even in the absence of this measurement.
A problem is well determined if there are no unobservable variables.
Consider the following simple system:
X1 = X2 + X3
X3 = 1
X3 is determined from the second equation. However X1 and X2 cannot be
determined from the first equation. Therefore both are unobservable. If we fix
X1 or X2 , then all the variables are observable.
If we attach measurement X2m to variable X2, then X2 can be estimated
from its measurement:
X2 = X2m
Then X1 can be computed from X2 and X3. Thus X2 becomes observable.
However this would not be possible without this measurement. Therefore
measurement X2m is nonredundant.
This report is written to the history device.
Input Language
ANALYZE VARIABLES obj, [ list ]
126
obj
Name of the objective function.
list
Comma separated list of variables. If provided, the command will pick from
the list the minimum number of variables to fix to make the problem solvable.
8 Analysis
Analyzing Equations
Equation analysis is a numerical tool that helps to troubleshoot problems with
singular jacobians by isolating the groups of equations which are linearly
dependent. These groups are unique and do not depend on any options for
the LU factorization. An equation is linearly dependent with other equations if
it can be reproduced by adding the other equations multiplied by appropriate
factors.
A problem with linearly dependent equations can arise from:
An improperly written model.
A flowsheet with multiple solutions.
Combinations of free/fixed variables that cause two or more equations to

become similar. Either the specifications do not make sense, or the model
has design or coding flaws, or both.
Note that because this algorithm factorizes the Jacobian, you should evaluate
the jacobian before invoking this command. Also note that active bounds are
not yet considered.
This command reports groups of dependent equations. Each group defines a
cluster of equations that are dependent among themselves. The equations
from one group are not dependent with respect to the other groups. Generally
speaking, the more groups you have the more broken your problem is.
This report is written to the history device.
Input Language
ANALYZE EQUATIONS
Examples of Analysis Commands

In this example, we take a simple feed block that is square and make a
specification change to show the output from the analysis commands. First,
lets look at the output when the problem is square:
EO> ANALYZE DOF
Problem is square
EO> EVALUATE JACOBIAN
EO> ANALYZE VARS
Number of observables
(determined) :
unobservables (undetermined):
Number of redundants
:
nonredundants
:
You have a well defined problem.
1489
0
3
0
EO> ANALYZE EQNS

-------------------------------REMINDER
Have you evaluated the Jacobian?
--------------------------------
8 Analysis
127
Number of incident variables:

1492
Number of incident equations:
1492
Numerical rank
:
1492
Structural rank
:
1492
No linearly dependent equations were found.
Now lets make a bad specification change by fixing an extra variable in a
block. This will create an overspecified problem:
EO> CVAP.BLK.COUT_PRES.SPEC = CONST>
EO> ANALYZE DOF
Problem is structurally singular. 1 too many specifications.
The following equations are unassigned:
STR.CVAP.BLK.CIN_PRES
EO> ANALYZE VARIABLES
Error. Problem is overspecified. Too many equations or too many
fixed variables.
Number of included equations
:
1492
Number of free variables
:
1491
EO> ANALYZE EQUATIONS
Error. Problem is overspecified. Too many equations or too many
fixed variables.
Number of included equations
:
1492
Number of free variables
:
1491
The DOF analysis indicates that the equation on the pressure drop has a
problem, which helps clue us in to our error.
An example of sensitivity analysis follows. This example is for a C2 Splitter
tower operating with fixed distillate and bottoms compositions. This analysis
will tell us the gain relationships between the compositions and the distillate
flow and reflux ratio. It also will tell us the gain with respect to the objective
function (in this case the profit of the tower).
SENSITIVITY [ C2S.BLK.DISTILLATE_MASS,
\
C2S.BLK.REFL_RATIO_MASS ], \
[ C2S.D.STR.C2H6,
\
C2S.B.STR.C2H4
]
This will result in the following to be output to the current history device:
Sensitivity of ... with respect to: C2S.D.STR.C2H6
... C2S.BLK.DISTILLATE_MASS
:0.43028D+05
... C2S.BLK.REFL_RATIO_MASS
:-.16265D+04
... Objective function
:0.64775D+03
Sensitivity of ... with respect to: C2S.B.STR.C2H4
... C2S.BLK.DISTILLATE_MASS
:-.94086D+04
... C2S.BLK.REFL_RATIO_MASS
:-.82312D+00
... Objective function
:0.14463D-02
128
8 Analysis
Solver Commands
These commands are used to specify the solver and its parameters.
Setting the Solver

This command is used to select the solver to be used on the problem.
Input Language
SOLVER solver

solver
Name of the solver to use. A blank will print the current solver.
DMO
DMO (default)
LSSQP
LSSQP
NSOLVE
NSOLVE
SPARSE
SPARSE
The following solvers can be used to solve square problems:

DECOMP DMO
DMO with group decomposition
DECOMP LSSQP
LSSQP with group decomposition
DECOMP SPARSE
SPARSE with group decomposition
Viewing Solver Settings

This command is used to view and change the settings of the solver.
Input Language
SOLVER SETTINGS parameter = value, parameter = value,

parameter
Name of the parameter to change. If no parameter is entered, this

command will list the current values of all the solver settings.
value
Value for the entered parameter.
Entering DMO Parameters

This command enters values for DMO parameters. Current settings may be
viewed or changed with the SOLVER SETTINGS command.
Input Language
DMO.parameter = value
8 Analysis
129

parameter
Name of the parameter to change.
value
DMO Parameters
DMO Parameter
Description
MAXITER
Maximum number of SQP iterations allowed (default = 50).
MINITER
Minimum number of SQP iterations allowed (default = 0).
CREEPFLAG
Flag for the creep mode. This mode is very effective for making the optimizer
moves more conservative. It is very helpful when the problem diverges.
0
No (default)
Yes
CREEPITER
Number of iterations to perform creep mode (default = 10).
CREEPSIZE
Creep mode step size. This is the fraction of the full step to be taken when in
creep mode (default = 0.1).
SEARCHMODE
Hessian initialization mode:
LINESEARCH
FACTORSPEED
USEDROPTOL
DROPTOL
130
Aggressive mode. The Hessian is initialized with small values. This mode
moves the problem to its bounds faster than the normal mode and is the
preferred mode for highly constrained optimization problems with few
degrees of freedom at the solution.
Normal mode. The Hessian is initialized with the identity matrix (default).
Advanced mode. The Hessian is initialized with second order information.

This mode is recommended for problems with many degrees of freedom
at the solution. It is ideal for reconciliation problems.
Scaled mode. A combination of the Aggressive and Advanced modes.

Recommended for highly constrained optimization problems with few
degrees of freedom at the solution and a nonlinear objective function.
Line search algorithm.

0
Exact penalty
Modified exact penalty method
Penalty with different weight update scheme
Penalty with modification for square cases (default)
Same as 3 modified to enforce bounds in square cases
LU factorization method.
1
Normal method. Optimizes pivot at every iteration (default).
Fast method. Uses original pivot sequence if possible. This can be faster.
In some cases (i.e. extreme phase changes) may cause additional
factorization.
Flag to indicate the use of the nonzero drop tolerance.

0
Do not drop small nonzeroes (default)
Drop small nonzeroes
Nonzero drop tolerance used to remove small Jacobian values. A larger tolerance
will reduce the number of nonzeroes and decrease factorization time. If the value
is too large, then the accuracy of the Jacobian will be reduced. This may lead to
an increase in the number of iterations and/or singularities. (default = 1.0D-20)
8 Analysis
DMO Parameter
Description
SAVEJDFFILE
Flag to save binary form of the Jacobian in the JDF file. This file is read by the
solution analysis, DMOSAT.
SCREENFORM
Do not save JDF file (default)
Save the JDF file
Flag to modify the output format for the iteration log.

0
Format designed for direction into a file
Format designed for interactive screen observation (default)
HESSIANUPDATES
Number of Hessian updates kept before resetting. (default = 10)
RIGORUPDATES
Number of constraint updates before a rigorous analysis phase. (default = 25)
FACTORSPACE
Parameter related to the workspace allocated for the solution of the linear system
of equations. Problems with excessive fill-in may require a higher number.
(default = 6)
ACTIVESPACE
Parameter related to the workspace allocated for part of the active set strategy.
(default = 2)
PIVOTSEARCH
Parameter related to the pivoting strategy. (default = 10)
VARSCALE
Flag to indicate the use of variable scaling.
PRINTFREQ
Do not scale variables
Scale variables (default)
Flag to indicate diagnostic printing level for variables and residuals.

-1
Minimum diagnostics (default)
1
Maximum diagnostics (including all variable and residual values at every
iteration)
LUSTATS
Flag to indicate diagnostic printing level for linear system.
QPSTATS
No diagnostics (default)
Full diagnostics
Flag to indicate diagnostic printing level for the QP subproblem.

0
No diagnostics (default)
Full diagnostics
IWORKF
Integer workspace parameter (default = 1.0)
RWORKF
Real workspace parameter (default = 1.0)
RESCVG
Residual convergence tolerance (default = 1.0D-6)
OBJCVG
Objective function convergence tolerance (default = 1.0D-6)
ANALYSISTHRES
Threshold parameter for a forced re-analysis of the problem structure. This

number should be higher in cases of a natural high fill-in such as highly heat
integrated units. (default = 2.0)
Entering LSSQP Parameters

This command enters values for LSSQP parameters. Current settings may be
viewed or changed with the SOLVER SETTINGS command.
Input Language
LSSQP.parameter = value
8 Analysis
131

parameter
value
LSSQP Parameters
LSSQP
Parameter
KPTLEV
KPFREQ
Description
History print level.
4
Summary information at each iteration (default)
Independent and constrained variables, inactive equations, top scaled/unscaled

variable changes, top scaled/unscaled constraint residuals, top block RMS
residuals, and top worst merit function contributors when line search is required
Top worst merit function contributors
Full variable vector (potentially large amount of output)
Full constraint vector
Control the frequency of printing full variable/constraint vectors. The first and last
vectors are always printed when requested by KPLLEV (default=1).
KPNTOP
Control the number of top entries to print in top entry outputs (default=10).
MAXITR
Maximum number of SQP iterations allowed (default=30).
MINITR
Minimum number of SQP iterations allowed (default=2).
RELEPS
Relative optimization convergence tolerance as indicated in step 6 of the algorithm

description given above (default = 1.0D-4).
NFINFB
Maximum number of feasibility corrections allowed to try to reduce constraint violations

below RFINFB after the optimization calculation is terminated (default = 5). If the
constraint violations are still greater than RFINFB after NFINFB corrections, the REZ file
will state Problem converged but residuals still too large, and the CONVERGED script
parameter will be false. However, the Kuhn-Tucker error is still satisfied.
RFINFB
Tolerance on final constraint violations (default = 1.0D-6). See above.
NFEASB
Maximum number of feasibility corrections allowed at each SQP iteration to try to keep
constraint violations below RFEASB (default = 2). The more feasibility corrections
allowed, the more the solution will become like a feasible-path optimization.
RFEASB
Tolerance on iteration constraint violations (default = RFINFB for simulation, 1.0D-2 for
other modes). See above.
ITRBND
Number of initial iterations when CHGBND instead of CHGMAX is used to limit search
steps (default = 3). This parameter, along with CHGBND, can be used to reduce the
step size during the initial iterations, thus keeping the optimization moves more
conservative.
CHGBND
Initial limit on the optimization step size. See above. The step size is limited such that
k|dk| CHGBND * max(1,|xk|). This is a relative step size limit. A negative value for
CHGBND implies an absolute step size limit (default=0.25).
CHGMAX
Step size limit after the first ITRBND iterations. The step size is limited such that k|dk|
CHGMAX *max(1,|xk|) (default=0.5).
ALFALS
Minimum step cutback ratio per line search iteration (default=0.25).
MAXLSC
Maximum number of line search cutbacks allowed per SQP iteration. When this limit is
reached, the SQP iteration continues with the final step size (default=1 for simulation, 10
for other modes).
MAXLSF
Maximum number of consecutive SQP iterations with line search failure before
terminating LSSQP (default=10 for simulation, 3 for other modes).
132
8 Analysis
LSSQP
Parameter
Description
MAXQPF
Maximum number of consecutive SQP iterations with QP failure before terminating

LSSQP (default=10).
GNPMAX
An artificial weighting factor to drive the QP problem to the feasible region. In rare
occasions, it has to be increased to avoid a small feasibility index (default=1.0D6).
MDHESS
Hessian approximation option. Generally, this should only be changed for the DRPE case.
The options follow:
LEWBAS
LSCOPT
IXSCS
Use general BFGS update to approximate the Hessian.
Always calculate Gauss-Newton-type Hessian approximation.
Use Gauss-Newton-type Hessian approximation for initialization but update it

with BFGS update.
Selectively choose between BFGS update or Gauss-Newton-type Hessian

approximation. (default=2 for DRPE, 0 for all other modes).
Type of basis for range-space representation. Allowed options follow:

0
Orthogonal basis (potentially more stable) (default)
Coordinate basis (less overhead especially for problems with large degree of
freedoms)
Line search options. Allowed options follow:

1
Same as option 3 for the first ITRBND iterations. Perform only step bounding
with CHGMAX thereafter.
Same as option 4 for the first ITRBND iterations. Perform only step bounding
with CHGMAX thereafter.
Exact penalty function.
Exact penalty function with Powells Watchdog relaxation (default).
Exact penalty function with second-order correction.
Exact penalty function with trust region control.
Exact penalty function with trust region control and second order correction.
LSSQP internal variable and constraint scaling options. Allowed options follow:
0
No internal variable or equation scaling (in addition to the scaling performed by

models and/or executive)
Derive variable scaling from initial x0; derive constraint scaling from Jacobian
No variable scaling; derive constraint scaling from Jacobian (default)
Derive variable and constraint scaling simultaneously from Jacobian
For some problems, IXSCS=3 can provide an improvement in performance.

BNDAPP
Approach to bounds allowed in one iteration (default=0.99).
QPINFE
QP infeasible parameter. If QPINFE is positive and greater than the QP feasibility index,
then a new search direction is determined by minimizing the sum of absolute violations.
This can be helpful when trying to find a feasible solution to an initially infeasible
optimization problem (default=0.0).
KMUDEC
Options for adjusting penalty parameters:

0
Do not allow penalty parameter to be decreased.
Allow penalty parameter to be decrease gradually (default).
Use Lagrange multiplier as penalty parameter. This may work better for some
problems.
TOLBAS
Threshold pivot tolerance when selecting a basis (default=0.1).
TOLANA
Threshold pivot tolerance for the rare case of reanalyzing a matrix (default=0.1).
8 Analysis
133
LSSQP
Parameter
Description
SPDROP
Matrix elements with absolute value smaller than SPDROP are dropped by the sparse
linear solver (default=1.D-15).
SINGT1
Matrix elements with absolute value less than SINGT1 are not allowed to become pivot
elements when selecting a basis (default=1.D-8).
SINGT2
Matrix elements with absolute value less than SINGT2 are not allowed to become pivot
elements during numerical factorization (default=1.D-10).
NNDCMP
Number of equality constraints that should not be used to eliminate variables

(default=0).
DELTLS
Actual to predicted merit function reduction ratio below which a line search step will be
rejected (default=0.1).
BIGBND
Big number to identify fake bounds (-BIGBND, BIGBND) (default=1.D20).
BNDADJ
Adjustment to bounds to create a feasible region when a QP subproblem is infeasible

(default=1.D-5).
BSMALL
Smallest diagonal in Choleskey decomposition of the projected Hessian (default=1.D-8).
SMLSCL
Small number to limit scaling (default=1.D-8).
BIGSCL
Big number to limit scaling (default=1.D10).
LCHBAS
Allow basis changing. See below:

0
No
Yes (default)
BASFLP
Growth of the largest sensitivity matrix element to trigger a new basis selection
(default=100.). Parameter LCHBAS must be 1. Set this number to a larger value to
prevent LSSQP from reselecting the basis.
TAUHYB
Parameter for deciding whether to use Gauss-Newton-type Hessian approximation for

MDHESS=4 (default=0.1).
LSIZEB
Hessian sizing option. This is represented as a two-digit decimal number; each digit sets
a parameter:
0
Dont resize Hessian after first iteration; use identity matrix for initial Hessian.
Dont resize Hessian after first iteration; use FSCALF to scale initial Hessian.
10
Resize Hessian after first iteration; use identity matrix for initial Hessian.
11
Resize Hessian after first iteration; use FSCALF to scale initial Hessian (default).
FSCALF
Initial Hessian scaling factor. If FSCALF is positive, the initial Hessian is set to
FSCALF*I. Otherwise, the initial Hessian is set to |FSCALF|*FSCALV*I where FSCALV
is an estimate of the magnitude of the objective function. If FSCALF is zero, a value of
-0.1 is used (default=0.01).
RRLOW
Low limit of yTs/sTBs to limit the BFGS update (default=0.2).
RRHIGH
High limit of yTs/sTBs to limit the BFGS update (default=100.).
ETASKP
Range-space to full step ratio above which BFGS update will be skipped (default=0.95).
VMUINI
Initial line search penalty parameter (default=1.D-3).
VMUMIN
Minimum line search penalty parameter (default=1.D-8).
VMUFAC
Penalty parameter multiplier factor from Lagrange multiplier (default=2.).
MSFREQ
134
Matrix scaling frequency.

0
No matrix scaling.
Scale matrix before a basis selection (default).
Scale matrix before an analyze call.
Scale matrix before both basis selection and analysis calls.
8 Analysis
LSSQP
Parameter
Description
MSMETH
Matrix scaling method.

0
Scale with MC19AD.
Scale with row and then column equilibration (default).
Scale with column and then row equilibration.
KOWARM
Warm start the optimization, not supported. (default=0).
LUBNDS
Bounds present flag:
LINCST
IFDTYP
No
Yes (default)
Linear constraint flag:

0
No (default)
Yes
Finite-difference Hessian approximation type. The frequency of this calculation is

determined by IFDITR. This option allows the computation of the Hessian via
perturbation of the independent variables rather than through an updating method.
However, it can be time consuming.
1
Projected Hessian, nonmultiplier version (default)
Same as 1 but drop bound contribution
Projected Hessian, multiplier version
Diagonal approximation, nonmultiplier version
Same as 4 but drop bound contribution
Diagonal approximation, multiplier version
IFDITR
A single-integer parameter used to set to separate parameters: the finite difference

frequency and the first finite difference iteration number. This value is the finite
difference frequency * 1000 + first finite difference iteration number. For example, if
IFDITR=5010, the first finite difference will occur at iteration 10 and then every five
iterations (default=0; no projected Hessian calculation).
ZPERTF
Perturbation factor for projected Hessian calculation (default=1.0D-4).
NICHK
Iteration count to check if the problem should be reinitialized. LSSQP checks the problem
status at the current iteration, INICHK iterations ago and 2*INICHK iterations ago. If
the problem is not making adequate progress, it is reinitialized. This causes the Hessian
to be reset, the problem to be rescaled, and a new basis to be selected (default=20).
KFOWDG
Accumulated line search counts to force a watchdog step. This relaxes the line search
criteria and allows the merit function to decrease. LSSQP will search along this path for
KBKOUT iterations. If the merit function has not improved by then, LSSQP will backtrack
to the iteration where the watchdog took place and perform a line search. The watchdog
relaxation technique can often help converge the problem (default=10).
KBKOUT
Number of iterations to wait for merit function to improve before backing out of a forced
watchdog relaxation (default=20).
NBDBAS
Number of bound violations for insensitive dependent variables before basis switching
(default=10).
8 Analysis
135
LSSQP
Parameter
Description
IFDTYP
Numerical derivative option. Users should use the numerical derivative options provided
by the executive. Potential nonzeros in the gradient that are actual zeros should be set
to small values for options 2 and 4:
0
No numerical derivative calculation (default).
Use numerical derivative for Jacobian.
Use numerical derivative for Jacobian and gradient.
Verify Jacobian at the initial point.
Verify Jacobian and gradient at the initial point.
Numerical derivatives are computed using the following step size:

DPERTF max(|X|,XPMIN)
When using this option to verify the Jacobian, derivatives are reported with errors
greater than:
DERDIF max( | analytic value |,| numerical value |, DERMIN )
DPERTF
Relative perturbation size for numerical derivative calculation. See above (default=1.D6).
XPMIN
Absolute perturbation size for numerical derivative. See above (default=0.01).
DERDIF
Relative tolerance for reporting derivative errors. See above (default=0.001).
DERMIN
Absolute tolerance for reporting derivative errors. See above (default=0.01).
Entering NSOLVE Parameters

This command enters values for NSOLVE parameters. Current settings may
be viewed or changed with the SOLVER SETTINGS command.
Input Language
NSOLVE.parameter = value

parameter
value
NSOLVE Parameters
NSOLVE Parameter
Description
Maximum_iterations
Maximum number of allowed iterations (default=100).
Bound_iterations
Maximum number of allowed consecutive iterations at which some of the

variables hit upper or lower bounds (default=20).
Divergent_steps
Maximum number of allowed iterations at which the residual function vector

diverges (default=20).
Stable_iterations
Number of initial iterations where the variable step sizes are controlled by
stabilization strategies such as Powells Dogleg or One Dimensional LineSearch (default=4). Stabilization techniques are enforced on subsequent
iterations only if the steps are grossly divergent.
136
8 Analysis
NSOLVE Parameter
Description
Stabilization
Stabilization technique used for controlling the variable step sizes: 0=

Powells Dogleg and 1=One Dimensional Line-Search (default=1).
Check_steps
Flag that indicates whether the 2-norm of the variable step vector needs to
be within the specified tolerance: 0=do not check for step sizes, 1=check for
step sizes (default = 1).
Print_level
Iteration history printing level. Values higher than 4 print a detailed iteration
history in the solver report file (default = 4).
Function_tolerance
Allowed tolerance on 2-norm of the residual function vector (default =

1.0D-6).
Maximum_function_error Maximum error allowed based on the 2-norm of the residual function vector
(default =1.0D30).
Variable_tolerance
Allowed tolerance on variable step sizes based on the 2-norm of the variable
step vector (default = 0.01). This is used only if the parameter
Check_steps=1.
Trust_radius
Radius of the initial trust region measured as a ratio of the 2-norm of the
variable vector (default=0.1). This is used only with Powells Dogleg strategy
(when parameter Stabilization=0). The radius is automatically adjusted after
each iteration using Powells formula.
Solving the Problem

This command begins the solution process.
Input Language
SOLVE objid
Models may add a custom solution algorithm that can augment or substitute
this primary solution process. These custom solution algorithms will be
invoked automatically.

objid
Name of the objective function to solve.
Examples of Solver Commands

To declare LSSQP as the solver and set the maximum iterations to 20, enter:
SOLVER LSSQP
LSSQP.MAXITR = 20
8 Analysis
137
Recovery Commands
These commands are used to restore the problem state after a failed solution.
Resetting Variables to Initial Values

This command sets every variable's Value attribute to the value in its Initial
attribute. Effectively, this resets the variable values to their state before the
solve command was issued.
Input Language
RESET VARIABLES
RESET VARS
RESET VAR
See Also
Aspen Plus Extensions - Recovery Commands
138
8 Analysis
9 Printing and Reports
This chapter describes the OOMF Script commands that let you print
information and create reports.
Printing Problem Information

These commands allow you to print general information about the problem.
Printing the Problem Summary

Prints a summary of the problem size to the report device. It also reports on
the degrees of freedom in the problem.
Input Language
PRINT SUMMARY
Printing Problem Convergence

Prints a summary of the convergence criteria. This includes the final
convergence status, the number of iterations, the objective and residual
convergence functions, the number of iterations and the initial and final
values of the objective function.
Input Language
PRINT CONVERGENCE SUMMARY
Examples of Printing Problem Information

This example of an interactive session shows the output from the PRINT
SUMMARY command.
EO> PRINT
Number of
Number of
Number of
Number of
SUMMARY
variables:
incident variables:
fixed variables:
free variables:
1526
1523
32
1491
139
Number of equations:
Number of included equations:
Block equations:
Connection equations:
Number of excluded equations:
Number of non-zeros:
Number of incident non-zeros:
Number of inactive connections:
Number of incomplete connections:
Problem is square
1492
1492
1443
49
0
7640
7261
0
0
This example shows the output form the PRINT CONVERGENCE SUMMARY
command.
EO> PRINT CONVERGENCE SUMMARY
Convergence summary
------------------Status:
Converged
Iterations:
7
Residual convergence: 3.861e-008
Objective convergence: 1.566e-007
Initial objective:
2.556
Final objective:
2.647
Formatted Printing
Formatted print is a powerful tool to allow you to create your own custom
reports.
Print Formatted Command

This command allows the use of formatted printing to create custom reports.
Input Language
PRINT FORMATTED expression1 , expression2 , expression3 ,

expression1
The format for the print. This must evaluate to a string data type. The
format may refer to a previously defined script parameter, in which case
the & should proceed the name in the PRINT command. The script
parameter may be defined with the SET command.
expression2
The data to print. The type of this data should match the corresponding
data type in the format string.
Note that in the above, the expressions are separated by commas, and that
the commas must be surrounded by blanks. Expressions are discussed further
in the section titled Expressions and Conditionals.
The format string is based on the ANSI C library function PRINTF. The format
may contain literal characters as well as control characters. The control
characters are case sensitive and are as follows:
140
Control
Character
Description
\n
Indicates a carriage return, line feed. Format statements are not assumed
to end with a carriage return and line feed so you must use the \n at the
end of the format if you wish to move to a new line.
\t
Horizontal tab (ASCII character HT).
\v
Vertical tab (ASCII character VT).
\b
Backspace (ASCII character BS).
\r
Carriage return without linefeed (ASCII character CR).
\f
Form feed (ASCII character FF).
\a
Audible bell (ASCII character BEL).
\\
Backslash character (\).
%n.mf
Indicates a field to print a real number in fixed format. n is the minimum

field width, and m specifies the number of digits to the right of the
decimal. If m is zero, no decimal point is printed. The default value for m
is 6. If the magnitude of the value youre printing is large enough, the
minimum field width n may be exceeded.
%n.me
Indicates a field to print a real number in exponential format. n is the

minimum field width. The case of the e indicates the case of the
exponential in the output. m is the number of places to the right of the
decimal. If m is zero, no decimal point is printed. The default value for m
is 6. The total number of spaces taken by this format is MAX(n,m+6) (two
spaces are allocated for the power term).
%n.mg
Indicates a field to print a real number in general format. n is the

minimum field width. The case of the g indicates the case of the
exponential in the output, if any. m is the number of significant digits.
Exponential (e) format is used if the exponent is less than -4 or greater
than or equal to m; otherwise, fixed (f) format is used. Trailing zeros and
a trailing decimal point are not printed. The exponential format uses 5
spaces. Thus, to ensure a fixed space usage, set n=m+5.
%nd
Print an integer value. n is the minimum field width.
%no
Print an integer value in octal.
%nx
Print an integer value in hexadecimal. The case of the x indicates the case
of the hexadecimal letters.
%c
Print an integer value as its equivalent ASCII character code.
%ns
Indicates a field to print a string. n is the minimum field width. If the

length of the string is less than n, then the string is right justified.
%%
Print a percent sign (%).
In the above formats, a flag may be placed between the percent sign (%)
and the format which indicates the following:
Flag
Description
Left justify the value in the field.
Always print the value with its sign.
space
If the first character is not a sign, a space will be prefixed.
Specifies padding of numeric values with leading zeros.
Specifies an alternate output form. For o, the first digit will be zero. For x, 0x
will be prefixed to a non-zero result. For e, f, and g, the output will always
have a decimal point. For g, trailing zeros will not be removed.
141
Examples of Formatted Printing

In the following example, we print the values of two compositions. The format
used is placed directly in the PRINT command and surrounded by quotation
marks.
PRINT FORMATTED "Top Comp = %1.7f
Btm Comp = %1.7f \n" ,\
C2SD.D.STR.C2H6 , C2SB.B.STR.C2H4
This command creates the output:
Top Comp = 0.0001000
Btm Comp = 0.0050000
Note the use of the \n in the format to create the carriage return and line
feed.
We can create a more complex output using a parameter for the format:
PRINT FORMATTED "Name
Low
Value
PRINT FORMATTED "---------SET FMT = "%-15s %-12.7g %-12.7g %-12.7g \n"
PRINT FORMATTED &FMT , "Top Comp" ,
\
MSMT.BLK.XD_PLANT.LOWER, \
MSMT.BLK.XD_PLANT,
\
MSMT.BLK.XD_PLANT.UPPER
Upper \n"
----- \n"
PRINT FORMATTED &FMT , "Btm Comp" ,

\
MSMT.BLK.XB_PLANT.LOWER, \
MSMT.BLK.XB_PLANT,
\
MSMT.BLK.XB_PLANT.UPPER
This input creates a table of values:
Name
---Top Comp
Btm Comp
Low
--1e-05
0.001
Value
----0.0001
0.015
Upper
----0.0002
0.05
Here, we use the s format for the string output and we use the g format for
the numbers. For the g format, we force the output to take up 12 spaces to
keep the table aligned regardless of the magnitude of the numbers. We use
the - flag in the format to left-justify the output.
142
Miscellaneous Printing
Commands
This section includes a general purpose printing command.
The Echo Command

This command prints a string to the report device.
Input Language
ECHO expression

expression
An expression to echo. This may be a string in double quotes, a

variable attribute, a block attribute, an equation attribute, a
parameter (preceded by a & sign) or a mathematical expression.
A mathematical expression may include the operators:

+, -, *, /, ^, .
<, >, =, <>, <=, >=
ABS, LOGE, LOG10, COS, SIN, TAN, EXP, SQRT, INT, STRING2ID,
ID2STRING, TOUPPER, TOLOWER, LENGTH, SUBSTR, INDEX,
INSERTSTR, REMOVESTR, OPENFILE, OPENBINARY, DEVICEINFO,
OPENTEE, VAL, TYPEOF, DEFINED, HEAD, TAIL, BLOCKVARS,
BLOCKATTRS, QUERYVARS, ALIASESBYVAR, CONNECTIONSBYVAR,
MEASUREMENTSBYVAR, SPECGROUPSBYVAR
Expressions are discussed further in the section entitled Expressions and
Conditionals.
Examples of the Miscellaneous Printing

Commands
Echo a string to the terminal:
ECHO "THE PROBLEM IS SOLVED!"
Add two variables and print the value:
ECHO FDEF.STR.C2H4.FLOW + FDEF.STR.C2H6.FLOW
143
Report Commands
These commands are used to generate reports. Products that embed OOMF
may have additional commands.
See Also
Aspen Plus Extensions - Report Commands
Reporting Blocks
This command prints a report of the specified blocks to the report device.
Input Language
REPORT BLOCKS block_list

block_list
Optional comma-separated list of blocks to report. ALL will

report all the blocks. If omitted, all blocks in the current scope
will be reported.
Reporting the Objective Function

This command writes a report for the objective function.
Input Language
REPORT OBJECTIVE objid

objid
144
Name of the objective function to report.
10 Support for Dynamic

Models
OOMF supports the instantiation of, interaction with, and solution of event
driven dynamic models. Typically, these models are comprised of differential
and algebraic equation systems. This chapter describes the OOMF
parameters, equation-based scripting language commands, and the XMLbased, task-modeling language that can be used to interact with these
models and control the simulation while it is running
Script Parameters that Support

Dynamic Models
OOMF defines several parameters that enable the user to control the solution
of a dynamic model.
Script Parameter
Description
RUN_MODE
Run mode for the simulation. The options are SS (for steady-state
simulations), INIT (for initialization simulations) and DYN (for dynamic
simulations). The default value is SS. The INIT and DYN run modes are
relevant only to dynamic models
DYN_RUN_TO
Time to which the dynamic simulation should run to.
DYN_INTERVAL
Reporting or communication interval for the dynamic simulation.
10 Support for Dynamic Models
145
Script Language Commands

that Support Dynamic Models
These commands can be used to interact with a dynamic model that has been
loaded into the OOMF kernel.
Pausing a simulation
This command is used to pause a dynamic simulation while it is running and
to enter dynamic interactive mode, which will be depicted by a Dyn> prompt
in the client window.
Input Language
PAUSE
Running a simulation
This command is used to continue running a dynamic simulation from a
paused state. The simulation will continue to run until the time specified in
the dyn_run_to parameter is reached or another pause command is invoked.
OOMF will only respond to a run command when it is in dynamic interactive
mode.
Input Language
RUN
Stepping through a simulation

This command is used to step through a dynamic simulation from a paused
state. The step command can only be invoked while in dynamic interactive
mode. Invoking this command will cause the solver to step to the next
communication point in time.
Input Language
STEP
Stopping a simulation
This command is used to exit from dynamic interactive mode.
Input Language
STOP
146
Reinitializing a simulation
This command is used to reinitialize a dynamic simulation.
Input Language
REINITIALIZE
Loading task definitions

This command is used to load one or more task specifications from a file.
Input Language
ADD TASKS FROM <file>

file
Full path to a file that contains the task definitions. The file
should have a .xml extension.
Viewing tasks
This command is used to send a list of all the tasks loaded in OOMF to the
current output device.
Input Language
SHOW TASKS
Deleting a task
This command is used to unload a task from OOMF.
Input Language
DELETE TASK <task_name>

task_name
Name of the task to be deleted.
Activating a variable profile

This command is used to activate variable profiles for one or more variables.
When a profile is activated for a variable, OOMF will record the time history of
the variable as the simulation progresses.
Input Language
ACTIVATE VARIABLE PROFILE <var_list>
147

var_list
A comma-separated list of variable names.
Inactivating a variable profile

This command is used to inactivate variable profiles for one or more
variables.
Input Language
INACTIVATE VARIABLE PROFILE <var_list>

var_list
Viewing a variable profile

This command is used to send the profiles for one or more variables to the
current output device.
Input Language
PRINT VARIABLE PROFILE <var_list>

file
Viewing a variable history

This command is used to compute a variables history and send it to the
current output device. A variable history is a collection of values for a variable
at regular time intervals. Given a start time, an end time and an interval,
OOMF will compute the history of a variable from its profile. If a variable
profile has not been activated, OOMF will not be able to compute the history
for that variable.
Input Language
PRINT VARIABLE HISTORY <var_name, start_time, end_time,
interval>
148
var_name
name of variable for which history is to be computed
start_time
start time for the history method
end_time
end time for the history method
interval
time interval for the history method
Saving a snapshot
This command is used to save a snapshot for a simulation.
A snapshot is the state of a simulation at a given instance. A snapshot can
be used to rollback a simulation to a prior point in time. For instance, you
could save a snapshot of the simulation after it has been initialized.
Each time OOMF saves a snapshot, it assigns it an ID.
Input Language
SAVE SNAPSHOT <snapshot_name>

snapshot_name
Name of the snapshot to be saved
Loading a snapshot
This command is used to load a snapshot into OOMF.
Input Language
LOAD SNAPHOT <snapshot_id>

snapshot_id
ID of the snapshot to be loaded
Viewing snapshots
This command is used to send the list of saved snapshots to the current
output device. The name, ID and time of each snapshot is printed to the
output device.
Input Language
SNAPSHOTS
Deleting a snapshot
This command is used to delete a snapshot.
Input Language
DELETE SNAPSHOT <snapshot_id>

snapshot_id
ID of the snapshot to be deleted
149
Task Language
The OOMF task language is an XML-based language with which the user can
write task specifications that can be loaded into the OOMF kernel to
automatically carry out certain actions during the execution of a dynamic
simulation. For instance, a task can be used to assign a value to a variable,
ramp a variable, invoke a loop, create a snapshot, print a variable or perform
other actions during the simulation run.
This section includes an overview of the task language, including its XML
schema, and some examples of common tasks written in the language.
XML Schema for Task Language

The root element of a task definition is <Tasks>, which may contain one or
more <Task> elements.
The <Task> element encapsulates the core definition of a task. The <Body>
element is the core part of a task definition. It is contained within a <Task>
element.
The body contains one or more task statements that constitute the task. Each
task statement is represented by a specific element. For example, to assign a
value to a variable, specify an <Assign> element; to ramp a variable, use a
<Ramp> element.
To start a task at a given time, specify a value for the time attribute of the
<Task> element. To start a task conditionally, specify a <When> element
within the <Task> element. The <When> element is used to define the
condition that must be satisfied before a task can be carried out.
<Parameter> elements can be used to define parameters that are employed
within the tasks. Parameters specified at the <Tasks> level are global in
scope whereas paramters specified at the <Task> level are local to that task.
The full XML schema for the OOMF task language is presented below.
Concrete examples of some tasks are presented in the next section.
<xs:schema
targetNamespace="http://aspentech.com/AMFTaskLanguage.xsd"
elementFormDefault="qualified"
xmlns="http://aspentech.com/AMFTaskLanguage.xsd"
xmlns:mstns="http://tempuri.org/XMLSchema.xsd"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:NS="http://aspentech.com/AMFTaskLanguage.xsd">
<xs:complexType name="TaskType">
<xs:sequence>
<xs:element name="When" type="xs:string" minOccurs="0"
maxOccurs="1" />
<xs:element name="Parameter" type="LocalParameterType"
minOccurs="0" maxOccurs="unbounded" />
150
<xs:element name="Body" type="TaskBody" minOccurs="0"

maxOccurs="1" />
</xs:sequence>
<xs:attribute name="name" type="xs:NCName" use="required" />
<xs:attribute name="active" type="xs:boolean" />
<xs:attribute name="time" type="xs:double" />
<xs:attribute name="once" type="xs:boolean" />
<xs:attribute name="always" type="xs:boolean" />
</xs:complexType>
<xs:complexType name="LocalParameterType">
<xs:sequence>
<xs:element name="Value" minOccurs="0" type="xs:anyType" />
</xs:sequence>
<xs:attribute name="name" type="xs:string" use="required" />
<xs:attribute name="as" type="xs:string" use="required" />
</xs:complexType>
<xs:element name="Tasks">
<xs:complexType>
<xs:sequence>
<xs:element name="ParameterType"
type="ParameterDefinition" minOccurs="0" />
<xs:element name="Task" type="TaskType" minOccurs="0" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:complexType name="ParameterDefinition">
<xs:sequence>
</xs:sequence>
<xs:attribute name="name" type="xs:string" use="required" />
<xs:attribute name="uses" type="EnumParameterBase"
use="required" />
<xs:attribute name="lower" type="xs:string" />
<xs:attribute name="upper" type="xs:integer" />
</xs:complexType>
<xs:simpleType name="EnumParameterBase">
<xs:restriction base="xs:string">
<xs:enumeration value="IntegerParameter" />
<xs:enumeration value="RealParameter" />
</xs:restriction>
</xs:simpleType>
<xs:complexType name="TaskStatement" abstract="true"
mixed="true">
<xs:sequence />
<xs:attribute name="label" type="xs:string" />
</xs:complexType>
<xs:complexType name="Assignment">
<xs:complexContent>
<xs:extension base="TaskStatement">
<xs:sequence>
</xs:sequence>
<xs:attribute name="to" type="xs:string" />
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="Conditional" mixed="true">
<xs:complexContent>
151
<xs:sequence>
maxOccurs="1" />
<xs:element name="False" type="Conditional"
minOccurs="0" maxOccurs="1" />
</xs:sequence>
</xs:extension>
</xs:complexType>
<xs:complexType name="CreateSnapshot">
<xs:complexContent>
<xs:sequence />
</xs:extension>
</xs:complexType>
<xs:complexType name="Wait">
<xs:complexContent>
<xs:sequence />
</xs:extension>
</xs:complexType>
<xs:complexType name="WaitFor">
<xs:complexContent>
<xs:sequence />
</xs:extension>
</xs:complexType>
<xs:complexType name="Parallel" mixed="true">
<xs:complexContent>
<xs:sequence>
maxOccurs="1" />
</xs:sequence>
</xs:extension>
</xs:complexType>
<xs:complexType name="Pause">
<xs:complexContent>
<xs:sequence />
</xs:extension>
</xs:complexType>
<xs:complexType name="Print" mixed="true">
<xs:complexContent>
<xs:sequence>
<xs:element name="Arg" type="xs:string" minOccurs="0"
maxOccurs="unbounded" />
</xs:sequence>
</xs:extension>
</xs:complexType>
152
<xs:complexType name="Ramp">
<xs:complexContent>
<xs:sequence>
</xs:sequence>
<xs:attribute name="variable" type="xs:string"
use="required" />
<xs:attribute name="period" type="xs:double"
use="required" />
<xs:attribute name="target" type="xs:string"
use="required" />
<xs:attribute name="type" type="EnumRampType"
use="required" />
</xs:extension>
</xs:complexType>
<xs:simpleType name="EnumRampType">
<xs:restriction base="xs:string">
<xs:enumeration value="Continuous" />
<xs:enumeration value="Discrtete" />
</xs:restriction>
</xs:simpleType>
<xs:complexType name="SRamp">
<xs:complexContent>
<xs:sequence>
</xs:sequence>
<xs:attribute name="variable" type="xs:string"
use="required" />
<xs:attribute name="period" type="xs:double"
use="required" />
<xs:attribute name="target" type="xs:double"
use="required" />
<xs:attribute name="type" type="EnumRampType"
use="required" />
</xs:extension>
</xs:complexType>
<xs:complexType name="Return">
<xs:complexContent>
<xs:sequence />
</xs:extension>
</xs:complexType>
<xs:complexType name="Invoke" mixed="true">
<xs:complexContent>
<xs:sequence>
<xs:element name="Script" type="xs:string"
minOccurs="1" maxOccurs="1" />
<xs:element name="Input" type="xs:string" minOccurs="0"
maxOccurs="unbounded" />
<xs:element name="Output" type="xs:string"
minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:extension>
153
</xs:complexType>
<xs:complexType name="TaskBody">
<xs:choice minOccurs="0" maxOccurs="unbounded">
<xs:element name="Assign" type="Assignment" />
<xs:element name="If" type="Conditional" />
<xs:element name="CreateSnapshot" type="CreateSnapshot" />
<xs:element name="Wait" type="Wait" />
<xs:element name="WaitFor" type="WaitFor" />
<xs:element name="Parallel" type="Parallel" />
<xs:element name="Pause" type="Pause" />
<xs:element name="Print" type="Print" />
<xs:element name="Ramp" type="Ramp" />
<xs:element name="SRamp" type="SRamp" />
<xs:element name="Return" type="Return" />
<xs:element name="Invoke" type="Invoke" />
<xs:element name="Stop" type="Stop" />
<xs:element name="For" type="For" />
</xs:choice>
</xs:complexType>
<xs:complexType name="Stop">
<xs:complexContent>
<xs:sequence />
</xs:extension>
</xs:complexType>
<xs:complexType name="For" mixed="true">
<xs:complexContent>
<xs:sequence>
maxOccurs="1" />
</xs:sequence>
<xs:attribute name="each" type="xs:string"
use="required"/>
<xs:attribute name="in" type="xs:string" use="required"/>
</xs:extension>
</xs:complexType>
</xs:schema>
154
Example Tasks
This section contains several example tasks written in the OOMF task
language.
Assigning a value to a variable

The following example depicts how a value is assigned to a variable:
<Tasks>
<Task name="SetFeed" active="true" once="true" time="0.05">
<Body>
<Assign to="B1.F">2{kg/hr}</Assign>
</Body>
</Task>
</Tasks>
In this task, the value of variable B1.F is set to 2 kg/hr. The name of the task
is SetFeed, it is active when it is loaded and it is carried out once at time
0.05.
Ramping a variable
The following example depicts how to ramp the value of a variable:
<Tasks>
<Task name="RampHeat" active="true" once="true" time="0.0">
<Body>
<Ramp variable="B1.Q" target="10" period="5.0" type="Discrete" />
</Body>
</Task>
</Tasks>
In this task, the value of variable B1.Q is ramped to a value of 10 over a
period of 5 time units starting a time 0. If the ramp type is Discrete, as
shown in the example, the solver will update the value of the ramped variable
at each communication step whereas if the ramp type is Continuous, the
solver will update the value at each integration step. While continuous ramps
are more accurate, they may also cause the solver to slow down.
155
Suspending a task
The following example depicts how to suspend a task:
<Tasks>
<Task name="Task1" active="true" once="true" time="0.0">
<Body>
<WaitFor> B1.M > 5{kg}</WaitFor>
<Assign to="B1.F">2{kg/hr}</Assign>
</Body>
</Task>
</Tasks>
The task is suspended until the value of B1.M reaches a value greater than 5
kg. When this condition is satisfied, the task resumes and the value of B1.F is
set to 2 kg/hr.
Using an IF statement in a task

The following example depicts how to use an IF statement in a task:
<Tasks>
<Body>
<If> 'B1.M' <= 2.5{KMOL}
<Body>
<Assign to="B1.F">10{KMOL/hr}</Assign>
</Body>
</If>
</Body>
</Task>
</Tasks>
In this task, the value of variable B1.F is set to 10 KMOL/hr if the value of
B1.M is 2.5 KMOL or less when the task is carried out.
156
Using a FOR loop in a task

The following example depicts how to use a FOR loop within a task:
<Tasks>
<Body>
<For each="c" in="['METHANOL','ETHANOL','WATER']">
<Body>
<Assign to="B2.x(c)">B1.x(c)</Assign>
</Body>
</Body>
</Task>
</Tasks>
In this task, the array B2.x, which is indexed over the components
METHANOL, ETHANOL and WATER, is set to the array B1.x, which is
indexed over the same set of components.
Printing a message from a task

The following example depicts how to print a message from a task:
<Tasks>
<Task name="PrintTask" active="true" once="true" time="5.0">
<Print>
<Arg>"Starting the HEAT operation"</Arg>
</Print>
</Task>
</Tasks>
In this task, the message Starting the HEAT operation is printed at time 5.0.
157
Conditional tasks
The previous examples all depicted tasks that are invoked at a specific time.
The following example presents a task that is carried out when a specified
condition is satisfied:
<Tasks>
<Task name="ImplicitTask" active="true" once="true">
<When>B1.Z < 3.2</When>
<Body>
<Assign to="B1.K">5.8</Assign>
</Body>
</Task>
</Tasks>
This task is only invoked when the value of variable B1.Z acquires a value of
3.2 or less. When this condition is satisfied, the variable B1.K is assigned a
value of 5.8.
158
11 Units of Measure,
Physical Types and
Connection Types
This chapter describes the OOMF script commands used to manipulate units
of measure, and lists the available units of measure and physical types.
Units of Measure Commands

These commands allow you to change a variables units of measure.
Changing a Variable's Units of Measure

A variables units of measure may be changed by its UOM attribute. Note that
this only allows you to change the units of measure and not the physical type.
Any changes made at the OOMF prompt will be lost upon a subsequent EO
Reinitialization.
Input Language
variableid.UOM = {uom}

variableid
Variable name.
uom
Units of measure. These units must be of the same physical type as the
variable.
Printing Units of Measure

This command prints the specified units of measure. The type and conversion
coefficients from the internal (SI) units are shown.
11 Units of Measure, Physical Types and Connection Types
159
Input Language
PRINT UOM {uom}
PRINT UOM FOR type

uom
String of the units of measure enclosed in braces.
type
String of the physical type, which includes:

TEMPERATURE Temperature
DELTA-T
Temperature change
PRESSURE
Pressure
MOLE-FLOW
Mole flow
MASS-FLOW
Mass flow
ENTHALPY
Specific enthalpy
Dealing with Untyped Variables

Some variables and script parameters may be untyped meaning that the units
of measure are {*}. This may make it difficult to perform calculations
between untyped variables and typed variables. The ## operator may be
used to assign a unit of measure to a variable that is untyped or to de-assign
a unit of measure to a variable that is typed. See the following section for
examples.
Input Language
variableid ## {uom}

variableid
Variable name.
uom
Units of measure.
Example Units of Measure Commands

Below we change the units of measure of a temperature to degrees
Fahrenheit:
C2S.BLK.TEMP_1.UOM = {F}
To print the available units of measure for temperature, enter:
PRINT UOM FOR TEMPERATURE
Let us assume that we wish to compare the untyped variable
MSMT.BLK.T1_PLANT, whose actual value is really in degrees Fahrenheit, to
the typed variable C2S.BLK.TEMP_1. We can do this with the ## operator:
IF ( MSMT.BLK.T1_PLANT ## {F} > C2S.BLK.TEMP_1 ) THEN
ECHO "TEMPERATURE IS TOO HIGH!"
ENDIF
The ## operator treats the untyped variable as a temperature variable in
degrees Fahrenheit. This could also have been done in the reverse manner:
160
IF ( MSMT.BLK.T1_PLANT > C2S.BLK.TEMP_1 ## {*} ) THEN

ECHO "TEMPERATURE IS TOO HIGH!"
ENDIF
Here are some more examples of the result of applying the ##:
EO> ECHO 10 {*} ## {F}
10 {F}
EO> ECHO 20 {*} ## {R}
20 {R}
EO> ECHO 10 {F} ## {*}
10 {*}
EO> ECHO 20 {R} ## {*}
20 {*}
Units of Measure
The units available include the English engineering set (ENG), the
International System set (SI) and the metric engineering set (MET), as well
as other common units. OOMF supports up to 2147483648 units of measure
per physical type.. The following table contains the set of available units.
Type of Units
Code SI Set
ENG Set
MET Set
Other Units Options
ANGLE
32
RAD
DEG
DEG
AREA
SQM
SQFT
SQM
SQCM, SQIN, SQMILE,

SQMM
AREA-PRICE
54
$/SQM
$/SQFT
$/SQM
$/SQCM, $/SQIN,
$/SQMILE, $/SQMM
AREA-USAGE
62
SQM/SEC
SQFT/HR
SQM/HR
SQM/DAY, SQM/YEAR
BOND-WORK-IN 34
J/KG
KWHR/TON
KWHR/TON
KJ/KG
CAPACITY
91
KG/KG
LB/LB
KG/KG
CHROM-VEL
69
M/SEC
FT/SEC
CM/HR
COMPOSITION
MOL-FR
MOL-FR
MOL-FR
MASS-FR
CONTENTS
85
FRACTION
PERCENT
FRACTION
PPM
COST-RATE
119
$/SEC
$/HR
$/HR
$/MIN, $/DAY, $/YEAR,

K$/HR, K$/DAY, K$/YEAR,
MM$/DAY, MM$/YEAR,
$/WEEK, $/NSEC
CURRENT
114
AMP
MAMP
DELTA-T
31
C, R, DELTA-K, DELTA-F,
DELTA-C, DELTA-R
DENSITY
KG/CUM
LB/CUFT
GM/CC
LB/GAL, GM/CUM, GM/ML,

LB/BBL
DESIGN-PRES
93
N/SQM-GAUGE
PSIG
BARG
LBF/SQFT-GAUGE, KPAGAUGE, MPA-GAUGE
DIFFUSIVITY
SQM/SEC
SQFT/HR
SQCM/SEC
CS
DIMENSIONLES 44
UNITLESS
UNITLESS
UNITLESS
UNTLESS, UNITLES
DIPOLEMOMENT 45
(J*CUM)**.5
(BTU*CUFT)**.5 DEBYE
(KJ*CUM)**.5
161
Type of Units
Code SI Set
ENG Set
MET Set
ELEC-POWER
47
WATT
KW
KW
ELEC-PRICE
48
$/J
$/KWHR
$/KWHR
ENERGY
BTU
CAL
KCAL, KWHR, FT-LBF, GJ,

KJ, N-M, MJ, MCAL, GCAL,
MBTU, MMBTU, HP-HR
ENERGY-PRICE
30
$/J
$/BTU
$/CAL
$/KCAL, $/KWHR, $/FTLBF, $/GCAL, $/MMBTU,

$/HP-HR, $/MBTU, $/KJ,
$/MJ, $/GJ, $/N-M,
$/MCAL
ENERGY-VOL
117
CUM/J
BBL/BTU
BBL/MMBTU
ENTHALPY
J/KMOL
BTU/LBMOL
CAL/MOL
J/KG, BTU/LB, CAL/GM,

MBTU/LBMOL
ENTHALPY-CYC
105
WATT/CYCLE
BTU/CYCLE
CAL/CYCLE
J/CYCLE, GJ/CYCLE,
KCAL/CYCLE,
MMKCAL/CYCLE,
MMBTU/CYCLE,
MMKCAL/CYCLE,
MMBTU/CYCLE,
PCU/CYCLE,
MMPCU/CYCLE, KJ/CYCLE,
KW/CYCLE, GCAL/CYCLE
ENTHALPY-FLO
13
WATT
BTU/HR
CAL/SEC
J/SEC, GJ/HR, KCAL/HR,

MMKCAL/HR, MMBTU/HR,
MMKCAL/DAY,
MMBTU/DAY, PCU/HR,
MMPCU/HR, KJ/SEC, KW,
MW, GW, MJ/HR,
GCAL/HR, MBTU/HR,
GCAL/DAY, MCAL/HR,
KJ/HR
ENTHALPY-OPR
109
WATT/CYCLE
BTU/OP-HR
CAL/OP-SEC
J/OP-SEC, GJ/OP-HR,
KCAL/OP-HR,
MMKCAL/OP-HR,
MMBTU/OP-HR,
MMKCAL/OP-DAY,
MMBTU/OP-DAY, PCU/OPHR, MMPCU/OP-HR,
KJ/OP-SEC, KW/CYCLE,
GCAL/OP-HR, GCAL/OPDAY
ENTROPY
J/KMOL-K
BTU/LBMOL-R
CAL/MOL-K
J/KG-K, BTU/LB-R,
CAL/GM-K, MJ/KMOL-K,
KCAL/KMOL-K,
GCAL/KMOL-K,
MBTU/LBMOL-R
F-FACTOR
101
(KGCUM)**.5/SEC
(LBCUFT)**.5/HR
(GM-L)**.5/MIN (LB-GAL)**.5/MIN
FILTER-RESIS
35
1/METER
1/FT
1/METER
FISCAL
162
Other Units Options
1/CM, 1/IN
Type of Units
Code SI Set
ENG Set
MET Set
Other Units Options
FLOW
KG/SEC
LB/HR
KG/HR
LB/SEC, MLB/HR,
TONS/DAY, MCFH,
TONNE/HR, LB/DAY,
KG/DAY, TONS/HR,
KG/MIN, KG/YEAR,
GM/MIN, GM/HR, GM/DAY,
MGM/HR, GGM/HR,
MGM/DAY, GGM/DAY,
LB/MIN, MMLB/HR,
MLB/DAY, MMLB/DAY,
LB/YEAR, MLB/YEAR,
MMLB/YEAR, TONS/MIN,
MTONS/YEAR,
MMTONS/YEAR, LTONS/MIN, L-TONS/HR, LTONS/DAY, MLTONS/YEAR, MMLTONS/YEAR,
KTONNE/YEAR
FLUX
61
CUM/SQM-SEC
CUFT/SQFT-SEC
L/SQM-SEC
L/SQM-HR, GAL/SQFT-MIN
FLUX-HEAT-AR
120
WATT/SQM
BTU/HR-SQFT
CAL/SEC-SQM
J/SEC-SQM, MMBTU/HRSQFT, KW/SQM
FLUX-MOLE
121
KMOL/SQM-S
LBMOL/SQFT-HR KMOL/SQM-HR
FORCE
14
NEWTON
LBF
DYNE
FREQUENCY
28
HZ
RPM
RPM
G-RATE
92
KG/SEC-SQM
LB/HR-SQFT
KG/HR-SQM
HEAD
33
J/KG
FT-LBF/LB
M-KGF/KG
SQM/SQSEC, INCH, FT,

METER, KJ/KG, KMKGF/KG, MFT, MJ/KG,
MFT-LBF/LB, FT-HEAD,
METER-HEAD, INCH-HEAD
HEAT
53
BTU
CAL
KCAL, MMKCAL, MMBTU,

PCU, MMPCU, KJ, GJ, N-M,
MJ, MCAL, GCAL, MBTU,
KW-HR
HEAT-FLUX
80
WATT/M
BTU/HR-FT
CAL/SEC-M
J/SEC-M, MMBTU/HRFT,GCAL/HR-M,GJ/HR-M,
KCAL/HR-M, KJ/HR-M,
HEAT-FLUX-AR
95
WATT/SQM
BTU/HR-SQFT
CAL/SEC-SQM
J/SEC-SQM, MMBTU/HRSQFT
HEAT-RATE-V
122
WATT/CUM
BTU/HR-CUFT
CAL/SEC-CUM
J/SEC-CUM, MMBTU/HRCUFT, GJ/HR-CUM
LBMOL/SQFT-S,
MOL/SQCM-S
RAD/SEC, RPS, KRPM,
MMRPM, RPH
163
Type of Units
Code SI Set
ENG Set
MET Set
HEAT-TRANS-C
16
WATT/SQM-K
BTU/HR-SQFT-R
CAL/SEC-SQCM- KCAL/SEC-SQM-K,
K
KCAL/HR-SQM-K, PCU/HRSQFT-K, KW/SQM-K,
J/SEC-SQM-K, KJ/SECSQM-K, MMBTU/HR-SQFTR, KJ/SEC-SQM-C,
MJ/SEC-SQM-K, MJ/SECSQM-C, GJ/HR-SQM-K,
GJ/HR-SQM-C, KCAL/HRSQM-C, BTU/HR-SQFT-F,
MMBTU/HR-SQFT-F
INVERSE-AREA
78
1/SQM
1/SQFT
1/SQM
INVERSE-HT-C
87
SQM-K/WATT
HR-SQFT-R/BTU
SEC-SQCMK/CAL
SEC-SQM-K/KCAL, HRSQM-K/KCAL, HR-SQFTK/PCU, SQM-K/KW, SECSQM-K/J, SEC-SQM-K/KJ
INVERSE-LENG
68
1/M
1/FT
1/CM
1/IN, 1/MM
INVERSE-PRES
82
SQM/N
1/PSI
1/ATM
SQFT/LBF, 1/BAR,
1/TORR, 1/IN-WATER,
SQCM/KG, 1/MMHG,
1/KPA, 1/MM-WATER
INVERSE-TEMP
81
1/K
1/R
1/K
INVERSE-TIME
59
1/SEC
1/HR
1/HR
ITEM-PRICE
56
$/ITEM
$/ITEM
$/ITEM
LENGTH
17
METER
FT
METER
LN-INV-TIME
60
LN(1/SEC)
LN(1/HR)
LN(1/HR)
LN(1/MIN)
MASS
18
KG
LB
KG
GM, TON, MLB, TONNE, LTON, MMLB
MASS-CONC
58
KG/CUM
LB/CUFT
GM/L
GM/CC, MG/L, MG/CC
MASS-CYCL
102
KG/CYCLE
LB/CYCLE
KG/CYCLE
LB/CYCLE, MLB/CYCLE,
TONS/CYCLE, GM/CYCLE,
TONNE/CYCLE, LB/CYCLE,
KG/CYCLE, TONS/CYCLE,
TONS/CYCLE
MASS-DENSITY 38
KG/CUM
LB/CUFT
GM/CC
LB/GAL, GM/CUM, GM/ML
MASS-ENTHALP 40
J/KG
BTU/LB
CAL/GM
KCAL/KG, MMKCAL/KG,
MMBTU/LB, PCU/LB,
MMPCU/LB, KJ/KG, MJ/KG,
GCAL/KG, MBTU/LB
MASS-ENTROPY 42
J/KG-K
BTU/LB-R
CAL/GM-K
KCAL/KG-K, KJ/KG-K,
MJ/KG-K, GCAL/KG-K,
MBTU/LB-R
164
Other Units Options
1/MIN, 1/DAY, 1/YEAR

CM, IN, MU, MM, MILE,
KM, ANGSTROM, MFT
Type of Units
Code SI Set
ENG Set
MET Set
Other Units Options
MASS-FLOW
10
KG/SEC
LB/HR
KG/HR
LB/SEC, MLB/HR,
TONS/DAY, GM/SEC,
TONNE/HR, LB/DAY,
KG/DAY, TONS/YEAR,
TONS/HR, TONNE/DAY,
TONNE/YEAR, KG/MIN,
KG/YEAR, GM/MIN,
GM/HR, GM/DAY,
MGM/HR, GGM/HR,
MGM/DAY, GGM/DAY,
LB/MIN, MMLB/HR,
MLB/DAY, MMLB/DAY,
LB/YEAR, MLB/YEAR,
MMLB/YEAR, TONS/MIN,
MTONS/YEAR,
MMTONS/YEAR, LTONS/MIN, L-TONS/HR, LTONS/DAY, MLTONS/YEAR, MMLTONS/YEAR,
KTONNE/YEAR
MASS-FLUX
70
KG/SQM-S
LB/SQFT-HR
KG/SQM-HR
LB/SQFT-S, GM/SQCM-S,
KG/SQCM-S, MLB/SQFTHR, TONS/SQFT-HR, LTONS/SQFT-HR,
TONNE/SQFT-HR
MASS-HEAT-CA 49
J/KG-K
BTU/LB-R
CAL/GM-K
KCAL/GM-K, PCU/LB-K,
KJ/KG-K, BTU/LB-F
MASS-OPER
106
KG/OP-SEC
LB/OP-HR
KG/OP-HR
LB/OP-SEC, MLB/OP-HR,
TONS/OP-DAY, GM/OPSEC, TONNE/OP-HR,
LB/OP-DAY, KG/OP-DAY,
TONS/OP-YEAR,
TONS/OP-HR
MASS-PER-LEN
116
KG/M
LB/FT
KG/M
MASS-TRANS-C 66
KG/S-SQMKG/CUM
LB/HR-SQFLB/CUF
GM/S-SQCMGM/CC
MASS-VOLUME
115
CUM/KG
CUFT/LB
CC/G
MOLAR-PERM
90
KMOL/SQMSEC0PA
LBMOL/SQFT-HR- KMOL/SQM-HRPSI
ATM
LBMOL/SQFT-HR-ATM,
SCFT/SQFT-DAY-PSI,
SCFT/SQFT-HR-100PSI,
STDCC/SQCM-SEC-CMHQ,
BARRERS/CM
MOL-FLOW-LEN 89
KMOL/SEC-M
LBMOL/HR-FT
KMOL/HR-M
MOL/SEC-M, LBMOL/SECFT, LBMOL/DAY-FT,

KMOL/DAY-M, MOL/MIN-M
MOLE-CONC
KMOL/CUM
LBMOL/CUFT
MOL/CC
MOL/L, MMOL/CC, MMOL/L
64
BPD/MLBPH, CC/KG
165
Type of Units
Code SI Set
ENG Set
MET Set
Other Units Options
MOLE-CYCL
103
KMOL/CYCLE
LBMOL/CYCLE
KMOL/CYCLE
MMSCFH/CYCLE,
MMSCMH/CYCLE,
MOL/CYCLE,
LBMOL/CYCLE,
SCMH/CYCLE,
LBMOL/CYCLE,
KMOL/CYCLE,
MMSCFD/CYCLE,
SCFM/CYCLE
MOLE-DENSITY
37
KMOL/CUM
LBMOL/CUFT
MOL/CC
LBMOL/GAL, MOL/L
MOLE-ENTHALP 39
J/KMOL
BTU/LBMOL
CAL/MOL
KCAL/MOL, TCAL/MOL,
MMKCAL/MOL,
MMBTU/LBMOL,
PCU/LBMOL,
MMPCU/LBMOL, KJ/KMOL,
GJ/KMOL, MJ/KMOL,
KCAL/KMOL, GCAL/KMOL,
MBTU/LBMOL, BTU/SCF,
GCAL/MOL
MOLE-ENTROPY 41
J/KMOL-K
BTU/LBMOL-R
CAL/MOL-K
KCAL/MOL-K, KJ/KMOL-K,
TCAL/MOL-K, MJ/KMOL-K,
KCAL/KMOL-K,
GCAL/KMOL-K,
MBTU/LBMOL-R
MOLE-FLOW
11
KMOL/SEC
LBMOL/HR
KMOL/HR
MMSCFH, MMSCMH,
MOL/SEC, LBMOL/SEC,
SCMH, LBMOL/DAY,
KMOL/DAY, MMSCFD,
MSCFD, SCFM, MOL/MIN,
KMOL/KHR, KMOL/MHR,
MOL/HR, MMOL/HR,
MLBMOL/HR, LBMOL/MHR,
LBMOL/MMHR, MSCFM,
SCFH, MSCFH, SCFD,
NCMH, NCMD, KMOL/MIN,
KMOL/WEEK,
KMOL/MONTH,
KMOL/YEAR, KMOL/OPERYEAR
MOLE-FLUX
96
KMOL/SQM-S
LBMOL/SQFT-HR KMOL/SQM-HR
LBMOL/SQFT-S,
MOL/SQCM-S
MOLE-HEAT-CA 15
J/KMOL-K
BTU/LBMOL-R
CAL/MOL-K
KCAL/MOL-K, TCAL/MOLK, PCU/LBMOL-K,

KJ/KMOL-K, BTU/LBMOL-F
MOLE-OPER
107
KMOL/OP-SEC
LBMOL/OP-HR
KMOL/OP-HR
MMSCF/CYCLE-HR,
MMSCM/CYCLE-HR,
MOL/OP-SEC, LBMOL/OPSEC, SCM/CYCLE-HR,
LBMOL/OP-DAY,
KMOL/OP-DAY,
MMSCF/CYCLE-DAY,
SCF/CYCLE-MIN
MOLE-PRICE
125
$/KMOL
$/LBMOL
$/MOL
166
Type of Units
Code SI Set
ENG Set
MET Set
Other Units Options
MOLE-RXN-RAT 123
KMOL/CUM-S
LBMOL/CUFT-HR
KMOL/CUM-HR
MOL/CC-S
MOL-RXN-RATW 124
KMOL/KG-S
LBMOL/LB-HR
KMOL/KG-HR
MOL/GM-S
MOLE-VOLUME
43
CUM/KMOL
CUFT/LBMOL
CC/MOL
ML/MOL, BBL/MSCF
MOLES
51
KMOL
LBMOL
KMOL
SCM, MMSCF, MSCF,

MMSCM, MOL, SCF
MOM-INERTIA
112
KG-SQM
LB-SQFT
KG-SQM
GM-SQCM, LB-SQIN
NUM-CON-RATE 77
NO/CUM-SEC
NO/CUFT-SEC
NO/L-SEC
NO/CC-SEC, NO/CUMSEC, NO/CUM-MIN,

NO/CUFT-MIN, NO/L-MIN,
NO/CC-MIN, NO/CUM-HR,
NO/CUFT-HR, NO/L-HR,
NO/CC-HR
NUM-CONC
NO/CUM
NO/CUFT
NO/L
NO/CC, 1E6/CC
57
PACK-FACTOR
76
1/M
1/FT
1/M
1/CM, 1/IN,1/MM
PDROP
75
N/SQM
PSI
ATM
LBF/SQFT, BAR, TORR, INWATER, KG/SQCM, MMHG,

KPA, MM-WATER, MBAR,
IN-WATER-60F, IN-HG,
LB/FT-SQSEC, KG/MSQSEC, PA, MPA, PSIA,
MM-WATER-60F,
PDROP-PER-HT
74
N/CUM
IN-WATER/FT
MM-WATER/M
MBAR/M, MMHG/FT,
TORR/M, MMHG/M
PDROP-PER-LEN 94
PA/M
PSI/FT
KGF/SQCM-KM
KPA/1000-M, PSI/1000FT, BAR/1000-M, KPA/M,

PA/1000-M, PA/CM,
PA/KM, PSI/100-FT,
n/sqm-1000ft
POP-DENSITY
86
NO/M/CUM
NO/FT/CUFT
NO/M/L
NO/MM/L, NO/MU/CC,
NO/IN/CUIN
POWER
19
WATT
HP
KW
BTU/HR, CAL/SEC, FTLBF/SEC, MW, GW, MJ/HR,

KCAL/HR, GCAL/HR,
MMBTU/HR, MBTU/HR,
MHP
POWERVOLUME
65
WATT/CUM
HP/CUFT
KW/L
KW/CUM
PRESSURE
20
N/SQM
PSIA
ATM
LBF/SQFT, BAR, TORR, INWATER, KG/SQCM, MMHG,

KPA, MM-WATER, MBAR,
PSIG, ATMG, BARG,
KG/SQCMG, LB/FTSQSEC, KG/M-SQSEC, PA,
MPA, PAG, KPAG, MPAG,
MBARG, IN-HG, MMHGVAC, IN-HG-VAC, INWATER-60F, IN-WATERVAC, IN-WATER-60F-VAC,
IN-WATER-G, IN-WATER60F-G, MM-WATER-G,
MM-WATER-60F-G, PSI,
MM-WATER-60F
167
Type of Units
Code SI Set
ENG Set
MET Set
RHO-VSQRD
110
KG/M-SQSEC
LB/FT-SQSEC
KG/M-SQSEC
SIEMENS-M
118
SIEMENS/M
SIEMENS/FT
SIEMENS/M
SIEMENS/CM
SOLUPARAM
46
(J/CUM)**.5
(BTU/CUFT)**.5
(CAL/CC)**.5
(KCAL/CUM)**.5,
(KJ/CUM)**.5,
(CAL/ML)**0.5
SOLUTE-PERM
72
SQM/M-S
SQFT/FT-HR
SQM/M-HR
SQCM/CM-S, SQFT/FT-S
SOLVENT-PERM 71
KG/SQM-S-PA
LB/SQFT-HR-ATM KG/SQM-HRATM
SOUND-LEVEL
111
DECIBELS
DECIBELS
DECIBELS
SPEC-FLT-RES
36
METER/KG
FT/LB
METER/KG
SPECIFICAREA
67
SQM/CUM
SQFT/CUFT
SQCM/CC
SURFACE-TENS 21
N/M
DYNE/CM
DYNE/CM
TEMP-VOLUME
83
CUM-K/KMOL
CUFT-R/LBMOL
CC-K/MOL
TEMPERATURE
22
C, R
THERMAL-COND 23
WATT/M-K
BTU-FT/HRSQFT-R
KCAL-M/HRSQM-K
BTU-IN/HR-SQFT-R, CCM/SEC-SQCM-K, CALCM/SEC-SQCM-K,

BTU/HR-FT-R, KCAL/HRM-K, J/SEC-M-K, KW/M-K,
BTU-FT/HR-SQFT-F, BTUIN/HR-SQFT-F, BTU/HRFT-F
TIME
24
SEC
HR
HR
DAY, MIN, YEAR, MONTH,

WEEK, NSEC
UA
50
J/SEC-K
BTU/HR-R
CAL/SEC-K
KJ/SEC-K, KCAL/SEC-K,
KCAL/HR-K, BTU/HR-F
UNIT-PRICE
29
$/KG
$/LB
$/KG
$/TON, $/MLB, $/GM, $/LTON, $/TONNE, $/MMLB
USR-DUMMY0
90
USR-DUMMY1
91
USR-DUMMY2
92
USR-DUMMY3
93
USR-DUMMY4
94
USR-DUMMY5
95
USR-DUMMY6
96
USR-DUMMY7
97
USR-DUMMY8
98
USR-DUMMY9
99
VELOCITY
25
M/SEC
FT/SEC
M/SEC
MILE/HR, KM/HR, FT/MIN,

MM/DAY, MM/HR,
MM/DAY30, IN/DAY
SQM/SEC
GPM/FT
SQCM/SEC
SQM/HR, SQFT/MIN
VFLOW-LENGTH 84
168
Other Units Options
GM/SQCM-S-ATM,
GM/SQCM-S-PA
CM/GM
LBF/FT, MN/M
Type of Units
Code SI Set
ENG Set
MET Set
Other Units Options
VFLOW-RPM
100
CUM/SEC/RPM
CUFT/HR/RPM
L/MIN/RPM
GAL/MIN/RPM,
GAL/HR/RPM,
BBL/DAY/RPM,
CUM/HR/RPM,
CUFT/MIN/RPM,
BBL/HR/RPM,
CUFT/SEC/RPM,
CUM/DAY/RPM,
CUM/YEAR/RPM,
L/HR/RPM,
KBBL/DAY/RPM,
MMCUFT/HR/RPM,
MMCUFT/DAY/RPM,
MCUFT/DAY/RPM,
L/SEC/RPM, L/DAY/RPM,
CUM/MIN/RPM
VISCOSITY
26
N-SEC/SQM
CP
CP
LB/FT-HR, MN-SEC/SQM,
P, GM/SEC-CM, DYNSEC/SQCM, PA-SEC
VOL-ENTHALPY
88
J/CUM
BTU/CUFT
CAL/CC
KCAL/CUM, KJ/CUM,
MMBTU/BBL
VOL-HEAT-CAP
79
J/CUM-K
BTU/CUFT-R
CAL/CC-K
KCAL/CUM-K, KJ/CUM-K,
BTU/CUFT-F
VOL-HTR-COEF
126
WATT/CUM-K
BTU/HR-CUFT-R
CAL/SEC-CC-K
WATT/CUM-C, WATT/CUMF, KW/CUM-K, KW/CUM-C,

BTU/HR-CUFT-F
VOLTAGE
113
VOLT
KVOLT
VOLUME
27
CUM
CUFT
CUIN, GAL, BBL, CC,

KCUM, MCUM, MCUFT,
MMCUFT, ML, KL, MML,
MGAL, MMGAL, UKGAL,
MUKGAL, MMUKGAL,
MBBL, MMBBL, KBBL,
CUYD
VOLUME-CYCL
104
CUM/CYCLE
CUFT/CYCLE
L/CYCLE
GAL/CYCLE, GAL/CYCLE,
BBL/CYCLE, CUM/CYCLE,
CUFT/CYCLE, BBL/CYCLE,
CUFT/CYCLE, CUM/CYCLE,
CUM/CYCLE, L/CYCLE,
KBBL/CYCLE,
MMCUFT/CYCLE
169
Type of Units
Code SI Set
ENG Set
MET Set
Other Units Options
VOLUME-FLOW
12
CUM/SEC
CUFT/HR
L/MIN
GAL/MIN, GAL/HR,
BBL/DAY, CUM/HR,
CUFT/MIN, BBL/HR,
CUFT/SEC, CUM/DAY,
CUM/YEAR, L/HR,
KBBL/DAY, MMCUFT/HR,
MMCUFT/DAY,
MCUFT/DAY, L/SEC,
L/DAY, CUM/MIN,
KCUM/SEC, KCUM/HR,
KCUM/DAY, MCUM/SEC,
MCUM/HR, MCUM/DAY,
ACFM, CUFT/DAY,
MCUFT/MIN, MCUFT/HR,
MMCUFT/HR, MGAL/MIN,
MMGAL/MIN, MGAL/HR,
MMGAL/HR, MBBL/HR,
MMBBL/HR, MBBL/DAY,
MMBBL/DAY
VOLUME-OPER
108
CUM/OP-SEC
CUFT/OP-HR
L/OP-MIN
GAL/OP-MIN, GAL/OP-HR,
BBL/OP-DAY, CUM/OP-HR,
CUFT/OP-MIN, BBL/OPHR, CUFT/OP-SEC,
CUM/OP-DAY, CUM/OPYEAR, L/OP-HR, KBBL/OPDAY, MMCUFT/OP-HR
VOLUME-PRICE
55
$/CUM
$/CUFT
$/L
$/CC, $/BBL, $/CUYD,

$/KL, $/CUIN, $/ML,
$/MML, $/GAL, $/MGAL,
$/MMGAL, $/UKGAL,
$/MUKGAL, $/MMUKGAL,
$/KBBL, $/MCUFT,
$/MMCUFT, $/KCUM,
$/MCUM, $/MBBL,
$/MMBBL
CUM/SEC
CUFT/HR
L/HR
L/DAY, L/YEAR, CUM/HR,

CUM/DAY, CUM/YEAR
VOLUME-USAGE 63
WATER-RATE
73
KG/J
LB/HP-HR
KG/KW-HR
WORK
52
HP-HR
KW-HR
FT-LBF, KJ, N-M, MJ,

MBTU, MMBTU, MCAL,
GCAL
Most of the above units are self-explanatory. Units and unit parts that may
require explanation follow:
170
Units
Description
MM
Used as a prefix meaning million before many units, such as

MMBTU = million BTU.
Used as a prefix meaning thousand with English units, such as

Mlb (thousand pounds) and Mscf (thousand standard cubic feet).
With metric/SI units, the M prefix represents Mega except with
millimeters and millinewtons.
SQ
Used as a prefix meaning squared, as in SQFT (square feet).
Units
Description
CU
Used as a prefix meaning cubed, as in CUM (cubic meters). The

common abbreviation CC is used for cubic centimeters.
Used as a suffix on pressure units such as ATMG, BARG, PSIG,

KG/SQCMG, and IN-WATER-G. The G indicates gauge pressure
(pressure above standard atmospheric pressure).
VAC
Used as a suffix on pressure units such as IN-WATER-VAC,

indicating vacuum pressure (pressure below standard
atmospheric pressure). Vacuum units are thus exactly negative of
the corresponding gauge pressure units.
IN-WATER,
IN-WATER-60F
These units represent pressure in inches of water. IN-WATER is

based on the density of water of 1 g/cc. IN-WATER-60F is based
on the density of water at 60 F.
MMKCAL
Million kcal (same as GCAL)
MN
MilliNewtons
MLB
Thousand lbs
NCM
Normal cubic meters (same as standard cubic meters).
NCMH
Normal cubic meters per hour
NCMD
Normal cubic meters per day
PCU
Pound centrigrade unit
PSIA
Absolute pounds per square inch. PSI is a synonym for PSIA.
SCF
Standard cubic feet. Standard conditions for all standard cubic

feet are ideal gas at 14.696 psi and 60 degrees F.
SCFH
Standard cubic feet per hour
SCFD
Standard cubic feet per day
SCM
Standard cubic meters. Standard conditions for all standard cubic

meters are ideal gas at 1 atm and 0 degrees C.
SCMH
Standard cubic meters per hour
TCAL
Thermodynamic calorie, equal to 4.184 Joules. The standard

calorie represented by CAL is the International Steam Table
calorie equal to 4.1868 Joules.
TONNE
Metric ton (1000 kg)
Physical Types
Every model variable has a physical dimensionality (physical type) that is
assigned by the model developer. Each physical type has a corresponding
integer code.
Type Code
Physical Type
UNTYPED
AREA (SQM)
COMPOSITION
MASS-DENSITY (KG/CUM)
DIFFUSIVITY (SQM/SEC)
ENERGY (J)
ENTHALPY (J/KMOL)
171
172
Type Code
Physical Type
ENTROPY (J/KMOL-K)
FISCAL ($)
FLOW (KG/SEC)
10
MASS-FLOW (KG/SEC)
11
MOLE-FLOW (KMOL/SEC)
12
VOLUME-FLOW (CUM/SEC)
13
ENTHALPY-FLO (WATT)
14
FORCE (N)
15
MOLE-HEAT-CA (J/KMOL-K)
16
HEAT-TRANS-C (WATT/SQM-K)
17
LENGTH (M)
18
MASS (KG)
19
POWER (WATT)
20
PRESSURE (N/SQM)
21
SURFACE-TENS (N/M)
22
TEMPERATURE (K)
23
THERMAL-COND (WATT/M-K)
24
TIME (SEC)
25
VELOCITY (M/SEC)
26
VISCOSITY (N-SEC/SQM)
27
VOLUME (CUM)
28
FREQUENCY (HZ)
29
UNIT-PRICE ($/KG)
30
ENERGY-PRICE ($/J)
31
DELTA-T (DELTA-K)
32
ANGLE (RAD)
33
HEAD (J/KG)
34
BOND-WORK-IN (J/KG)
35
FILTER-RESIS (1/M)
36
SPEC-FLT-RES (M/KG)
37
MOLE-DENSITY (KMOL/CUM)
38
MASS-DENSITY (KG/CUM)
39
MOLE-ENTHALPY (J/KMOL)
40
MASS-ENTHALPY (J/kg))
41
MOLE-ENTROPY (J/KMOL/K)
42
MASS-ENTROPY (J/KG-K)
43
MOLE-VOLUME (CUM/KMOL)
44
DIMENSIONLESS
45
DIPOLEMOMENT (J*CUM)**0.5
46
SOLUPARAM (J/CUM)**0.5
47
ELEC-POWER (WATT)
48
ELEC-PRICE ($/J)
49
MASS-HEAT-CA (J/KG-/K)
Type Code
Physical Type
50
UA (J/SEC-K)
51
MOLES (KMOL)
52
WORK (J)
53
HEAT (J)
54
AREA-PRICE ($/SQM)
55
VOLUME-PRICE ($/CUM)
56
ITEM-PRICE ($/ITEM)
57
NUM-CONC (NO/CUM)
58
MASS-CONC (KG/CUM)
59
INVERSE-TIME (1/SEC)
60
LN-INV-TIME (LN(1/SEC))
61
FLUX (CUM/SQM-SEC)
62
AREA-USAGE (SQM/SEC)
63
VOLUME-USAGE (CUM/SEC)
64
MOLE-CONC (KMOL/CUM)
65
POWER-VOLUME (WATT/CUM)
66
MASS-TRANS-C (KG/S-SQM-KG/CUM)
67
SPECIFICAREA (SQM/CUM)
68
INVERSE-LENG (1/M)
69
CHROM-VELOCITY (M/SEC)
70
MASS-FLUX (KG/SQM-SEC)
71
SOLVENT-PERM (KG/SQM-S-PA)
72
SOLUTE-PERM (SQM/M-S)
73
WATER-RATE (KG/J)
74
PDROP-PER-HT (N/CUM)
75
PDROP (N/SQM)
76
PACK-FACTOR (1/M)
77
NUM-CON-RATE (NO/CUM-SEC)
78
INVERSE-AREA (1/SQM)
79
VOL-HEAT-CAP (J/CUM-K)
80
HEAT-FLUX (WATT/M)
81
INVERSE-TEMP (1/K)
82
INVERSE-PRES (SQM/N)
83
TEMP-VOLUME (CUM-K/KMOL)
84
VFLOW-LENGTH (SQM/SEC)
85
CONTENTS (FRACTION)
86
POP-DENSITY (NO/M/CUM)
87
INVERSE-HT-C (SQM-K/WATT)
88
VOL-ENTHALPY (J/CUM)
89
MOLE-FLOW-LEN (KMOL/SEC-M)
90
USR-DUMMY0
91
USR-DUMMY1
92
USR-DUMMY2
173
174
Type Code
Physical Type
93
USR-DUMMY3
94
USR-DUMMY4
95
USR-DUMMY5
96
USR-DUMMY6
97
USR-DUMMY7
98
USR-DUMMY8
99
USR-DUMMY9
100
VFLOW-RPM (CUM/SEC/RPM)
101
F-FACTOR (KG-CUM)**0.5/SEC
102
MASS-CYCL (KG/CYCLE)
103
MOLE-CYCL (MOL/CYCLE)
104
VOLUME-CYCL (L/CYCLE)
105
ENTHALPY-CYC (J/CYCLE)
106
MASS-OPER (KG/OP-SEC)
107
MOLE-OPER (MOL/OP-SEC)
108
VOLUME-OPER (L/OP-MIN)
109
ENTHALPY-OPR (J/OP-SEC)
110
RHO-VSQRD (KG/M-SQSEC)
111
SOUND-LEVEL (DECIBELS)
112
MOM-INERTIA
113
VOLTAGE (VOLT)
114
CURRENT (AMP)
115
MASS-VOLUME (CUM/KG)
116
MASS-PER-LEN
117
ENERGY-VOL
118
SIEMENS-M
119
COST-RATE
120
FLUX-HEAT-AR
121
FLUX-MOLE
122
HEAT-RATE-V
123
MOLE-RXN-RATE
124
MOL-RXN-RATW
125
MOLE-PRICE
126
VOL-HTR-COEF
Connection Types
Connection types can be specified for block variables. Connection types are
used to create custom connections between block ports.
In OOMF, every physical type has a corresponding connection type with the
same name. Additionally, there are several special connection types which are
listed in the following table.
Type Code
Connection Type
AROM-FACTOR
ANILINE-PT
API
AROM-BY-VOL
BASIC-N2-CONT
BENZ-BY-VOL
CON-11
CON-CLEAR
CONRAD-CARBON
10
CETANE-IDX
11
DON-11
12
DON-CLEAR
13
EX-BENZ-EMISS
14
WATSON-K
15
LUMIN-NO
16
MON-11
17
MON-CLEAR
18
NPLUS2A-BY-VOL
19
NAPH-VOL-PCT
20
NOX-EMISS
21
OLEF-VOL-PCT
22
O2-WT-PCT
23
POUR-PT
24
POUR-PT-IDX
25
RON-11
26
RON-CLEAR
27
RVP-IDX
28
REID-VAP-PRES
29
SP-GRAVITY
30
SP-VOLUME
31
SULF-WT-PCT
32
TOXIC-EMISS
33
VANADIUM-BY-WT
175
Type Code
Connection Type
34
VISCO-INDEX
35
VOC-EMISS
36
AROM-BY-WT
37
ASPHALT-CONT
38
C5-BY-WT
39
CLOUD-PT
40
COPPER-CONT
41
IRON-CONT
42
D2887-X-PCT
43
D86-X-PCT
44
DRIVE-IDX
45
FLASH-PT
46
FREEZE-PT
47
NPLUSA-BY-VOL
48
NAPH-WT-PCT
49
NICKEL-CONT
50
N2-CONT
51
OLEF-WT-PCT
52
PARAF-VOL-PCT
53
PARAF-WT-PCT
54
REFRACT-INDEX
55
SMOKE-PT
56
SODIUM-CONT
57
STD-LIQ-DEN
58
SULFUR-MCAP-WT
59
TBP-X-PCT
60
WAX-CONT
61
X-PCT-EVAP
If unspecified, a model variable is given a default connection type of

UNTYPED. Additionally, if a variable has a physical type specified and its
connection type is UNTYPED, its connection type will be set to that
corresponding to its physical type when the block that owns the variable is
initialized.
176
Connection Type Commands

These commands allow you to change a variables connection type.
Changing a Variable's Connection Type

A variables connection type may be changed by its conn_type attribute.
Input Language
variableid.conn_type = {conn_type}

variableid
Variable name.
Conn_type
Connection type. The connection type must be one from table presented
earlier.
177
178
12 Global Structures
This chapter describes the use of global structures in OOMF.
Overview
Variable data within any model in OOMF can serve as a global data structure
that can be used within another model in OOMF. Models that contain global
structure data can be instantiated and deleted in a manner similar to any
other OOMF model. In order to account for the possibility that the model with
global structure data may move around in the matrix after it is first
instantiated since a hierarchy container or another intermediate block may
expand or contract and to account for the possibility that the global structure
may be deleted by a user without deleting the model that uses the structure,
a generic OOMF model has the capability to restructure itself in place, i.e.,
starting at the position in the matrix where it was first instantiated.
Since a generic OOMF model can now restructure itself after it is placed in the
matrix, it can be parameterized by another model that contains global
structure data. For example, a model that wishes to be a consumer of
external global data within another model should have a named block
attribute or parameter that can later be associated with an instance of the
model that contains the global data. This mechanism will allow the model
that is consumer of a global structure to be able to instantiate itself in the
matrix even if the global structure has not been placed yet. When the model
that uses an external global structure, referred to as AModel, is first
instantiated, with instance name B2, it can build all its variables, including
dummy variables that are similar to those contained in the structure
instance, and the associated equations. Later, when a model with global
structure data, referred to as AStruct, is instantiated, with instance name
B1, and the global structure parameter of B2 is assigned to be B1, B2
will restructure itself in place, i.e., the dummy (redundant) variables
and incorrect rows in B2 will get eliminated and a new set of variables and
equations that now refer to the global structure data from B1 will be
created. The choice of what B2 adds to the matrix initially when the global
structure instance is not present and later when it restructures is completely
up to the model writer. The only requirement is that B2 is square before
and after the global structure instance is assigned.
OOMFs default implementation of the abstract class AMFEOBlock,
AMFEOBlockImpl, provides all the necessary functionality. All OOMF
179
compatible models except the Aspen Plus EO models derive from this class
and inherit this new functionality. Hence, any OOMF model that derives from
AMFEOBlockImpl can choose to act as a global structure, a consumer of a
global structure, or both (if necessary). The implementation has the
following restrictions:
The instance of the model (AStruct) with global structure data must be
placed in the root container, i.e., outside hierarchy containers.
The name of the global structure parameter in the model (AModel) that is
a consumer of the global structure data must be different from the names
of the 13 default OOMF model parameters
"DERIV_METHOD", "INCLUDED", "MODEL", "PERT", "DIAG_LEVEL",
"NLRATIODEV", "NLRATIO", "ZEROTOL", "MOVE", "MOVEAMOUNT",
"SPARSITY_FILE", "SPARSITY_GEN", and "SPARSITY_TYPE".
These restrictions can be changed, if necessary. Of course, an individual

model writer can override all the methods in the default AMFEOBlock
implementation.
As mentioned earlier, model writers will have to ensure the following:
A model that can be used as a global structure must override the

CreateInstance method that allows the creation of a copy of the global
structure in an independent container (ORION / SM solution usage).
A model that can be used as a global structure must set the structure data
variable start offset. This is an offset from the model's variable start
index. It must also set the number of consecutive structure data
variables.
A model that uses a global structure must set the generic type of the
global structure that it can consume. This is used for type checking when
the model is parameterized by the global structure instance.
Example
An example of how the global structure data within AStruct can be used within a
generic OOMF model AModel is presented in the example script that follows:
load lib "amodel"
load lib "astruct"
load lib "pltcon"
DEFINE SUPERPLANT myplant
END myplant
add block hier as myplant
add block b1 as astruct
push scope hier
add block b2 as amodel
add block PLT as pltcon
print var
print eqn
print jac
//Assign the global structure parameter name in block B2 to be

the global structure instance named B1
B2.MYSTRUCT="B1"
print var
print eqn
print jac
180
reset scope
print var
print eqn
print jac
solver dmo
dmo.rescvg=1e-8
solve
print var
push scope hier

//Assign the global structure
the global structure instance
B3.MYSTRUCT="B1"
reset scope
//Assign the global structure
the global structure instance
B4.MYSTRUCT="B1"
parameter name in block B3 to be

named B1
parameter name in block B4 to be

named B1
print jac
//Increase the size of the global structure data in block B1

B1.NVAR=10
print var
print eqn
print jac
solve
print var
add block PLT2 as pltcon

add conn conn1, [PLT2.BLK.VAR_1, HIER.PLT.BLK.VAR_1]
print var
print eqn
print jac
solve
print var
//Decrease the size of the global structure data in block b1

B1.NVAR=1
print var
print eqn
print jac
solve
print var
//Add another instance of the global structure model

add block b5 as astruct
push scope hier
//Reset b2's global structure instance to be "b5"
b2.mystruct="B5"
print jac
reset scope
B5.ASTRUCT.VAR_1=8
solve
print var
blocks
//Reset b4's global structure instance to be nothing
b4.mystruct=""
print var
print eqn
print jac
solve
print var
181
182
13 Aspen Properties Data
This chapter describes the commands that let you use Aspen Properties data
in an OOMF simulation.
Loading Properties Data

This command initializes Aspen Properties and loads the specified Aspen
Properties file.
Input Language
LOAD PROP DATA filename

filename
Aspen Properties file that contains the properties data. This file
usually has the extension aprpdf or appdf.
Freeing Properties Data

This command initializes Aspen Properties and frees the specified Aspen
Properties file.
Input Language
FREE PROP DATA filename

filename
Aspen Properties file to be freed. This file usually has the

extension aprpdf or appdf.
Swapping Properties Data

This command swaps the current property methods and option sets with
those specified. The specified option sets and methods should be available in
the Aspen Properties file that is currently loaded.
183
Input Language
SWAP PROPERTY list

list
List of property methods and option sets to be swapped with the

current ones.
Examples Of Properties Commands

To load the Aspen Properties file "C:\Aspen Catref 12.1\apinit\catref2.aprpdf",
enter:
LOAD PROP DATA "C:\Aspen Catref 12.1\apinit\catref2.aprpdf"
To free the Aspen Properties file "C:\Aspen Catref 12.1\apinit\catref2.aprpdf,
enter:
FREE PROP DATA "C:\Aspen Catref 12.1\apinit\catref2.aprpdf"
To swap the current option set with SRK, the current Henry ID with HC-1, the
current free water option with RTOSTM, the current integerTrue value with 1
and the current integerSolu value with 2, enter:
SWAP PROP OpsetName:SRK, HenryID:HC-1, ChemID:C-1,
FreeWater:RTOSTM, integerTrue:1, integerSolu:2
184
14 Aspen Plus Extensions
Aspen Plus embeds OOMF and extends its equation oriented capabilities. The
following sections explain how to use OOMF and these extensions from within
the Aspen Plus user interface or the engine.

You can enter script commands interactively into the OOMF kernel. This is
done in two ways:
From the Aspen Plus user interface

o
From the Control Panel, set the strategy to Sequential Modular and
solve the problem. Then switch the strategy to Equation Oriented. This
will synchronize the EO strategy. Commands may be typed at the
Command Line near the bottom of the Control Panel.
From IAP
o
Add the SIMULATE INTERACTIVE = YES command to the INP file.

From the Simulation Engine window, enter ASPEN filename. When
the A+ prompt appears enter GO to solve the Sequential Modular
strategy. When complete, enter SYNCEO to synchronize the Equation
Oriented strategy. Then enter the TOEO command to switch to the EO
strategy. The EO prompt appears. At this point, the EO plant is built
and all blocks, connections, specification groups, etc. are instantiated.
See Also
Standard OOMF - Using the Interactive Prompt
185
Defining and Executing Scripts

Defining Scripts
Scripts may be defined in the following ways:
An external file that may be created with a standard text editor. The
extension of the file should be EBS.
Scripts may be defined within the Aspen Plus user interface as a LOCAL
script or a GLOBAL script. In the Aspen Plus user interface there is an
object manager for each of these at the flowsheet level and at each
hierarchy level. When you define a script in this manner, you type your
script commands into a text box in the Aspen Plus user interface.
Do not enter more than 64 characters per line, and do not begin lines
with more than 3 spaces within the Aspen Plus user interface. The scripts
are saved with the rest of the flowsheet input.
Local scripts are available only within the scope where they are defined.
Global scripts are available everywhere, regardless of scope. More
information on hierarchies and scope may be found in chapter.
Scripts may be defined in the INP (input language) file. Input in the INP
file must skip column one and may go to column 80. The script follows a
line with a GLOBALSCRIPT or LOCALSCRIPT keyword and the script name;
this line begins in column one. Use the following format:
GLOBALSCRIPT scriptname
SCRIPT 'first script line' / 'second script line' / &
'third script line' / &
'fourth script line' / 'fifth script line'
For more information on using scripts in the INP file, see Chapter 48 of
the Aspen Plus Input Language Guide.
Executing Scripts
Scripts may be executed in a number of ways:
186
By manually executing the script from the command line or from another
script. This may be done with the INVOKE, INVOKELOCAL and
INVOKEGLOBAL commands.
By associating the script with a block or the flowsheet. This is done by

assigning the script as a method attached to the block. A method is a
function that is called at specific times during the execution sequence of
OOMF. The following methods are available:
INIT
This method is executed when the block is created and is available for
all blocks except hierarchies.
PRESOLVE
This method is executed before a solve is started. It can be very useful

for defining run-specific information, such as process data.
POSTSOLVE
This method is executed after a solve is completed. This is useful for

checking the results of the run and writing customized reports.
MIXSOLVE
This method is executed before solving the EO hierarchy block it is

attached to within a Mixed Mode run. Only available for hierarchies
within Aspen Plus.
The script that is assigned as the block method can be an external file, a
local script, or a global script. You can also manually execute a blocks
script method with the INVOKE command.
More on invoking scripts may be found in Invoke Commands.
See Also
Standard OOMF - Defining and Executing Scripts
Command Summary
In addition to the generic OOMF commands mentioned in previous sections,
the following commands are available within the Aspen Plus environment.
EO Commands
Command
Purpose
APPLY SOLVER SETTINGS
Apply the solver settings from the input file to the current mode.
DISABLE HXFLUX
Disable all Hxflux connections in the local scope.
DISABLE STREAM
Disable all streams in the local scope.
ENABLE HXFLUX
Enable all Hxflux connections in the local scope.
ENABLE STREAM
Enable all streams in the local scope.
HXFLUX
Turn on/off Aspen Plus Hxflux connections
INVOKEGLOBAL
Execute commands in a GLOBALSCRIPT
INVOKELOCAL
Execute commands in a LOCALSCRIPT from block script
PRINT COMPONENT LIST
Print the list of components in a component group.
RECOVER
Recover from a bad EO solution by calling every block's pre and postsolve steps
REPORT ALL
Print a report for blocks and streams
REPORT APBLK
Report on overall work requirements for blocks and thermo
REPORT FLOWSHEET
Make an Aspen Plus flowsheet report
REPORT FULL
Print a full Aspen Plus report for the current set of blocks and streams
REPORT STREAMS
Print an Aspen Plus stream report
SETCOMPLIST
Set the list of components in a component group to a variable.
STREAMS
Turn on/off AspenPlus stream connections
SYNCHRONIZE
Synchronize an Aspen Plus block with its block bead
UPDATE BLEND
Update the crude assays
UPDATE PDF
Update the AspenPlus PDF
See Also
Standard OOMF - Command Summary
187
Invoke Commands
These commands allow you to call, or invoke, other scripts. These may be
scripts that have been entered in the Aspen Plus user interface or external
files.
Invoking a Local Script

A local script may be invoked with this command. Local scripts are available
only within the scope where they are defined.
Input Language
INVOKELOCAL scriptid, arg1, arg2,

scriptid
Name of a local script to execute.
arg1,
arg2
Invoking a Global Script

A global script may be invoked with this command. Global scripts are
available everywhere, regardless of the scope where they are defined.
Input Language
INVOKEGLOBAL scriptid, arg1, arg2,

scriptid
Name of a global script to execute.
arg1,
arg2
See Also
Standard OOMF - Invoke Commands
188
Miscellaneous Commands
Specific to Aspen Plus
Updating Crude Blends
This command is used to update the crude assays.
Input Language
UPDATE BLEND
Updating the PDF

The PDF is a binary file that contains all the problem information. This file is
written by Aspen Plus with a filename extension of APPDF. You can update
this file with this command.
Input Language
UPDATE PDF
Hierarchies
Aspen Plus has the following extensions that make it easier for a user to
create hierarchies.
See Also
Standard OOMF - Hierarchies
How are Hierarchies Created?

Hierarchies are created through the Aspen Plus user interface or input
language by placing a hierarchy block onto the flowsheet. When you double
click on the hierarchy, a flowsheet diagram of the hierarchy appears. Blocks
may be placed into the hierarchy in the same manner as at the flowsheet
level.
Hierarchy Input
Hierarchies have sets of input that are similar to what can be defined for an
entire flowsheet. These include:
Property methods.
Streams.
Blocks.
Convergence options, such as EO solver parameters.
189
Flowsheeting Options, such as measurement blocks.
EO Configuration, such as EO input, Objective functions, Spec Groups, and

Connections.
The type of input that may be entered for an EO configuration item is limited
by the scope.
Stream Commands
Adding and Removing Stream Connections
This command controls all the Aspen Plus stream connections within the
current scope.
Input Language
STREAMS status

status
Stream connection status. ALL indicates that all stream connections in the
current scope are to be added to the problem. NONE indicates that all the
stream connections in the current scope are to be removed from the
problem (they will not appear on the Inactive connection list). With no
argument, all the active stream connections in the current scope are
printed to the current report device.
Disabling Stream Connections

This command is used to disable all Aspen Plus stream connections in the
current scope.
When the stream connections are disabled, Spec Management automatically
reprocesses all the Connections and Spec Groups to ensure that the problem
remains square. (The Status on the GUI is not updated until an Incremental
Build or Solve is performed.)
Input Language
DISABLE STREAMS
Enabling Stream Connections

This command is used to enable all Aspen Plus stream connections in the
current scope. It does the reverse of the DISABLE STREAMS command
discussed in the previous section.
Input Language
ENABLE STREAMS
190
Examples of Stream Commands

To fix stream C2SD in block C2S:
C2S.C2SD.STR.SPEC = CONST
See Also
Standard OOMF - Stream Commands
HXFlux Commands
These commands are used to control the connections configured for HXFlux
blocks. These commands only affect the HXFlux connections defined through
the blocks input form and not connections defined through EO
Configuration | Connection forms.
Controlling HXFlux Connections

This command is used to view, remove and restore previously removed
HXFlux temperature connections within the current scope.
When the status of an HXFlux connection is changed, Spec Management
automatically reprocesses all the Connections and Spec Groups to ensure that
the problem remains square. (The Status on the GUI is not updated until an
Incremental Build or Solve is performed.)
Input Language
HXFLUX status

status
HXFlux connection status. ALL indicates that all HXFlux

temperature connections in the current scope are to be added to
the problem. NONE indicates that all the HXFlux temperature
connections in the current scope are to be removed from the
problem (they will not appear on the Inactive connection list).
With no argument, all the active HXFlux temperature
connections in the current scope are printed to the current
report device. (Note that this list does include connections
defined through the EO Configuration | Connection forms,
though these are not disabled by the HXFLUX NONE
command.)
Disabling HXFlux Connections

This command is used to disable HXFlux temperature and duty connections
within the current scope. The disabled connections will appear in the Inactive
connection list.
191
Input Language
DISABLE HXFLUX
This command disables both the temperature and duty connections for all
HXFlux blocks in the current scope. A PRINT INACTIVE CONNECTIONS
command will show the disabled connections. This command no effect on
connections defined through the EO Configuration | Connection forms.
Enabling HXFlux Connections

This command is used to enable previously disabled HXFlux temperature and
duty connections within the current scope.
Input Language
ENABLE HXFLUX

This command enables both the temperature and duty connections for all
HXFlux blocks in the current scope that have been previously disabled. This
command no effect on connections defined through the EO Configuration |
Connection forms.
See Also
Standard OOMF - Connection Commands
Recovery Commands
These commands are used to restore the problem state after a failed solution.
Recovery
This command calls every block's pre and post-solve methods. This command
was introduced because Aspen Plus blocks use their post-solve method to
update SM block values after an EO solution. If the EO solution does not
converge, the EO variable values are bad and the SM data is corrupted with
bad values. In order to recover the state of the flowsheet, you must use the
RESET VARIABLES command to restore the EO variable values, followed by
this command.
192
Input Language
RECOVER
RECOVERFROMBADSOLUTION
See Also
Standard OOMF -Recovery Commands
Report Commands
These commands are used to generate an Aspen Plus report.
Reporting Everything
These commands print Aspen Plus report files. REPORT ALL prints
information on the current scope level only (not into any hierarchies).
REPORT FULL prints information on the complete flowsheet, regardless of
the current scope.
Input Language
REPORT ALL
REPORT FULL
Reporting the Flowsheet

This command prints a report of the flowsheet to the report device. This
includes the flowsheet connectivity by streams and blocks.
Input Language
REPORT FLOWSHEET
Reporting Streams
This command prints a report of the specified streams to the report device.
Input Language
REPORT STREAMS stream_list

stream_list
Optional comma separated list of streams to report. ALL will

report all the streams. If omitted, all streams at the current
scope level will be reported.
See Also
Standard OOMF Report Commands
193
194
15 Aspen Custom Modeler

Models Related Extensions
Models exported from Aspen Custom Modeler may be instantiated in

standalone OOMF or in products that embed OOMF. In order to use these
extensions, you must ensure that the AMSystem core component is installed
on your PC. This happens automatically when you install Aspen Plus, Aspen
Custom Modeler, or products related to ACM. The following sections explain
how to instantiate a model exported from ACM in OOMF.

You can enter script commands interactively into the OOMF kernel.
1
Click Start | Run, type cmd and click OK to open a command window.
Add the path to the folder that contains oomf.exe (typically C:\Program
Files\AspenTech\OOMF\version\Xeq) and the path to the folder that
contains acmexp.dll (typically C:\Program Files\AspenTech\AMSystem
version\Bin) to the current path environment variable. For example:
set path= C:\Program Files\AspenTech\OOMF V7.3\Xeq;C:\Program
Files\AspenTech\AMSystem V7.3\Bin;%path%
Type oomf.exe and press enter.

You can now type commands at the OOMF prompt.
See Also
15 Aspen Custom Modeler Models Related Extensions
195
Adding an ACM Model to OOMF

You can instantiate models exported from ACM in OOMF by using acmexp.dll.
The acmexp.dll is an OOMF compatible model adapter DLL that will enable
you to load ACM models into OOMF.
1
Export the model from ACM and install it on your PC by following the
instructions given in the ACM user guide.
The examples which follow assume that the name of the model that you
exported is MyModel, it does not require physical property evaluations, and
the model DLL was installed in the folder
C:\AMModels\MyModel\
The italic sections in these examples should be updated to match your
situation.
2
Start an interactive OOMF session as per the instructions in the previous

section.
Load the acmexp library into OOMF by issuing the command:
load library "acmexp"

4
Instantiate the model in OOMF by issuing either of the following

commands:
add block b1 as
acmexp("model=mymodel,library=mymodel,path=C:\AMModels\MyModel")
or
add block b1 as acmexp("model=C:\AMModels\MyModel\MyModel")
Pick a solver to solve the model by issuing the command:
solver sparse
6
Solve the current simulation by issuing the command
solve
7
Quit the OOMF session by issuing the command
quit
If the exported ACM model requires Aspen Properties to evaluate physical
properties of components, then review the example applications listed in the
document titled A Programmers Guide to OOMF that illustrate the steps
needed to load the components listed in an Aspen Properties file, implement a
host component list manager, and analyze the simulation.
196
ACM Block Attributes

These block attributes are supported by the exported Aspen Custom Modeler
models but not the base OOMF models.
RunMode
The current run mode of the model:
Steady State
Initialization
Dynamic
This mode is normally set by the solver and should not be modified
by scripting.
Procedure_Mode
The perturbation mode to be used for models during solver

iterations for those procedures that dont return derivatives.
All (default) perturb only fixed inputs during the solution

pass but all variables during jacobian evaluations outside of
the solution pass
Free perturb only fixed inputs
Always perturb all inputs whether in solution pass or not
IncrementalUpdate Enable model dependency updates (1, 0). Each 0 (Off) call must be
matched with a 1 (On).
Solution_Mode
SM_Status
EO_Status
DOF
(Read Only) The type of solution that the model is currently

instantiated under.
Equation Oriented
Sequential Modular
(Read Only) The status of the block under its sequential modular
container:
Incomplete the block hasnt been instanced or is

incomplete
Not Solved the block is complete but has not been

solved since the last structural update
Converged the last solution using the block converged
Not Converged the last solution using the block did not
converge
Built-In this block only has an EO configuration
(Read Only) The status of the block under its equation oriented
container
Incomplete the block hasnt been instanced or is

incomplete
Not Solved the block is complete but has not been

solved since the last structural update
Converged the last solution using the block converged
Not Converged the last solution using the block did not
converge
Built-In this block only has an EO configuration
(Read Only) The current degrees of freedom the model. A value of

less than zero indicates that the model is overspecified. A value of
999999 indicates the model is incomplete or has an error in the
formulation.
197
198
16 Aspen HYSYS Refining

Extensions
Aspen HYSYS Refining embeds OOMF and extends its equation-oriented

capabilities. In Aspen HYSYS Refining, OOMF is used for the equation-oriented
simulation of the refinery reactor models. The following sections explain how
to use OOMF and these extensions from within the Aspen HYSYS Refining user
interface.

A live OOMF kernel can be accessed from the Aspen HYSYS Refining user
interface via the Solver Console page of the Reactor Section tab in the
main workbook, or Operation tab in the subflowsheet workbook. Commands
may be typed at the Script Command Line text box near the bottom of
either page.
See Also
Command Summary
In addition to the generic OOMF commands mentioned in previous sections,
the following commands are available within the Aspen HYSYS Refining
environment. These commands are implemented in the OOMF loadable DLL
called refcmds.
16 Aspen HYSYS Refining Extensions
199
EO Commands
Command
Purpose
CONNECTIONSTATUS
Set the status of a connection to a parameter.

Usage: connectionstatus [connection_name,parameter_name]
Use echo &parameter_name to view the contents of the parameter.
Note that a specgroup, meas, var, and stream connection name may be
used..
INITAPROP
Initialize Aspen Properties and load an aprpdf file.

Usage: initaprop "name of the aprpdf or appdf".
SWAPPROP
Swap the Aspen Properties property method and option set.

Usage: swapprop "FCC" or "CATREF" or "HCR"
VARSINSPECGROUP
Set the variable names and specs of variables in a specgroup to a

parameter.
Usage: varsinspecgroup [specgroup_name, parameter_name].
Use echo &parameter_name to view the contents of the parameter.
See Also
Standard OOMF - Command Summary
200
16 Aspen HYSYS Refining Extensions
Index
## script function, 160

. script function, 39
^ script function, 38
< script function, 40
<= script function, 40
<> script function, 40
= script function, 40
> script function, 40
>= script function, 40
ABS script function, 38
ACM models
adding to OOMF, 196
Activating a variable profile
script command, 147
ACTIVESPACE DMO parameter, 131
adding ACM models to OOMF, 196
ALFALS LSSQP parameter, 132
Alias Commands
Printing alias definitions, 73
Printing alias values, 73
Printing alias variables, 74
ALIAS script command, 73
ALIASBYVAR script function, 41
Analysis Commands
Analyzing Equations, 127
Analyzing Variables, 126
Checking degrees of freedom,
125
Sensitivity Analysis, 125
ANALYSISTHRES DMO parameter,
131
ANALYZE DOF script command,
125
ANALYZE EQUATIONS script
command, 127
ANALYZE JACOBIAN script
command, 121
Index
ANALYZE SPARSITY script

command, 121
ANALYZE VARIABLES script
command, 126
AND script function, 40
AspenTech support, 7
AspenTech Support Center, 7
BAD_STATUS_LIST script
parameter, 96
BASFLP LSSQP parameter, 134
BIGBND LSSQP parameter, 134
BIGSCL LSSQP parameter, 134
Block Commands
Attributes
Aspen Custom Modeler, 197
Changing, 63
Printing, 64, 65
Derivative method. See Block
Commands: Attributes
Printing, 123
Excluding blocks, 61
Finding in a hierarchy, 58
Including blocks, 61
Listing block scripts, 62
Listing blocks, 61
Printing block convergence, 62
Printing block statistics, 62
BLOCK SCRIPTS script command,
62
BLOCKATTRS script function, 41
BLOCKS script command, 61
BLOCKS script parameter, 27
BLOCKVARS script function, 41
BNDADJ LSSQP parameter, 134
BNDAPP LSSQP parameter, 133
BOUND variable attribute, 66
Bound_iterations NSOLVE
parameter, 136
201
BSMALL LSSQP parameter, 134

BUILD_DATE script parameter,
27, 145
BUILD_NUMBER script parameter,
27, 145
Built-In script parameters, 27
CHANGE FLUSHING script
command, 24
CHANGE SCOPE script command,
57
CHANGE variable attribute, 66
CHECK CONNECTIONS script
command, 87
CHECK MEASUREMENT script
command, 91
Check_steps NSOLVE parameter,
137
CHECK_UOM script parameter, 27
CHGBND LSSQP parameter, 132
CHGMAX LSSQP parameter, 132
Command Line Prompt, Using, 4
Command Line Prompt, Using in
Aspen Plus, 185
Command Line Prompt, Using in
RefSYS, 199
Command Line Prompt, Using with
ACM Models, 195
COMPARE VARFILE script
command, 105
Connection Commands
Checking connections, 87
Disabling connections, 86
Enabling connections, 86
Printing connection variables, 89
Printing connections, 87
Printing inactive connections, 88
Printing incomplete connections,
88
Removing Connections, 84, 85
Connections
And variable specifications, 84
CONNECTIONS script command, 87
CONNECTIONSBYVAR script
function, 41
Controlling kernel
Defined, 55
CONVERGED script parameter, 27
COS script function, 38
CREEPFLAG DMO parameter, 130
CREEPITER DMO parameter, 130
CREEPSIZE DMO parameter, 130
Crude blends
Update script command, 189
202
customer support, 7
DATE script parameter, 27
DEFAULT_FLUSHING script
parameter, 24, 27
DEFINED script function, 41
Degrees of freedom, checking, 125
Deleting a snapshot
script command, 149
Deleting a task
script command, 147
DELTLS LSSQP parameter, 134
DERDIF LSSQP parameter, 136
DERIV_METHOD block attribute, 63
Derivative Commands. See
Jacobian and Derivative
Commands
DERIVATIVE script command, 123
DERMIN LSSQP parameter, 136
DEVICEINFO script function, 40
DIAG_LEVEL script parameter, 27
DIRECTION Objective function
attribute, 119
DISABLE CONNECTION script
command, 86
DISABLE HXFLUX script command,
191
DISABLE MEASUREMENT script
command, 92
DISABLE SPECIFICATION GROUPS
script command, 80
DISABLE STREAMS script
command, 190
Divergent_steps NSOLVE
parameter, 136
DMO script command, 129
DPERTF LSSQP parameter, 136
DROPTOL DMO parameter, 130
DYN_INTERVAL
script parameter, 145
DYN_RUN_TO
e-bulletins, 7
ECHO script command, 143
ENABLE CONNECTION script
command, 86
ENABLE HXFLUX script command,
192
ENABLE MEASUREMENT script
command, 92
ENABLE SPECIFICATION GROUP
script command, 80
ENABLE STREAMS script command,
190
Index
Equal to (=) script function, 40

Equation Commands
Evaluating, 75
Excluding, 75
Including, 75
Printing, 76
Printing largest, 76
Printing largest residual prices,
77
ETASKP LSSQP parameter, 134
EVALUATE JACOBIAN script
command, 122
EVALUATE OBJECTIVE DERIVATIVE
script command, 120
EVALUATE OBJECTIVE HESSIAN
script command, 120
EVALUATE OBJECTIVE script
command, 120
EXCLUDE BLOCKS script command,
61
EXIT script command, 50
EXP script function, 38
FACTORSPACE DMO parameter,
131
FACTORSPREED DMO parameter,
130
File Commands
Comparing variables with an
ASCII file, 105
Restoring free variables from a
binary file, 103
Restoring variables and block
attributes from an ASCII file,
106
Restoring variables from a binary
file, 102, 108, 109, 115, 116
Restoring variables from an
ASCII file, 104
Saving variables and block
attributes to an ASCII file,
106
Saving variables to a binary file,
101
Saving variables to an ASCII file,
104
Updating variables in a binary
file, 103
File script functions, 40
FIND BLOCK script command, 58
FLANGE_PHASE script parameter,
27
FLUSH script command, 24
FOR-DO script command, 35
Index
Formatted printing, 140

Freeing Properties Data
script command, 183
FSCALF LSSQP parameter, 134
Function_tolerance NSOLVE
parameter, 137
Global script parameters, 26
Global Scripts
Defining, 5, 186
Invoking, 188
GNPMAX LSSQP parameter, 133
Greater than (>) script function,
40
Greater than or equal to (>=)
script function, 40
HEAD script function, 41
help desk, 7
HELP script command, 49
HESSIANUPDATES DMO
parameter, 131
Hierarchies
Defining the scope, 57
Finding a block, 58
Printing the hierarchy, 58
Solving a hierarchy, 59
HISTORY_DEVICE script
parameter, 23, 27
HXFlux Commands
Controlling HXFlux Connections,
191
Disabling HXFlux Connections,
191
Enabling HXFlux Connections,
192
HXFLUX script command, 191
ID2STRING script function, 39
IFDITR LSSQP parameter, 135
IFDTYP LSSQP parameter, 135,
136
IF-THEN-ELSE script command, 34
Inactivating a variable profile
script command, 148
INCLUDE BLOCKS script command,
61
INCLUDED block attribute, 63
INCLUDED Equation attribute, 75
INDEX script function, 39
INITIAL variable attribute, 66
Input Language Rules, 6
INSERTSTR script function, 39
INT script function, 38
Interactive Prompt, Using, 4
203
Interactive Prompt, Using in Aspen

Plus, 185
Interactive Prompt, Using in
RefSYS, 199
Interactive Prompt, Using with ACM
Models, 195
INVOKE command, 32
Invoke Commands
Invoking a block script, 32
Invoking a global script, 188
Invoking a local script, 188
Invoking an external file, 32
Invoking scripts within a scope,
33
Using script arguments, 33
INVOKEGLOBAL command, 188
INVOKELOCAL command, 188
ITRBND LSSQP parameter, 132
IWORKF DMO parameter, 131
Jacobian and Derivative Commands
Analyzing the Jacobian, 121
Analyzing the Jacobian Sparsity,
121
Evaluating the Jacobian, 122
Printing block derivative
methods, 123
Printing the Jacobian, 122
Printing the Jacobian equations,
123
Printing the Jacobian variables,
122
JOURNAL_DEVICE script
parameter, 24, 28
JOURNAL_LEVEL script parameter,
24, 28
Journaling. See Redirecting Output
and Journaling
KBKOUT LSSQP parameter, 135
KFOWDG LSSQP parameter, 135
KMUDEC LSSQP parameter, 133
KOWARM LSSQP parameter, 135
KPFREQ LSSQP parameter, 132
KPNTOP LSSQP parameter, 132
KPTLEV
IXSCS Parameter, 133
KPTLEV LSSQP Parameter, 132
LCHBAS LSSQP parameter, 134
LENGTH script function, 39
Less than (<) script function, 40
Less than or equal to (<=) script
function, 40
LEWBAS LSSQP parameter, 133
LINCST LSSQP parameter, 135
204
LINESEARCH DMO parameter, 130

list concatenation script function,
41
List script functions, 41
Loading a snapshot
script command, 149
Loading Properties Data
script command, 183
Loading task definitions
script command, 147
LOCAL script command, 29
Local script parameters, 27
Local Scripts
Defining, 5, 186
Invoking, 188
LOG10 script function, 38
LOGE script function, 38
Logical script functions, 40
LOWER variable attribute, 66
LSCOPT LSSQP parameter, 133
LSIZEB LSSQP parameter, 134
LSSQP script command, 131
LUBNDS LSSQP parameter, 135
LUSTATS DMO parameter, 131
MAJOR_VERSION script parameter,
28
Mathematical script functions, 38
Maximum_function_error NSOLVE
parameter, 137
Maximum_iterations NSOLVE
Parameter, 136
MAXITER DMO parameter, 130
MAXITR LSSQP parameter, 132
MAXLSC LSSQP parameter, 132
MAXQPF LSSQP parameter, 133
MAXSLF LSSQP parameter, 132
MDHESS LSSQP parameter, 133
MEAS_CAPACITY script parameter,
28
Measurement Commands
Checking measurements, 91
Disabling measurements, 92
Enabling measurements, 92
Measurement Qualities, 96
Printing measurements, 93
Printing measurements variables,
93
MEASUREMENTSBYVAR script
function, 41
Methods
Defined, 5, 186
MINITER DMO parameter, 130
MINITR LSSQP parameter, 132
Index
MINOR_VERSION script parameter,

28
MODE script parameter, 28
Modes
script parameter for, 28
MOVE block attribute, 63
MOVEAMOUNT block attribute, 63
MSFREQ LSSQP parameter, 134
MSMETH LSSQP parameter, 135
NAME_WIDTH script parameter, 28
NBDBAS LSSQP parameter, 135
NFEASB LSSQP parameter, 132
NFINFB LSSQP parameter, 132
NICHK LSSQP parameter, 135
NLRATIODEV block attribute, 63
NNDCMP LSSQP parameter, 134
Not equal to (<>) script function,
40
NOT script function, 40
NSOLVE script command, 136
NUMBER_WIDTH script parameter,
28
OBJCVG DMO parameter, 131
Objective Function Commands
Attributes, 119
Evaluating the objective function,
120
Evaluating the objective
functions derivatives, 120
Evaluating the objective
functions Hessian, 120
Printing the objective function,
121
OBJECTIVE script parameter, 28
ONLINE script parameter, 28
OPENBINARY script function, 40
OPENFILE script function, 40
OPENTEE script function, 40
OR script function, 40
P_AMB script parameter, 28
Pausing a simulation
script command, 146
PERT block attribute, 63
PHASE Stream attribute, 83
Physical Type, 171
PIVOTSEARCH DMO parameter,
131
POP SCOPE script command, 57
Port Commands. See Stream
Commands
Power (^) script function, 38
PRINT ACTIVE_BOUNDS script
command, 70
Index
PRINT ACTIVE_BOUNDS SSI script

command, 70
PRINT ALIAS script command, 73
PRINT ALIAS VARIABLES script
command, 74
PRINT BLOCK ATTRIBUTES script
command, 63, 64, 65
PRINT BLOCK CONVERGENCE
script command, 62
PRINT BLOCK HIERARCHY script
command, 58
PRINT BLOCK PORTS DETAILED
script command, 82
PRINT BLOCK PORTS script
command, 82
PRINT BLOCK STATISTICS FULL
script command, 62
PRINT BLOCK STATISTICS script
command, 62
Print Commands
Formatted printing, 140
Miscellaneous print commands,
143
Printing problem convergence,
139
Printing the problem summary,
139
PRINT CONNECTION VARIABLES
script command, 89
PRINT CONVERGENCE SUMMARY
script command, 139
PRINT EQUATIONS script
command, 76
PRINT FIXED script command, 69
PRINT FLUSHING script command,
24
PRINT FORMATTED script
command, 140
PRINT INACTIVE CONNECTIONS
script command, 88
PRINT INACTIVE SPECIFICATION
GROUPS Script command, 80
PRINT INCOMPLETE CONNECTIONS
script command, 88
PRINT JACOBIAN EQUATIONS
script command, 123
PRINT JACOBIAN script command,
122
PRINT JACOBIAN VARIABLES script
command, 122
script command, 77
205

SHADOW_PRICES script
command, 77
script command, 77
SHADOW_PRICES script
command, 77
PRINT LARGEST RESIDUALS script
command, 76
SHADOW PRICES script
command, 70
SHADOW PRICES SSI script
command, 70
PRINT MEASUREMENTS script
command, 93
PRINT MEASUREMENTS VARIABLES
script command, 93
PRINT OBJECTIVE script command,
121
PRINT QUERY script command, 71
PRINT RESIDUALS script
command, 76
PRINT SCOPE script command, 57
VARIABLES script command,
81
PRINT SPECIFICATION GROUPS
script command, 80
PRINT SPECIFICATIONS script
command, 69
PRINT SUMMARY script command,
139
PRINT TIMER script command, 50
PRINT UOM script command, 159
PRINT VARIABLES script command,
68
PRINT VARIABLES SSI script
command, 68
Print_level NSOLVE parameter, 137
PRINT_VAR_MASK script
parameter, 28
PRINTFREQ DMO parameter, 131
PROBID script parameter, 28
PROBNAME script parameter, 28
script command, 96
Program flow control
FOR-DO constructs, 35
IF-THEN-ELSE constructs, 34
206
WHILE-DO constructs, 36
PROMPT script parameter, 28
PUSH SCOPE script command, 57
QPINFE LSSQP parameter, 133
QPSTATS DMO parameter, 131
Query
Printing variables with, 71
Query script functions, 41
QUERYVARS script function, 41
QUIT script command, 50
READ SNAPSHOT script command,
106
READ VARFILE EXCEPT script
command, 104
READ VARFILE script command,
104
READ_VARFILE_MASK script
parameter, 28
RECOVER script command, 192
Recovery commands
Recovery, 192
Resetting variables, 138
Redirecting output and Journaling
Examining the output devices, 25
Flushing, 24
Journaling, 24
Redirecting the output of a
command, 21
the history device, 23
the report device, 23
Reinitializing a simulation
script command, 147
Relational script functions, 40
RELAX_TOL script parameter, 28
RELEPS LSSQP parameter, 132
REMOVE CONNECTIONS script
command, 84, 85
REMOVE SPECIFICATION GROUPS
script command, 79, 146, 147,
148, 149
REMOVESTR script function, 39
REPORT ALL script command, 193
REPORT BLOCKS script command,
144
Report Commands
Reporting blocks, 144
Reporting everything, 193
Reporting streams, 193
Reporting the flowsheet, 193
Reporting the objective function,
144
REPORT FLOWSHEET script
command, 193
Index
REPORT OBJECTIVE script

command, 144
REPORT STREAMS script command,
193
REPORT_DEVICE script parameter,
23, 28
RESCVG DMO parameter, 131
RESET SCOPE script command, 57
RESET VARIABLES script
command, 138
Residual Commands. See Equation
Commands
RESTART TIMER script command,
50
RESTORE FREE VARIABLES EXCEPT
script command, 103
RESTORE FREE VARIABLES script
command, 103
RESTORE VARIABLES script
command, 102, 108, 109, 115,
116
RETURN command, 33
RFEASB LSSQP parameter, 132
RFINFB LSSQP parameter, 132
RIGORUPDATES DMO parameter,
131
RRHIGH LSSQP parameter, 134
RRLOW LSSQP parameter, 134
RUN_MODE
Running a simulation
script command, 146
RWORKF DMO parameter, 131
SAVE VARIABLES script command,
101
SAVEJDFFILE DMO parameter, 131
Saving a snapshot
script command, 149
SBWEIGHT variable attribute, 66
SCALE Objective function attribute,
119
SCALE variable attribute, 66
Scope
Defined, 55
SCOPE INVOKE command, 33
SCREENFORM DMO parameter, 131
Script Functions, 38
Script parameters
Accessing, 30
Built-in script parameters, 27
Global script parameters, 26
Local script parameters, 27
Setting, 29
Index
Unsetting, 30
SCRIPT_PATH script parameter, 29
Scripts
Defining, 5, 186
Executing, 5, 186
Global, defined, 5, 186
Local, defined, 5, 186
SEARCHMODE DMO parameter,
130
SENSITIVITY script command, 125
SET script command, 29
SIN script function, 38
SINGT1 LSSQP parameter, 134
SINGT2 LSSQP parameter, 134
SMLSCL LSSQP parameter, 134
snapshot, 149
SOFT_BOUND script parameter, 29
SOLVE script command, 137
Solver commands
Entering DMO parameters, 129
Entering LSSQP parameters, 131
Entering NSOLVE parameters,
136
Setting the solver, 129
Solving the problem, 137
Viewing solver settings, 129
SOLVER script command, 129
SOLVER SETTINGS script
command, 129
SPDROP LSSQP parameter, 134
SPEC Stream attribute, 83
SPEC variable attribute, 66
SPECGROUPSBYVAR script
function, 41
Specification Group Commands
Disabling Specification Groups,
80
Enabling Specification Groups,
80
Printing inactive specification
groups, 80
Printing Specification Group
variables, 81
Printing specification groups, 80
Removing Specification Groups,
79, 146, 147, 148, 149
Specification variable attribute, 66
SQRT script function, 38
Stabilization NSOLVE parameter,
137
Stable_iterations NSOLVE
parameter, 136
START TIMER script command, 50
207
STEP variable attribute, 66

STEP_BOUND script parameter, 29
Stepping through a simulation
script command, 146
STOP TIMER script command, 50
Stopping a simulation
script command, 146
Stream Commands
Adding and removing stream
connections, 190
Attributes, 83
Disabling Stream connections,
190
Enabling Stream connections,
190
Printing block ports, 82
Printing stream values, 82
STREAMS script command, 190
string concatenation script
function, 39
String script functions, 39
STRING2ID script function, 39
SUBSTR script function, 39
support, technical, 7
Swapping Properties Data
script command, 183
System commands, executing, 50
SYSTEM script command, 50
TAIL script function, 41
TAN script function, 38
task, 147
task language, 150
TAUHYB LSSQP parameter, 134
technical support, 7
TIMER script commands, 50
TO script command, 21
TOGGLE SOLVE SCOPE script
command, 59
TOLANA LSSQP parameter, 133
TOLBAS LSSQP parameter, 133
TOLOWER script function, 39
TOUPPER script function, 39
Trust_radius NSOLVE parameter,
137
TYPE Stream attribute, 83
TYPEOF script function, 41
Units of measure, 161
Units of measure commands
Dealing with Untyped Variables,
160
Printing units of measure, 159
208
Variable Units of Measure, 159,

177
UNITS variable attribute, 66
UNSET script command, 30
UOM Objective function attribute,
119
UOM_WIDTH script parameter, 29
UPDATE BLEND script command,
189
UPDATE PDF script command, 189
UPDATE VARIABLES script
command, 103
UPPER variable attribute, 66
USERDROPTOL DMO parameter,
130
VAL script function, 41
VALUE Objective function attribute,
119
VALUE variable attribute, 66
Variable Commands
Changing variable attributes, 67
Printing largest variable shadow
prices, 70
Printing variables, 68
Printing variables fixed in other
modes, 69
Printing variables fixed in the
current mode, 69
Printing variables using a query,
71
Printing variables with active
bounds, 70
Variable_tolerance NSOLVE
parameter, 137
VARSCALE DMO parameter, 131
Viewing a variable history
script command, 148
Viewing a variable profile
script command, 148
Viewing snapshots
script command, 149
Viewing tasks
script command, 147
VMUINI LSSQP parameter, 134
VMUMIN LSSQP parameter, 134
web site, technical support, 7
WHILE-DO script command, 36
Wildcards
Glob-style, 47
Regular expression matching, 47
WRITE SNAPSHOT script
command, 106
Index
WRITE VARFILE EXCEPT script

command, 104
WRITE VARFILE script command,
104
WRITE_VARFILE_MASK script
parameter, 29
XPMIN LSSQP parameter, 136
ZEROTOL block attribute, 63
ZPERTF LSSQP parameter, 135
Index
209

AspenOOMFScriptLangV7 3 Ref

Transféré par

Informations du document

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

AspenOOMFScriptLangV7 3 Ref

Transféré par

Droits d'auteur :

Formats disponibles

Aspen OOMF

Script Language Reference Manual

Version Number: V7.3

FOR-DO Command ............................................................................... 35

Printing Variables Fixed in the Current Mode............................................ 69

Deleting a snapshot............................................................................ 149

Assigning a value to a variable ............................................................... 155

Adding and Removing Stream Connections............................................ 190

Who Should Read this Guide

Who Should Read this Guide

Who Should Read this Guide

Introducing OOMF Script

Debugging an equation-oriented run.

Defining sets of process values.

Setting the inclusion status of blocks, measurements, etc.

Creating custom reports.

The script language has many features of an advanced programming

Introducing OOMF Script Language

Using the Interactive Prompt

Move cursor to beginning of line.

Move cursor to end of line.

Delete the character left of the cursor.

Delete the character right of the cursor.

Return the current line.

Move cursor left (back) 1 column.

Move cursor right (forward) 1 column.

Fetches previous line from the history list.

Fetches next line from the history list.

Introducing OOMF Script Language

Defining and Executing Scripts

Products using OOMF may define additional ways to create scripts.

By associating the script with a block or the flowsheet. This is done by

This method is executed before a solve is started. It can be very useful

This method is executed after a solve is completed. This is useful for

Introducing OOMF Script Language

Input Language Rules

Percent signs (%) are used to delimit regular expressions (a powerful

Some commands support single character (also known as glob style)

Spaces must be used between all operators.

Many of these commands may have their output redirected by using TO

Aspen Engineering Suite Installation

Instructions for installing Aspen

Aspen Plus User Guide

Procedures for using Aspen Plus

Aspen Plus User Models Reference Manual

Instructions for creating custom

Aspen Plus Input Language Guide

Commands for Aspen Plus input

Introducing OOMF Script Language

Access current product documentation

Search for and download application examples

Search for and download service packs and product updates

Submit and track technical issues

Report product defects

Review lists of known deficiencies and defects

Registered users can also subscribe to our Technical Support e-Bulletins.

Product updates and releases

Introducing OOMF Script Language

Introducing OOMF Script Language

ACTIVATE VARIABLE PROFILE

Activate a variable profile

Add variable aliases

Add blocks to the current scope

ADD CONDITIONAL EQUATION