Aspen OOMF

Script Language Reference Manual

Version Number: V10
June 2017
Copyright (c) 1997 - 2017 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., Bedford, 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.

20 Crosby Drive
Bedford, MA 01730
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 .................................................................. 31
Accessing Parameter Values .................................................................. 31
Examples of Script Parameters............................................................... 31
Invoke Commands ......................................................................................... 33
Invoking an External File....................................................................... 33
Invoking a Block Script ......................................................................... 33
Invoking Scripts Within a Scope ............................................................. 34
Script Arguments ................................................................................. 34
Examples of Invoke Commands ............................................................. 34
Program Flow Control ..................................................................................... 35
IF-THEN-ELSE Command ...................................................................... 35

Contents iii
 FOR-DO Command ............................................................................... 36
WHILE-DO Command ........................................................................... 37
Examples of Program Flow Control ......................................................... 37
Expressions and Conditionals ........................................................................... 39
Examples of Math Functions .................................................................. 42
Examples of String Functions ................................................................. 43
Examples of Relational and Logical Functions........................................... 44
Examples of File Functions .................................................................... 44
Examples of List Functions .................................................................... 45
Examples of Query Functions ................................................................. 45
Examples of Miscellaneous Functions ...................................................... 46
Examples of Effects of Units of Measure .................................................. 46
Examples Using String Functions to Create Variable Names ....................... 47
Wildcards ...................................................................................................... 48
Glob-Style Wildcards ............................................................................ 48
Regular Expression Matching ................................................................. 48
Examples of Wildcards .......................................................................... 49
General Commands ........................................................................................ 51
Getting Help ........................................................................................ 51
Exiting the System ............................................................................... 51
Executing System Commands ................................................................ 51
Timer.................................................................................................. 51
OOMF Model Adapters..................................................................................... 52

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 ................................................................... 63
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............................................ 70
Printing Variables Fixed in Other Modes .................................................. 70
Printing Variables with Active Bounds ..................................................... 71
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 v
 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 ........... 108
Saving a Simulation to a Compound Storage File.................................... 108
Opening a Simulation from a Compound Storage File.............................. 109
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...................................... 110
Examples of Binary Persistence Commands ........................................... 110
Persisting Simulation and Block Data in XML Files............................................. 110
XML Schema for Simulation Persistence ................................................ 111
Writing a Simulation to a XML File ........................................................ 115
Reading a Simulation from a XML File ................................................... 116
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 .............................................. 117

7 Objective Functions.........................................................................................119
Objective Function Commands ....................................................................... 119
Changing Objective Function Attributes................................................. 119
Evaluating the Objective Function ........................................................ 120
Evaluating the Objective Function’s Derivatives...................................... 120
Evaluating the Objective Function’s 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

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

viii Contents
 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

Using the Interactive Prompt ......................................................................... 195
Adding an ACM Model to OOMF ...................................................................... 196
ACM Block Attributes .................................................................................... 198

16 Aspen HYSYS Refining Extensions .................................................................199

Using the Interactive Prompt ......................................................................... 199
Command Summary ..................................................................................... 199

Index ..................................................................................................................201

Contents ix
x 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.

Who Should Read this Guide 1

2 Who Should Read this Guide
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 3

 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.

4 Introducing OOMF Script Language

 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 block’s script method with the INVOKE
command.
More on invoking scripts may be found in Invoke Commands.

Introducing OOMF Script Language 5

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

Manual 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

6 Introducing OOMF Script Language

 Technical Support
AspenTech customers with a valid license and software maintenance
agreement can register to access the online AspenTech Support Center at:
https://support.aspentech.com
This Web support site allows you to:
 Access current product documentation
 Search for tech tips, solutions and frequently asked questions (FAQs)
 Search for and download application examples
 Search for and download service packs and product updates
 Submit and track technical issues
 Send suggestions
 Report product defects
 Review lists of known deficiencies and defects
Registered users can also subscribe to our Technical Support e-Bulletins.
These e-Bulletins are used to alert users to important technical support
information such as:
 Technical advisories
 Product updates and releases
Customer support is also available by phone, fax, and email. The most up-to-
date contact information is available at the AspenTech Support Center at
https://support.aspentech.com.

Introducing OOMF Script Language 7

8 Introducing OOMF Script Language
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 Add specification connections
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 9parsity patterns.
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 9
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 Disable any specification group whose name matches a list of name
GROUPS 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 Enable any specification group whose name matches a list of name
GROUPS 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 Evaluate and display the derivative
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
10parsity solver.
IDENTIFY LIBRARY Ask a loaded library to give its version
INACTIVATE VARIABLE Inactivate a variable profile
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 Print the list of attributes in detail for a specified block
DETAILED
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 Print the list of connections that are incomplete. Incomplete
CONNECTIONS 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 Show the largest equation shadow prices
SCALED_SHADOW_PRICES
PRINT LARGEST EQUATION Show the largest equation shadow prices
SHADOW_PRICES
PRINT LARGEST EQUATIONS Show the largest residuals
PRINT LARGEST RESIDUAL Show the largest residual shadow prices
SCALED_SHADOW_PRICES
PRINT LARGEST RESIDUAL Show the largest residual shadow prices
SHADOW_PRICES
PRINT LARGEST RESIDUALS Show the largest residuals
PRINT LARGEST VARIABLE Show the largest variable shadow prices in scaled SI
SHADOW_PRICES SSI
PRINT LARGEST VARIABLE Show the largest variable shadow prices in user units
SHADOW_PRICES
PRINT MEASUREMENTS Report on all or specified variable measurements.
PRINT MEASUREMENTS Report the measurements that reference the specified variables
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.
PRINT SPECIFICATION GROUP Print the specification group name that references the specified
VARIABLES 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 Print a report for variable connections
CONNECTIONS
PRINT VARIABLE HISTORY Compute a variable’s 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 Remove any specification group whose name matches a list of name
GROUPS 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 Restore attributes for free variables in current MODE from a binary
EXCEPT 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 Define an objective function
SWAP PROPERTY Swap the Aspen Properties property method or option set
SYMBOLIC OBJECTIVE Define an objective function
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 | 15parsit 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_<15parsit 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:
 number

1 Script Commands 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 PortVars QuerySpecGroups
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 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 (read-
only)
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

18 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 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.)
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.
EXISTFILE Checks the existence of a file
EXISTFILE( "file" )
The name of a file is enclosed in double quotation marks along with
the path. This command returns True if the file exists, else returns
False.
OPENBINARY Redirects output to the specified binary file. To simply open the file,
enter:
OPENBINARY( "file" )
The name of the file is enclosed in double quotation marks. To open
the file with an option, enter:
OPENBINARY( [ "file", option ] )
Note the use of the brackets. option is one of the following:
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 2 OOMF Script Language Basics

 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

Input Language Description

device Device to which output is to be directed:

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

Input Language Description

device Device to which output is to be directed:
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.

2 OOMF Script Language Basics 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

Input Language Description

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 2 OOMF Script Language Basics

 Input Language
SET JOURNAL_DEVICE = device
SET JOURNAL_LEVEL = level

Input Language Description

device Device to which output is to be directed:
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
See the section Redirecting the Output of a Command for details on these
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 ] )

2 OOMF Script Language Basics 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 2 OOMF Script Language Basics

 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.
NEVER Never flush
PER_LINE Flush after each line (default)
PER_WRITE Flush after each write command
DIAG_LEVEL 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:
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).
HISTORY_DEVICE Destination where history information is to be output. Use ECHO
&HISTORY_DEVICE to examine the current value.
device defaults to TERMINAL but may be any of the following:
TERMINAL NOWHERE OPENFILE OPENTEE
See the section Redirecting the Output of a Command for details on
these options.

2 OOMF Script Language Basics 27

Script Parameter Description

JOURNAL_DEVICE Destination where journaling output is to be directed. Use ECHO

&JOURNAL_DEVICE to examine the current value.
device defaults to TERMINAL but may be any of the following:
TERMINAL NOWHERE OPENFILE OPENTEE
See the section Redirecting the Output of a Command for details on
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)
MEAS_DECIMAL_WIDTH Number of digits after the decimal point in numbers printed by the
PRINT_MEAS.ebs script (default = 3). This script uses a fixed decimal
format, unlike PRINT MEASUREMENT.
MEAS_DESC_WIDTH Width of the description field in the PRINT MEASUREMENT command
(default = 16)
MEAS_NUMBER_WIDTH Width of the number fields in the PRINT MEASUREMENT command (default
= 9)
MEAS_TAG_WIDTH Width of the tag field in the PRINT MEASUREMENT command (default =
24)
MEAS_UOM_WIDTH Width of the units field in the PRINT MEASUREMENT command (default =
8)
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 MEASUREMENT,
PRINT EQUATIONS, PRINT LARGEST EQUATIONS, PRINT JACOBIAN,
and WRITE VARFILE (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)

28 2 OOMF Script Language Basics

Script Parameter Description

REPORT_DEVICE Destination where output from the PRINT and REPORT commands are to
be directed. Use ECHO &REPORT_DEVICE to examine the current value.
device defaults to TERMINAL but may be any of the following:
TERMINAL NOWHERE OPENFILE OPENTEE
See the section Redirecting the Output of a Command for details on
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).
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 units 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

Input Language Description

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,

2 OOMF Script Language Basics 29

 STRING2ID, ID2STRING, TOUPPER, TOLOWER, LENGTH, SUBSTR,
INDEX, INSERTSTR, REMOVESTR, OPENFILE, EXISTFILE,
OPENBINARY, DEVICEINFO, OPENTEE, VAL, TYPEOF, DEFINED,
HEAD, TAIL, BLOCKVARS, BLOCKATTRS, QUERYVARS,
ALIASESBYVAR, CONNECTIONSBYVAR, MEASUREMENTSBYVAR,
SPECGROUPSBYVAR, PORTVARS, QUERYSPECGROUPS
Expressions are discussed further in the section titled Expressions and
Conditionals.

30 2 OOMF Script Language Basics

 Unsetting Script Parameters
The value of any script parameter may be set to undefined with the UNSET
command.

Input Language
UNSET parameter

Input Language Description

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.

2 OOMF Script Language Basics 31

 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}

EO> ECHO TYPEOF(&VAR)

REAL

32 2 OOMF Script Language Basics

 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, …

Input Language Description

file Name of an external script file to execute. The default extension is EBS.
arg1, Optional list of arguments passed to the script file. This may be referenced in
arg2 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 block’s level.
You may pass arguments to the invoked script and get a returned value.

Input Language
INVOKE blockid, method, arg1, arg2, …

Input Language Description

blockid Name of the block script to execute.
method Name of the script method to execute.
arg1, Optional list of arguments passed to the script. This may be referenced in the
arg2 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.

2 OOMF Script Language Basics 33

 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 block’s level.

Input Language
SCOPE INVOKE blockid, method

Input Language Description

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:

34 2 OOMF Script Language Basics

 PLANT

S1 S2

B1 B2 B3 S3 B6

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

2 OOMF Script Language Basics 35

 Input Language Description
condition A TRUE/FALSE condition. This 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,
EXISTFILE, OPENBINARY, DEVICEINFO, OPENTEE, VAL,
TYPEOF, DEFINED, HEAD, TAIL, BLOCKVARS, BLOCKATTRS,
QUERYVARS, ALIASESBYVAR, CONNECTIONSBYVAR,
MEASUREMENTSBYVAR, SPECGROUPSBYVAR, PORTVARS,
QUERYSPECGROUPS
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

Input Language Description

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.

36 2 OOMF Script Language Basics

 WHILE-DO Command
This command can be used to define an execution loop.

Input Language
WHILE ( condition ) DO
BREAK
CONTINUE
ENDWHILE

Input Language Description

condition A TRUE/FALSE condition. This 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, EXISTFILE,
OPENBINARY, DEVICEINFO, OPENTEE, VAL, TYPEOF, DEFINED,
HEAD, TAIL, BLOCKVARS, BLOCKATTRS, QUERYVARS,
ALIASESBYVAR, CONNECTIONSBYVAR, MEASUREMENTSBYVAR,
SPECGROUPSBYVAR, PORTVARS, QUERYSPECGROUPS
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

2 OOMF Script Language Basics 37

 ECHO "TEMP OK"
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 TEST1 = 100
SET TEST2 = 200
SET VARNAME = [ TEST1, TEST2 ]
FOR 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

38 2 OOMF Script Language Basics

 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}

Input Language Description

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:
+ 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

2 OOMF Script Language Basics 39

 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.

40 2 OOMF Script Language Basics

 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" )
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.
EXISTFILE Checks the existence of a file
EXISTFILE( "file" )
The name of a file is enclosed in double quotation marks along with the path.
This command returns True if the file exists, else returns False.
OPENBINARY Redirects output to the specified binary file. To simply open the file, enter:
OPENBINARY( "file" )
The name of the file is enclosed in double quotation marks. To open the file
with an option, enter:
OPENBINARY( [ "file", option ] )
Note the use of the brackets. option is one of the following:
BINARY_READ Open file for binary reading only.
BINARY_WRITEOpen 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.
DEVICEINFO Returns information about the specified device. This function should be used
in PRINT FORMATTED and IF-THEN-ELSE commands.

2 OOMF Script Language Basics 41

 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.
Wildcards may be used for the variable name.
MEASUREMENTSBYVAR Returns list of measurement names (as
blockid.tagid_description) matching the specified variable.
Wildcards may be used for the variable name.
SPECGROUPSBYVAR Returns list of Specification Groups matching the specified
variable. Wildcards may be used for the variable name.

PORTVARS Returns list of variables in the specified port

QUERYSPECGROUPS Returns Specification Groups information that matches the
specified query string as a list.

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

Let’s 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:

42 2 OOMF Script Language Basics

 C2S.BLK.DISTILLATE_MASS.LOWER = C2S.BLK.DISTILLATE_MASS - 5000.
{KG/HR}
C2S.BLK.DISTILLATE_MASS.UPPER = C2S.BLK.DISTILLATE_MASS + 5000.
{KG/HR}

Examples of String Functions

Here’s 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> SET STR = "12345"
EO> SET STR1 = SUBSTR(&STR,2,2)

2 OOMF Script Language Basics 43

 EO> ECHO &STR1
23
EO> SET STR2 = SUBSTR(&STR,-2,2)
EO> ECHO &STR2
45
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
Here’s 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.

44 2 OOMF Script Language Basics

 To change the report device to file COLUMN.REP and open it with the
appending option enter:
SET REPORT_DEVICE = OPENFILE( [ "COLUMN.REP", APPEND ] )

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

To get the list of all the variables in port C2S.F.STR and then print it to the
screen, enter the following commands:

SET VARRLIST = PORTVARS( C2S.F.STR )

ECHO &VARLIST

2 OOMF Script Language Basics 45

 To get the information related to all Specification Groups whose names
contain COMPS as a list and then print it to the screen, enter the following
commands:

SET SPECGROUPSLIST = QUERYSPECGROUPS( *COMPS )

ECHO &SPECGROUPSLIST

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:
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}

EO> ECHO TYPEOF(&VAR)

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:

46 2 OOMF Script Language Basics

 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}
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 Upper \n"
PRINT FORMATTED "---- --- ----- ----- \n"
SET FMT = "%-20s %-12.7g %-12.7g %-12.7g \n"

2 OOMF Script Language Basics 47

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

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.

Input Language Description

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.

Input Language Description

Regular expression matching uses special characters to provide the matching
functions. The string to be matched is enclosed in percent signs (%). Regular

48 2 OOMF Script Language Basics

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

2 OOMF Script Language Basics 49

 %\.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:
*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
C2S.*.FLOW.LOWER = 0.0 {KMOL/HR}
Let’s 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:
C2S.*.FLOW.LOWER = 0.0 {KMOL/HR}
C2SBDEF.*.FLOW.LOWER = 0.0 {KMOL/HR}
C2SDDEF.*.FLOW.LOWER = 0.0 {KMOL/HR}

50 2 OOMF Script Language Basics

 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

Input Language Description

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

2 OOMF Script Language Basics 51

 PRINT TIMER

Input Language Description

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

Input Language Description

IDENTIFY LIBRARY Returns the version number of the specified DLL
LOAD LIBRARY Loads the specified DLL
UNLOAD LIBRARY Unloads a previously loaded DLL

52 2 OOMF Script Language Basics

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 Plus’s user
interface or input language by placing a hierarchy block onto the flowsheet.
See Also
Aspen Plus Extensions - Hierarchies
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 3 Hierarchies, Blocks, Variables and Equations

 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
Aspen Plus Extensions - Hierarchies

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:

3 Hierarchies, Blocks, Variables and Equations 55

 Flowsheet Level

S1 S2

B1 B2 B3 S3 B6

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 3 Hierarchies, Blocks, Variables and Equations

 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.
o 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 product’s user interface. Therefore, care should be exercised when using
these commands in the product’s user interface.

3 Hierarchies, Blocks, Variables and Equations 57

 Input Language
PUSH SCOPE blockid
CHANGE SCOPE blockid
POP SCOPE
RESET SCOPE
PRINT SCOPE

Input Language Description

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

Input Language Description

blockid Name of block to find.

58 3 Hierarchies, Blocks, Variables and Equations

 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 product’s user interface or with the PUSH SCOPE command. The scope
may then be solved either through the product’s 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 re-
activated.

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- -Nfix- Nexcld -Ndof- NfreeI --Nnz- --Nz%-
C2HIER 1369 1324 24 0 0 7 6808 0.38
C3HIER 79 64 7 0 0 1 183 4
CONDUA 12 5 3 0 0 0 15 33
---------- ------ ------ ------ ------ ------ ------ ------ ------
Total 1460 1393 34 0 0 8 7006
EO> PUSH SCOPE C3HIER
EO> PRINT BLOCK STATISTICS
---Block-- -Nvar- -Neqn- -Nfix- Nexcld -Ndof- NfreeI --Nnz- --Nz%-
CVAP 41 33 3 0 0 1 96 7.7
CIN 35 30 3 0 0 0 85 8.9
C3MEAS 3 1 1 0 0 0 2 1e+002
---------- ------ ------ ------ ------ ------ ------ ------ ------
Total 79 64 7 0 0 1 183

3 Hierarchies, Blocks, Variables and Equations 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 Percent

================================ ======== =======

MODEL computations 0.02 secs 12.50 %

DMO computations 0.00 secs 0.00 %
Miscellaneous 0.14 secs 87.50 %
-------------------------------- --------- -------
Total Optimization Time 0.16 secs 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 3 Hierarchies, Blocks, Variables and Equations

 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.

3 Hierarchies, Blocks, Variables and Equations 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

Input Language Description

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

Input Language Description

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

Input Language Description

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

62 3 Hierarchies, Blocks, Variables and Equations

 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

Input Language Description

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

Input Language Description

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.

3 Hierarchies, Blocks, Variables and Equations 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

Input Language Description

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 block’s non-linearity ratio when using
Schubert updating. If the non-linearity ratio is greater than this value,
the block’s Jacobian is re-computed. (default = 0.01)
DERIV_METHODDerivative method.
ANALYTIC Derivatives are set by the model subroutine.
NUMERIC Derivatives are computed numerically. The
perturbation size may be specified with the PERT block
attribute.
PERT 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

Input Language Description

block_list Comma-separated list of blocks to print. If not entered,
the attributes of all blocks are printed.

64 3 Hierarchies, Blocks, Variables and Equations

 Printing Block Attributes in Detail
Prints a list of all the block attributes in detail.

Input Language
PRINT BLOCK ATTRIBUTES DETAILED block_list

Input Language Description

block_list Comma-separated list of blocks to print. If not entered,
the attributes of all blocks are printed.

Printing Block Parameters

Prints a list of all the block attributes.

Input Language
PRINT BLOCK PARAMETERS block_list

Input Language Description

block_list Comma-separated list of blocks to print. If not entered,
the attributes of all blocks are printed.

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.

3 Hierarchies, Blocks, Variables and Equations 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

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 ) 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]
[C2MEAS.BLK.C3R_PLANT,Meas]
[C2MEAS.BLK.C3R_OFFSET,Param]
1 specification group found.
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 3 Hierarchies, Blocks, Variables and Equations

 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)

3 Hierarchies, Blocks, Variables and Equations 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 The quality of the parameterized variable is to be
overridden.
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
...

Input Language Description

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:
VALUE INITIAL CHANGE LOWER
UPPER STEP BOUND SBWEIGHT
SPEC UNITS SCALE PHYSICAL_TYPE

68 3 Hierarchies, Blocks, Variables and Equations

 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 variable’s 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 parameters NAME_WIDTH and
UOM_WIDTH. Numbers are printed using a “g” format which switches
between decimal and scientific notation based on the magnitude of the
number, using a fixed width which cannot be changed.

Input Language
PRINT VARIABLES [ vmask ], list
PRINT VARIABLES SSI [ vmask ], list

Input Language Description

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

3 Hierarchies, Blocks, Variables and Equations 69

 Printing Variables Fixed in the Current
Mode
This command prints the variables that are fixed in the current mode to the
report device.
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.
Numerical values are given in the variable’s units of measure.
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 parameters NAME_WIDTH and
UOM_WIDTH.

Input Language
PRINT FIXED [ vmask ], list

Input Language Description

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

Input Language Description

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

70 3 Hierarchies, Blocks, Variables and Equations

 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.
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 ACTIVE_BOUNDS, values are given in the variable’s units of
measure; for PRINT ACTIVE_BOUNDS 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 parameters NAME_WIDTH and
UOM_WIDTH.

Input Language
PRINT ACTIVE_BOUNDS [ vmask ], list
PRINT ACTIVE_BOUNDS SSI [ vmask ], list

Input Language Description

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

3 Hierarchies, Blocks, Variables and Equations 71

 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 parameters NAME_WIDTH and
UOM_WIDTH.

Input Language
PRINT LARGEST VARIABLE SHADOW_PRICES integer, list
PRINT LARGEST VARIABLE SHADOW_PRICES SSI integer, list

Input Language Description

integer Optional length of largest shadow price list (default = 10)
list A comma separated list of block names, variable names, stream names or
variable indices. If omitted, all variables are searched. A range of indices may
be printed by using a colon with spaces on either side ( : ) between the
indices.

Printing Variables Using a Query

Prints to the report device selected information about variables using a query
string.
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.
The format of the output is affected by script parameters NAME_WIDTH and
UOM_WIDTH.

Input Language
PRINT QUERY [ vmask ], block_list, query

Input Language Description

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 3 Hierarchies, Blocks, Variables and Equations

 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 -50C:
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 = 0.0001
C2SD.D.STR.C2H6.LOWER = 0.00001
C2SD.D.STR.C2H6.UPPER = 0.0002
C2SD.D.STR.C2H6.SPEC = 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:

3 Hierarchies, Blocks, Variables and Equations 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
masking, which is a list of variable attributes enclosed by parentheses.
Numerical values are given in the variables units of measure.
The width of the name and units fields in the report may be controlled with
script parameters NAME_WIDTH and UOM_WIDTH.

Input Language
PRINT ALIAS name [ vmask ]

74 3 Hierarchies, Blocks, Variables and Equations

 Input Language Description
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

Input Language Description

var_list Optional comma-separated list of variable names. If no list is given,
then all alias definitions for the current scope are printed.

3 Hierarchies, Blocks, Variables and Equations 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

Input Language Description

equationid Equation name.

Including Equations
This command may be used to include equations that have been previously
excluded.

Input Language
equationid.INCLUDED = TRUE

Input Language Description

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 3 Hierarchies, Blocks, Variables and Equations

 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.
The width of the name field in the report may be controlled with script
parameter NAME_WIDTH.

Input Language
PRINT EQUATIONS list
PRINT RESIDUALS list

Input Language Description

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.
The width of the name field in the report may be controlled with script
parameter NAME_WIDTH.

Input Language
PRINT LARGEST RESIDUALS integer, block_list
PRINT LARGEST EQUATIONS integer, block_list

Input Language Description

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.

3 Hierarchies, Blocks, Variables and Equations 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.)
The width of the name field in the report may be controlled with script
parameter NAME_WIDTH.

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

Input Language Description

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.

78 3 Hierarchies, Blocks, Variables and Equations

4 Specification Groups and
Connections

This chapter describes the OOMF Script commands used to manipulate

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

Input Language Description

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
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 SPECIFICATION GROUP spec_list

Input Language Description

spec_list A comma-separated list of names. If no name is entered, all
Spec Groups within the current scope are disabled. Wildcards
may be used in the names.

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

Input Language Description

spec_list A comma-separated list of names. If no name is entered, all
Spec Groups within the current scope are enabled. Wildcards
may be used in the names.

Printing Specification Groups

This command prints the Specification Groups in the current scope.

Input Language
PRINT SPECIFICATION GROUP spec_list

Input Language Description

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 4 Specification Groups and Connections

 Input Language
PRINT INACTIVE SPECIFICATION GROUPS spec_list

Input Language Description

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

Input Language Description

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]
1 specification group found.

EO> DISABLE SPEC GROUP DOG

1 specification group disabled.

EO> PRINT SPEC GROUP DOG

<< Specification group DOG, disabled, and inactive >>
[CIN.BLK.C3H6_MOLE_FRAC,Calc]
[CIN.BLK.SUM_MOLE_FRAC,Const]
1 specification group found.

EO> ENABLE SPEC GROUP DOG

1 specification group enabled.

EO> PRINT SPEC GROUP DOG

<< Specification group DOG, enabled, and active >>
[CIN.BLK.C3H6_MOLE_FRAC,Calc]
[CIN.BLK.SUM_MOLE_FRAC,Const]
1 specification group found.

4 Specification Groups and Connections 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

Input Language Description

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

Input Language Description

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.

82 4 Specification Groups and Connections

 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

Input Language Description

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 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 Mixed vapor, liquid and free water phases (flash with free
water 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).
TYPE 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

4 Specification Groups and Connections 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 RECON INDEP

CONST= CALC=CONST CALC=CALC CALC=MEAS CALC=PARAM CALC=OPTIM 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

OPTIM= CALC=CONST CALC=CALC CALC=MEAS CALC=PARAM CALC=OPTIM CALC=RECON CALC=INDEP

RECON= CALC=CONST CALC=CALC CALC=MEAS CALC=PARAM CALC=OPTIM CALC=RECON CALC=INDEP

INDEP= CALC=CONST CALC=CALC CALC=MEAS CALC=PARAM CALC=OPTIM CALC=RECON CALC=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 4 Specification Groups and Connections

 Input Language Description
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

Input Language Description

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
all the Connections and Spec Groups to ensure that the problem remains
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
Solve is performed.)
If you use these commands from within products that embed OOMF, note that
any Connections defined in the product’s 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

4 Specification Groups and Connections 85

 Input Language Description
cxn_list A comma-separated list of names. If no name is entered, all
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
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 CONNECTION cxn_list

Input Language Description

cxn_list A comma-separated list of names. If no name is entered, all
Connections and Spec Groups within the current scope are
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

Input Language Description

cxn_list A comma-separated list of names. If no name is entered, all
Connections and Spec Groups within the current scope are
enabled. Wildcards may be used in the names.

86 4 Specification Groups and Connections

 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

Input Language Description

cxn_list A comma-separated list of names. If no name is entered, all
connections within the current scope are printed. Wildcards may
be used in the names.

4 Specification Groups and Connections 87

 Printing Inactive Connections
This command is used to print the following items that are inactive:
 User connections.
 Product specific connections such as
Aspen Plus stream connections.
Aspen Plus HXFlux connections.
These may become inactive because the connection was disabled through the
product’s 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

Input Language Description

cxn_list A comma-separated list of names. If no name is entered, all
inactive connections within the current scope are printed.
Wildcards may be used in the names.

Printing Incomplete Connections

This command is used to print the following items that are incomplete:
 Spec Groups.
 User connections.
 Product specific connections such as
Aspen Plus stream connections.
Aspen Plus HXFlux 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

Input Language Description

cxn_list A comma-separated list of names. If no name is entered, all
incomplete connections within the current scope are printed.
Wildcards may be used in the names.

88 4 Specification Groups and Connections

 Printing Connection Variables
This command is used to locate variable references in the following:
 Spec Groups.
 User connections.
 Product specific connections such as
Aspen Plus stream connections.
Aspen Plus HXFlux connections.

Input Language
PRINT CONNECTION VARIABLES var_list

Input Language Description

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.

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.

4 Specification Groups and Connections 89

EO> PRINT VAR CONDUA.BLK.H_IN_TEMP
-index- ------variable------ -----lower---- ---value---- ----upper----- -----uom ------ -spec-
1430 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.

EO> PRINT VAR CONDUA.BLK.H_IN_TEMP

-index- ------variable------ -----lower---- ---value---- ----upper----- -----uom ------ -spec-
1430 CONDUA.BLK.H_IN_TEMP -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.

EO> PRINT VAR CONDUA.BLK.H_IN_TEMP

-index- ------variable------ -----lower---- ---value---- ----upper----- -----uom ------ -spec-
1430 CONDUA.BLK.H_IN_TEMP -1e+020 -20 1e+020 C Calc

90 4 Specification Groups and Connections

5 Measurements

This chapter describes the OOMF Script commands used to manipulate

measurements and measurement qualities.

Measurement Commands
Measurements are used to associate model variables with actual plant
measurements. Measurements are typically configured through the product’s
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

Input Language Description

meas_list A comma-separated list of names. If no name is entered, all
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

Input Language Description

meas_list A comma-separated list of names. If no name is entered, all
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.

92 5 Measurements
 Printing Measurements
Prints a list of measurements to the report device. This command uses the
following script parameters for controlling the format of portions of the
output: NAME_WIDTH, MEAS_TAG_WIDTH, MEAS_DESC_WIDTH,
MEAS_UOM_WIDTH, MEAS_NUMBER_WIDTH. Numbers are printed in a
“g” format (decimal or scientific notation depending on the magnitude of the
number).

Input Language
PRINT MEASUREMENTS meas_list

Input Language Description

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

Input Language Description

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- -Source-
C2MEAS.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,

5 Measurements 93
 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:
EO> PRINT BLOCK STAT
---Block-- -Nvar- -Neqn- -Nfix- Nexcld -Ndof- NfreeI --Nnz- --Nz%-
C2S 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 Pspec Ospec
-------- -------- ---------------- --- -------- --------- --------- --------- ----- -----
C2MEAS F F.BLK.MASS Y KG/HR 49000.000 50000.000 0.0 Const Const
C2MEAS XF F.BLK.C2H6_MOLE| Y UNITLESS 0.200 0.200 0.0 Const Const
C2MEAS D C2S.BLK.DISTILL| Y KG/HR 41000.000 39000.493 0.0 Meas Param
C2MEAS B C2S.BLK.BOTTOMS| Y KG/HR 12000.000 11000.000 0.0 Meas Param
C2MEAS RR C2S.BLK.REFL_RA| Y UNITLESS 4.300 4.000 0.0 Meas Param
C2MEAS XD C2S.D.STR.C2H6 Y FRACTION 1.0000e-4 2.1613e-4 0.0 Optim Const
C2MEAS XB C2S.B.STR.C2H4 Y FRACTION 1.5000e-2 4.2976e-2 0.0 Optim Const
C2MEAS C3R CIN.BLK.MASS Y KG/HR 140000. 150000. 0.0 Meas Param

EO> CHECK MEASUREMENTS

All measurements are correctly specified.

EO> DISABLE MEASUREMENT C2MEAS.C3R

1 measurement disabled.

EO> PRINT BLOCK STAT

---Block-- -Nvar- -Neqn- -Nfix- Nexcld -Ndof- NfreeI --Nnz- --Nz%-
C2S 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

EO> PRINT MEASUREMENTS

Current scope
Msmt ID Tagname Description Inc UOM Plant Model Offset Pspec Ospec
-------- -------- ---------------- --- -------- --------- --------- --------- ----- -----
C2MEAS F F.BLK.MASS Y KG/HR 49000.000 50000.000 0.0 Const Const
C2MEAS XF F.BLK.C2H6_MOLE| Y UNITLESS 0.200 0.200 0.0 Const Const
C2MEAS D C2S.BLK.DISTILL| Y KG/HR 41000.000 39000.493 0.0 Meas Param
C2MEAS B C2S.BLK.BOTTOMS| Y KG/HR 12000.000 11000.000 0.0 Meas Param
C2MEAS RR C2S.BLK.REFL_RA| Y UNITLESS 4.300 4.000 0.0 Meas Param
C2MEAS XD C2S.D.STR.C2H6 Y FRACTION 1.0000e-4 2.1613e-4 0.0 Optim Const
C2MEAS XB C2S.B.STR.C2H4 Y FRACTION 1.5000e-2 4.2976e-2 0.0 Optim Const
C2MEAS C3R CIN.BLK.MASS N KG/HR 140000. 150000. 0.0 Meas Param

EO> CHECK MEASUREMENTS

All measurements are correctly specified.

EO> PRINT INACTIVE SPEC GROUPS

0 inactive specification groups found.

94 5 Measurements
 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
bad measurements appear when the CHECK MEASUREMENTS command is
issued:
EO> DISABLE MEASUREMENT C2MEAS.XD
1 measurement disabled.

EO> PRINT BLOCK STAT

---Block-- -Nvar- -Neqn- -Nfix- Nexcld -Ndof- NfreeI --Nnz- --Nz%-
C2S 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

EO> PRINT MEASUREMENTS

Current scope
Msmt ID Tagname Description Inc UOM Plant Model Offset Pspec Ospec
-------- -------- ---------------- --- -------- --------- --------- --------- ----- -----
C2MEAS F F.BLK.MASS Y KG/HR 49000.000 50000.000 0.0 Const Calc
C2MEAS XF F.BLK.C2H6_MOLE| Y UNITLESS 0.200 0.200 0.0 Const Calc
C2MEAS D C2S.BLK.DISTILL| Y KG/HR 41000.000 39000.493 0.0 Const Calc
C2MEAS B C2S.BLK.BOTTOMS| Y KG/HR 12000.000 11000.000 0.0 Const Calc
C2MEAS RR C2S.BLK.REFL_RA| Y UNITLESS 4.300 4.000 0.0 Const Calc
C2MEAS XD C2S.D.STR.C2H6 N FRACTION 1.0000e-4 2.1613e-4 0.0 Const Calc
C2MEAS XB C2S.B.STR.C2H4 Y FRACTION 1.5000e-2 4.2976e-2 0.0 Const Calc
C2MEAS C3R CIN.BLK.MASS Y KG/HR 140000. 150000. 0.0 Const Calc

EO> CHECK MEASUREMENTS

The specifications for these measurements are not as expected:
Measurement -Connected?- -Model- -Source-
C2MEAS.XB Yes Calc Optim
C2MEAS.XF Yes Calc Const
C2MEAS.F Yes Calc Const

EO> PRINT INACTIVE SPEC GROUPS

<< 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]
[C2MEAS.BLK.C3R_PLANT,Meas]
[C2MEAS.BLK.C3R_OFFSET,Param]
[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]

5 Measurements 95
 [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.

EO> PRINT BLOCK STAT

---Block-- -Nvar- -Neqn- -Nfix- Nexcld -Ndof- NfreeI --Nnz- --Nz%-
C2S 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 Pspec Ospec
-------- -------- ---------------- --- -------- --------- --------- --------- ----- -----
C2MEAS F F.BLK.MASS Y KG/HR 49000.000 50000.000 0.0 Const Const
C2MEAS XF F.BLK.C2H6_MOLE| Y UNITLESS 0.200 0.200 0.0 Const Const
C2MEAS D C2S.BLK.DISTILL| Y KG/HR 41000.000 39000.493 0.0 Meas Param
C2MEAS B C2S.BLK.BOTTOMS| Y KG/HR 12000.000 11000.000 0.0 Meas Param
C2MEAS RR C2S.BLK.REFL_RA| Y UNITLESS 4.300 4.000 0.0 Meas Param
C2MEAS XD C2S.D.STR.C2H6 Y FRACTION 1.0000e-4 2.1613e-4 0.0 Optim Const
C2MEAS XB C2S.B.STR.C2H4 Y FRACTION 1.5000e-2 4.2976e-2 0.0 Optim Const
C2MEAS C3R CIN.BLK.MASS Y KG/HR 140000. 150000. 0.0 Meas Param

EO> CHECK MEASUREMENTS

All measurements are correctly specified.

EO> PRINT INACTIVE SPEC GROUPS

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:

96 5 Measurements
 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.
The BAD_STATUS_LIST contains a list of Specification Groups and Variable-
Specification 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 ], ...

5 Measurements 97
 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
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
PROCESS VARIABLE QUALITY
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

98 5 Measurements
 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>
If we reset the quality to GOOD and process again, the new Specification
Group is removed:
EO> C2HIER.C2MEAS.BLK.RR_PLANT.QUALITY = GOOD
EO> PROCESS VARIABLE QUALITY
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 variable’s 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
EO> PROCESS VARIABLE QUALITY
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 other 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"

Input Language Description

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.

6 Saving and Restoring 101

 These attributes can be used. (See the Variable Commands section for
descriptions.)
VALUE INITIAL LOWER UPPER
STEP BOUND SBWEIGHT SPEC
UNITS 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"

Input Language Description

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 Optional list of block names, variable names, stream names, or port names.
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 Name of file. The name must be in double quotation marks.
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 6 Saving and Restoring

 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.
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 FREE VARIABLES [ vmask ], list FROM "file"
RESTORE FREE VARIABLES EXCEPT [ vmask ], list FROM "file"

Input Language Description

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 Optional list of block names, variable names, stream names, or port names.
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 Name of file. The name must be in double quotation marks.
These attributes can be used. (See the Variable Commands section.)
VALUE INITIAL LOWER UPPER
STEP BOUND SBWEIGHT SPEC
UNITS 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"

Input Language Description

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 Name of file. The name must be in double quotation marks.

6 Saving and Restoring 103

 These attributes can be used. (See the Variable Commands section for
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, UOM_WIDTH, and NUMBER_WIDTH. Numbers in this file
are always printed in scientific notation. If the name or units width is
exceeded, the variable line wraps, with the remainder printed on a new line.
If the page width is exceeded, the file is broken into separate sections with
the variable names repeated.

Input Language
WRITE VARFILE [ vmask ], list TO "file"
WRITE VARFILE EXCEPT [ vmask ], list TO "file"

Input Language Description

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 Name of file. The name must be in double quotation marks.

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
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 6 Saving and Restoring

 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
READ VARFILE [ vmask ], list FROM "file"
READ VARFILE EXCEPT [ vmask ], list FROM "file"
READ VARFILE QUERY [QUERY], [ vmask ], list FROM "file"

Input Language Description

vmask Optional list of variable attributes to restore, separated by commas. Note that
this list is enclosed in brackets and followed by a comma. Variable names are
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 Optional list of block names, variable names, variable indices, stream names,
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 Name of file. The name must be in double quotation marks.
query A string containing the query enclosed in double quotation marks. Usually of
the form: "attribute = value"
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

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"

Input Language Description

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 Optional list of block names, variable names, variable indices, stream names,
or port names. The list is separated by commas. If no list is given, then all
variables within the current scope are compared.
file Name of file. The name must be in double quotation marks.

6 Saving and Restoring 105

 These attributes can be used. (See the Variable Commands section for
descriptions.)
UNITS LOWER BOUND SCALE
VALUE UPPER SPEC SBWEIGHT
INITIAL STEP

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

Input Language Description

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 Name of file. The name must be in double quotation marks.
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
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.

106 6 Saving and Restoring

 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"

Input Language Description

vmask Optional list of variable attributes to restore, separated by commas. Note that
this list is enclosed in brackets and followed by a comma. Variable names are
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 Optional list of block names, variable names, variable indices, stream names,
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 Name of file. The name must be in double quotation marks.
query A string containing the query enclosed in double quotation marks. Usually of
the form: "attribute = value"
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

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"

6 Saving and Restoring 107

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

Input Language Description

file Name of the file to which the simulation is to be saved.

108 6 Saving and Restoring

 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"

Input Language Description

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

Input Language Description

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"

Input Language Description

blk_nameName of the block to be saved.
file Name of the file to which the block is to be saved.

6 Saving and Restoring 109

 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"

Input Language Description

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

110 6 Saving and Restoring

 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>
<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"
minOccurs="0" maxOccurs="1"/>
<xs:element name="equations" type="equationsType"
minOccurs="0" maxOccurs="1"/>
<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">

6 Saving and Restoring 111

 <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"/>
</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:attribute name="name" use="required"/>
</xs:complexType>
<xs:complexType name="blocksType">
<xs:sequence>
<xs:element name="block" type="blockType" minOccurs="0"
maxOccurs="unbounded"/>
</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"
minOccurs="0" maxOccurs="1"/>
<xs:element name="connections" type="connectionsType"
minOccurs="0" maxOccurs="1"/>
<xs:element name="blockSpecificData" minOccurs="0"
maxOccurs="1"/>
</xs:all>
<xs:attribute name="name" use="required"/>
<xs:attribute name="type" use="required"/>
<xs:attribute name="modid" use="required"/>
<xs:attribute name="subid" use="optional"/>
<xs:attribute name="included" use="optional"/>
<xs:attribute name="category" use="optional"/>

112 6 Saving and Restoring

 <xs:attribute name="parent" use="optional"/>
</xs:complexType>
<xs:complexType name="blockAttributesType">
<xs:sequence>
<xs:element name="blockAttribute" type="blockAttributeType"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="blockPortsType">
<xs:sequence>
<xs:element name="blockPort" type="blockPortType"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="blockAttributeType">
<xs:attribute name="name" use="required"/>
<xs:attribute name="readOnly" use="required"/>
<xs:attribute name="modified" use="required"/>
<xs:attribute name="baseType" use="required"/>
<xs:attribute name="type" use="required"/>
<xs:attribute name="value" use="required"/>
</xs:complexType>
<xs:complexType name="blockPortType">
<xs:sequence>
<xs:element name="variables" type="portVariablesType"
minOccurs="1" maxOccurs="1"/>
</xs:sequence>
<xs:attribute name="name" use="required"/>
<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"
minOccurs="1" maxOccurs="unbounded"/>
</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"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="connectionType">
<xs:attribute name="name" use="required"/>
<xs:attribute name="connType" use="required"/>

6 Saving and Restoring 113

 <xs:attribute name="type" 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"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="variableType">
<xs:attribute name="index" use="required"/>
<xs:attribute name="name" use="required"/>
<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"/>
<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"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="equationType">
<xs:attribute name="index" use="required"/>
<xs:attribute name="name" use="required"/>
<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"
maxOccurs="unbounded"/>
</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="name" use="required"/>

114 6 Saving and Restoring

 <xs:attribute name="type" use="required"/>
<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"
maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="type" use="required"/>
</xs:complexType>
<xs:complexType name="termType">
<xs:attribute name="name" use="required"/>
<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"/>
<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"
maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="tagType">
<xs:attribute name="name" use="required"/>
</xs:complexType>
<xs:complexType name="solverType">
<xs:sequence>
<xs:element name="solverSetting" type="solverSettingType"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="name" use="required"/>
</xs:complexType>
<xs:complexType name="solverSettingType">
<xs:attribute name="type" use="required"/>
<xs:attribute name="name" use="required"/>
<xs:attribute name="value" use="required"/>
</xs:complexType>
</xs:schema>

Writing a Simulation to a XML File

This command is used to write a simulation to a XML file.

6 Saving and Restoring 115

 Input Language
WRITE SIMULATION TO "file"

Input Language Description

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"

Input Language Description

file Name of the file from which the simulation is to be loaded.

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"

Input Language Description

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"

Input Language Description

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.

116 6 Saving and Restoring

 Input Language
READ BLOCK blk_name FROM "file"

Input Language Description

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

6 Saving and Restoring 117

118 6 Saving and Restoring
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 variable’s 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

7 Objective Functions 119

 Input Language Description
Objective function attributes can be changed by referring to the objective
function by name along with its attribute. The allowed attributes are:
VALUE Value of the objective function. If you do not enter the units of measure,
SI units are assumed.
DIRECTION 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

Input Language Description

objid Name of the objective function

Evaluating the Objective Function’s

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

Input Language Description

objid Name of the objective function

Evaluating the Objective Function’s 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 7 Objective Functions

 Input Language Description
objid Name of the objective function

Printing the Objective Function

This command prints all terms in the objective function.

Input Language
PRINT OBJECTIVE objid

Input Language Description

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

Input Language Description

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

7 Objective Functions 121

 Input Language Description
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

Input Language Description

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

122 7 Objective Functions

 Input Language Description
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.
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 EQUATIONS list

Input Language Description

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.

7 Objective Functions 123

 Let’s 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

Let’s 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
3392 C2S.BLKEQN_PHSEQBL_59_C2H4 C2S.F.STR.MOLES 0.002919 -0.001528
3393 C2S.BLKEQN_PHSEQBL_59_C2H4 C2S.BLK.F.C2H4.FL_VMFRC 0.001769 0.0233
3403 C2S.BLKEQN_PHSEQBL_59_C2H4 C2S.BLK.EFF_1 -0.09316 0.01107

124 7 Objective Functions

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 ]

Input Language Description

obj Name of the objective function to compute sensitivity for. If omitted, the

8 Analysis 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 ]

Input Language Description

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.

126 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,
let’s 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) : 1489
unobservables (undetermined): 0
Number of redundants : 3
nonredundants : 0
You have a well defined problem.

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 let’s 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

Input Language Description

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,…

Input Language Description

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
 Input Language Description
parameter Name of the parameter to change.
value Value for the entered parameter.

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)
1 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:
0 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.
1 Normal mode. The Hessian is initialized with the identity matrix (default).
2 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.
3 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.
LINESEARCH Line search algorithm.
0 Exact penalty
1 Modified exact penalty method
2 Penalty with different weight update scheme
3 Penalty with modification for square cases (default)
4 Same as 3 modified to enforce bounds in square cases
FACTORSPEED LU factorization method.
1 Normal method. Optimizes pivot at every iteration (default).
2 Fast method. Uses original pivot sequence if possible. This can be faster.
In some cases (i.e. extreme phase changes) may cause additional
factorization.
USEDROPTOL Flag to indicate the use of the nonzero drop tolerance.
0 Do not drop small nonzeroes (default)
1 Drop small nonzeroes
DROPTOL 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)

130 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.
0 Do not save JDF file (default)
1 Save the JDF file
SCREENFORM Flag to modify the output format for the iteration log.
0 Format designed for direction into a file
1 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.
0 Do not scale variables
1 Scale variables (default)
PRINTFREQ 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.
0 No diagnostics (default)
1 Full diagnostics
QPSTATS Flag to indicate diagnostic printing level for the QP subproblem.
0 No diagnostics (default)
1 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
 Input Language Description
parameter Name of the parameter to change.
value Value for the entered parameter.

LSSQP Parameters
LSSQP Description
Parameter

KPTLEV History print level.

4 Summary information at each iteration (default)
5 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
6 Top worst merit function contributors
7 Full variable vector (potentially large amount of output)
8 Full constraint vector
KPFREQ 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 Description
Parameter

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:
0 Use general BFGS update to approximate the Hessian.
2 Always calculate Gauss-Newton-type Hessian approximation.
3 Use Gauss-Newton-type Hessian approximation for initialization but update it
with BFGS update.
4 Selectively choose between BFGS update or Gauss-Newton-type Hessian
approximation. (default=2 for DRPE, 0 for all other modes).
LEWBAS Type of basis for range-space representation. Allowed options follow:
0 Orthogonal basis (potentially more stable) (default)
1 Coordinate basis (less overhead especially for problems with large degree of
freedoms)
LSCOPT Line search options. Allowed options follow:
1 Same as option 3 for the first ITRBND iterations. Perform only step bounding
with CHGMAX thereafter.
2 Same as option 4 for the first ITRBND iterations. Perform only step bounding
with CHGMAX thereafter.
3 Exact penalty function.
4 Exact penalty function with Powell’s Watchdog relaxation (default).
5 Exact penalty function with second-order correction.
6 Exact penalty function with trust region control.
7 Exact penalty function with trust region control and second order correction.
IXSCS 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)
3 Derive variable scaling from initial x0; derive constraint scaling from Jacobian
4 No variable scaling; derive constraint scaling from Jacobian (default)
5 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.
1 Allow penalty parameter to be decrease gradually (default).
2 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 Description
Parameter

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
1 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 Don’t resize Hessian after first iteration; use identity matrix for initial Hessian.
1 Don’t 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 Matrix scaling frequency.
0 No matrix scaling.
1 Scale matrix before a basis selection (default).
2 Scale matrix before an analyze call.
3 Scale matrix before both basis selection and analysis calls.

134 8 Analysis
LSSQP Description
Parameter

MSMETH Matrix scaling method.

0 Scale with MC19AD.
1 Scale with row and then column equilibration (default).
2 Scale with column and then row equilibration.
KOWARM Warm start the optimization, not supported. (default=0).
LUBNDS Bounds present flag:
0 No
1 Yes (default)
LINCST Linear constraint flag:
0 No (default)
1 Yes
IFDTYP 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)
2 Same as 1 but drop bound contribution
3 Projected Hessian, multiplier version
4 Diagonal approximation, nonmultiplier version
5 Same as 4 but drop bound contribution
6 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 Description
Parameter

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).
1 Use numerical derivative for Jacobian.
2 Use numerical derivative for Jacobian and gradient.
3 Verify Jacobian at the initial point.
4 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.D-
6).
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

Input Language Description

parameter Name of the parameter to change.
value Value for the entered parameter.

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 “Powell’s Dogleg” or “One Dimensional Line-
Search” (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=
Powell’s 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 Powell’s Dogleg strategy
(when parameter Stabilization=0). The radius is automatically adjusted after
each iteration using Powell’s 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.

Input Language Description

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 SUMMARY
Number of variables: 1526
Number of incident variables: 1523
Number of fixed variables: 32
Number of free variables: 1491

9 Printing and Reports 139

 Number of equations: 1492
Number of included equations: 1492
Block equations: 1443
Connection equations: 49
Number of excluded equations: 0
Number of non-zeros: 7640
Number of incident non-zeros: 7261
Number of inactive connections: 0
Number of incomplete connections: 0
Problem is square

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 , …

Input Language Description

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 9 Printing and Reports

 Control Description
Character

\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 you’re 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.
0 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.

9 Printing and Reports 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 Upper \n"
PRINT FORMATTED "---- --- ----- ----- \n"
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

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 Low Value Upper
---- --- ----- -----
Top Comp 1e-05 0.0001 0.0002
Btm Comp 0.001 0.015 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 9 Printing and Reports

 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

Input Language Description

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:
+, -, *, /, ^, .
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, EXISTFILE, OPENBINARY,
DEVICEINFO, OPENTEE, VAL, TYPEOF, DEFINED, HEAD, TAIL,
BLOCKVARS, BLOCKATTRS, QUERYVARS, ALIASESBYVAR,
CONNECTIONSBYVAR, MEASUREMENTSBYVAR, SPECGROUPSBYVAR,
PORTVARS, QUERYSPECGROUPS
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

9 Printing and Reports 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

Input Language Description

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

Input Language Description

objid Name of the objective function to report.

144 9 Printing and Reports

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 XML-
based, 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 10 Support for Dynamic Models

 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>

Input Language Description

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>

Input Language Description

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>

10 Support for Dynamic Models 147

 Input Language Description
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>

Input Language Description

var_list A comma-separated list of variable names.

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>

Input Language Description

file A comma-separated list of variable names.

Viewing a variable history

This command is used to compute a variable’s 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>

Input Language Description

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

148 10 Support for Dynamic Models

 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>

Input Language Description

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>

Input Language Description

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>

Input Language Description

snapshot_id ID of the snapshot to be deleted

10 Support for Dynamic Models 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.

<?xml version="1.0" encoding="utf-8"?>

<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 10 Support for Dynamic Models

 <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>
<xs:extension base="TaskStatement">

10 Support for Dynamic Models 151

 <xs:sequence>
<xs:element name="Body" type="TaskBody" minOccurs="1"
maxOccurs="1" />
<xs:element name="False" type="Conditional"
minOccurs="0" maxOccurs="1" />
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="CreateSnapshot">
<xs:complexContent>
<xs:extension base="TaskStatement">
<xs:sequence />
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="Wait">
<xs:complexContent>
<xs:extension base="TaskStatement">
<xs:sequence />
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="WaitFor">
<xs:complexContent>
<xs:extension base="TaskStatement">
<xs:sequence />
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="Parallel" mixed="true">
<xs:complexContent>
<xs:extension base="TaskStatement">
<xs:sequence>
<xs:element name="Body" type="TaskBody" minOccurs="1"
maxOccurs="1" />
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="Pause">
<xs:complexContent>
<xs:extension base="TaskStatement">
<xs:sequence />
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="Print" mixed="true">
<xs:complexContent>
<xs:extension base="TaskStatement">
<xs:sequence>
<xs:element name="Arg" type="xs:string" minOccurs="0"
maxOccurs="unbounded" />
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>

152 10 Support for Dynamic Models

 <xs:complexType name="Ramp">
<xs:complexContent>
<xs:extension base="TaskStatement">
<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:complexContent>
</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:extension base="TaskStatement">
<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:complexContent>
</xs:complexType>
<xs:complexType name="Return">
<xs:complexContent>
<xs:extension base="TaskStatement">
<xs:sequence />
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="Invoke" mixed="true">
<xs:complexContent>
<xs:extension base="TaskStatement">
<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>

10 Support for Dynamic Models 153

 </xs:complexContent>
</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:extension base="TaskStatement">
<xs:sequence />
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="For" mixed="true">
<xs:complexContent>
<xs:extension base="TaskStatement">
<xs:sequence>
<xs:element name="Body" type="TaskBody" minOccurs="1"
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:complexContent>
</xs:complexType>
</xs:schema>

154 10 Support for Dynamic Models

 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:
<?xml version="1.0" encoding="utf-8"?>
<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:
<?xml version="1.0" encoding="utf-8"?>
<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.

10 Support for Dynamic Models 155

 Suspending a task
The following example depicts how to suspend a task:
<?xml version="1.0" encoding="utf-8"?>
<Tasks>
<Task name="Task1" active="true" once="true" time="0.0">
<Body>
<WaitFor> ‘B1.M’ &gt; 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:
<?xml version="1.0" encoding="utf-8"?>
<Tasks>
<Task name="Task1" active="true" once="true" time="0.0">
<Body>
<If> 'B1.M' &lt;= 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 10 Support for Dynamic Models

 Using a FOR loop in a task
The following example depicts how to use a FOR loop within a task:
<?xml version="1.0" encoding="utf-8"?>
<Tasks>
<Task name="Task1" active="true" once="true" time="0.0">
<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:
<?xml version="1.0" encoding="utf-8"?>
<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.

10 Support for Dynamic Models 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:
<?xml version="1.0" encoding="utf-8"?>
<Tasks>
<Task name="ImplicitTask" active="true" once="true">
<When>B1.Z &lt; 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 10 Support for Dynamic Models

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 variable’s units of measure.

Changing a Variable's Units of Measure

A variable’s 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}

Input Language Description

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

Input Language Description

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}

Input Language Description

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 11 Units of Measure, Physical Types and Connection Types

 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

ACCELERATION 132 M/SQSEC FT/SQSEC M/SQSEC

ANGLE 32 RAD DEG DEG
AREA 1 SQM SQFT SQM SQCM, SQIN, SQMILE,
SQMM
AREA-PRICE 54 $/SQM $/SQFT $/SQM $/SQCM, $/SQIN,
$/SQMILE, $/SQMM
AREA-SQTIME 134 SQM/SQSEC SQFT/SQSEC SQM/SQSEC SQMM/SQSEC,
SQIN/SQSEC
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 2 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 K F K C, R, DELTA-K, DELTA-F,
DELTA-C, DELTA-R
DENSITY 3 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, KPA-
GAUGE, MPA-GAUGE

11 Units of Measure, Physical Types and Connection Types 161

Type of Units Code SI Set ENG Set MET Set Other Units Options

DIFFUSIVITY 4 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, C*M
ELEC-POWER 47 WATT KW KW
ELEC-PRICE 48 $/J $/KWHR $/KWHR
ENERGY 5 J 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, $/FT-
LBF, $/GCAL, $/MMBTU,
$/HP-HR, $/MBTU, $/KJ,
$/MJ, $/GJ, $/N-M,
$/MCAL
ENERGY-VOL 117 CUM/J BBL/BTU BBL/MMBTU
ENTHALPY 6 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/OP-
HR, MMPCU/OP-HR,
KJ/OP-SEC, KW/CYCLE,
GCAL/OP-HR, GCAL/OP-
DAY
ENTROPY 7 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 (KG- (LB- (GM-L)**.5/MIN (LB-GAL)**.5/MIN
CUM)**.5/SEC CUFT)**.5/HR
FILTER-RESIS 35 1/METER 1/FT 1/METER 1/CM, 1/IN

162 11 Units of Measure, Physical Types and Connection Types

Type of Units Code SI Set ENG Set MET Set Other Units Options

FISCAL 8 $ $ $
FLOW 9 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, L-
TONS/MIN, L-TONS/HR, L-
TONS/DAY, ML-
TONS/YEAR, MML-
TONS/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/HR-
SQFT, KW/SQM
FLUX-MOLE 121 KMOL/SQM-S LBMOL/SQFT-HR KMOL/SQM-HR LBMOL/SQFT-S,
MOL/SQCM-S
FORCE 14 NEWTON LBF DYNE
FREQUENCY 28 HZ RPM RPM RAD/SEC, RPS, KRPM,
MMRPM, RPH
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, KM-
KGF/KG, MFT, MJ/KG,
MFT-LBF/LB, FT-HEAD,
METER-HEAD, INCH-HEAD
HEAT 53 J 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/HR-
FT,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/HR-
SQFT
HEAT-RATE-V 122 WATT/CUM BTU/HR-CUFT CAL/SEC-CUM J/SEC-CUM, MMBTU/HR-
CUFT, GJ/HR-CUM

11 Units of Measure, Physical Types and Connection Types 163

Type of Units Code SI Set ENG Set MET Set Other Units Options

HEAT-TRANS-C 16 WATT/SQM-K BTU/HR-SQFT-R CAL/SEC-SQCM- KCAL/SEC-SQM-K,

K KCAL/HR-SQM-K, PCU/HR-
SQFT-K, KW/SQM-K,
J/SEC-SQM-K, KJ/SEC-
SQM-K, MMBTU/HR-SQFT-
R, KJ/SEC-SQM-C,
MJ/SEC-SQM-K, MJ/SEC-
SQM-C, GJ/HR-SQM-K,
GJ/HR-SQM-C, KCAL/HR-
SQM-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-SQCM- SEC-SQM-K/KCAL, HR-
K/CAL SQM-K/KCAL, HR-SQFT-
K/PCU, SQM-K/KW, SEC-
SQM-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 1/MIN, 1/DAY, 1/YEAR
INVERSE-VEL 130 SEC/M SEC/FT SEC/CM SEC/IN, SEC/MM
ITEM-PRICE 56 $/ITEM $/ITEM $/ITEM
LENGTH 17 METER FT METER CM, IN, MU, MM, MILE,
KM, ANGSTROM, MFT
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, L-
TON, MMLB
MASS-CONC 58 KG/CUM LB/CUFT GM/L GM/CC, MG/L, MG/CC
MASS-CONTENT 133 KG/KG_DRY LB/LB_DRY KG/KG_DRY
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-EMISSIO 129 KG/J LB/BTU KG/CAL TONNE/GJ,
TONNE/MMBTU, KG/KCAL,
KG/GJ, KG/KJ, KG/MJ,
KG/MMKCAL,
TONNE/MMKCAL,
KG/MMBTU, G/MJ,
LB/MMBTU, TONNE/TJ
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

164 11 Units of Measure, Physical Types and Connection Types

Type of Units Code SI Set ENG Set MET Set Other Units Options

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
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, L-
TONS/MIN, L-TONS/HR, L-
TONS/DAY, ML-
TONS/YEAR, MML-
TONS/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/SQFT-
HR, TONS/SQFT-HR, L-
TONS/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/OP-
SEC, 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-SQM- LB/HR-SQF- GM/S-SQCM-
KG/CUM LB/CUF GM/CC
MASS-VOLUME 115 CUM/KG CUFT/LB CC/G BPD/MLBPH, CC/KG
MOLAR-PERM 90 KMOL/SQM- LBMOL/SQFT-HR- KMOL/SQM-HR- LBMOL/SQFT-HR-ATM,
SEC0PA PSI 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/SEC-
FT, LBMOL/DAY-FT,
KMOL/DAY-M, MOL/MIN-M

11 Units of Measure, Physical Types and Connection Types 165

Type of Units Code SI Set ENG Set MET Set Other Units Options

MOLE-AREA 135 SQM/KMOL SQFT/LBMOL SQM/KMOL SQFT/MOL, SQCM/MOL,

SQIN/MOL, SQMM/MOL,
SQFT/KMOL, SQCM/KMOL,
SQIN/KMOL, SQMM/KMOL,
SQIN/LBMOL
MOLE-CONC 64 KMOL/CUM LBMOL/CUFT MOL/CC MOL/L, MMOL/CC, MMOL/L
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/OPER-
YEAR
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/MOL-
K, PCU/LBMOL-K,
KJ/KMOL-K, BTU/LBMOL-F

166 11 Units of Measure, Physical Types and Connection Types

Type of Units Code SI Set ENG Set MET Set Other Units Options

MOLE-OPER 107 KMOL/OP-SEC LBMOL/OP-HR KMOL/OP-HR MMSCF/CYCLE-HR,

MMSCM/CYCLE-HR,
MOL/OP-SEC, LBMOL/OP-
SEC, SCM/CYCLE-HR,
LBMOL/OP-DAY,
KMOL/OP-DAY,
MMSCF/CYCLE-DAY,
SCF/CYCLE-MIN
MOLE-PRICE 125 $/KMOL $/LBMOL $/MOL
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/CUM-
SEC, 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 57 NO/CUM NO/CUFT NO/L NO/CC, 1E6/CC
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, IN-
WATER, KG/SQCM, MMHG,
KPA, MM-WATER, MBAR,
IN-WATER-60F, IN-HG,
LB/FT-SQSEC, KG/M-
SQSEC, 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/1000-
FT, 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, FT-
LBF/SEC, MW, GW, MJ/HR,
KCAL/HR, GCAL/HR,
MMBTU/HR, MBTU/HR,
MHP
POWER-AREA 127 WATT/SQM HP/SQFT KW/SQM W/SQCM, KW/SQCM
POWER-MASS 128 WATT/KG HP/LB KW/KG W/G, KW/G, MW/KG
POWER- 65 WATT/CUM HP/CUFT KW/L KW/CUM
VOLUME

11 Units of Measure, Physical Types and Connection Types 167

Type of Units Code SI Set ENG Set MET Set Other Units Options

PRESSURE 20 N/SQM PSIA ATM LBF/SQFT, BAR, TORR, IN-

WATER, KG/SQCM, MMHG,
KPA, MM-WATER, MBAR,
PSIG, ATMG, BARG,
KG/SQCMG, LB/FT-
SQSEC, KG/M-SQSEC, PA,
MPA, PAG, KPAG, MPAG,
MBARG, IN-HG, MMHG-
VAC, IN-HG-VAC, IN-
WATER-60F, IN-WATER-
VAC, IN-WATER-60F-VAC,
IN-WATER-G, IN-WATER-
60F-G, MM-WATER-G,
MM-WATER-60F-G, PSI,
MM-WATER-60F
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-HR- GM/SQCM-S-ATM,
ATM GM/SQCM-S-PA
SOUND-LEVEL 111 DECIBELS DECIBELS DECIBELS
SPEC-FLT-RES 36 METER/KG FT/LB METER/KG CM/GM
SPEC-MAT-RES 131 KG/J-M LB/BTU-FT GM/CAL-CM
SPECIFICAREA 67 SQM/CUM SQFT/CUFT SQCM/CC
SURFACE-TENS 21 N/M DYNE/CM DYNE/CM LBF/FT, MN/M
TEMP-VOLUME 83 CUM-K/KMOL CUFT-R/LBMOL CC-K/MOL
TEMPERATURE 22 K F K C, R
THERMAL-COND 23 WATT/M-K BTU-FT/HR- KCAL-M/HR- BTU-IN/HR-SQFT-R, C-
SQFT-R SQM-K CM/SEC-SQCM-K, CAL-
CM/SEC-SQCM-K,
BTU/HR-FT-R, KCAL/HR-
M-K, J/SEC-M-K, KW/M-K,
BTU-FT/HR-SQFT-F, BTU-
IN/HR-SQFT-F, BTU/HR-
FT-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, $/L-
TON, $/TONNE, $/MMLB
USR-DUMMY0 90
USR-DUMMY1 91
USR-DUMMY2 92
USR-DUMMY3 93
USR-DUMMY4 94

168 11 Units of Measure, Physical Types and Connection Types

Type of Units Code SI Set ENG Set MET Set Other Units Options

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
VFLOW-LENGTH 84 SQM/SEC GPM/FT SQCM/SEC SQM/HR, SQFT/MIN
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, DYN-
SEC/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/CUM-
F, KW/CUM-K, KW/CUM-C,
BTU/HR-CUFT-F
VOLTAGE 113 VOLT KVOLT
VOLUME 27 CUM CUFT L 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

11 Units of Measure, Physical Types and Connection Types 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/OP-
HR, CUFT/OP-SEC,
CUM/OP-DAY, CUM/OP-
YEAR, L/OP-HR, KBBL/OP-
DAY, 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
VOLUME-USAGE 63 CUM/SEC CUFT/HR L/HR L/DAY, L/YEAR, CUM/HR,
CUM/DAY, CUM/YEAR
WATER-RATE 73 KG/J LB/HP-HR KG/KW-HR
WORK 52 J 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:
Units Description

MM Used as a prefix meaning million before many units, such as

MMBTU = million BTU.
M 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).

170 11 Units of Measure, Physical Types and Connection Types

 Units Description

CU Used as a prefix meaning cubed, as in CUM (cubic meters). The

common abbreviation CC is used for cubic centimeters.
G 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, These units represent pressure in inches of water. IN-WATER is
IN-WATER-60F 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

0 UNTYPED
1 AREA (SQM)
2 COMPOSITION
3 MASS-DENSITY (KG/CUM)
4 DIFFUSIVITY (SQM/SEC)
5 ENERGY (J)
6 ENTHALPY (J/KMOL)

11 Units of Measure, Physical Types and Connection Types 171

 Type Code Physical Type

7 ENTROPY (J/KMOL-K)
8 FISCAL ($)
9 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)

172 11 Units of Measure, Physical Types and Connection Types

 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

11 Units of Measure, Physical Types and Connection Types 173

 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
127 POWER-AREA
128 POWER-MASS
129 MASS-EMISSIO (KG/J)
130 INVERSE-VEL (SEC/M)
131 SPEC-MAT-RES (KG/J-M)
132 ACCELERATION
133 MASS-CONTENT (KG/KG_DRY)
134 AREA-SQTIME
135 MOLE-AREA

174 11 Units of Measure, Physical Types and Connection Types

 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

1 AROM-FACTOR
2 ANILINE-PT
3 API
4 AROM-BY-VOL
5 BASIC-N2-CONT
6 BENZ-BY-VOL
7 CON-11
8 CON-CLEAR
9 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

11 Units of Measure, Physical Types and Connection Types 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 11 Units of Measure, Physical Types and Connection Types

 Connection Type Commands
These commands allow you to change a variable’s connection type.

Changing a Variable's Connection Type

A variable’s connection type may be changed by its conn_type attribute.

Input Language
variableid.conn_type = {conn_type}

Input Language Description

variableid Variable name.
Conn_type Connection type. The connection type must be one from table presented
earlier.

11 Units of Measure, Physical Types and Connection Types 177

178 11 Units of Measure, Physical Types and Connection Types
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.
OOMF’s default implementation of the abstract class AMFEOBlock,
AMFEOBlockImpl, provides all the necessary functionality. All OOMF

12 Global Structures 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 12 Global Structures

 reset scope
print var
print eqn
print jac
solver dmo
dmo.rescvg=1e-8
solve
print var
push scope hier
add block b3 as amodel
//Assign the global structure parameter name in block B3 to be
the global structure instance named “B1”
B3.MYSTRUCT="B1"
reset scope
add block b4 as amodel
//Assign the global structure parameter name in block B4 to be
the global structure instance named “B1”
B4.MYSTRUCT="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

12 Global Structures 181

182 12 Global Structures
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

Input Language Description

filename Aspen Properties or Aspen Plus 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

Input Language Description

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.

13 Aspen Properties Data 183

 Input Language
SWAP PROPERTY list

Input Language Description

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 13 Aspen Properties Data

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.

Using the Interactive Prompt

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

14 Aspen Plus Extensions 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:
 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.

186 14 Aspen Plus Extensions

 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 block’s
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 post-
solve 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

14 Aspen Plus Extensions 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.
You may pass arguments to the invoked script and get a returned value.

Input Language
INVOKELOCAL scriptid, arg1, arg2, …

Input Language Description

scriptid Name of a local script to execute.
arg1, Optional list of arguments passed to the script. This may be referenced in the
arg2 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 Global Script

A global script may be invoked with this command. Global scripts are
available everywhere, regardless of the scope where they are defined.
You may pass arguments to the invoked script and get a returned value.

Input Language
INVOKEGLOBAL scriptid, arg1, arg2, …

Input Language Description

scriptid Name of a global script to execute.
arg1, Optional list of arguments passed to the script. This may be referenced in the
arg2 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.
See Also
Standard OOMF - Invoke Commands

188 14 Aspen Plus Extensions

 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.

14 Aspen Plus Extensions 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

Input Language Description

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 14 Aspen Plus Extensions

 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 block’s 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

Input Language Description

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.
When the status of an HXFlux connection is changed, Spec Management
automatically reprocesses all the Connections and Spec Groups to ensure that

14 Aspen Plus Extensions 191

 the problem remains square. (The Status on the GUI is not updated until an
Incremental Build or Solve is performed.)

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

Input Language Description

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 14 Aspen Plus Extensions

 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

Input Language Description

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

14 Aspen Plus Extensions 193

194 14 Aspen Plus Extensions
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 directly in standalone OOMF.

Using the Interactive Prompt

You can enter script commands interactively into the OOMF kernel.
1 Click Start | Run, type cmd and click OK to open a command window.
2 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 V8.0\Xeq;C:\Program
Files\AspenTech\AMSystem V8.0\Bin;%path%
3 Type oomf.exe and press enter.
You can now type commands at the OOMF prompt.

See Also
Standard OOMF - Using the Interactive Prompt

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.
The examples which follow assume that the name of the model that you
exported is MyModel 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.

ACM Models Without Aspen Properties

1 Export the model from ACM and install it on your PC by following the
instructions given in the ACM user guide.
2 Start an interactive OOMF session as per the instructions in the previous
section.
3 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")
5 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

ACM Models Using Aspen Properties

See Chapter 13 Aspen Properties Data for more details about the OOMF
commands related to working with Aspen Properties files. If the exported ACM
model requires Aspen Properties to evaluate physical properties of
components:
1 Begin by following steps 1 to 4 of the procedure above for ACM models
without Aspen Properties, which brings you to the point of having the ACM
model instantiated in OOMF.
2 Reference a local properties file (one which has previously been exported
from Aspen Properties as a .aprpdf file) with the commands:

196 15 Aspen Custom Modeler Models Related Extensions

 local PROPFILE = "C:\AMModels\MyModel\MyModel.aprpdf"
initaprop &PROPFILE
3 The ACM model implements a host components manager with the default
component list from the Aspen Properties or Aspen Plus file. If you need to
create your own component list, enter this command:
add complist comp_list_name, [components]
Where comp_list_name is the name of the new component list and
components is a list of components in that list.
There must not already be a component list named comp_list_name. The
new list created is a child of the *DEFAULT list and inherits all options
from it. All the specified components must be present in the *DEFAULT
list. All component names must be legal OOMF IDs.
Block-specific component lists can be added (using the name of the ACM
block as the name of the component list), but for general usage a
wildcarded name should be used so all ACM blocks can find it. For
example:
add complist *C2S, [ETHANE, ETHYLENE]
4 Perform steps 5 to 7 of the procedure for ACM models without Aspen
Properties to solve the model.
It is also possible to print a component list to the console. This is useful for
debugging. Use the command:
print complist comp_list_name

15 Aspen Custom Modeler Models Related Extensions 197

 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 don’t 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 (Read Only) The type of solution that the model is currently
instantiated under.
 Equation Oriented
 Sequential Modular
SM_Status (Read Only) The status of the block under its sequential modular
container:
 Incomplete – the block hasn’t 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
EO_Status (Read Only) The status of the block under its equation oriented
container
 Incomplete – the block hasn’t 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
DOF (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.

198 15 Aspen Custom Modeler Models Related Extensions

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.

Using the Interactive Prompt

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
Standard OOMF - Using the Interactive Prompt

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, 161 ANALYZE SPARSITY script

. script function, 40 command, 122
^ script function, 39 ANALYZE VARIABLES script
< script function, 41 command, 127
<= script function, 41 AND script function, 41
<> script function, 41 AspenTech support, 7
= script function, 41 AspenTech Support Center, 7
> script function, 41 BAD_STATUS_LIST script
>= script function, 41 parameter, 97
ABS script function, 39 BASFLP LSSQP parameter, 135
ACM models BIGBND LSSQP parameter, 135
adding to OOMF, 197 BIGSCL LSSQP parameter, 135
Activating a variable profile Block Commands
script command, 148 Attributes
ACTIVESPACE DMO parameter, 132 Aspen Custom Modeler, 198
adding ACM models to OOMF, 197 Changing, 65
ALFALS LSSQP parameter, 133 Printing, 65, 66
Alias Commands Derivative method. See Block
Printing alias definitions, 75 Commands: Attributes
Printing alias values, 75 Printing, 124
Printing alias variables, 76 Excluding blocks, 62
ALIAS script command, 75 Finding in a hierarchy, 59
ALIASBYVAR script function, 42 Including blocks, 63
Analysis Commands Listing block scripts, 63
Analyzing Equations, 128 Listing blocks, 62
Analyzing Variables, 127 Printing block convergence, 64
Checking degrees of freedom, Printing block statistics, 64
126 BLOCK SCRIPTS script command,
Sensitivity Analysis, 126 63
ANALYSISTHRES DMO parameter, BLOCKATTRS script function, 42
132 BLOCKS script command, 62
ANALYZE DOF script command, BLOCKS script parameter, 27
126 BLOCKVARS script function, 42
ANALYZE EQUATIONS script BNDADJ LSSQP parameter, 135
command, 128 BNDAPP LSSQP parameter, 134
ANALYZE JACOBIAN script BOUND variable attribute, 68
command, 122 Bound_iterations NSOLVE
parameter, 137

Index 201
 BSMALL LSSQP parameter, 135 customer support, 7
BUILD_DATE script parameter, DATE script parameter, 27
27, 146 DEFAULT_FLUSHING script
BUILD_NUMBER script parameter, parameter, 24, 27
27, 146 DEFINED script function, 42
Built-In script parameters, 27 Degrees of freedom, checking, 126
CHANGE FLUSHING script Deleting a snapshot
command, 24 script command, 150
CHANGE SCOPE script command, Deleting a task
58 script command, 148
CHANGE variable attribute, 68 DELTLS LSSQP parameter, 135
CHECK CONNECTIONS script DERDIF LSSQP parameter, 137
command, 88 DERIV_METHOD block attribute, 65
CHECK MEASUREMENT script Derivative Commands. See
command, 92 Jacobian and Derivative
Check_steps NSOLVE parameter, Commands
138 DERIVATIVE script command, 124
CHECK_UOM script parameter, 27 DERMIN LSSQP parameter, 137
CHGBND LSSQP parameter, 133 DEVICEINFO script function, 41
CHGMAX LSSQP parameter, 133 DIAG_LEVEL script parameter, 27
Command Line Prompt, Using, 4 DIRECTION Objective function
Command Line Prompt, Using in attribute, 120
Aspen Plus, 186 DISABLE CONNECTION script
Command Line Prompt, Using in command, 87
RefSYS, 200 DISABLE HXFLUX script command,
Command Line Prompt, Using with 192
ACM Models, 196 DISABLE MEASUREMENT script
COMPARE VARFILE script command, 93
command, 106 DISABLE SPECIFICATION GROUPS
Connection Commands script command, 81
Checking connections, 88 DISABLE STREAMS script
Disabling connections, 87 command, 191
Enabling connections, 87 Divergent_steps NSOLVE
Printing connection variables, 90 parameter, 137
Printing connections, 88 DMO script command, 130
Printing inactive connections, 89 DPERTF LSSQP parameter, 137
Printing incomplete connections, DROPTOL DMO parameter, 131
89 DYN_INTERVAL
Removing Connections, 85, 86 script parameter, 146
Connections DYN_RUN_TO
And variable specifications, 85 script parameter, 146
CONNECTIONS script command, 88 e-bulletins, 7
CONNECTIONSBYVAR script ECHO script command, 144
function, 42 ENABLE CONNECTION script
Controlling kernel command, 87
Defined, 56 ENABLE HXFLUX script command,
CONVERGED script parameter, 27 193
COS script function, 39 ENABLE MEASUREMENT script
CREEPFLAG DMO parameter, 131 command, 93
CREEPITER DMO parameter, 131 ENABLE SPECIFICATION GROUP
CREEPSIZE DMO parameter, 131 script command, 81
Crude blends ENABLE STREAMS script command,
Update script command, 190 191

202 Index
 Equal to (=) script function, 41 FLUSH script command, 24
Equation Commands FOR-DO script command, 36
Evaluating, 77 Formatted printing, 141
Excluding, 77 Freeing Properties Data
Including, 77 script command, 184
Printing, 78 FSCALF LSSQP parameter, 135
Printing largest, 78 Function_tolerance NSOLVE
Printing largest residual prices, parameter, 138
79 Global script parameters, 26
ETASKP LSSQP parameter, 135 Global Scripts
EVALUATE JACOBIAN script Defining, 5, 187
command, 123 Invoking, 189
EVALUATE OBJECTIVE DERIVATIVE GNPMAX LSSQP parameter, 134
script command, 121 Greater than (>) script function,
EVALUATE OBJECTIVE HESSIAN 41
script command, 121 Greater than or equal to (>=)
EVALUATE OBJECTIVE script script function, 41
command, 121 HEAD script function, 42
EXCLUDE BLOCKS script command, help desk, 7
62 HELP script command, 51
EXISTFILE script function, 41 HESSIANUPDATES DMO
EXIT script command, 51 parameter, 132
EXP script function, 39 Hierarchies
FACTORSPACE DMO parameter, Defining the scope, 58
132 Finding a block, 59
FACTORSPREED DMO parameter, Printing the hierarchy, 59
131 Solving a hierarchy, 60
File Commands HISTORY_DEVICE script
Comparing variables with an parameter, 23, 27
ASCII file, 106 HXFlux Commands
Restoring free variables from a Controlling HXFlux Connections,
binary file, 104 192
Restoring variables and block Disabling HXFlux Connections,
attributes from an ASCII file, 192
107 Enabling HXFlux Connections,
Restoring variables from a binary 193
file, 103, 109, 110, 111, 116, HXFLUX script command, 192
117 ID2STRING script function, 40
Restoring variables from an IFDITR LSSQP parameter, 136
ASCII file, 105 IFDTYP LSSQP parameter, 136,
Saving variables and block 137
attributes to an ASCII file, IF-THEN-ELSE script command, 35
107 Inactivating a variable profile
Saving variables to a binary file, script command, 149
102 INCLUDE BLOCKS script command,
Saving variables to an ASCII file, 63
105 INCLUDED block attribute, 65
Updating variables in a binary INCLUDED Equation attribute, 77
file, 104 INDEX script function, 40
File script functions, 41 INITIAL variable attribute, 68
FIND BLOCK script command, 59 Input Language Rules, 6
FLANGE_PHASE script parameter, INSERTSTR script function, 40
27 INT script function, 39

Index 203
 Interactive Prompt, Using, 4 LINCST LSSQP parameter, 136
Interactive Prompt, Using in Aspen LINESEARCH DMO parameter, 131
Plus, 186 list concatenation script function,
Interactive Prompt, Using in 42
RefSYS, 200 List script functions, 42
Interactive Prompt, Using with ACM Loading a snapshot
Models, 196 script command, 150
INVOKE command, 33 Loading Properties Data
Invoke Commands script command, 184
Invoking a block script, 33 Loading task definitions
Invoking a global script, 189 script command, 148
Invoking a local script, 189 LOCAL script command, 29
Invoking an external file, 33 Local script parameters, 27
Invoking scripts within a scope, Local Scripts
34 Defining, 5, 187
Using script arguments, 34 Invoking, 189
INVOKEGLOBAL command, 189 LOG10 script function, 39
INVOKELOCAL command, 189 LOGE script function, 39
ITRBND LSSQP parameter, 133 Logical script functions, 41
IWORKF DMO parameter, 132 LOWER variable attribute, 68
Jacobian and Derivative Commands LSCOPT LSSQP parameter, 134
Analyzing the Jacobian, 122 LSIZEB LSSQP parameter, 135
Analyzing the Jacobian Sparsity, LSSQP script command, 132
122 LUBNDS LSSQP parameter, 136
Evaluating the Jacobian, 123 LUSTATS DMO parameter, 132
Printing block derivative MAJOR_VERSION script parameter,
methods, 124 28
Printing the Jacobian, 123 Mathematical script functions, 39
Printing the Jacobian equations, Maximum_function_error NSOLVE
124 parameter, 138
Printing the Jacobian variables, Maximum_iterations NSOLVE
123 Parameter, 137
JOURNAL_DEVICE script MAXITER DMO parameter, 131
parameter, 24, 28 MAXITR LSSQP parameter, 133
JOURNAL_LEVEL script parameter, MAXLSC LSSQP parameter, 133
24, 28 MAXQPF LSSQP parameter, 134
Journaling. See Redirecting Output MAXSLF LSSQP parameter, 133
and Journaling MDHESS LSSQP parameter, 134
KBKOUT LSSQP parameter, 136 MEAS_CAPACITY script parameter,
KFOWDG LSSQP parameter, 136 28
KMUDEC LSSQP parameter, 134 Measurement Commands
KOWARM LSSQP parameter, 136 Checking measurements, 92
KPFREQ LSSQP parameter, 133 Disabling measurements, 93
KPNTOP LSSQP parameter, 133 Enabling measurements, 93
KPTLEV Measurement Qualities, 97
IXSCS Parameter, 134 Printing measurements, 94
KPTLEV LSSQP Parameter, 133 Printing measurements variables,
LCHBAS LSSQP parameter, 135 94
LENGTH script function, 40 MEASUREMENTSBYVAR script
Less than (<) script function, 41 function, 42
Less than or equal to (<=) script Methods
function, 41 Defined, 5, 187
LEWBAS LSSQP parameter, 134 MINITER DMO parameter, 131

204 Index
 MINITR LSSQP parameter, 133 PRINT ACTIVE_BOUNDS script
MINOR_VERSION script parameter, command, 72
28 PRINT ACTIVE_BOUNDS SSI script
MODE script parameter, 28 command, 72
Modes PRINT ALIAS script command, 75
script parameter for, 28 PRINT ALIAS VARIABLES script
MOVE block attribute, 65 command, 76
MOVEAMOUNT block attribute, 65 PRINT BLOCK ATTRIBUTES script
MSFREQ LSSQP parameter, 135 command, 65, 66
MSMETH LSSQP parameter, 136 PRINT BLOCK CONVERGENCE
NAME_WIDTH script parameter, 28 script command, 64
NBDBAS LSSQP parameter, 136 PRINT BLOCK HIERARCHY script
NFEASB LSSQP parameter, 133 command, 59
NFINFB LSSQP parameter, 133 PRINT BLOCK PORTS DETAILED
NICHK LSSQP parameter, 136 script command, 83
NLRATIODEV block attribute, 65 PRINT BLOCK PORTS script
NNDCMP LSSQP parameter, 135 command, 83
Not equal to (<>) script function, PRINT BLOCK STATISTICS FULL
41 script command, 64
NOT script function, 41 PRINT BLOCK STATISTICS script
NSOLVE script command, 137 command, 64
NUMBER_WIDTH script parameter, Print Commands
28 Formatted printing, 141
OBJCVG DMO parameter, 132 Miscellaneous print commands,
Objective Function Commands 144
Attributes, 120 Printing problem convergence,
Evaluating the objective function, 140
121 Printing the problem summary,
Evaluating the objective 140
function’s derivatives, 121 PRINT CONNECTION VARIABLES
Evaluating the objective script command, 90
function’s Hessian, 121 PRINT CONVERGENCE SUMMARY
Printing the objective function, script command, 140
122 PRINT EQUATIONS script
OBJECTIVE script parameter, 28 command, 78
ONLINE script parameter, 28 PRINT FIXED script command, 71
OPENBINARY script function, 41 PRINT FLUSHING script command,
OPENFILE script function, 41 24
OPENTEE script function, 41 PRINT FORMATTED script
OR script function, 41 command, 141
P_AMB script parameter, 28 PRINT INACTIVE CONNECTIONS
Pausing a simulation script command, 89
script command, 147 PRINT INACTIVE SPECIFICATION
PERT block attribute, 65 GROUPS Script command, 81
PHASE Stream attribute, 84 PRINT INCOMPLETE CONNECTIONS
Physical Type, 172 script command, 89
PIVOTSEARCH DMO parameter, PRINT JACOBIAN EQUATIONS
132 script command, 124
POP SCOPE script command, 58 PRINT JACOBIAN script command,
Port Commands. See Stream 123
Commands PRINT JACOBIAN VARIABLES script
PORTVAR script function, 42 command, 123
Power (^) script function, 39

Index 205
 PRINT LARGEST EQUATION Program flow control
SCALED_SHADOW_PRICES FOR-DO constructs, 36
script command, 79 IF-THEN-ELSE constructs, 35
PRINT LARGEST EQUATION WHILE-DO constructs, 37
SHADOW_PRICES script PROMPT script parameter, 28
command, 79 PUSH SCOPE script command, 58
PRINT LARGEST RESIDUAL QPINFE LSSQP parameter, 134
SCALED_SHADOW_PRICES QPSTATS DMO parameter, 132
script command, 79 Query
PRINT LARGEST RESIDUAL Printing variables with, 73
SHADOW_PRICES script Query script functions, 42
command, 79 QUERYSPEVGROUPS script
PRINT LARGEST RESIDUALS script function, 42
command, 78 QUERYVARS script function, 42
PRINT LARGEST VARIABLE QUIT script command, 51
SHADOW PRICES script READ SNAPSHOT script command,
command, 72 107
PRINT LARGEST VARIABLE READ VARFILE EXCEPT script
SHADOW PRICES SSI script command, 105
command, 72 READ VARFILE script command,
PRINT MEASUREMENTS script 105
command, 94 READ_VARFILE_MASK script
PRINT MEASUREMENTS VARIABLES parameter, 28
script command, 94 RECOVER script command, 193
PRINT OBJECTIVE script command, Recovery commands
122 Recovery, 193
PRINT QUERY script command, 73 Resetting variables, 139
PRINT RESIDUALS script Redirecting output and Journaling
command, 78 Examining the output devices, 25
PRINT SCOPE script command, 58 Flushing, 24
PRINT SPECIFICATION GROUP Journaling, 24
VARIABLES script command, Redirecting the output of a
82 command, 21
PRINT SPECIFICATION GROUPS the history device, 23
script command, 81 the report device, 23
PRINT SPECIFICATIONS script Reinitializing a simulation
command, 71 script command, 148
PRINT SUMMARY script command, Relational script functions, 41
140 RELAX_TOL script parameter, 28
PRINT TIMER script command, 51 RELEPS LSSQP parameter, 133
PRINT UOM script command, 160 REMOVE CONNECTIONS script
PRINT VARIABLES script command, command, 85, 86
70 REMOVE SPECIFICATION GROUPS
PRINT VARIABLES SSI script script command, 80, 147, 148,
command, 70 149, 150
Print_level NSOLVE parameter, 138 REMOVESTR script function, 40
PRINT_VAR_MASK script REPORT ALL script command, 194
parameter, 28 REPORT BLOCKS script command,
PRINTFREQ DMO parameter, 132 145
PROBID script parameter, 28 Report Commands
PROBNAME script parameter, 28 Reporting blocks, 145
PROCESS VARIABLE QUALITY Reporting everything, 194
script command, 97 Reporting streams, 194

206 Index
 Reporting the flowsheet, 194 Accessing, 31
Reporting the objective function, Built-in script parameters, 27
145 Global script parameters, 26
REPORT FLOWSHEET script Local script parameters, 27
command, 194 Setting, 29
REPORT OBJECTIVE script Unsetting, 31
command, 145 SCRIPT_PATH script parameter, 29
REPORT STREAMS script command, Scripts
194 Defining, 5, 187
REPORT_DEVICE script parameter, Executing, 5, 187
23, 29 Global, defined, 5, 187
RESCVG DMO parameter, 132 Local, defined, 5, 187
RESET SCOPE script command, 58 SEARCHMODE DMO parameter,
RESET VARIABLES script 131
command, 139 SENSITIVITY script command, 126
Residual Commands. See Equation SET script command, 29
Commands SIN script function, 39
RESTART TIMER script command, SINGT1 LSSQP parameter, 135
51 SINGT2 LSSQP parameter, 135
RESTORE FREE VARIABLES EXCEPT SMLSCL LSSQP parameter, 135
script command, 104 snapshot, 150
RESTORE FREE VARIABLES script SOFT_BOUND script parameter, 29
command, 104 SOLVE script command, 138
RESTORE VARIABLES script Solver commands
command, 103, 109, 110, 111, Entering DMO parameters, 130
116, 117 Entering LSSQP parameters, 132
RETURN command, 34 Entering NSOLVE parameters,
RFEASB LSSQP parameter, 133 137
RFINFB LSSQP parameter, 133 Setting the solver, 130
RIGORUPDATES DMO parameter, Solving the problem, 138
132 Viewing solver settings, 130
RRHIGH LSSQP parameter, 135 SOLVER script command, 130
RRLOW LSSQP parameter, 135 SOLVER SETTINGS script
RUN_MODE command, 130
script parameter, 146 SPDROP LSSQP parameter, 135
Running a simulation SPEC Stream attribute, 84
script command, 147 SPEC variable attribute, 68
RWORKF DMO parameter, 132 SPECGROUPSBYVAR script
SAVE VARIABLES script command, function, 42
102 Specification Group Commands
SAVEJDFFILE DMO parameter, 132 Disabling Specification Groups,
Saving a snapshot 81
script command, 150 Enabling Specification Groups,
SBWEIGHT variable attribute, 68 81
SCALE Objective function attribute, Printing inactive specification
120 groups, 81
SCALE variable attribute, 68 Printing Specification Group
Scope variables, 82
Defined, 56 Printing specification groups, 81
SCOPE INVOKE command, 34 Removing Specification Groups,
SCREENFORM DMO parameter, 132 80, 147, 148, 149, 150
Script Functions, 39 Specification variable attribute, 68
Script parameters SQRT script function, 39

Index 207
 Stabilization NSOLVE parameter, Units of measure commands
138 Dealing with Untyped Variables,
Stable_iterations NSOLVE 161
parameter, 137 Printing units of measure, 160
START TIMER script command, 51 Variable Units of Measure, 160,
STEP variable attribute, 68 178
STEP_BOUND script parameter, 29 UNITS variable attribute, 68
Stepping through a simulation UNSET script command, 31
script command, 147 UOM Objective function attribute,
STOP TIMER script command, 51 120
Stopping a simulation UOM_WIDTH script parameter, 29
script command, 147 UPDATE BLEND script command,
Stream Commands 190
Adding and removing stream UPDATE PDF script command, 190
connections, 191 UPDATE VARIABLES script
Attributes, 84 command, 104
Disabling Stream connections, UPPER variable attribute, 68
191 USERDROPTOL DMO parameter,
Enabling Stream connections, 131
191 VAL script function, 42
Printing block ports, 83 VALUE Objective function attribute,
Printing connections, 88 120
Printing stream values, 83 VALUE variable attribute, 68
STREAMS script command, 191 Variable Commands
string concatenation script Changing variable attributes, 69
function, 40 Printing connections, 88
String script functions, 40 Printing largest variable shadow
STRING2ID script function, 40 prices, 72
SUBSTR script function, 40 Printing variables, 70
support, technical, 7 Printing variables fixed in other
Swapping Properties Data modes, 71
script command, 184 Printing variables fixed in the
System commands, executing, 51 current mode, 71
SYSTEM script command, 51 Printing variables using a query,
TAIL script function, 42 73
TAN script function, 39 Printing variables with active
task, 148 bounds, 72
task language, 151 Variable_tolerance NSOLVE
TAUHYB LSSQP parameter, 135 parameter, 138
technical support, 7 VARSCALE DMO parameter, 132
TIMER script commands, 51 Viewing a variable history
TO script command, 21 script command, 149
TOGGLE SOLVE SCOPE script Viewing a variable profile
command, 60 script command, 149
TOLANA LSSQP parameter, 134 Viewing snapshots
TOLBAS LSSQP parameter, 134 script command, 150
TOLOWER script function, 40 Viewing tasks
TOUPPER script function, 40 script command, 148
Trust_radius NSOLVE parameter, VMUINI LSSQP parameter, 135
138 VMUMIN LSSQP parameter, 135
TYPE Stream attribute, 84 web site, technical support, 7
TYPEOF script function, 42 WHILE-DO script command, 37
Units of measure, 162 Wildcards

208 Index
 Glob-style, 48 WRITE VARFILE script command,
Regular expression matching, 48 105
WRITE SNAPSHOT script WRITE_VARFILE_MASK script
command, 107 parameter, 29
WRITE VARFILE EXCEPT script XPMIN LSSQP parameter, 137
command, 105 ZEROTOL block attribute, 65
ZPERTF LSSQP parameter, 136

Index 209
210 Index