gPROMS ModelBuilder version 2.3.1

gPROMS ModelBuilder 

version 2.3.1 

Process Systems Enterprise Ltd 

13 May 2004 

Process Systems Enterprise Limited 

Bridge Studios 107a Hammersmith Bridge Road 

London W6 9DA 

t: +44 (0)20 8563 0888 f: +44 (0)20 8563 0999 

e: info@psenterprise.com w: www.psenterprise.com 

The model company 

This document is the property of Process Systems Enterprise Ltd. 

No part of the material contained herein may be copied, distributed, published, retransmitted or 

modified, in any way without the prior written consent of Process Systems Enterprise Ltd.

Contents 

Chapter 1 - Introduction............................................................................................................................ 1 

1.1 gPROMS ModelBuilder..................................................................................................................... 2 

Chapter 2 - Projects and Entities ............................................................................................................... 3 

2.1 gPROMS ModelBuilder environment.................................................................................................. 4 

2.1.1 The gPROMS ModelBuilder Project tree ........................................................................................ 4 

2.1.2 Projects ..................................................................................................................................... 4 

2.1.3 Entity creation and deletion ......................................................................................................... 5 

2.1.4 Opening and closing an entity editor............................................................................................. 6 

2.2 Entity editors .................................................................................................................................. 7 

2.2.1 The entity properties tab ............................................................................................................. 7 

2.2.2 The gPROMS language tab .......................................................................................................... 8 

2.3 Project organisation ...................................................................................................................... 11 

2.3.1 Project properties..................................................................................................................... 11 

2.3.2 Entity cross-referencing and hierarchical libraries ........................................................................ 11 

2.3.3 Automatic loading of Projects .................................................................................................... 14 

2.3.4 Read-only Projects .................................................................................................................... 14 

2.3.5 Display of empty groups in Project tree ...................................................................................... 14 

2.4 Library projects ............................................................................................................................ 16 

2.4.1 Creation of libraries .................................................................................................................. 16 

2.4.2 Display of libraries in the project tree ......................................................................................... 16 

2.5 Model palette ............................................................................................................................... 17 

2.5.1 Displaying the Model palette ...................................................................................................... 17 

Chapter 3 - Variable and Connection Type Entities .................................................................................... 19 

3.1 Variable Types editor .................................................................................................................... 20 

3.2 Connection Types editor................................................................................................................ 21 

3.2.1 Introduction.............................................................................................................................. 21

Contents 

3.2.2 “Parameters & variables” editor tab ........................................................................................... 21 

3.2.3 “Graphical representation” tab ................................................................................................... 22 

3.2.4 Port categories tab................................................................................................................... 24 

Chapter 4 - Model Entities ...................................................................................................................... 25 

4.1 Introduction .................................................................................................................................. 26 

4.2 Interface tab................................................................................................................................. 27 

4.2.1 Icon definition........................................................................................................................... 27 

4.2.2 Port definition........................................................................................................................... 28 

4.3 Topology tab ................................................................................................................................ 31 

4.3.1 Instances of component models (Units) ...................................................................................... 31 

4.3.2 Defining the connectivity of a composite model........................................................................... 33 

4.3.3 Hierarchical model construction................................................................................................. 35 

4.3.4 Arrays of Units.......................................................................................................................... 36 

4.3.5 The Topology editor tool bar...................................................................................................... 37 

Chapter 5 - Optimisation Entities ............................................................................................................. 41 

5.1 Introduction .................................................................................................................................. 42 

5.2 Specifying General information for an optimisation activity ............................................................... 43 

5.3 Specifying control variables for an optimisation activity.................................................................... 44 

5.3.1 Time-invariant controls .............................................................................................................. 44 

5.3.2 Piecewise-constant controls....................................................................................................... 46 

5.3.3 Piecewise-linear controls ........................................................................................................... 47 

5.4 Specifying Constraints for an optimisation activity ........................................................................... 49 

Chapter 6 - Performed Experiment Entities .............................................................................................. 51 

6.1 Introduction .................................................................................................................................. 52 

6.2 Specifying steady state or dynamic experiments and initial conditions............................................... 53 

6.3 Specifying experiment control actions ............................................................................................ 54 

6.4 Specifying measured data ............................................................................................................. 55 

Chapter 7 - Activity execution.................................................................................................................. 57

Contents 

7.1 Cross-reference check .................................................................................................................. 58 

7.2 Cases .......................................................................................................................................... 59 

7.2.1 The Case configuration and execution control dialog ................................................................... 59 

7.2.2 Management of Cases .............................................................................................................. 60 

7.2.3 Default Case configuration and activity execution Preferences...................................................... 61 

7.3 Interacting with executing Model-based activities ............................................................................. 63 

7.3.1 Execution output....................................................................................................................... 63 

7.3.2 Diagnostics console.................................................................................................................. 64 

7.4 Activity Results ............................................................................................................................. 65 

7.4.1 Simulation activities .................................................................................................................. 65 

7.4.2 Optimisation activities ............................................................................................................... 66 

7.4.3 Parameter Estimation activities.................................................................................................. 68 

Chapter 8 - Modelling Support Tools........................................................................................................ 71 

8.1 Introduction .................................................................................................................................. 72 

8.2 Global “Search-and-replace” ........................................................................................................... 73 

8.3 Project and entity “Compare”......................................................................................................... 75 

8.3.1 Entity comparison..................................................................................................................... 75 

8.3.2 Project comparison................................................................................................................... 75 

8.3.3 Entity group comparison ........................................................................................................... 77 

8.4 “Import files” ................................................................................................................................ 78 

8.5 “Create links to external files” ........................................................................................................ 79 

8.6 “Export” ....................................................................................................................................... 81 

8.6.1 Export Entity with dependencies................................................................................................. 81 

8.6.2 Encryption................................................................................................................................ 81 

8.7 “Export to ModelBuilder v2.2 Project”............................................................................................. 83 

8.8 “Export to Simulink” ...................................................................................................................... 84 

8.9 “Browse variables”........................................................................................................................ 86 

Chapter 9 - Utilities ................................................................................................................................ 87

Contents 

9.1 Introduction .................................................................................................................................. 88 

9.2 ModelBuilder Preferences.............................................................................................................. 89 

9.3 Text editor short-cut keys .............................................................................................................. 91 

9.3.1 Navigation Shortcuts................................................................................................................. 91 

9.3.2 Edit shortcuts........................................................................................................................... 94 

9.4 Miscellaneous Utilities ................................................................................................................... 96 

9.4.1 Editing of Saved Variable Sets using external editor software....................................................... 96 

9.4.2 Printing .................................................................................................................................... 96 

9.4.3 Multiple selection ...................................................................................................................... 96 

9.4.4 Desktop view............................................................................................................................ 96 

9.4.5 “Collapse project tree” action .................................................................................................... 98

Chapter 1 - Introduction

Introduction 

1.1 gPROMS ModelBuilder 

The gPROMS ModelBuilder is at the centre of: 

all model development and maintenance activities; 

the archiving of models and results 

the execution of all model-based activities. 

This guide gives a description of the features and functionality of gPROMS ModelBuilder - including some of the 

advanced tools that are available: 

Chapter 2 introduces the ModelBuilder environment – looking at Projects and the general properties of all 

Entity editors. 

In Chapter 3, the Variable and Connection type Entity editors are explained. 

The Model Entity editor is described in Chapter 4. 

The Optimisation Entity editor is described in Chapter 5. 

The Performed Experiment Entity editor is described in Chapter 6 

Activity execution is discussed in Chapter 7. 

Chapters 8 and 9 describe the tools and utilities available in the ModelBuilder environment. 

Throughout this guide, it is assumed that the user is already familiar with the basic features of the gPROMS model 

and task language. 

2

Chapter 2 - Projects and Entities

Projects and Entities 

2.1 gPROMS ModelBuilder environment 

2.1.1 The gPROMS ModelBuilder Project tree 

The project tree (see Figure 2.1) allows the user to navigate all the (Library) Projects and Cases that have been 

respectively opened and created during a ModelBuilder session. They are distinguished by their colours: yellow 

(Projects); green (Library projects); and blue (Cases) and their ordering: Library projects, Projects and Cases. 

Projects of the same type are then ordered alphabetically. 

2.1.2 Projects 

4 

Libraries 

Project 

Case 

Figure 2.1 gPROMS ModelBuilder project tree 

To create a new gPROMS “Project'' select New from the Project menu. This will bring up a tree in the left-hand pane 

containing a number of folders (as shown in Figure 2.2): 

Variable Types 

Stream Types 

Connection Types 

Models 

Tasks 

Processes 

Optimisations 

Estimations 

Experiments 

o for parameter estimation

o for experiment design 

Saved Variable Sets 

Miscellaneous Files 

Figure 2.2: New project tree entries 

5 

New project tree 

entries 

gPROMS ModelBuilder environment 

Each of these entries represents a group of gPROMS Entities. Each entity type represents a fundamental gPROMS 

concept., and ModelBuilder provides a customised “entity editor” for working with each entity type, as described in 

the next section. 

The Project can be renamed from its default of gPROMS_Project_1 by: 

Selecting Save As from the Project menu 

Entering a new “File Name” 

Clicking “Save” 

2.1.3 Entity creation and deletion 

To create a new entity 1 : 

place the pointer on the desired folder 

1 Alternatively, select the desired project, select “New entity” from the Entity menu.


click the right mouse button 

select “New entity” from the shortcut menu 

give a name to the new entity 

select the type of entity in the drop-down menu, 

fill in a description of the entity if desired and click “OK” 

To delete an entity 2 

: 

select the entity 


select delete from the shortcut menu 

confirm the delete by selecting Yes (alternatively the delete can be cancelled) 

Note: select several entities simultaneously with the shift and/or control key to delete all. 

To rename an existing entity 3 : 

place the pointer on the desired entity 


select “Rename” from the shortcut menu 

fill in the desired name in the dialog window and click OK 

2.1.4 Opening and closing an entity editor 

To open an entity editor 4 : 

place the pointer on the desired entity 

click on the right mouse button 

select “Open” on the shortcut menu 

ModelBuilder supports both multiple and single editor modes: selected from the Window menu – refer to Section 

9.4.4 for further details. When working in multiple editor mode, an entity editor can be closed by clicking on the 

cross in the top right corner. 

2 

Alternatively, select the entity press “Delete” in the keyboard. 

3 Alternatively, select the desired entity; select “Rename” from the Entity menu. 

4 Alternatively, double clicking on an entity will open its editor. 

6

2.2 Entity editors 

7 

Entity editors 

As mentioned previously, ModelBuilder provides customised editors for each type of entity. Each editor provides a 

number of tabs, allowing the user to view or alter the different aspects of the entity’s behaviour. 

This section will cover the two tabs which are present on most of ModelBuilder’s entity editors – the “gPROMS 

language” and “properties” tabs. Tabs specific to individual entities will be described in subsequent chapters. 

2.2.1 The entity properties tab 

All Entity editors in gPROMS ModelBuilder have an Entity Properties tab (see Figure 2.3) that includes the following 

information: 

description of the Entity; this is an arbitrary text provided by the Entity developer(s) for future reference. 

Entity creation and last modification information, including the user who performed these actions, and their 

times and dates; this information is read-only as it is constructed and maintained automatically by 

ModelBuilder. 

a list of all other Entities on which this Entity depends; again this is read-only information that is constructed 

and maintained automatically by ModelBuilder. 5 

Cross-referenced 

Entities 

Figure 2.3: Entity properties 

Entity description 

Projects from 

which crossreferenced 

are 

obtained 

Creation 

information 

Last 

modification 

information 

5 The appearance of a referenced Entity in this list simply indicates that it is required for the correct operation of the 

current Entity; it does not necessarily imply that the referenced Entity actually exists and/or can be located at this 

point in the ModelBuilder session.


2.2.2 The gPROMS language tab 

Almost all Entity editors in gPROMS ModelBuilder have a tab that displays and allows the editing of the 

representation of the Entity in the gPROMS language (see Figure 2.4). 

“Cross” indicates 

Entity has errors 

2.2.2.1 Syntax highlighting 

8 

Syntax-sensitive 

editor 

Figure 2.4: The gPROMS language tab in an Entity Editor 

List of syntactic or 

semantic errors 

gPROMS ModelBuilder automatically employs syntax-sensitive highlighting of the gPROMS language to support the 

creation and modification of each Entity. 

A default set of colours is assigned for different types of gPROMS constructs. The user can overwrite these default 

settings, or indeed switch syntax highlighting off, by going to the ModelBuilder Preferences dialog (see Section 9.2) 

and highlighting the “Entity editor” category. 

2.2.2.2 Syntax checking 

gPROMS ModelBuilder will automatically check the syntax in any of the Entities that have been written. In addition, a 

wide range of semantic checks are performed, e.g. flagging the use of unidentified local variables. 6 

Syntax and semantic checking is invoked by a number of different methods: 

When the user saves the Project. 

6 

The semantic checking performed is currently local within the current Entity. ModelBuilder does not attempt to 

validate any cross-referenced Entities.

By clicking on the check syntax button just under Tools on the top toolbar. 

By selecting Check Syntax from the Entity menu. 

Right clicking on the Entity and selecting Check syntax. 

By using the keyboard short-cut (F4). 

9 

Entity editors 

If ModelBuilder finds an error, as shown in Figure 2.4, a small pane appears just underneath the text editor reporting 

the error. Double-click the error message in the error pane and the cursor will automatically go to the 

corresponding line number to show where the syntax error is. 

You will also see that the error is highlighted in the text editor window and that a red cross appears through the icon 

for the Entity in the Project tree. Correcting this error will then cause this cross and the error pane to disappear. 

2.2.2.3 Assisted pathname completion 

Most gPROMS language entity editors support pathname completion. The pathname completion applies to all the 

Units, Variables, Parameters, Selector names and values and Distribution Domains declared in a specific Model and 

all its sub-models, as well as cross-referenced entities. Note that pathname completion only works on entities that 

have been validated by a syntax check (F4) - see Section 2.2.2.2) and its suggestions are limited to variable names 

etc. which were defined at that time. 

Auto-completion is invoked manually by pressing Ctrl + Space or automatically following a small delay after typing 

the name of a Unit followed by dot. When invoked, a list box shows all the possible Units and Variable names for 

completion (see Figure 2.5). Typing additional characters will narrow down the selection as the partially typed word 

matches the appropriate Unit or Variable name. However, once a unique Unit or Variable name exists, the pathname 

will be automatically completed. The user may also use the cursor key to navigate around the list box. Pressing the 

“Space” or “Enter” key at any time will select the Unit or Variable name to replace the partially entered name. On the 

other hand, pressing the “Escape” key will close the list box without completion. 

The user also has the option to disable or delay the pop-up list box by changing the default setting in the Entity 

Editor category in the ModelBuilder Preferences menu (see section 9.2). Once this option has been disabled, the 

user can only manually invoke the list box by using the Ctrl + Space short-cut keys. 

2.2.2.4 Word Match 

This is similar to automatic pathname completion in that it completes the current word being typed. However, it 

does not require a valid syntax check to be used and applies to any word that may have previously been typed (not 

just Units, Variables, Parameters, Selector names and values and Distribution Domains). For example, it can be used 

to auto-complete gPROMS language key words, such as WITHIN, SWITCH, END, etc. 

Word match is invoked manually by pressing: 

Ctrl + K to find the previous word that begins like the current word and complete it so that they match. 

Ctrl + L to find the next word that begins like the current word and complete it so that they match. 

As well as completing the word, word match will also match the case. This is particularly useful for gPROMS 

language keywords where it is usually preferred to have the whole word in upper case.


Figure 2.5: Automatic pathname completion 

10

2.3 Project organisation 

2.3.1 Project properties 

11 

Project organisation 

Each Project records information relating to the user(s) who created and last modified it, as well as the dates and 

times of creation and last modification. This information is read-only and is recorded and maintained automatically 

by ModelBuilder under the Project's Properties. 

Project Properties can be viewed by right-clicking on the Project's name in ModelBuilder's navigation tree and 

selecting “Properties” in the context-sensitive menu that appears (see Figure 2.6). 

The Properties dialog has a second tab that controls the list of Projects that can be cross-referenced - this is 

discussed below. 

Right-click on 

project name to 

see this menu 

Enable/disable 

display of empty 

Entity groups 

Cross-references 

tab 

Figure 2.6 Project properties dialog 

2.3.2 Entity cross-referencing and hierarchical libraries 

Enable/disable 

Library project in 

the project tree 

In gPROMS ModelBuilder, the Entities in one Project may make references to Entities that belong to another Project. 

For example, 

a Model Entity in Project A may refer to Variable Types in a Project B in declaring its Variables; 

a Model Entity in Project A may refer to Models in a Project B in declaring its Unit sub-models; 

a Task or Process Entity in Project A may refer to Models and/or Tasks in Project B;


and so on. This provides a convenient way of building libraries of Variable and Connection types, Models and Tasks - 

or indeed any type of Entity - within gPROMS. Please note that only Projects currently loaded within ModelBuilder 

can be searched for Entities. 

Cross-reference 

tab in project 

properties dialog 

Projects already in 

cross-reference list 

Check-box for temporary 

disabling of cross-referencing 

12 

Buttons for changing 

search order 

Projects that may be 

added to crossreference 

list 

Figure 2.7 Specifying cross-referenced Projects 

2.3.2.1 Specifying a Project's list of cross-referenced Projects 

A Project may refer to Entities residing in any number of other Projects. As shown in Figure 2.7 the latter can be 

specified explicitly via the “Cross-references” tab of the Project's Properties dialog (see section 2.3.1). Note that 

only Projects that are currently open within the ModelBuilder session can be selected in this manner. 7 

The ordering of a Project's list of cross-referenced Projects is important in that it determines the order in which the 

various Projects in the list will be searched (discussed below). Each new Project added is inserted immediately 

below the Project in the list that is currently highlighted. However, the position of any Project in the list may be 

modified at any time via the “Raise” and “Lower” buttons provided. 

2.3.2.2 Search rules for cross-referenced Projects 

In technical terms, ModelBuilder supports multiple libraries organised in hierarchies of arbitrary depth which are 

searched in a depth-first manner. This sophisticated capability is best explained via an example. Suppose a Model 

Entity M1 in a certain Project A contains a Unit sub-model that is of type Model M2. ModelBuilder starts by looking 

for M2 within A itself. If this search is not successful, then it starts looking for M2 within the Projects that can be 

cross-referenced by A in the order in which these have been specified (see section 2.3.2.1). If one of these other 

Projects, say B, has its own list of cross-referenced Projects, then these will also be searched - and this will be done 

7 

This is consistent with the fact that only Projects that are currently open are actually searchable.

13 

Project organisation 

before moving on to the next Project in A's list 8 . The search for a particular Entity ends when M2 is either found or 

there are no more Projects to be searched. 

Assuming that MODEL M2 has been found, it is entirely possible that it, in turn, refers to lower-level Entities such as 

other MODELs, or variable or stream types. The search for these Entities will follow exactly the same rules as that 

for M2 itself. It is worth noting that the search will always commence from the current Project A and not from the 

Project in which M2 was found. This is designed to allow, for example, a user's Project to make use of a standard 

library MODEL (e.g. “Reactor”) while overriding the library definition of a variable type (e.g. “Temperature”) or indeed 

of a sub-model (e.g. “KineticMechanism”) by providing its own Entity of the same name. 

2.3.2.3 Temporary suspension of Project cross-referencing 

At any point during a ModelBuilder session, the user may instruct ModelBuilder not to search other Projects for any 

missing Entities until further notice. This can be done by checking the “Disable cross-references” check-box in the 

cross-references tab of the Project's Properties dialog (see Figure 2.6). 

2.3.2.4 Creating a self-contained Project 

It is sometimes desirable to create a completely self-contained Project that contains physical copies of all necessary 

Entities, including any that may reside in cross-referenced Projects. 

The creation of a self-contained Project may be performed automatically using the “Copy X-referenced Entities into 

Project” utility under the ModelBuilder's Tools menu. This operation cannot be reversed automatically. 

Project to be made 

self-contained 

Initiating the automatic entity 

copying operation 

Projects from which 

cross-referenced 

entities will be copied 

Figure 2.8 Creating a self-contained Project 

8 

gPROMS ModelBuilder will automatically detect and deal with any circular references. In particular, no Project is 

searched more than once while searching for a particular Entity


2.3.3 Automatic loading of Projects 

The list of Projects to be automatically loaded whenever ModelBuilder is started can be specified as part of the 

user's ModelBuilder Preferences. This feature is particularly useful for library Projects. 

The ModelBuilder Preferences dialog can be accessed from the Edit menu. Simply highlight the “Projects” category; 

and add or delete Projects in the “start-up Projects” list using the corresponding buttons. The file navigation dialog 

that appears when the “Add” button is pressed permits the selection of any Project (.gPJ) file that is currently visible 

to the user -including those that reside on shared file systems. 

2.3.4 Read-only Projects 

In order to protect against inadvertent modifications being made to a particular Project or Library project, it is 

recommended that the corresponding gPJ file be declared as “read-only” using standard operating system facilities 

prior to loading the project into ModelBuilder. In such cases, a “lock” symbol will be displayed against both the 

Project and any Entity that it contains in the ModelBuilder's navigation tree. Any operation that may result in a 

modification of this Project is automatically disabled. 

2.3.5 Display of empty groups in Project tree 

The Properties dialog can also be used to control the appearance of the Project in ModelBuilder's navigation tree. In 

particular, the display of empty folder groups (e.g. the TASK group in a Project that does not actually contain any 

TASK Entities) can be enabled or disabled by ticking the relevant check-box (see Figure 2.9). The same effect can 

be achieved by ticking the “Display empty groups” entry in the Project's context-sensitive menu. 

14

Figure 2.9 Display of empty groups in Project tree 

15 

Project organisation


2.4 Library projects 

Project libraries are projects marked by the user as such to indicate that they contain potentially re-usable 

components. Project libraries are marked in green and always appear at the top of the Project tree. Their purpose 

is to enhance the management, usability and operability of generic Models and Tasks. They can contain all entity 

types and can cross-reference other libraries/projects. The gPROMS Process Model Library (PML) makes extensive 

use of this new concept. 

Entities in a library project can be used by another project opened in ModelBuilder if: 

the library is open in ModelBuilder, and 

the library is cross-referenced by the project 

2.4.1 Creation of libraries 

Any project can be converted into a library and vice versa. To create a library from a project: 

Open the “Properties” tab of the project:, 

Check the “library project” checkbox to convert to project into a library (Figure 2.6). 

Similarly, a library can be converted into a project by following step 1 and un-checking the “library project” 

checkbox. 

2.4.2 Display of libraries in the project tree 

Libraries can be displayed or hidden in the project tree in two alternative manners: 

click on “View” on the ModelBuilder top bar menu and select “display libraries” in the scroll-down menu (a 

check next to the option marks if it is on or off) 

Ctrl+D to toggle between displayed and hidden libraries 

Note: the selection is permanently saved for the next time you open ModelBuilder. 

16

2.5 Model palette 

17 

Model palette 

The Model palette (Figure 2.10) graphically displays the Model Entities contained in open Projects (and Library 

projects) and provides an alternative view to the Project tree. All Models that have an icon defined (see Section 

4.2.1) are shown on the Model palette 9 . The Models are grouped by the Projects to which they belong. The Model 

palette provides a graphical view of models that can be used to build flowsheets. 

Tabs to switch between 

Project tree view and 

Model palette view 

2.5.1 Displaying the Model palette 

To display the Model palette (see Figure 2.10): 

Model palette 

Figure 2.10 Model palette 

click on “View” in the ModelBuilder top bar menu 

select “Model palette” in the scroll-down menu (a check next to the option marks if it is on or off) 

The model palette window will appear on the left hand side. If the Project tree is also open, a tab at the bottom of 

the window will allow the user to toggle between the Project tree and the Model palette. 

The arrow to the left of the Project name allows the palette for each Project to be collapsed and expanded. 

Selecting a Model on the Palette displays the description of the Model Entity (refer to Section 2.2.1). 

9 Models will only appear on the palette if the “Show in palette” option is checked on their Properties tabs.


18

Chapter 3 - Variable and Connection Type Entities

Variable and Connection Type Entities 

3.1 Variable Types editor 

Variable Types are displayed and edited in a tabular format. A new Variable Type can be added either by defining a 

New Entity from the Entity menu or by completing the entries in the blank row that always appears at the bottom of 

the Variable Types table (see Figure 3.1). When this happens, a corresponding new Variable Type is created and a 

new blank row is automatically appended to the table. 

To help the user navigate the various Variable Types, when a particular Variable Type is selected in the Project tree, 

the corresponding row is automatically highlighted in the Variable Types table. 

Figure 3.1: Variable Types Editor 

20

3.2 Connection Types editor 

3.2.1 Introduction 

21 

Connection Types editor 

Component models are connected on a composite model’s topology via their Ports (refer to Section 4.3). Each Port 

is declared as an instance of a Connection Type. 

Connection Types include 

Variables: these can be referred to in component models; 

Parameters and Distribution domains: these can be used to provide the dimensions of any Parameters and 

Variables defined for the Connection Type; 

A graphical representation; 

Port categories: these can be used to disallow certain connections. 

It should be noted that a Model’s Port declaration, in effect, declares the Variables, Parameters and Distribution 

domains associated to the Connection Type used for the port declaration. 

In addition to the Properties tab (see Section 2.2.1), three tabs are used to define a Connection Type 

“Parameters & Variables” 

“Graphical representation” 

“Port categories” 

Each of these tabs is now considered. 

3.2.2 “Parameters & variables” editor tab 

The Parameters, Distribution domains and Variables are defined on the “Parameters & Variables” editor tab (see 

Figure 3.2). 

For each Parameter the user should specify: 

o a type (Real, Integer, or Foreign Object 10 

) 

o and (optionally) a default value, 

For each Distribution domain the user should specify 

o lower and upper bounds 

For each Variable the user should specify 

o a Variable Type (see Section 3.1) 

o Variable dimensions (or if a scalar variable). Both the size and number of dimensions are 

declared in the Dimensions field: any size and number of dimensions are permitted. 

The lower and upper bounds for Distribution domains and the size of array Variables can be given either directly as 

a literal constant (e.g. 2) or using any of the Parameters also defined for the Connection Type 11 . 

10 If a parameter of type Foreign Object is specified then a Foreign Object Class can also be specified. 

11 Only Parameters of type integer can be use to size Array Variables


Figure 3.2: The Parameters and Variables tab 

3.2.2.1 Adding a new Parameter, Distribution domain or Variable 

To add a new Parameter, Distribution domain or Variable 

select the cell in the corresponding cell matrix, 

type the new entity name, 

use the keyboard right arrow, TAB, or the mouse, to move to the next cell and enter the required 

information 

press “Enter” when finished 

The contents of a cell can be modified by double clicking on it or by selecting the cell and pressing F2. To delete an 

entry, select the whole row and press the delete key. 

3.2.3 “Graphical representation” tab 

The appearance of the Unit Ports and the connections between them on a component Model’s topology tab are 

determined by the Port’s Connection Type. 

22

23 

Connection Types editor 

The graphical view of the Connection Type is defined using the “Graphical representation” tab (Figure 3.3). A 

preview of a connection based on this Connection Type is shown on the tab. 

3.2.3.1 Changing the colour specification 

To change the colour of the Port or the connection, simply click the arrow next to the colour for the Port or 

connection colour, and select a suitable colour from the drop-down list (Figure 3.3). The drop-down list includes a 

selection of standard colours, but a new colour can be created from the Advanced option if desired. To do this: 

Click on the button next to colour 

Select the suitable options in the tabs: 

o “Swatches”: allows the user to select the suitable colour 

o “HSB”: Hue, Saturation, Brightness 

o “RGB”: Red-Green-Blue tone 

click OK 

The user-defined colour will appear at the bottom of the colour drop-down list with the name of “Custom”. 

3.2.3.2 To change the connection line thickness 

Similarly, to change the thickness of the connection line, simply click the arrow next to the “Connection thickness” 

label, and select a suitable thickness from the drop-down list. 

Line thickness 

Figure 3.3 Graphical representation tab 

Advanced colour options 

Colour options


3.2.4 Port categories tab 

Connections are only permitted between Ports of the same Connection Type (see Section 4.3.2). In addition, Port 

categories allow the user to define permitted connections between Ports of the same Connection type (Figure 3.4). 

Rules on permitted connections are given later in Section 4.3.2. 

To create a new Port category: 

A Node Port is allowed to connect only with a Connector Port 

type the name in the “New Port Category” field, 

click on the “add” button 

A Connector Port is allowed to connect with another 

Connector Port or a Node Port 

Figure 3.4 Port categories tab 

The new Port category will be then added to the “Allowable connections” table at the end of the first row and at the 

bottom of the first column. A checked box denotes that connections between the corresponding Port categories are 

permitted. 

When a Port is declared in a Model’s definition the category of the Port is selected from those defined for the 

Connection Type. 

24

Chapter 4 - Model Entities

Model Entities 

4.1 Introduction 

gPROMS ModelBuilder allows users to build composite models graphically. This functionality is designed to enable 

you to quickly construct process flowsheet models that are suitable for use in any model based activity (e.g. steadystate 

and dynamic simulation, parameter estimation and optimisation studies). To this end, in addition to the 

standard gPROMS language and Properties tabs (Section 2.2), Model Entities have two additional tabs: interface 

and topology. These are described in this Chapter. 

26

4.2 Interface tab 

27 

Interface tab 

The Interface tab (Figure 4.1) allows a user to define a public view of the Model: in particular it determines how the 

Model appears when used on the Topology tab of a composite model. Primarily, the interface is used to determine 

two characteristics: the Model icon and the Model Ports. 

4.2.1 Icon definition 

Position of the Ports in 

the icon 

Figure 4.1 The Model Interface tab 

Icon 

Ports 

An icon should first be created in an external graphical package and then imported into gPROMS 12 . To do this: 

click on the “Select icon” button, 

browse to the location of the icon file using popup dialog window, and 

select the file containing the icon 

The current icon is always displayed in the “Interface” window. The user can also select the size of the icon, to do 

this: 

click on the field next to the label “Icon size when added to the topology diagrams”, 

select the suitable option in the drop-down list 

12 Note: the icon files must be GIF, JPEG or PNG formats


The icon sizes are defined as follows: 

“Default”: corresponds to the actual size of the icon in pixels as imported 

“Tiny” shows the icon extrapolated to a size of 16 x 16 pixels 

“Small” shows the icon extrapolated to a size of 32 x 32 pixels 

“Medium” shows the icon extrapolated to a size of 64 x 64 pixels 

“Large” shows the icon extrapolated to a size of 128 x 128 pixels, and 

“Huge” shows the icon extrapolated to a size of 256 x 256 pixels 

Note: To ensure that the Model appears on the Model palette the user should confirm that “Show in palette” option 

is checked on the Model Properties tab (see Section 2.5 for further details). 

4.2.2 Port definition 

The table displayed underneath the icon shows the Ports defined for the Model. Ports are instances of Connection 

type entities (see Section 3.2 for further details) and can be used to define the connectivity of composite models 

(see Section 4.3). 

To define a new Port click on the “Add” button this will open a dialog box (Figure 4.2) where the user will be asked 

to enter the following information: 

Port name: a user defined name for the specific Port. 

Connection type: a drop-down list allows the user to select from the Connection types defined in the 

working project or in a cross-referenced project or library project. 

Port category: the drop-down list shows the Port categories defined for the selected Connection type. 

Direction: defines the directionality of the Port (inlet, outlet, bi-directional). 

Dimensionality: 

o Select scalar to define a simple Port. 

o To define a fixed array Port, select Fixed sizes(s). Both the size and number of dimensions are 

declared in the Size of dimension(s) field 13 

: any size and number of dimensions are permitted. 

o To define a dynamic array Port, select Dynamic size. The size of the dynamic array is declared in 

the Bound size parameter field 14 

and can be made equal to any integer parameter declared in the 

model (this field is automatically populated with the possible parameters). When the model is 

added to a topology this parameter is automatically set, based on the number of connections to 

the dynamic port. 

The Port position on the icon must also be specified. To do this 15 

: 

place the pointer on the Port shown in the icon in the “Interface” tab, 

click on the Port and drag it to a suitable position, 

release the mouse button to finalise the Port position 

Note that a Port definition is also reflected on the gPROMS language tab (see Figure 4.3). 

13 only highlighted if Fixed size(s) is selected in the dimensionality field. 

14 

only highlighted if Dynamic size is selected in the dimensionality field. 

15 Alternatively, the Port position can be set by typing the rectangular coordinates in the appropriate fields (Figure 

9). 

28

Edited Port 

Figure 4.2 Defining a Port 

4.2.2.1 Using Port Variables and Parameters in the gPROMS language 

29 

Interface tab 

By implication, defining a Port declares all the Variables and Parameters defined for that Port’s Connection type. 

These are referred to via the standard “pathname” construction used widely in gPROMS: 

PortName.VariableName or PortName.ParameterName 

A simple example from the gPROMS Process Model Library is shown in Figure 4.3. This illustrates the use of Port 

Parameters and Variables in the gPROMS language definition of a Model.


Figure 4.3 The gPROMS language tab for a simple Model with a Port declaration 

30

4.3 Topology tab 

31 

Topology tab 

Composite models can be constructed by dragging (with the mouse) component models from the Project tree, or 

Model palette, and dropping them onto a graphical topology editor. The connectivity of the composite model can 

also be specified by connecting the Ports of the component models. 

Figure 4.4 shows the Topology editor for a blank Model along with the Project tree displaying the Process Model 

Library. 

4.3.1 Instances of component models (Units) 

To add a Model instance (a Unit) to the topology editor: 

Figure 4.4 Model topology 

select the Model in the Project tree or from Model palette, 

drag it to the desired position on the Topology editor and drop it by releasing the mouse button 

The new Unit is automatically named as ModelName001. If a second Model of the same type is dragged onto the 

Topology, the new Unit will be automatically named as ModelName002, and so on. 

4.3.1.1 The Unit shortcut menu 

ModelBuilder tool bar 

Topology editor tool bar 

Any model from the palette can be 

dragged on to the topology editor 

Once positioned on the topology tab, changes can be made to a Unit using its shortcut menu. To display the 

shortcut menu right-click on the Unit - Figure 4.5.


Figure 4.5 Unit shortcut menu 

As well as standard editing tools (cut, copy and paste) the Unit shortcut menu gives the following options: 

To Delete 16 

a Unit (if the selected Unit is connected to other Units, these connections will be also deleted). 

To Rename 17 

a Unit. 

Make Unit into an array – see Section 4.3.4. 

Set Unit size (choose from Default, Tiny, Small, Medium. Large, Huge – see Section 4.2.1) 

Open Model: this allows the user to open the Model editor for the component model that the selected Unit 

is an instance of. 

Note that it is possible to undo/redo any command or action using the and commands on the 

ModelBuilder tool bar menu. 

16 A Unit can also be deleted by selecting the Unit on the topology and pressing delete. 

17 A Unit name also can be changed by selecting the Unit name; double clicking the selected unit name. 

32

4.3.2 Defining the connectivity of a composite model 

33 

Topology tab 

Once more than one Unit has been added to a composite model, the connectivity of the system can be defined by 

connecting the Ports of each Unit. This can be done in the following manner: 

select the button on the Topology editor tool menu: this will switch the pointer to connection mode 

select the starting Port 

move the pointer to the destination Port 

select the destination Port 

If the line becomes solid then the connection has been verified. If the connection is invalid, ModelBuilder will issue a 

pop-up message giving an explanation (Figure 4.6). 

Figure 4.6 An invalid connection 

ModelBuilder applies the following rules to determine the validity of a connection: 

Both Ports must be instances of the same Connection Type. 

The Port categories of the two Ports must permit the connection, as defined for the Ports’ Connection Type 

(see Section 3.2.4 for further details). 

The directionality of the two Ports must be consistent: 

o An inlet Port can be connected to an outlet or a bi-directional Port; 

o An outlet Port can be connected to an inlet or a bi-directional Port; 

o A bi-directional Port can be connected to an inlet, outlet or another bi-directional Port. 

To delete a connection: select the connection and press “Delete”. 

4.3.2.1 Arrays of Ports 

As discussed in Section 4.2.2, gPROMS supports Arrays of Ports. This functionality allows multiple streams to be 

connected to a single Port (as shown in Figure 4.7). An Array Port is indicated by a hollow Port icon.


When connecting to (or from) an Array Port a Connection details dialog box prompts the user to confirm to which 

Port index the connection should be made (Figure 4.7). In most cases the user can simply “OK” this box. 

4.3.2.2 Additional information display 

Figure 4.7 Array of Ports 

The Topology editor provides additional information via a pop-up message approach. To access this information: 

Connection information: placing the mouse pointer over a connection displays the corresponding gPROMS 

language for the connection equation (Figure 4.8). 

Port information: placing the mouse pointer over a Port displays the Port name, type and direction (Figure 

4.8). 

34

Figure 4.8 Additional information display 

4.3.2.3 Topology connections and the gPROMS language 

35 

Topology tab 

Each Unit on the Topology corresponds to a declaration of a Model instance. The Unit declarations are shown (and 

can be edited) on the gPROMS language tab in the UNIT section 

Each connection on the Topology corresponds to an equation that equates the two Ports 18 . Like the Unit 

declarations, the equations are shown (and can be edited) on the gPROMS language tab in the TOPOLOGY section. 

4.3.3 Hierarchical model construction 

Most of the models in the gPROMS Process Model Library (PML) are primitive models – i.e. non-composite models. 

However, in gPROMS there is no limitation with respect to the number of levels in the hierarchical model 

decomposition: composite models with a defined topology can themselves be used to build even more complex 

composite models (see for example the PML distillation column). 

To use a composite model on the Topology tab of a higher level model the user must simply define the Interface for 

the composite model (i.e. introduce an icon and add Ports) as described earlier in Section 4.2. The Ports of a 

composite model appear on this Model’s own Topology tab: these can be connected to any other valid Port on the 

topology as shown in Figure 4.9. 

18 More explicitly gPROMS expands the Port definition to equate all the variables in the two Ports.


4.3.4 Arrays of Units 

Ports to be connected at 

the higher level model 

4.3.4.1 Making a Unit into an Array 

Figure 4.9 Hierarchical model construction 

The Topology editor also supports Arrays of Units. Making a Unit into an array is easily done from the Unit shortcut 

menu (Section 4.3.1.1): 

select “Make Unit into an array” in the popup menu, 

fill in the size of the array in the different dimensions separated by commas, and click OK 

Arrays of Units are distinguished on the topology editor by a coloured rectangle as shown in Figure 4.10. This gives 

the following information 

the Model icon, 

the size and dimensions (in the bottom right corner) 

an expansion node to expand the display of the array (top left corner) 

36

Node to expand the 

array view 

Unit name 

37 

Array elements 

connected 

Figure 4.10 Array of Units 

4.3.4.2 Interior connections within an Arrays of Units 

To specify connections between the component Units of an array: 

expand the array by clicking on the expansion node, 

click on the “Creating Port connection” button, 

create the connections using the procedure described in Section 4.3.2. 

4.3.4.3 Connecting to an Array of Units 

Number of units in 

the array 

Topology tab 

Connections to an array of Units are handled in the same way as connections to an array of Ports (see Section 

4.3.2.1): a Connection details dialog box prompts the user to confirm to which Unit index the connection should be 

made. 

4.3.5 The Topology editor tool bar 

The Topology editor provides many tools that enable the user to manipulate the look of the system model. These 

tools can be accessed from the Topology editor tool bar which is shown in Figure 4.11.


Select 

Create port 

connection 

Pan 

Drag a rectangle 

to zoom 

Zoom in 

Zoom to 

100% 

Zoom out 

Fit to current 

window 

4.3.5.1 Display of Unit and Model names 

Flip horizontal 

Snap to grid 

38 

Flip vertical 

Show unit 

names 

Show overview 

panel 

Figure 4.11 The Topology editor toolbar 

Show model 

names 

Rotate left 

Rotate right 

To toggle the display of the names of the Units in the flowsheet click on the button on the Topology 

editor tool bar, this will display or hide the names of the Units in the flowsheet 

To toggle the display of the names of the generic Models underneath each Unit in the flowsheet click on the 

button on the Topology editor tool bar, this will display or hide the names of the models underneath 

the Units in the flowsheet 

The font size of the Units and Model names is determined by the ModelBuilder preferences (accessed from the Edit 

menu - see Section 9.2). 

4.3.5.2 Zoom controls 

To pan the Model: click the button from the Topology editor tool bar. Select the Model and move the 

mouse to pan. 

To zoom in on a specific area of the flowsheet click the button from the Topology editor tool bar. 

Draw a rectangle covering the area of interest, to do this: click, hold and drag a rectangle and then release 

the mouse button. 

To zoom in and out the flowsheet with respect to the centre of the Topology editor window: click the 

or buttons from the Topology editor tool 19 

. 

19 Alternatively, to zoom in and out the flowsheet with respect to the centre of the Topology editor rotate the mouse 

wheel.

To return the flowsheet to its original size click the button from the Topology editor tool bar. 

39 

Topology tab 

To fit the Model to the current topology editor view size, click the button from the topology editor tool 

bar. 

4.3.5.3 Moving and rotating Units 

To move a Unit, or a set of Units: first select the Unit, or the set of Units, then, drag the selection with 

the mouse to a new location. 

To rotate a Unit, or a set of Units: select the Unit, or the set of Units, then click on the or buttons 

on the Topology editor tool bar. 

To flip a Unit, or a set of Units: select the Unit, or the set of Units, then click on the or buttons on 

the Topology editor tool bar to flip. 

4.3.5.4 The Topology overview panel 

A view of the whole flowsheet can be seen by opening a Topology overview panel (Figure 4.12). This can be 

activated from the view menu, or by selecting the button from the Topology editor tool bar. The whole 

flowsheet will appear in a detached small window along with a rectangle representing the area currently shown on 

the Topology editor view. 

The overview panel can be used to move the area shown on the topology editor, to do this: click and drag the 

rectangle on the overview window to the desired location. 

Figure 4.12 The overview panel

Chapter 5 - Optimisation Entities

Optimisation Entities 


This chapter describes the functionality and use of the intelligent editor for the formulation of an optimisation 

problem. Some basic familiarity with the gPROMS language and concepts is assumed. Details of how gPROMS can 

be used to perform (dynamic) optimisation calculations can be found in the gPROMS Advanced User Guide. 

Apart from the usual gPROMS language and properties tabs, there are three additional tabs for an Optimisation 

Entity: 

General 

Controls 

Constraints 

Please note that any changes in the intelligent editor will affect the text based editor and vice versa. 

42

43 

Specifying General information for an optimisation activity 

5.2 Specifying General information for an optimisation activity 

The user can define the name of the Process which the optimisation refers to, the objective function, whether this 

function is to be maximised or minimised and the type of optimisation (point or dynamic) to be performed in the 

General tab (see Figure 5.1) 

When dynamic optimisation is selected, the user needs to provide values for the guess, lower and upper bounds of 

the Time horizon. A default entry for the Control interval also appears in the cell matrix at the bottom window. The 

user needs to specify the values of the duration, lower and upper bounds for this Control interval before proceeding 

to another Control interval by clicking the Duplicate button. If the Fixed check box is selected, the bounds will be 

fixed according to the specified duration. For point or steady state optimisation, the Time horizon and the Control 

interval fields are disabled. 

Process name 

Variable full pathname 

Figure 5.1: General tab of Optimisation Entity 

Editor tabs


5.3 Specifying control variables for an optimisation activity 

The user can specify the name of the Control Variables, Control type (Time-invariant, Piecewise-constant or 

Piecewise-linear) and Allowable values (Continuous, Binary, Enumerated, Integer or Special Ordered Set 1) in the 

Control tab (see Figure 5.2). 

Depending on the Control type selected, the user will have different options for the Allowable values. Details of how 

to specify these will be presented in the following sections. 

Selected variable 

(yellow frame) 

Time profile shown in the 

bottom cell matrix 

Drag to 

internally 

resize the 

workbook 

Figure 5.2: Control tab of Optimisation Entity 

44 

Selected in the middle group 

of radio buttons 

Button to delete variables 

5.3.1 Time-invariant controls 

The user needs to specify the Initial guess, Lower bound and Upper bound for both the Continuous and Integer 

control variables, as shown in Figure 5.3 and Figure 5.4.

Figure 5.3: Time-invariant continuous control variables 

Figure 5.4: Time-invariant integer control variables 

45 

Specifying control variables for an optimisation activity 

When Binary Allowable values is selected, the user needs to select an appropriate initial guess for the Time-invariant 

control variable from the drop-down list, i.e. 0 is False and 1 is True (see Figure 5.5). 

Click on the arrow to display 

drop-down list 

Figure 5.5: Time-invariant binary control variables 

For Time-invariant Enumerated control variables, the user can enter the possible guesses in the blank field and then 

use the Add and Delete buttons to compile the list. The initial guess can be selected either by clicking the arrows to 

scroll to the desired value of the list of possible values or choosing the value directly in the list (see Figure 5.6).


46 

Arrows to scroll the possible guesses 

list to select the initial guess 

Text field to add new possible 

guesses 

Figure 5.6: Time-invariant enumerated control variables 

When Special Ordered Set 1 is selected for Allowable values, the user needs to provide the initial guess of the nonzero 

element as in Figure 5.7: 

Figure 5.7: Time-invariant control variables of type Special Ordered Set 1 

5.3.2 Piecewise-constant controls 

For Piecewise-constant control variables, the user needs to specify the values of the initial guess, lower and upper 

bounds for both the Continuous or Integer Allowable values as for the Time-invariant Control type. However, in this 

particular case, the same procedure is repeated for each Interval (see Figure 5.8): 

Value of the variable fixed in 

the interval

Figure 5.8: Piecewise-constant continuous control variables 

47 

Specifying control variables for an optimisation activity 

The user needs to activate/inactive the True check box for each Interval when defining the Piecewise-constant 

Binary option as in Figure 5.9: 

Check boxes to toggle 

between true and false 

Figure 5.9: Piecewise-constant binary control variables 

For Piecewise-constant and Enumerated option, the user needs to specify the initial guesses and possible values for 

each Interval (see Figure 5.10). Please note that the possible values of a Variable must be typed in the same cell 

only separated by commas. 

Possible values of the variable separated by 

commas 

Figure 5.10: Piecewise-constant enumerated control variables 

5.3.3 Piecewise-linear controls 

These are set in the same manner as Piecewise-constant continuous control variable, but different initial guesses 

and bounds must be set for both bounds of each interval (see Figure 5.11). The values at each Interval bound can 

also be fixed by checking the corresponding box.


Figure 5.11: Piecewise-linear control variables 

48 

Value of the variable fixed in 

this interval bound

5.4 Specifying Constraints for an optimisation activity 

49 

Specifying Constraints for an optimisation activity 

There are three types of Constraints that can be specified using the intelligent editor (see Figure 5.12): 

Equality end-point constraints 

Inequality end-point constraints 

Interior-point constraints 

Figure 5.12: Equality endpoint constraints, inequality endpoint constraints and interior-point constraints

Chapter 6 - Performed Experiment Entities

Performed Experiment Entities 


This chapter describes the functionality and use of the intelligent editor for the representation of information 

contained in performed experiments to be used for parameter estimation and experiment design purposes. Some 

basic familiarity with the gPROMS language and concepts is assumed. Details of how gPROMS can be used to 

perform parameter estimation and experiment design calculations can be found in the gPROMS Advanced User 

Guide. The user can find the Performed experiment Entity in the “… for parameter estimation” and in the “…for 

experiment design” Entities. 

Apart from the usual gPROMS language and properties tabs, there are three tabs for a Performed Experiment 

Entity: 

Initial conditions 

Controls 

Measured data 

Please note that any changes in the intelligent editor will affect the text based editor and vice versa. 

52

Specifying steady state or dynamic experiments and initial conditions 

6.2 Specifying steady state or dynamic experiments and initial 

conditions 

The user can specify the initial conditions for the Performed experiment Entity in the Initial condition tab (see Figure 

6.1). The selection of Steady state radio button will automatically disable the Initial condition cell matrix. 

When the Dynamic radio button is selected, the Initial condition cell matrix is activated. The user can enter a new 

Initial condition by double clicking on the new cell in the Variable name column and specify the corresponding Initial 

value for the defined Variable name. 

Figure 6.1: Initial conditions tabs of Performed Experiment Entity 

53

Performed Experiment Entities 

6.3 Specifying experiment control actions 

The specification of Time-invariant and Piecewise-constant control actions can be done in the Control tab as shown 

in Figure 6.2. 

The name and the value of the Time-invariant control can be specified using the same approach as with the 

specification of the Initial Conditions in section 6.2. 

For Piecewise-constant control, the user need to specify the Interval duration for each Interval first, and then fill in 

the corresponding values of the defined Piecewise-constant Variable at the appropriate column. 

Cell to introduce new 

piecewise-constant control 

variables 

Cell to introduce the duration of new 

intervals 

Figure 6.2: Controls tab of Performed Experiment Entity 

54

6.4 Specifying measured data 

55 

Specifying measured data 

All the measured experimental data can be recorded in the Measured data tab (see Figure 6.3). Double clicking on 

the New cell in the first row allows user to define new Variable name that will appear on the head row. The user can 

then enter the corresponding Time and value for the measured Variable. 

The user also has the option to choose the desired variance model for the measured variable by double clicking on 

the Variance model row. After selecting the desired Variance model in the drop-down list, the user needs to fill in the 

statistical variance model parameters (initial guesses and bounds or fixed values). 20 Please note that the measured 

values of different variables do not need to be synchronised, empty cells will become green. 

Statistical 

variance model 

Statistical variance model set in 

the Estimation entity 

Complete variable pathname 

Cell to introduce new measured 

variables 

Figure 6.3: Measured data tab of Performed Experiment Entity 

20 Refer to our Advanced User Guide for the definition of the statistical variance model.

Chapter 7 - Activity execution

Activity execution 

7.1 Cross-reference check 

Before attempting to execute an activity gPROMS checks that all Entities referenced from other Entities are either 

present in the current Project or from a cross referenced Project (see Section 2.3.2). gPROMS will notify you if you 

have made a mistake and a referenced Entity cannot be located, for example, by referring to a Model that does not 

exist within a Process. An example of this is shown in Figure 7.1. 

Figure 7.1 Automatic cross-reference checking using gPROMS 

58

7.2 Cases 

59 

Cases 

A Case is a combined record of all the input information that defines a Model-based activity and the results 

generated by the execution of this activity, as well as any diagnostic messages that may have been issued during its 

execution. The intention is that a Case may serve as a permanent record of a particular Model-based activity that 

can be archived for future reference, thus providing auditability and traceability of Model-based decisions. 

7.2.1 The Case configuration and execution control dialog 

A Case is created automatically by ModelBuilder at the start of the execution of any Model-based activity. An 

execution control dialog (see Figure 7.2) is presented to allow the user to configure various aspects of the Case 

including the following: 

The name of the Case 

Figure 7.2 The execution control dialog 

Default name for 

Case 

ModelBuilder creates a default name for the Case. This comprises the name of the Process Entity that is 

involved in this Model-based activity followed by the date and the time, the three parts being separated by 

underscore characters. The user may overwrite this name by editing the corresponding field in the Case dialog.


The contents of the Case 

o a copy of each and every Entity that has been used for defining this Model-based activity, including 

any Entities that reside in cross-referenced Projects (e.g. libraries, see Section 2.3.2) 

o a complete definition of the activity in the gPROMS language; this contains the above Entities in the 

correct reference order; the first line of each Entity is annotated with a comment naming the 

Project from which the Entity was obtained; 

o the results generated by the execution of the activity (see Section 7.4) 

The user may specify that one or more of the items above may be omitted from the Case by un-checking the 

corresponding check boxes. 

In addition to supporting the configuration of a Case, the Case dialog provides the user with some control over the 

execution of the Model-based activity, including: 

the amount of output information to be generated during execution 21 

. 

whether the licence required by the Model-based activity should be retained at the end of the execution 

(Release model after execution) 22 ; 

whether any Entities that are used by the activity and which are modified by its execution should 

automatically be updated at the end of the execution 23 . 

Finally, the execution control dialog provides a Cancel button that allows the user not to go ahead with the execution 

of the Model-based activity. On the other hand, pressing the OK button instructs the ModelBuilder to proceed with 

the execution. 

7.2.2 Management of Cases 

Once the user presses the OK button in the execution control dialog, ModelBuilder creates the Case. Just like a 

Project, a Case appears as a sub-tree of ModelBuilder's navigation tree (see Figure 7.3). However, unlike most 

Projects (also see Section 2.3.4), all entries in a Case are read-only, and this is indicated by a lock symbol 

annotating each entry in the Case sub-tree. 

Cases may be saved to disk using standard Save and “Save as…” mechanisms from ModelBuilder's Project menu. 

The files used for their permanent storage have the .gCS suffix and are marked as read only. Cases may also be 

closed (with or without saving) at any time, and also be opened at a later stage using standard Project-management 

mechanisms. 

21 

This output does not include any output generated by the gPROMS numerical solvers. This can be controlled 

separately using the PROCESS Entity's SOLUTIONPARAMETERs. 

22 

Retaining the licence allows some interaction with the Model at the end of the execution, see section 7.3. The 

licence can always be released manually at any time. 

23 This is particularly useful for gPROMS saved variable sets that may be used to provide initial guesses for the 

initialisation of the activity, and which are subsequently over-written by values obtained as a result of the execution 

of the activity. 

60

“Ribbon” symbol 

indicates that 

license is 

currently in use 

Case sub-tree 

“Lock” symbol 

indicates read-only 

Entities in Case 

Execution 

diagnostics 

output 

Figure 7.3 Cases and activity execution 

7.2.3 Default Case configuration and activity execution Preferences 

61 

Menu for 

interacting with 

executing activity 

Cases 

The default choices for the entries in the execution control dialog (see section 7.2.1) can be specified as part of the 

user's ModelBuilder Preferences. 

Highlighting the Activity execution entry in the Preferences dialog shows the window illustrated in Figure 7.4. An 

important aspect of this window is the check-box marked “Delete previous Case(s) from same Process”: during 

Model development, one typically executes the same Model-based activity (based on the same Process Entity) time 

and time again. In such situations, it is usually both unnecessary and undesirable for ModelBuilder to keep the Case 

corresponding to each and every execution. By enabling this check-box, the user instructs ModelBuilder to retain 

only one Case arising from any particular Process Entity. 

Further configuration options can be accessed by highlighting the “Case content defaults” entry in the ModelBuilder 

Preferences dialog.


Option to delete previous Cases 

from same Process entity 

Figure 7.4 ModelBuilder preference dialogs relating to Case management and activity execution 

62

7.3 Interacting with executing Model-based activities 

63 

Interacting with executing Model-based activities 

The execution of an activity is initiated by the user pressing the “OK” button on the execution control dialog. At this 

point, as has already been mentioned in section 7.2.2, the ModelBuilder creates the Case. It also requests and 

obtains the licence necessary for execution; this licence is associated with the Case until it is released either 

automatically at the end of the execution or manually at a later stage if the user has disabled this automatic licence 

release mechanism (see section 7.2.1). The fact that the Case is holding (“tying down”) a licence is indicated by a 

“ribbon” symbol attached to the Case's name in the ModelBuilder's navigation tree (see Figure 7.3). The symbol 

automatically disappears as soon as the licence is released. 

7.3.1 Execution output 

Once the necessary licence is obtained, ModelBuilder also creates an execution output window which displays all 

the messages relating to the solution of the Model-based activity. During this execution, the user can interact with 

the executing activity by right clicking on this window, which causes the execution interaction menu to appear; this 

is also shown in Figure 7.3. While the execution is actually proceeding, the menu has two main options that are 

enabled: 

The “stop execution, release model” option stops the execution at the earliest convenient stage and 

releases the licence. No further interaction with this Model-based activity is possible. 

The “stop execution, keep model” option also stops the execution at the earliest convenient stage. 

However, the licence is retained, and this allows the user to interact further with the executing activity via 

additional options in the execution interaction menu that become enabled at this stage, including: 

o “Release licence” releases the licence and essentially aborts the activity execution; no further 

interaction is possible with it. 

o “Query variable” allows the examination of the information available on a particular variable 

specified by its number as this is reported during the numerical solution; 

o “Query equation” allows the examination of the information available on a particular equation 

specified by its number as this is reported during the numerical solution; 

o “Query block” allows the examination of the information available on a particular block specified by 

its number as this is reported during the numerical solution. This option is only available when 

BDNLSOL is used as the non-linear solver and the block reported corresponds to the block in last 

initialisation/re-initialisation of the activity before it is stopped; 

o “Query unit” allows the examination of the information available on a particular UNIT specified by its 

complete pathname; 

o “Create Model report” creates a report on all parameters, variables and equations in the Model and 

incorporates this under the “Results” category of the current Case for later inspection or archiving; 

o “Create saved variable set” creates a gPROMS saved variable set using the current values of all 

variables; it then incorporates this under the “Results” category of the current Case. 

All the options listed above available after “stop execution, keep model” can also be performed once the activity has 

stopped automatically (whether it has failed or completed successfully) if the “Release model after execution” option 

was not selected in the case configuration dialog at the start of the activity. 

It is worth noting that (when in multiple windows mode) closing the execution output window by clicking on the X 

button at its top right corner does not cause the activity execution to be aborted or interrupted. In fact, the activity 

proceeds as before and all messages issued by it continue to be recorded within the Case. The execution output 

window can be made to re-appear at any time simply by double-clicking on the “Execution Output” entry in the Case 

sub-tree.


7.3.2 Diagnostics console 

The diagnostics console provides an alternative window for interacting with the model, see Figure 7.5. It displays 

the same information as the execution output during the simulation and can be interacted with in the same way by 

right clicking on the window. The diagnostics console provides a convenient way of interacting with the model whilst 

still being able to view the execution output in a separate window. It also provides a number of shortcuts for 

performing the various interactions with the models. 

As well right clicking on the window interactions can be performed using: 

buttons at the bottom of the diagnostics console. The buttons available for interaction are: 

o “qv” – query variable; 

o “qe” – query equation; 

o “qb” – query block; 

o “qu” – query unit; 

o “wr” – create model report; 

o “sa” – create saved variable set. 

commands in the command line at the bottom of the diagnostics console. The commands available are: 

o help [] 

o write [-v|--verbose] [-e|--edit] [] 

o save [-i] [-a] [-s] [-e|--edit] [] 

o qv 

o qe 

o qb [-b|--brief] 

o qu 

o release – to release the licence. 

Diagnostics buttons 

Figure 7.5 Diagnostics console 

64 

Execution output 

Diagnostics console 

Diagnostics 

command line

7.4 Activity Results 

65 

Activity Results 

All the results and any files (e.g. Saved Variable Sets) created during an activity run in the gPROMS environment are 

stored in the Case. 

7.4.1 Simulation activities 

gPROMS ModelBuilder stores the results of a simulation activity in the Case 24 . The results can be viewed in a tabular 

form on a single Variable basis (Figure 7.6). To access the results for a particular Variable: 

Expand the “Results” entity group 

Expand the “Simulation trajectory” entity group 

Expand the desired Unit tree, and 

Open the desired Variable by double-clicking it. 

Simulation results 

included in the Case 

Figure 7.6 Simulation results 

Note that this capability is complementary to the other gPROMS output channels. These include gRMS (gPROMS 

Result Manager System) 25 and the gPROMS Excel Output Channel which provide additional ways of viewing the 

results of a Simulation activity. 

24 If enabled from the Execution Control dialog (Section 7.2.1) 

25 

Sending results to gRMS can also be configured from the Execution Control dialog (Section 7.2.1).


7.4.1.1 Exporting the results 

The data for a single Variable can be exported as single Variable to a .cvs file - which can be opened for example by 

Microsoft Excel and Microsoft Word. To do this, right-click on the results table for a Variable to activate the 

Results shortcut menu and select “Export table”. Alternatively, the table data can be copied to the “clipboard” to be 

pasted into another application: to do this, select “Copy table to clipboard” from the Results shortcut menu. 

The complete results set for a simulation can be exported to a .gRMS file to be read by gRMS. To do this select the 

Simulation Trajectory entity group and select “Export”. 

7.4.2 Optimisation activities 

The execution of an optimisation run will generate four files in the Results folder of the Case: 

PPP 

PPP.out 

PPP.SCHEDULE 

PPP.point 

where PPP is the name of the optimisation entity that has been executed to produce these results. 

7.4.2.1 The comprehensive optimisation report file 

Double-clicking on the report entry, PPP, in the Case tree causes a report window to appear in the main window, 

see Figure 7.7. The report, presented in HTML format, includes: 

a table of contents that allows quick access to the information listed below via “hyperlinks”; 

general information such as the date and time of the execution of the activity, its final status and the value 

of the objective function; 

information on the various optimisation decision variables (time horizon, control interval durations, and timeinvariant 

and time-varying controls), including the values of: 

o the initial guess used, 

o the final value obtained, 

o the lower and upper bounds, 

o the Lagrange multipliers corresponding to the above bounds. 

All active bounds are automatically highlighted. 

66

Optimisation report in Case 

7.4.2.2 The optimisation report file 

Optimisation entity executed 

Figure 7.7 Comprehensive optimisation report 

The PPP.out file contains a summary report on the optimisation run in a simple text format, including: 

67 

Activity Results 

the outcome of the optimisation run; 

the final value of the objective function; 

the final value of the time horizon and the lengths of the time intervals; 

the final values of the time-invariant parameters, and the control-variable profiles; the latter are specified in 

terms of a single value per interval for piecewise-constant controls, and a pair of values for piecewise-linear 

controls (as usual, corresponding to the value of the control at the start and end of each interval); and 

the values of variables on which end-point and/or interior-point constraints where specified, at the 

corresponding final and/or interior points. 

The file also contains computational statistics on the performance of the numerical method. 

7.4.2.3 The Schedule file 

The PPP.SCHEDULE presents the most recent optimisation solution point in the form of a gPROMS Schedule. 

The Schedule file can be used to reproduce the detailed results of the optimisation by carrying out a Simulation 

activity within gPROMS. This provides you access to the full facilities of the gPROMS Results Management System 

(gRMS). In order to do this:


Paste the contents of the Schedule file except for the final END statement into the relevant Process entity 

of your gPROMS project. 

Also, paste the lines that appear inside the first RESET statement in the SCHEDULE into the ASSIGN section 

of the Process entity. 

Note: the contents of the Schedule file do not necessarily represent an optimal or even a feasible solution to the 

problem: if the optimisation run is interrupted by the user, or ends without finding a satisfactory solution, the file will 

simply show the point last considered by gPROMS. Only if a comment at the top of the file states the following: 

Final Optimisation Status : Optimal Solution Found 

should the results be relied upon as a (locally) optimal solution. 

7.4.2.4 The point file 

The PPP.point file is generated at every iteration of the optimisation calculation. It contains the same information as 

the Schedule file, but in the format of an Optimisation entity (except that constraints are not reproduced). This is 

useful if there is a need to restart an optimisation after a system crash or other catastrophic event, or, following a 

successful solution, to provide a good `initial guess' for a slightly altered optimisation problem. 

7.4.3 Parameter Estimation activities 

The execution of a parameter estimation run will generate four files in the Results sub-directory of the Case: 

PPP 

PPP.out 

PPP.stat 

PPP.stat-mr 

where PPP is the name of the parameter estimation entity that has been executed to produce these results above. 

7.4.3.1 The comprehensive estimation report file 

Double-clicking on the comprehensive report entry in the Case tree, PPP, causes a report window to appear. The 

comprehensive report, presented in HTML format, includes: 

a table of contents that allows quick access to the information listed below via “hyperlinks”; 

general information such as the date and time of the execution of the activity, and its final status; 

a detailed breakdown of the value of the likelihood function in terms of the constant, variance and residual 

terms of each measured variable in each experiment; 

the initial guesses and final (optimal) values of all Model parameters being estimated, together with the 

corresponding lower and upper bounds, the 90%, 95% and 99% confidence intervals, the 95% t-value and 

the standard deviation; 

the same information as above for any parameters describing the variance behaviour of the various 

sensors used for the measurements; these parameters will also have been estimated; 

a detailed analysis of each experiment, including the experimental controls and initial conditions, and the 

measured and estimated values of each measured point, as well as the corresponding difference 

(“residual”); 

the variance/covariance matrix; 

the correlation matrix; 

a goodness-of-fit analysis based on the 95% 2 criterion. 

Figure 7.8 shows an example of a comprehensive report. 

68

Parameter estimation 

report in Case 

7.4.3.2 The estimation report file 

Parameter estimation 

entity entity entity entity executed 

Figure 7.8 Parameter estimation comprehensive report 

The PPP.out file contains a summary report on the optimisation run, including: 

the outcome of the estimation run; 

the final value of the objective function; and 

the final values of the estimated parameters. 

The file also contains computational statistics on the performance of the numerical method. 

7.4.3.3 The estimation statistics file 

The PPP.stat file contains a report on the statistical validity of, and other indicators on the final results of the 

parameter estimation. Specifically, it contains the following information: 

69 

Activity Results


The variance Model used for each estimated parameter (measured variable) in each experiment, and 

information on the parameters of the variance Model. If these variance Model parameters were determined 

by the optimisation, PPP.stat lists the final values, initial guess, lower and upper bounds. Otherwise, the 

fixed values specified by the user are listed. 

Tables comparing each measurement from each experiment with the predicted values from the Process 

Model, together with: 

o the absolute deviation, 

o the relative deviation, 

o the standard deviation, 

o the scaled residual, 

The total contribution of each measured variable in each experiment to the objective function. This can help 

the user to identify experiments and/or measurements that give large contributions to the objective 

function and so are potentially inaccurate. 

A breakdown of the contributions to the objective function of: 

the variance terms, 

the residual terms, 

7.4.3.4 The machine-readable estimation statistics file 

The PPP.stat-mr file contains all the information that appears in the PPP.stat file but in machine-readable form. This 

is designed to be used with the advanced statistical analysis tool (see the gPROMS Advanced User Guide for further 

details). Note that to use the file with the statistical analysis tool you first need to export it from ModelBuilder as 

described in Section 8.6. 

70

Chapter 8 - Modelling Support Tools

Modelling Support Tools 


gPROMS ModelBuilder provides a set of powerful tools to support the user in developing and maintaining complex 

models. These are accessed from the “Tools” menu. These include productivity tools that allow the user to perform 

search and replace operations on the whole project tree and a comparison tool. The variable browser provides a 

convenient view of the different variables in a particular Process. Files can be imported into or linked too 

ModelBuilder and various export operations from ModelBuilder can be performed. 

This chapter describes the different tools available in more detail. 

72

8.2 Global “Search-and-replace” 

73 

Global “Search-and-replace” 

The search-and-replace tool can be used to search for a text string within selected Entities or Projects, and 

optionally to replace it with another string. The tool can be accessed via ModelBuilder's Tools menu and appears as 

a separate window, normally located at the bottom of the main ModelBuilder window (see Figure 8.1). The user has 

to specify a string to be searched for, and optionally a replacement string. The search can take place over all 

Projects that are currently open in ModelBuilder, or be limited to one or more Entities selected by left-clicking 26 

on 

their names in ModelBuilder's navigation tree. Various other aspects of the scope of the search 27 can be specified 

by enabling or disabling the check-boxes provided. 

Navigation 

buttons 

String 

occurrence tree 

Entity editor pops up automatically by 

clicking on entry in occurrence tree 

Replacement 

string 

Search-and-replace 

window 

Figure 8.1 The search and replace tool 

Scope of search 

to be performed 

Original string 

to search for 

Clicking on the “Search” button causes the search results to appear in the form of an occurrence tree, organised by 

Project, Entity group and Entity, in the left part of the search-and-replace window. 

Clicking on the “Search and Replace” button has a similar result, with the additional effect that all occurrences of the 

search string are changed to the specified replacement string. A replacement may be applied selectively by 

selecting one or more entries in the occurrence tree and clicking on the “Replace in selected occurrences” button. 

In this case, the selection moves on automatically to the next occurrence. This allows the replacement to be applied 

one-at-a-time in a controlled fashion. 

The navigation buttons situated on the left-hand side (Figure 8.1) help the user to manage the search results. These 

include: 

26 Standard Shift-left Click and Ctrl-left Click mechanisms can be used to select multiple Entities. 

27 e.g. whether the string should be an entire word or a sub-string within another word.


Expand all nodes in the search tree 

Collapse the search tree 

Select the next match 

Select the previous match 

Delete selected nodes from the search tree 

Select all visible replaceable matches in the search tree 

Double-clicking on any Entity name in the occurrence tree will cause the corresponding Entity editor to be displayed 

in the main ModelBuilder window. Double-clicking on a particular occurrence will have a similar effect, with the 

cursor located at the precise position within the Entity editor. 

The effects of any “replace” actions affected by ModelBuilder on a particular Entity can be reversed by opening the 

relevant Entity and pressing “undo" (Ctrl + Z) a sufficient number of times. 

74

8.3 Project and entity “Compare” 

75 

Project and entity “Compare” 

gPROMS ModelBuilder provides a comparison tool that can be used to compare any two selected Entities or 

Projects. The tool can be accessed via ModelBuilder's Tools menu, provided two comparable entries (e.g. Entities 

or Projects or Entity groups) have been selected in ModelBuilder's main navigation tree (see Figure 8.2). 

8.3.1 Entity comparison 

When two Entities are compared, a comparison window will pop-up highlighting the differences between them (e.g. 

any lines that are different in the two Entities, or which have been added or deleted); this is also illustrated in Figure 

8.2. The colours used for the highlighting can be configured as part of the user's ModelBuilder Preferences by 

highlighting the “Text comparison” entry in the Preferences dialog (see section 9.2). 

8.3.2 Project comparison 

The comparison tool may also be applied to two entire Projects. In this case, the results of the comparison will 

appear in a separate window, normally located at the bottom of the main ModelBuilder window (see Figure 8.3). In 

general, all Entities which occur in one of the two Projects but not in the other, or which occur in both Projects but 

in different versions, are presented in a comparison tree form in the left part of the comparison window. 

Different colours are used to denote various types of difference (e.g. addition, deletion, modification) in the 

comparison tree. These colours can be configured as part of the user's ModelBuilder Preferences by highlighting 

the “Group comparison” entry in the Preferences dialog (see section 9.2) 28 

. 

28 The content of the comparison tree can be controlled via the check-boxes provided in the right part of the 

comparison window.


Lines 

modified 

Projects Entities to to be 

be 

compared 

compared 

Clicking on added or 

deleted 

Entity entity entry entry launches 

launches 

Entity entity editor 

editor 

Entities to be 

compared 

76 

Entity 

comparison 

Lines added 

or deleted 

Figure 8.2 Comparison of two Entities 

Clicking Clicking on on modified modified Entity Entity entry 

entry 

launches launches Entity Entity comparison comparison window 

window 

Comparison 

window 

Figure 8.3 Comparison of two Projects 

Click here to repeat 

comparison

77 

Project and entity “Compare” 

Double clicking on an entry in the comparison tree corresponding to a deleted or added Entity will cause the 

corresponding Entity editor to pop up in the main ModelBuilder window. Double clicking on an entry corresponding 

to a modified Entity causes the Entity comparison window to appear (see section 8.3.1). 

The comparison tool may also be used to compare two Cases or a Case and a Project. This is particularly useful 

when attempting to compare a current model with one that was used in the past to produce certain archived 

results. 

8.3.3 Entity group comparison 

The comparison tool may also be used to compare corresponding groups of Entities (e.g. all Model Entities) 

residing in two different Projects. The behaviour of the comparison tool in group comparison mode is identical to 

that in the Project comparison mode described above.


8.4 “Import files” 

In addition to text files containing gPROMS language descriptions of various Entities 29 as well as other plain text 

files, ModelBuilder allows the importation into a Project of non-text (binary) files. These are held within the current 

Project under the “Miscellaneous files” category. 

This useful capability allows any type of file that is necessary for the correct operation of a Project (e.g. a MS Excel 

spreadsheet used in conjunction with gPROMS’ Excel Foreign Object/Foreign Process 30 

) to be incorporated within 

the Project, thus making the latter completely self-contained in this respect. 

Double-clicking on a binary miscellaneous file brings up a Properties dialog similar to the Properties tab of the 

standard Entity editors (see Section 2.2.1). A useful feature of this dialog is the “Export filename” property. This 

allows the user to specify the export filename as well as the sub-directory of the gPROMS execution into which this 

external binary file should be copied during execution of any gPROMS model-based activity. For example, consider a 

gPROMS model making use of a MS Excel Foreign Object described by the MS Excel file crystalliser.xls. Suppose, 

further, that the PROCESS Entity describing a simulation activity SETs the value of this Foreign Object as 

“ExcelForeignObjects\crystalliser.xls”. In this case, the export filename for this binary file should be set to 

“ExcelForeignObjects\crystalliser.xls” (see Figure 8.4). 

29 i.e. .gPROMS, .gOPT, .gEST, .RUN and .gSTORE files compatible with gPROMS v1.x. 

30 see the gPROMS Advanced User Guide. 

78

8.5 “Create links to external files” 

79 

“Create links to external files” 

It may sometimes be impractical and/or undesirable to import all files needed for the execution of a Project's 

model-based activities within the Project (see section 8.4). This is likely to be the case, for example, when such files 

are very large or when they are shared files that may need to be updated centrally from time to time. On the other 

hand, it may still be desirable to inform the Project explicitly of the association with these files and the need for 

copies of them to be present in certain sub-directories during execution. 

The above requirements can be addressed by establishing a link to the external file without physically importing it 

into the Project. ModelBuilder supports this activity via the “Create links to external files” tool provided under the 

Tools menu. The links established using this tool are displayed under the Project's Miscellaneous Files category (see 

Figure 8.5). 

Binary file imported 

into Project 

Filename and sub-directory to receive 

binary file during activity execution 

Figure 8.4 Binary files imported in Project


Link to 

external file 

Figure 8.5 Link to external files 

80

8.6 “Export” 

81 

“Export” 

ModelBuilder allows the contents of a Project or an Entity to be exported as a plain text file containing the 

corresponding gPROMS language description. This type of operation, which is useful for exporting models for use 

with gPROMS-based applications (e.g. gO:Matlab), can be performed using the “Export” tool provided under the 

Tools menu (see Figure 8.6). 

Entity to be 

exported 

Exported file to 

be encrypted 

8.6.1 Export Entity with dependencies 

Figure 8.6 The export tool 

Include crossreferenced 

Entities 

Password needed 

to run model 

Password needed 

to decode model 

When exporting an individual Entity, the user may request that all other Entities on which it depends (via crossreferencing) 

should be exported with it. 

This is achieved automatically by ModelBuilder irrespective of whether these Entities reside in the same Project as 

the Entity being exported, or in other Projects being cross-referenced by the current Project (see Section 2.3.2). 

The gPROMS language representation of each Entity in the export file is annotated with a comment stating the 

Project from which this Entity was extracted. 

8.6.2 Encryption 

The user can also request that the exported text file is encrypted. The encryption is performed using standard 

gPROMS file encryption facilities and makes use of a pair of passwords supplied by the user. The first password 

must be supplied for the use of the exported file within any gPROMS-based application. The second password is 

needed to decode the file and have access to its contents 31 .If this password is given then the encrypted file can be 

31 Leaving the second password blank in the export dialog will ensure that the exported file cannot be decoded.


opened in ModelBuilder. To open an encrypted file, use the normal open file methods (File>Open, the open tool bar 

button, etc) and change the Files of type field in the open dialog to “Encrypted gPROMS input files (*.gENCRYPT)”. 

Browse for and select the encrypted file to be opened and select open. A dialog then appears asking for the 

encryption and decryption passwords to be specified, Figure 8.7. 

Figure 8.7 Open encrypted file dialog 

82

8.7 “Export to ModelBuilder v2.2 Project” 

83 

“Export to ModelBuilder v2.2 Project” 

ModelBuilder v2.3 uses a different file format for storing its projects to that used by previous versions of 

ModelBuilder. In the interests of forward compatibility, ModelBuilder v2.3 projects may be exported in v2.2 format 

using the “Export to ModelBuilder v2.2 Project” tool in the Tools menu. Note that, not all gPROMS v2.3 concepts 

are recognised by earlier versions of gPROMS ModelBuilder (for example icons, ports).


8.8 “Export to Simulink” 

ModelBuilder can export gPROMS models to be used as Simulink ®32 blocks, see gOSimulink User Guide for 

information on how to use the exported model. 

To export a gPROMS model as a gOSimulink block, a working Process that uses a flowsheet containing the model 

must first be created in ModelBuilder. The model that is to become a gOSimulink block (“open loop” model) must 

contain ports, and these become the inputs and outputs of the block in Simulink ® 

(see Figure 8.8). 

„open loop“ model 

to be exported 

input ports 

Other blocks 

Figure 8.8 gPROMS Model with Ports 

84 

output ports 

A gSTORE file is needed to provide good initial guesses for the model and must be present in the project. Once the 

desired working Process is created the following steps should be followed to export it to gOSimulink: 

Highlight the Process, 

Select “Tools” from the menu bar, 

Select “Export to Simulink…”. 

This will pop-up a dialog box with various options to configure the exported files (Figure 8.9). 

32 Simulink is provided by Mathworks Inc.

Figure 8.9 Export to Simulink dialog 

The fields in this dialog box are described in more detail in Table 1 

Export Directory The directory in which the files exported will be located in 

85 

“Export to Simulink” 

Dictionary directory The directory in which dictionary files are located for models in gPROMS that 

can be replaced by standard Simulink ® 

models 

Simulink model (mdl) file The name of the Simulink ® file to be created 

gPROMS based Simulink block The unit in the Process that is to be the gOSimulink block 

Use assignments from saved 

variable set 

This selects the gSTORE file from which the values for the input and output 

ports are taken from to allow the open model to be run 

Overwrite Simulink model (mdl) file The export will write over the existing mdl file of the same name if it already 

exists 

Include generated open loop process 

and model in the current project 

A model and corresponding process to run it will be created in the project 

file that consists of just the gPROMS unit that was exported as the 

gOSimulink block (open model) 

Encryption password ModelBuilder creates an encrypted file during the export which is then used 

by gOSimulink. The encrypted file needs a password to allow it to be run 

Decryption password The encrypted file can be decrypted so that it can be viewed 

Table 1 Fields in Export to Simulink Dialog


8.9 “Browse variables” 

Although all the information of the Variables can be obtained from various Entities within a Project, the Variable 

browser tool can display the preset values of State and Algebraic variables 33 , the actual value for Assigned variables 

and other information on the Process Variables in a dialog window (see Figure 8.10). This tool can be accessed via 

ModelBuilder’s Tool menu, provided the Process whose Variables the user wants to browse has been selected in 

ModelBuilder’s main navigation tree. 

Figure 8.10 Variable browse 

33 

The Preset value for any state or algebraic variable corresponds to the value taken by gPROMS as the initial 

guess for the specific variable during the initialisation calculation. 

86

Chapter 9 - Utilities

Utilities 


A range of other features increase the functionality of gPROMS ModelBuilder. These features include standard 

utilities such as printing capabilities and window layouts. Also, ModelBuilder has a number of shortcut keys, many of 

which are the same as standard shortcut keys plus some ModelBuilder specific ones. 

This chapter describes the important features that haven’t been mentioned so far. 

88

9.2 ModelBuilder Preferences 

89 

ModelBuilder Preferences 

Many of ModelBuilder’s features can be customised by the user. The ModelBuilder preferences dialog (see Figure 

9.1) is opened from the Edit menu. There are seven preference categories, the main options for each are 

highlighted in Table 2. 

Figure 9.1 ModelBuilder Preference dialog

Utilities 

Categories Option 

Project Specify the number of recently opened projects to appear at the bottom of the 

Project menu; 

Specify any projects to be opened on start-up; 

Choose whether to make backup projects when saving or not; 

Entity editor Specify the general text editor settings, such as font properties, tab size; 

Customise the syntax highlighting attributes; 

Customise the settings for auto-completion in gPROMS language; 

View Choose the default setting for the editor mode (single or multiple editors); 

Specify the look and feel of gPROMS ModelBuilder. Three options are available: 

Metal, Windows and Motif; 

Specify the text size to be displayed in the Project tree; 

Comparison Specify the colours used for text and group comparison; 

File locations Specify the location for the temporary directory used by ModelBuilder. This is the 

temporary execution directory used to run model based activities; 

Specify the default starting location for the file dialog used for opening and saving 

projects; 

Specify a search path for any software components used by gPROMS, e.g. foreign 

objects, foreign processes etc. 

Activity execution Specify whether to delete previous Cases from the same processes when 

executing an activity; 

Configure the look of the execution output window; 

Configure the default settings for the contents of a Case; 

Flowsheeting Specify the font size to be displayed in the flowsheeting tab; 

Table 2: ModelBuilder preferences 

90

9.3 Text editor short-cut keys 

91 

Text editor short-cut keys 

A number of useful text editor short-cut keys have been defined in gPROMS ModelBuilder. Most commonly used 

short-cuts include: F4 to check syntax and F5 to simulate a PROCESS. This section lists the short-cut keys available 

in ModelBuilder and the associated action. 

'Current line' refers to the line that the cursor/caret is on. 

A '+' sign means hold the two keys either side of it down simultaneously. A ',' separates key presses, e.g. Alt + 

U, U means press the alt and U keys together, and then press the U key on its own. 

9.3.1 Navigation Shortcuts 

9.3.1.1 Shortcuts with standard navigation keys 

Keyboard shortcut With no selected text With selected text 

RIGHT 

LEFT 

Move the insertion point one character to 

the right. 

Move the insertion point one character to 

the left. 

DOWN Move the insertion point to the next line. 

UP 

SHIFT+RIGHT 

SHIFT+LEFT 

SHIFT+DOWN 

SHIFT+UP 

CTRL+RIGHT 

CTRL+LEFT 

CTRL+SHIFT+RIGHT 

CTRL+SHIFT+LEFT 

Move the insertion point to the previous 

line. 

Select the character to the right of the 

insertion point. 

Select the character to the left of the 

insertion point. 

Create a text selection and extend it to 

the next line. 


the previous line. 

Move the insertion point one word to the 

right. 

Move the insertion point one word to the 

left. 

Create a text selection and extend it one 

word to the right. 


word to the left. 

Deselect the text and move the insertion point 

one character to the right. 


one character to the left. 


to the next line. 


to the previous line. 

Extend the selection one character to the right. 

Extend the selection one character to the left. 

Extend the selection to the next line. 

Extend the selection to the previous line. 


one word to the right. 


one word to the left. 

Extend the selection one word to the right. 

Extend the selection one word to the left.

Utilities 

PgDown Move the insertion point one page down. 

PgUp Move the insertion point one page up. 

SHIFT+ PgDown 

SHIFT+PgUp 

HOME 

END 

SHIFT+HOME 

SHIFT+END 

CTRL+HOME 

CTRL+END 

CTRL+SHIFT+HOME 

CTRL+SHIFT+END 

ALT+u , e 


page down. 


page up. 

Move the insertion point to the beginning 

of the line. 

Move the insertion point to the end of the 

line. 


the beginning of the line. 


the end of the line. 

Move the insertion point to the beginning 

of the document. 


document. 


the beginning of the document. 


the end of the document. 


current word. 

Table 3 

92 


one page down. 


one page up. 

Extend the selection one page down. 

Extend the selection one page up. 


to the beginning of the line. 


to the end of the line. 

Extend the selection to the beginning of the 

line. 

Extend the selection to the end of the line. 


to the beginning of the document. 


to the end of the document. 

Extend the selection to the beginning of the 

document. 

Extend the selection to the end of the 

document. 

Move the insertion point to the end of the last 

word in the selection.

9.3.1.2 Insertion point/screen position shortcuts 

Keyboard 

shortcut 

93 

Action 

CTRL+UP Scroll the text one line up while holding the insertion point in the same position. 

CTRL+DOWN Scroll the text one line down while holding the insertion point in the same position. 

ALT+u , t 

ALT+u , m 

ALT+u , b 


Scroll the text up so that the insertion point moves to the top of the window while remaining at 

the same point in the text. 

Scroll the text so that the insertion point moves to the middle of the window while remaining at 

the same point in the text. 

Scroll the text down so that the insertion point moves to the bottom of the window while 

remaining at the same point in the text. 

SHIFT+ALT+t Move the insertion point to the top of the window. 

SHIFT+ALT+m Move the insertion point to the middle of the window. 

SHIFT+ALT+b Move the insertion point to the bottom of the window. 

9.3.1.3 Jump list shortcuts 

Keyboard shortcut Action 

Table 4 

ALT+k Go to previous entry in the jump list. 

ALT+l Go to next entry in the jump list. 

SHIFT+ALT+k Go to the previous jump list entry not in the same file. 

SHIFT+ALT+l Go to the next jump list entry not in the same file. 

9.3.1.4 Miscellaneous navigation shortcuts 

Keyboard shortcut Action 

F2 Go to next bookmark. 

CTRL+F2 Toggle bookmark. 

CTRL+[ Find matching bracket. 

Table 5 

CTRL+SHIFT+[ Select block between current bracket and matching one. 

Table 6

Utilities 

9.3.1.5 Find shortcuts 

Keyboard 

shortcut 

CTRL+f Show Find dialog. 

F3 Search for the next occurrence. 

SHIFT+F3 Search for the previous occurrence. 

CTRL+F3 

With no selected text With selected text 

Search for the next occurrence of the word that 

the insertion point is on. 

ALT+SHIFT+h Switch highlight search on or off. 

CTRL+g Show Goto Line dialog. 

9.3.2 Edit shortcuts 

9.3.2.1 Edit shortcuts 

Keyboard 

shortcut 

Table 7 

94 

Action 

INSERT Switch between insert mode and overwrite mode. 

CTRL+a Select all. 

CTRL+z Undo the previous command. 

CTRL+y Redo the undone command. 

CTRL+x Delete the selected text from the file and copy it the clipboard. 

SHIFT+DELETE Delete the selected text from the file and copy it the clipboard. 

CTRL+c Copy the selected text to the clipboard. 

CTRL+INSERT Copy the selected text to the clipboard. 

CTRL+v Insert the clipboard text into the file. 

SHIFT+INSERT Insert the clipboard text into the file. 

CTRL+e Remove the current line. 

CTRL+u 

Show Find dialog and show selected text 

as the text to find. 

Search for the next occurrence of the 

selected text. 

Delete text in the following cycle (when using the shortcut successive times): first the text 

preceding the insertion point on the same line, then the indentation on the line, then the line 

break, then the text on the previous line, and so on.

CTRL+w Remove the current word or the word preceding the insertion point 

CTRL+k 

CTRL+l 

95 


Word Match - find the previous word that begins like the current word and complete the current 

word so that they match 

Word Match - find the next word that begins like the current word and complete the current 

word so that they match 

DELETE Remove character after the insertion point 

SHIFT+SPACE Insert space without expanding abbreviation 

ALT+j Select the word the insertion point is on or deselect any selected text 

9.3.2.2 Indentation shortcuts 

Table 8 

Keyboard shortcut With no selected text With selected text 

TAB Insert tab Shift selection right 

SHIFT+TAB Shift selection left 

CTRL+t Shift line right Shift selection right 

CTRL+d Shift line left Shift selection left 

9.3.2.3 Capitalization shortcuts 

Keyboard 

shortcut 

Table 9 

With no selected text With selected text 

ALT+u , u Make the character after the insertion point uppercase Make the selection uppercase 

ALT+u , l Make the character after the insertion point lowercase Make the selection lowercase 

ALT+u , r 

Reverse the case of the character after the insertion 

point 

Table 10 

Reverse the case of the selected 

text

Utilities 

9.4 Miscellaneous Utilities 

9.4.1 Editing of Saved Variable Sets using external editor software 

Right clicking on the selected Saved Variable Sets file and subsequently selecting “Edit using external program…” 

will bring up an application chooser window for the user to select the .exe file of the desired editor. The file can then 

be modified in the chosen editor and saved again to be used by gPROMS (Please note that the user needs to close 

the editor application in order to return to ModelBuilder.). 

9.4.2 Printing 

Whole Projects or individual Entities can be printed by choosing the “Print…” option from the Project menu. If a PDF 

writer is installed, this facility can also be used to create a .pdf (Portable Document Format) file by choosing the 

PDF writer as the printer. 

9.4.3 Multiple selection 

Many “standard” editing features, e.g. cut, copy, paste, delete etc. all found under the Edit menu are available within 

the gPROMS ModelBuilder environment. Most of these (and other) actions can be applied to multiple Entities and 

Projects. Multiple selections are made using Ctrl + Left-click and Shift + Left-click mechanisms applied to the 

Project and Entity names in the ModelBuilder's navigation tree. 

Similarly, the “Open” action in the Project menu can be applied simultaneously to multiple Projects in the file 

selection dialog. 

9.4.4 Desktop view 

The Window menu gives the user the option of having multiple editors open simultaneously (see Figure 9.2) or only 

having a single editor open at a time (see Figure 9.3). In multiple editor mode, the Window menu contains standard 

“Cascade”, “Tile Horizontally”, ”Tile Vertically” and “Close All” options. 

The default setting for this option can be adjusted in the “ModelBuilder Preferences” dialog (see section 9.2) for 

details. 

96

Figure 9.2 Multiple editor mode 

Figure 9.3 Single editor mode 

97 

Miscellaneous Utilities

Utilities 

9.4.5 “Collapse project tree” action 

The “Collapse project tree” action (Ctrl + T) is found on ModelBuilder's View menu, allowing the Project tree to be 

collapsed to a view showing only the names of the open (Library) Projects and Cases. 

98

gPROMS ModelBuilder version 2.3.1

You also want an ePaper? Increase the reach of your titles

Delete template?

Save as template?