Download as pdf or txt
Download as pdf or txt
You are on page 1of 440

Table of Contents

Copyright © 1998-2007 Ventana Systems, Inc. Revision Date: July 4, 2007

1 Introduction 8
Vensim Documentation........................................................................................................... 8
User's Guide 8
Modeling Guide 8
Reference Manual 8
DSS Reference Supplement 9
Readme Notes 9
Version 5 Changes................................................................................................................... 9
Vensim Overview...................................................................................................................... 9
General Navigation 11
Vensim Software....................................................................................................................11
Vensim PLE 11
Vensim PLE Plus 12
Vensim Professional 12
Vensim DSS 12
Vensim Model Reader 12
Vensim DLL 12
Model Capacities 12
Publishing your Model ...........................................................................................................12
Computer Platforms...............................................................................................................13
Macintosh Notes 13
Technical Notes ......................................................................................................................14
Typographic Conventions 14
Mouse Movement Terminology 14

2 The Vensim Modeling Language 16


Mathematical Foundation......................................................................................................16
Integral and Differential Equations 16
Variable Types 17
Causal Models 17
Computational Sequence18
Variables ..................................................................................................................................19
Rules for Variable Names 20
Equations .................................................................................................................................21
Equation Components 21
Equation Format and Conventions 23
Operators 24
:NA: 25
Data Equations .......................................................................................................................25
Getting Data from Spreadsheets 27
Shifting Time Points 27
Subscripts†..............................................................................................................................28
Multiple Equations 29
Subscripting Constants 29
Subscript Functions 30
Mixed Variables Types† 31
Advanced Subscript Manipulation†.....................................................................................31
Numeric Ranges 31
VECTOR ELM MAP32
Subranges 32
Mapping of Subscript Ranges 33
Simulation Control Parameters ............................................................................................37
Special Variable Names ........................................................................................................38
Acceptable Integration Errors 39
Alternative Time Bases 39
RC START TIME 39
Groups......................................................................................................................................40
Definition of Ranges...............................................................................................................40
Macros†...................................................................................................................................40
Defining Macros 41
Using Macros 42

3 Model Settings to Units Checking 43


Model Settings ........................................................................................................................43
Time Bounds 43
Info/Sketch 44

1
Units Equiv 46
Error Checking........................................................................................................................48
Equation Editor 48
Text Editor 49
Error Checking Sequence.....................................................................................................49
Syntax Errors and Incomplete Equations ...........................................................................50
Syntax Errors and the Text Editor† 50
Syntax Errors in a .mdl File 51
Problems with Variable Types†............................................................................................51
Subscript Errors†....................................................................................................................52
Tracing Subscript Errors 53
Usage Messages....................................................................................................................53
Not Defined 53
Multiple Equations ..................................................................................................................54
Simultaneous Equations........................................................................................................55
Subscripts and Simultaneous Equations 55
Fixing Simultaneous Equations 56
Iterative Solutions to Active Simultaneous Equations 56
Units Checking........................................................................................................................57
Units Check Output 57
Source of Units Check Errors 58
Units and Lookup Functions 59
Correcting Units Errors 59
Reforming and Cleaning Models .........................................................................................60
4 Functions and Keywords 61
Summary List of Functions ...................................................................................................61
Lookups....................................................................................................................................68
Using Lookups 69
Special Interpolation Modes (Not PLE or PLE Plus) 71
Detailed Function Descriptions ............................................................................................71
5 The Sketch Editor 133
Starting the Sketch Editor...................................................................................................133
Notes on Sketch Behavior 133
Models and Views...............................................................................................................134
Sketches and V iews 134
Sketches and Equations 135
Variables, Words and Arrows .............................................................................................135
The Edit Menu.......................................................................................................................135
The View Menu.....................................................................................................................140
The Layout Menu..................................................................................................................144
Status Bar..............................................................................................................................144
The Sketch Layout...............................................................................................................146
Defined Variables and Shadow Variables ........................................................................146
Defined Variables 147
Shadow Variables 147
Sketch Comments, Valves and Junctions ........................................................................147
Sketch Tools..........................................................................................................................148
Pointer 149
Variable Class 150
Arrow Class 151
Rate Class 153
Input Output Object 155
Sketch Comment 156
Existing Variable Class 157
Merge 157
Magic Wand 159
Delete 160
Equations Class 160
Building Sketches from Models..........................................................................................161
Changing the Appearance of a View.................................................................................162
Moving a Word162
Reshaping an Arrow 162
Reattaching an Arrow 162
Resizing a Box or Circle around a Word 163
Wrapping Text 163
Joining Words 163
Variable Word Options 163
Sketch Comment Options 164
Valve Options 166
Arrow Options 166
Editing Equations 168
Sketch Workbench Interactions .........................................................................................168
Variable Selection 168
Navigation 168

2
Tool Activation 168
Simulation 168
Free-Form Sketching...........................................................................................................169
Sketching a Database..........................................................................................................169
6 The Equation Editor 170
Starting the Equation Editor................................................................................................170
Anatomy of the Equation Editor.........................................................................................170
Making Changes with the Equation Editor.......................................................................171
Entering Equations 171
Specifying Units 177
Setting the Range 178
Specifying the Group (Not PLE or PLE Plus) 178
Adding a Comment 178
Navigation inside the Equation Editor (Not PLE or PLE Plus) 179
The Errors Line 180
Dialog Control Buttons 180
Correcting Errors ..................................................................................................................182
Syntax Errors 182
Semantic Errors and Messages 183
Editing Lookups ....................................................................................................................183
Moving Points 186
Tracing Lines 186
Creating Subscripts†............................................................................................................186
Modifying Macros†...............................................................................................................186
Variable Types......................................................................................................................187
Returning from the Equation Editor...................................................................................187
7 The Text Editor† 188
Using the Text Editor ...........................................................................................................188
Notes on Text Edit Behavior 188
Text Editor Tool Options 188
The File Menu 189
The Edit Menu.......................................................................................................................190
The Insert Menu....................................................................................................................191
The View Menu.....................................................................................................................192
The Status Bar......................................................................................................................192
Using a Mouse in the Text Editor.......................................................................................193
Selecting Text .......................................................................................................................193
Search and Replace............................................................................................................193
The Text Editor Keys ...........................................................................................................194
Interacting With Models .......................................................................................................196
Syntax Errors 196
Semantic Errors 197
Causal Tracing198
Using Sketch Information in the Editor 198
Backup and History Files ....................................................................................................198
Backup File-Naming Conventions 199

8 Simulating Models 201


Selecting the Time Range...................................................................................................201
Simulating from the Toolbar................................................................................................201
Running a Game 202
Simulation Control Dialog....................................................................................................203
Standard 203
Changes 204
Sensitivity 205
Advanced 206
Closing the Dialog 207
Simulating the Model...........................................................................................................207
Simulation Error Messages 207
Work-in-Progress (WIP) Graphs 209
Interrupting Simulations 209
Changing Constant and Lookup Values ...........................................................................209
Interactive Changes 209
Constant Changes 210
Lookup Changes 211
Constant Input Files (Not PLE or PLE Plus) 212
Getting Constant Changes from Spreadsheets 212
Selecting an Integration Technique...................................................................................213
Euler Integration 214
Difference Integration 214
TIME STEP 214
Runge-Kutta Integration 215
Interactive Simulations (Gaming).......................................................................................216
Partial Model Simulation (Not PLE or PLE Plus).............................................................217

3
Simulating Incomplete Models ...........................................................................................218
Placeholder Values 219
Ignoring Variables 219

9 Preparing, Using and Exporting Data 221


Overview 221
Importing Data ......................................................................................................................222
Active Links to Spreadsheets 222
.dat Format DATA 222
Tab Delimited and Spreadsheet Data 224
Time Slop 228
Managing Data 228
Using Data to Drive a Model...............................................................................................229
Lookups and Data 230
Loading Data as a Model....................................................................................................230
Exporting Datasets ...............................................................................................................230
Export Dataset Example 232
Exporting Sensitivity Results ..............................................................................................233
10 Advanced Simulation Techniques 237
Overview 237
Save Lists ..............................................................................................................................237
Simulating with a Save List.................................................................................................239
Sensitivity Simulations (Monte-Carlo)...............................................................................239
Distributions 242
File Format 243
Noise in Active Variables 243
Combinatorial Sensitivity 244
Payoff Definitions†...............................................................................................................244
File Format 246
Payoff Computation 246
Payoff Definition Examples 247
Optimization† ........................................................................................................................248
Specifying Optimization Control 248
Starting the Optimization 250
Optimization Options 251
Examples of Optimization Control Files 258
Optimization Output 258
Additional Files 259
Using Output Files 259
Interrupting and Resuming Optimizations 260
Kalman Filtering†..................................................................................................................260
Driving Noise and Initial State Covariance 260
Example 260
Combining Filtering and Optimization 265
Optimizing Everything 266
Time Required for Simulations 266

11 SyntheSim 267
Seeing Behavior 267
Enlarging SyntheSim Graphs 267
Subscripts and SyntheSim Graphs† 268
Starting SyntheSim ..............................................................................................................269
SyntheSim Toolbar 269
Keeping Results from SyntheSim 271
Changing Constants ............................................................................................................271
Using the Keyboard 272
Setting Slider Bounds 272
Changing Constants from the Toolbar (Not PLE or PLE Plus) 273
Changing Lookups ...............................................................................................................274
Changing Behavior...............................................................................................................275
Input Modes 276
Freezing Levels 277
Model Errors..........................................................................................................................278
Input Output Controls with SyntheSim ..............................................................................279
Bigger Models .......................................................................................................................279
12 Control Panel and Subscript Control 281
Control Panel........................................................................................................................281
Time Axis 284
Scaling 285
Datasets 287
Graphs 288
Placeholders (Not PLE or PLE Plus) 290
Subscript Control†................................................................................................................291
Other Control Windows†.....................................................................................................293

4
13 Toolsets, Tools, and Causal Tracing 295
Sketch and Analysis Tools..................................................................................................295
Sketch Tools 296
The Analysis Tools 296
Customizing Tools (Not PLE or PLE Plus).......................................................................297
Opening and Saving Toolsets (Not PLE or PLE Plus)...................................................298
Toolsets Menu (Not PLE or PLE Plus) 298
The Toolset Editor (Not PLE or PLE Plus).......................................................................299
Adding Tools 301
Moving Tools 301
Deleting Tools 301
Locking Analysis Tools (Not PLE or PLE Plus)...............................................................301
Activating Analysis Tools ....................................................................................................302
Working with Tool Output....................................................................................................304
Menus 304
Moving Among Output Windows 305
Sizing 305
Exporting 305
Saving 307
Selecting Variables into the Workbench 307
Selecting a Time Range 308
Selecting a Vertical Range 309
Causal Tracing......................................................................................................................309
Causal Tracing Example 309

14 Analysis Tools 312


Structural Analysis Tools.....................................................................................................312
Tree Diagram ........................................................................................................................313
Outline....................................................................................................................................315
Document..............................................................................................................................315
Loops......................................................................................................................................318
Dataset Analysis Tools ........................................................................................................318
Strip Graph Tool ...................................................................................................................318
Sensitivity Graph ..................................................................................................................322
Graph......................................................................................................................................323
Table.......................................................................................................................................326
Stats†.....................................................................................................................................329
Bar Graph..............................................................................................................................330
Gantt Chart†..........................................................................................................................334
Runs Compare......................................................................................................................336
Miscellaneous Tools ............................................................................................................337
Units Check...........................................................................................................................337
Equation Editor.....................................................................................................................337
Text Editor†...........................................................................................................................337
Venapp Editor‡.....................................................................................................................338
Reality Check........................................................................................................................338
15 Custom Graphs, Tables and Reports 339
Overview 339
The Custom Graph Editor...................................................................................................339
Variable Entry 341
Displaying a Named Graph 342
XY Graphs.............................................................................................................................343
Getting Values for Variables ...............................................................................................344
Displaying the Dataset Name 346
The Custom Table Editor....................................................................................................346
Variable Entry 347
Comment Entry 347
Time Range 347
Custom Graph Definition Files†.........................................................................................348
File Format 348
Common Keywords 349
Custom Graphs.....................................................................................................................349
Graph Tool Keywords 350
Custom Bar Graph†.............................................................................................................354
Bar Graph Tool Keywords 354
Population Pyramids 357
Custom Tables†....................................................................................................................358
Custom Table Keywords 358
Custom Reports†..................................................................................................................359
Custom Report Tool Keywords 359
Text for Reports 360
Variables in Reports 360

5
16 Menus and Common Dialogs 362
Menu Commands .................................................................................................................362
File Menu 362
View/Edit/Layout Menus 364
Model Menu 364
Tools Menu 367
Windows Menu 367
Help Menu 369
Main Toolbar.........................................................................................................................369
Printing...................................................................................................................................369
Print Options Dialog 370
Printing In Color 372
Utility Dialogs ........................................................................................................................372
File Selection Dialog 372
Variable Selection Dialog 373
Written Response Dialog 374
Color Selection Dialog 374
List Reorder Dialog 375
Fonts Selection Dialog 375
Query Boxes 376
Message Boxes 376

17 Options 378
Options for PLE and PLE Plus ...........................................................................................378
The Global Options Dialog..................................................................................................380
Fonts.......................................................................................................................................380
Fonts1 381
Fonts2 382
Colors & Markings ................................................................................................................382
Graphics.................................................................................................................................384
Units (for New Models)........................................................................................................386
Startup....................................................................................................................................386
Sketch and Sketch Defaults................................................................................................387
Sketch 387
Sketch Defaults 389
Toolbars .................................................................................................................................390
Settings and Advanced........................................................................................................390
Settings 391

Appendix A — Glossary of Terms 395


Appendix B — Bibliography 402
Building Models ....................................................................................................................402
System Dynamics 402
Model Analysis......................................................................................................................403
Filtering and Optimal Control 403
Schweppe Statistics 403
Probability and Statistics 403
Technical Reference............................................................................................................404
Appendix C — Converting Models 405
Model Interchange Format..................................................................................................405
Converting DYNAMO Models to Vensim..........................................................................405
Converting Stella® or ithink® Models to Vensim ............................................................406
Appendix D — File Formats 408
Sketch Information...............................................................................................................408
Objects 409

Appendix E — Allocation 413


Difficulty of Getting a Good Formulation 413
Requirements of a realistic allocation logic 413
Market Clearing Allocation 414
Prioritization, Demand and Supply Curves 416
Specifying the Curves 417
One-to-many Allocation 419
Many-to-many Allocation.....................................................................................................421
Matching Suppliers and Demanders .................................................................................423

6
7
1 Introduction

This reference manual is not intended to be read from cover to cover. It is organized by subject area
and the individual subject areas can be read together, or the manual can be used to look up information.
It is designed to work in conjunction with the Vensim User's Guide and the Vensim Modeling Guide.
There is also a supplementary manual called the Vensim DSS Reference Supplement which describes
functionality unique to Vensim DSS. This chapter:
? Describes the Vensim documentation.
? Summarizes Changes in Vensim 5 and indicates where they are documented
? Discusses the Vensim interface, with pointers to further documentation.
? Provides an overview of the different Vensim configurations.
? Describes how to publish your model for use with the Vensim Model Reader.
? Reviews platform-specific issues related to Vensim.
? Outlines the typographic and terminology conventions used in this model.

Vensim Documentation
The documentation consists of four separate books plus notes.

User's Guide
Regardless of your skill level, the best way to get started with Vensim is probably to use the Vensim
User's Guide. This is a hands-on description of the steps you need to go through to build and work
with Vensim models. If you are just getting started on modeling, the User’s Guide will walk you
through a number of examples. This is a good way of building up the mechanical skills that will
support further learning. If you are a skilled modeler but are unfamiliar with Vensim, this is a good
way of getting up to speed on how to use Vensim. If you are upgrading from an earlier version of
Vensim, skimming through the User's Guide is a good way to see how things have changed.

Modeling Guide
The Vensim Modeling Guide is intended to demonstrate good practice in the development of Vensim
models for a variety of problems. The Modeling Guide does not go into the detailed mechanics of
using Vensim. Instead, the Modeling Guide focuses on the conceptual parts of building a model and
shows a number of different ways to approach the modeling process. The models in the Modeling
Guide are very simple and designed to be fairly easy to create. If you are not an experienced modeler,
reading through the Modeling Guide and working some of the examples should prove quite fruitful.

Reference Manual
The Reference Manual is a comprehensive coverage of the functionality of the Vensim software. It is
organized by function, with references to other material when different functions overlap. The
Reference Manual can be used to look up particular pieces of information, such as the meaning of a
check box in a dialog box. It is also useful for reviewing a particular piece of functionality such as the
management of toolsets.

8
DSS Reference Supplement
The DSS Reference Supplement contains information that is specific to Vensim DSS. It is organized in
the same way as the Reference Manual.

Readme Notes
These notes contain corrections, clarifications and additions to the standard documentation. Readme
notes are supplied in electronic form and are automatically installed whenever you install or update
Vensim. You can open the Readme notes using the Help>Readme command.

Version 5 Changes

SyntheSim
SyntheSim is new to Vensim 5 and is discussed at length in Chapter 13 of the User's Guide and
Chapter 11 of this manual.

Language, Functions and Data


Several new functions have been added and these are discussed in Chapter 4. There is also some
discussion of discrete event functions in Chapter 9 of the Modeling Guide. The macro definition
language has changed somewhat and this is discussed in Chapter 2.

Model Comparison
The model comparison function allows you to compare the current model to other models or previous
versions of the same model. This is very useful in helping track down what changes were recently
made.

Single Clicking
Variable selection now occurs on a single click almost everywhere. The most notable selection is the
Text editor (Professional and DSS only) where double clicks are still used. The variable selection
dialog also selects a variable from its list into the workbench when you click on it.

Sketch Behavior
The sizing of words has changed so that they are anchored from the upper left corner and word
wrapping occurs as the words are sized. This makes it much easier to select the appropriate size,
especially for clear boxes.

Vensim DLL Changes


The Vensim DLL has been changed to include the SyntheSim functionality. There is also a multiple
context version of the DLL available as a separate product.

Backward Compatibility
Models developed in earlier versions of Vensim can be used in version 5 without difficulty. Models
that have been developed in 5 and do not make use of any of the enhanced functionality can be used in
earlier versions of Vensim. Models using new functions or language extensions in will give a syntax
error message and will not open in earlier versions. The most common likely difference is the addition
of the increment to the variable range specification. If you use File>Save As and specify that the
model be saved in an earlier format these increment will be dropped from the range specifications.

Vensim Overview
Vensim is organized around models, and data or simulation results that relate to those models. These
two concepts are often labeled structure and behavior, and Vensim maintains a strong distinction

9
between the two. If you have worked with spreadsheets you may be used to thinking of a spreadsheet
as containing both formulas and relationships and the numbers these generate. In Vensim the formulas
and relationship make up the model. The numbers these generate are treated as experiments with the
model and they are stored as datasets separate from the model. This allows you to make any number
of experiments and retain the results without having to set up additional places to put them.
Vensim uses a workbench toolbox metaphor to deal with models and data. The program is analogous
to a workbench that allows you to build and analyze a model and its related data. We will often refer
to the main Vensim window as the Workbench, and this is what appears when you start Vensim. The
Workbench contains a menu, a model, a variable, datasets, a toolbar, one or more toolsets, controls,
tool output windows and model building windows.

Model Workbench Variable Build Window (Sketch Editing Area)

Menu

Main
Toolbar

Sketch
Toolset

Analysis
Toolset

Tool
Output

Status
Bar

Control Panel Available Dataset Loaded Datasets


The model (world.mdl) and variable (deaths crowding multiplier) are named in the title bar of the
window. The datasets in use (current and base) are named in the Control Panel. The menu is below
the title bar and the Main Toolbar below the menu. The Analysis Toolset is visible on the left. The
Build window contains the model in the Workbench (this is normally the case unless there are multiple
Build windows open). The Control Panel is open showing the Datasets tab. There is tool output from
the Tree Diagram and the Strip Graph tools. The Status Bar reflects the Build window because the
Build window (containing the model) is the active window (The Windows>Keep Build Behind toggle
was checked for the above screenshot).
? The menu and Main Toolbar are discussed in Chapter 16. Chapter 8 contains discussion of how to
use the Main Toolbar to simulate models.
? The Control Panel and Subscript Control are discussed in Chapter 12.
? The modification and use of toolsets (both Sketch and Analysis toolsets) as well as how to work
with tool output windows are discussed in Chapter 13. The Analysis Tools themselves are

10
discussed in Chapter 14.
? The Build windows are discussed in Chapter 5 and Chapter 7 (Text editor). The Equation Editor
and Graph Lookup Editor are discussed in Chapter 6.
? The Status Bar is used by the Sketch Editor and Text Editor and is discussed in Chapter 5 and
Chapter 7

General Navigation
Vensim uses an extended Multiple Document Interface (MDI) to manage its windows. It is extended
in the sense that there are three classes of windows.
Build windows let you modify models and other files. Build windows can be open in the Sketch
Editor or the Text Editor.
Control windows let you change the settings in Vensim. There are two control windows: the Control
Panel, and the Subscript Control.
Output windows (or Tool Output windows) are the output from the Analysis Tools, from some menu
items, and from error or warning messages and simulation messages. Output windows can be viewed
but they cannot be changed. You can select the Workbench Variable from an Output window.

In order to manage the three classes of windows, Vensim lets you move among windows in a class,
and among the classes of windows. You also have the option of keeping the Build windows behind,
and of keeping the Control windows in front.
From the keyboard, you can move among windows in a class by holding down the Ctrl key and
pressing the Tab key. You can move among window classes by holding down the Ctrl and Shift keys
and pressing the Tab key.
Using the mouse, you can move among windows in class with by clicking on the windows, or clicking
on any of the rightmost buttons in the Main Toolbar. If, for example, an Output window is open and
you click on the Output button it will show the next Output window. If the Build window is
active and hiding any Output windows, clicking on the Output button brings all Output windows
forward.
Note that if you are keeping the Build windows behind or the Control windows in front, the window
you activate might be partially, or even completely, obscured by other windows.
You can maximize or minimize windows by clicking on the appropriate button at the right of the title
bar for that window. A minimized Build window has a restore button in the Menu area. Double
clicking on a title bar of a window will also maximize or restore the window.

Vensim Software
Vensim is available in a number of different configurations. Each configuration provides an increasing
level of functionality. Vensim also provides you with the capability to publish your models for free
distribution using the Vensim Model Reader.
Vensim PLE, PLE Plus Standard, Professional and DSS and are all documented in this reference
manual. Not all material is applicable to all configurations and this is indicated as clearly as possible.
In addition, chapters and sections that are applicable only to Vensim Professional and Vensim DSS are
marked with a † while chapters and sections that are applicable only to Vensim DSS are marked with a
‡.

Vensim PLE
Vensim Personal Learning Edition (PLE) is a configuration of Vensim that makes it easy to learn to
build system dynamics models. Vensim PLE is similar to other Vensim configurations, except that a

11
number of features and many options have been removed. The result is a simple product aimed at
people who want to learn how to build good quality system dynamics models.
Vensim PLE is intended for people who want to learn how to build system dynamics models. It is free
for educational and personal use, and available at a modest price for commercial use. Vensim PLE is
shareware and can be downloaded from our web site (http://www.vensim.com) for your own use or to
pass onto others.

Vensim PLE Plus


Vensim PLE Plus has the same interface as Vensim PLE but extensions to its functionality that allow
multiple Views, use of data, sensitivity simulations and breaking of feedback links in SyntheSim
mode. In keeping with the design philosophy for Vensim PLE it still has the simplest possible
interface and a reduced number of menu items. It is intended for students and practitioners who want
to do relatively simple modeling work but need to go beyond what is available in Vensim PLE.

Vensim Professional
Vensim Professional is designed for the development of larger and more elaborate models containing
subscripted variables. Almost all of the material covered in this manual documents functionality that is
part of Vensim Professional. Vensim Professional does not allow you to extend your models using
external functions, compile simulations, build Vensim applications, or access the Vensim DLL.

Vensim DSS
Vensim DSS includes all the features of Vensim Professional and also allows you to compile
simulations, create external functions, write Vensim applications, write Command Scripts, and use the
Vensim DLL with other computer languages. Vensim DSS has a supplementary reference manual for
features that are not documented in this manual.

Vensim Model Reader


The Vensim Model reader is a freely-distributable piece of software that allows you to publish your
model. It has a very simple interface and menu structure, simpler even than Vensim PLE. Publishing
your model is as easy as using menu File>Save As — see the information on Publishing your model
below. The Vensim Model reader is available for download from http://www.vensim.com. A copy
(named venred32.exe) is also contained on the Vensim CD.

Vensim DLL
The Vensim DLL allows you to call Vensim functions from other applications. You can simulate
models, retrieve results and even create Vensim graphs and tables. The Vensim DLL is part of Vensim
DSS. If you develop applications using them these can be packaged for use with the Vensim Model
Reader. Details for doing this are contained in the Vensim DSS Reference Supplement.

Model Capacities
All of the Vensim configurations are available for Window (98/ME/NT/2000/XP) and Power
Macintosh. There are no hard limitations on model capacity. Large models will require large amounts
of memory and disk space to store results. When models get large you may need to use Save Lists to
manage both disk and memory usage.

Publishing your Model

You can give your model to anyone you want to by supplying them with a copy of the Vensim Model
reader. To prepare your model for use with the reader, you need to publish to a published model
(.vpm) or published application (.vpa) format or save it as a Binary (.vmf) file. Anyone with the
Vensim Model Reader will then be able to simulate and experiment with your model.

12
If you are planning on sending out your model using the Model Reader you might want to put
navigation icons on the first view of the model to make it easier to explore model structure. See
Chapter 5.
More notes on preparing your model for publication are contained in Chapter 19 of the User's Guide.

Computer Platforms
Vensim runs on Window 98, Millennium, NT 4.0, 2000 and XP. Vensim will Run on the Macintosh
under System X in "Classic" mode. With the exception of Binary Graph definitions (.vgf) and binary
Venapp Definitions (.vcf), all files are compatible between the different platforms. If you are moving
between Windows and the Macintosh, you might find that it takes a longer time to open a binary
format model or dataset the first time. Vensim must modify these files when moving back and forth
and this can be a little slow.
All of the screen shots in this manual were done using Windows, most with Windows XP using
Vensim DSS and there may be some slight differences in appearance depending on your Vensim
configuration and operating system.
For the most part the screens look very similar on the Macintosh. There are, however, some behavior
differences on the Macintosh that are worth noting.

Macintosh Notes
NOTE By default Vensim is allocated two megabytes of memory. If you are working with larger
models you might want to increase this by clicking on the Vensim icon and using the File>Get Info
command from the Macintosh Finder. Using less than one megabyte is unlikely to work.

Differences from Other Macintosh Applications


There are several differences between Vensim and most other Macintosh Application: The parent-child
form of the user interface, the appearance of dialogs and the printing dialogs.
The user interface in Vensim is an extended multiple document interface in which all windows are
maintained within a parent window. Because there are three different types of window — build,
control and output — and because there can be tens or even hundreds of output windows, containing
them within a parent makes it much easier to move between applications. This does, however, mean
that Vensim appears as one big window containing numerous smaller windows instead of numerous
small windows spread out across the desktop. The smaller windows are also sized following the
Windows convention of dragging on their borders rather than the Macintosh conventions of dragging
on the lower right hand corner. The parent window is sized following Macintosh conventions.
Dialogs on the Macintosh will appear quite similar to the way they appear on Windows. Buttons will
be square and have a three dimensional appearance.
In some places Vensim will use file name with paths. Normally this is accessed through a file dialog
and should be transparent. Nonetheless, there are many places where you might see file names such as
:Macintosh HD:Vensim:models:butter.mdl. The colon : is used to separate folders. File extensions
such as .mdl can be used to identify TEXT files as models.
Printing with Vensim is discussed in Chapter 15. Vensim uses its own print dialog. The standard
dialog for printing that would normally be seen on a Macintosh does not appear.

Differences Between the Macintosh and PC


Vensim uses standard Macintosh file access dialogs. Because these are the standard dialogs they will
look very different from other dialogs in Vensim.

13
Vensim for the Macintosh is constructed as a 32 bit application. This removes most of the limitations
on model size, but the Macintosh operating system does impose several restrictions that do reduce
capacity relative to Vensim DSS32 under Windows NT.
The compiled simulation and external function options of Vensim are not available on the Macintosh.
The functions that communicate with spreadsheets (GET 123 DATA, GET XLS DATA, GET 123
CONSTANTS and GET XLS CONSTANTS) as no available on the Macintosh.
The Macintosh does not support hardware interrupts on floating point errors and therefore these are
checked in software by Vensim. Normally both platforms will yield the same results. For example
mytime=1/(25-Time)
will cause an error message to be reported at time 25. However, the equation
mytime = IF_THEN_ELSE(1/(25-Time),Time,-Time)
will cause an error message to be reported on the PC but not on the Macintosh.

Dialog boxes on the Macintosh have the standard Macintosh Tab behavior. You cannot use the Tab
key to move between buttons.

The Macintosh has only one mouse button; the PC has two. Vensim uses a convention of left button
(on the PC) or only button (on the Macintosh) for most mouse click operations. Setting options on
sketch objects and Analysis tools is performed by a right mouse click (on the PC) or a combination
Control key (or Apple key) plus mouse click (on the Macintosh).

Technical Notes

Typographic Conventions
Sections marked with a dagger † are applicable only to Vensim Professional and Vensim DSS.
Sections marked with a double dagger ‡ are applicable only to Vensim DSS.
File names and directories are shown in italics, as in vensim.exe, or c :\vensim. File names might
appear in lower or upper-case depending on context.
Variable names are displayed in Italic Courier font.

Functions names, keywords and model control parameters (such as TIME STEP) are displayed in all
caps.
The name of a label in a dialog box is displayed in Bold the first time it appears, and elsewhere when
clarity requires.
When symbols are used in the manual they will be first named, and then shown with no intervening
punctuation. Thus, for example, a tilde ~ appears like this.

When there are option settings for which one or more choices are allowed the choices are separated by
commas , (Level, Auxiliary, Constant). Default choices are shown bold.
When there are option settings for which only a single choice is allowed, the choices are separated by
the word "or" (On or Off). The default choice is shown bold.
Menu items are shown as the name of the menu heading, followed by a greater than sign > and the
entry under that heading. As in File>New Model.

Mouse Movement Terminology


Vensim is a highly visual product that relies heavily on the use of the mouse. If you have worked with
other mouse-driven applications you should have no trouble understanding how to use the mouse with
Vensim. Still, it is useful to define some basic terminology. Words appearing in bold are also defined
in the glossary.

14
Click. To click on an object, you position the pointer over the object and then depress and release the
left mouse button without any intervening mouse motion. A Click with the right mouse button is
accomplished in a similar fashion.
Control-click. To control-click is the same as to click , except that the keyboard's Ctrl key is held
down throughout the operation. Normally a Click with the right mouse button is the same as a
Control-click.
Drag. To drag, depress the left mouse button and move the mouse without releasing the mouse
button. Dragging can be used to move objects, and to highlight text.
To move an object, position the pointer over the object and drag. As you drag an outline or other
indicator will show you where the object will be moved to on completion. Position the outline where
you want the object to be and release the mouse button.
To highlight text, position the pointer over the beginning of the text you want to highlight and drag.
Let go of the mouse button when the text you want is highlighted.

Highlight. Highlighted objects indicate that they will be used for a special purpose. You can
highlight text by dragging over it.
Select. You can select a menu item such as File>Exit by depressing the left mouse button over "File"
in the menu-bar and dragging until "Exit" is highlighted and releasing the mouse button. You can
also select a menu item by clicking on "File" in the menu bar, and then clicking on "Exit" which,
along with the other File commands , will remain visible after your first click on "File."
Shift-click. To shift-click is the same as to click, except that the keyboard's Shift key is held down
throughout the operation.

15
2 The Vensim Modeling Language

The Vensim modeling language is a rich and readable way of representing dynamic systems. This
chapter:
? Introduces the mathematical concepts underlying the language.
? Shows the different variable types used by Vensim.
? Provides the syntax for writing Vensim equations.
? Discusses the use of subscripts to simplify equation writing.
? Explains the definition and use of macros.

Mathematical Foundation
Lest the very first thing you read in this manual is an integral equation, let us hasten to say that the
purpose of Vensim is to help solve problems that would be hard to address mathematically without the
aid of simulation. To a very large extent, the Vensim environment will insulate you from both the
underlying mathematics and the details of the language specification. The graphical creation of
models using the Sketch and Equation Editors allows you to build and use models without worrying
too much about how the Vensim modeling language works or what the underlying mathematics are.
Still, there comes a time in every modeler's career when there is a strong need to delve a little deeper.

Integral and Differential Equations


This chapter is a detailed discussion of the Vensim modeling language, which allows for simple
representation of complex dynamic systems. For the discussion that follows it is important to
understand that it is the Levels (or state variables) that define the dynamics of a system. For the
mathematically inclined we can introduce this in a more formal way. The following equations show
the basic mathematical form of the Vensim modeling language.
T

levelst ? ?ratest dt d
levelst ? ratest
(1) 0 or dt
ratest ? g ( levelst , auxt , datat , const )
(2)
auxt ? f (levelst , auxt , datat , const )
(3)
levels0 ? h(levels0 , aux0 , data0 , const )
(4)
In these equations g, h, and f are arbitrary, nonlinear, potentially time varying, vector-valued functions.
Equation 1 represents the evolution of the system over time, equation 2 the computation of the rates
determining that evolution, equation 3 the intermediate results necessary to compute the rates, and
equation 4 the initialization of the system.

Equation 1 above is written using both integral and differential notation. The format that Vensim uses
for expressing equations matches more closely the first, but the two equations have the same meaning.
Equation 3 above could also be written as:

f (levels t , auxt , datat , const ) ? 0


(3a)

16
In this notation the implicit solution to the above equation defines auxt. We do not use this notation
because Vensim allows elements of auxt to depend on other elements, but not normally in a circular
fashion (see "Causal Models " below). Vensim does have the functionality to solve special cases of
equation 3a, (see "Simultaneous Equations" below) but this functionality it not part of the standard
system dynamics framework.

Variable Types
The symbols aux, const, data, levels and rates represent different types of variables.
? auxt Auxiliary. These are computed (see equation 3) from Levels , Constants, Data, and other
Auxiliaries. Auxiliary variables have no memory, and their current values are independent of the
values of variables at previous times.
? const Constants. These do not change with time.
? datat Data (also called exogenous). These have values that change over time but are
independent of anything that happens to other variables.
? levelst Levels (also called accumulations, stocks and states). These change only over time
and the values they take on at any time depend on the value they (and other variables) took on at
previous times. Equation 1 shows how the Levels integrate or "accumulate" based on the values
themselves and other variables in the system. The Level variables ultimately determine the
dynamic behavior of a system.
? ratest Rates (also called flows). These are the variables that directly change the Levels . Rates
are essentially the same as Auxiliaries and differ only in the way they are used in a model.
In the Vensim modeling language, Rates are implicitly determined based on Auxiliaries and other
variables, and are not broken out as a separate variable type. Put another way, an Auxiliary that is used
to change a Level can also be thought of as a Rate.
In addition to Auxiliaries, Constants, Data and Levels the Vensim modeling language contains a
number of additional variable types that make analysis easier and more powerful. The different
variables types are discussed in detail in the section "Variables" below.

Causal Models
Equation 4 shows that the values of the Levels and Auxiliaries depend on each other at initialization
time. Equation 3 shows that the values of Auxiliaries depend on other Auxiliaries at all times. Both of
these equations must satisfy the additional restriction that the value of any given variable at a particular
time cannot depend on itself. The value of a variable can, however, depend upon its value at a
previous time. A model in which the value of a variable at aparticular time can be determined without
reference to that variable is said to be causal.
As an example of a model that is not causal, consider a company that attempts to set price in order to
achieve a revenue goal. You could represent this as:

price
sales
target revenue
inidicated
price

If sales change as soon as price does, price changes as soon as indicated price does, and
indicated price changes as soon as sales does, then sales effectively depends on itself.
Such a system is not causal, and although a mathematical solution to the problem might exist, Vensim
will report this as an error and make no attempt to solve it (see Chapter 3).

17
In this simple example, causality can be restored by recognizing that indicated price is not
adjusted based on current sales, but rather on average sales over the previous weeks, months, or
even years.

sales

Average time to average sales


price
Sales

inidicated target revenue


price

In the above diagram, a box is used to show that Average Sales is a Level variable. Because
Average Sales is a Level, its value at a particular time is known as a result of integration from
previous times. All feedback loops require at least one Level. (The exception to this rule is that you
can use the SIMULTANEOUS or FIND ZERO function to solve a model such as the first one shown.
Whether or not simultaneous circular causality constitutes feedback is a question we will leave open.)

Computational Sequence
As long as a model is causal, Vensim can determine the values of all variables. Vensim uses the causal
structure to determine the appropriate sequence of computation. The order in which you define the
variables makes no difference to the computational sequence. Vensim performs the following steps in
simulating a model:

1 - Preparation
All the Constants are set to the values specified for them and any changes files or spreadsheet
references for Constants are processed.. All Data (both exogenous variables and data needed for
payoff computation) are read, the values loaded and data equations computed. This includes data that
are read from spreadsheets. The value of the initial time is computed and all the Data variables are set
to their values at this time.
At the end of preparation all Constants and Data will have values assigned.

2 - Initialization
For each level in the model Vensim determines the initial value for that level by looking at the
variables used in the initial part of the equation for that level. If a variable used in the equation has not
been computed, Vensim uses the equation for that variable to compute its value. This process is
performed recursively until only constants or data appear on the right hand side, or a circle is detected.
If a circle is detected, Vensim issues a simultaneous initial equation error message.
At the end of initialization all the Levels in the model will have values. In the process of computing
these values, some Auxiliaries might also have values assigned.

3 - Storage of Results (Diff only)


If the Integration type Diff (for Difference Equation) is selected results will be stored at this point.
Note that on the first pass this can mean that some Auxiliaries have not been computed and will be
recorded with a missing value. The recorded results are the Levels (at a particular time) and the
Auxiliaries that resulted in those Levels.

4 - Computation of Auxiliaries
For each Auxiliary in the model, the Auxiliary's value is computed by looking at its equation. If an
input to the equation has not been computed, it's value is computed before proceeding. This process is
again recursive and ends when the variables to be used are Constants, Data, or Levels. If a circle is

18
detected, a simultaneous equation error is issued. For obvious computational reasons this ordering of
computation occurs in advance of the actual simulation.
If an Auxiliary variable was computed in step 2 above it is possible that it will be computed to have a
different value in this step. This will only occur if an ACTIVE INITIAL equation is used. If this
does happen, and the difference is bigger than the threshold value specified in the Options dialog, this
condition will be reported in an error window.

In Reality Check mode if a variable has an active test input the value for that variable is first computed
using its normal equation and then overridden using the test input. This overriding occurs before the
variable is used in any other equation.
At the end of this step all the model variables will have a value.

5 - Storage of Results (normal)


For all integration types except Diff the results of all the previous steps computations are stored at this
point. The values that are stored are those of the Levels and of the Auxiliaries that result from those
Levels.

6 - Computation of Net Rates


Based on the Auxiliaries, the net rate of change for each Level in the model is computed.

7 - Integration
For Euler Integration, the results of step 6 are multiplied by TIME STEP and added to the values of
the Levels. For Runge-Kutta Integration, steps 4 and 6 are repeated a number of times (but no
information is stored during this computation). The book Numerical Recipes in C cited in the
bibliography contains more information on these integration techniques.

At the end of this step, Time has advanced by TIME STEP and the values of the Levels at the new
time have been computed.

9 - Continuation
Steps 3,4,5,6 and 7 are repeated until time reaches FINAL TIME.

Variables
Explaining variables is often difficult without reference to equations, but it is useful to have a complete
categorization and specify conventions before we talk about equations. Vensim is designed so that
what a variable is and does can be determined by the way it is defined or used. There are no forward
declarations of variables and no added markers indicating what a variable is. The following list
describes the eleven variable types used in Vensim (four of which were introduced in the previous
section).
NOTE Vensim is not case sensitive. You can enter variables with any mix of lower and upper case
you like. Vensim will retain the case, but recognize the variable even when used with other
capitalization patterns.
? Auxiliary. Any dynamic variable that is computed from other variables at a given time.
Auxiliaries are typically the most numerous variable type. An auxiliary variable has an expression
involving other variables in its equation.
? Constant. A variable whose value does not change over time. Constants have numbers on the
right side of their equations or can be defined using the GET XLS CONSTANTS function or the
TABBED ARRAY function. A constant can be temporarily changed prior to simulating a model.
? Data. These have values that change over time, but do not depend on other model variables
(except possibly other data). Data use an empty equation to denote raw data or a := equation to
indicate the way in which they are derived. If a variable is used in a model, but not defined, it will

19
be assumed exogenous and therefore treated as a Data variable. This makes it easy to run sections
of a model without writing new equations.
? Group. Groups are not really variables, but a way to group different variables together. They
have no values, but can be used to access collections of other variable types. Groups appear
enclosed in special markers which consist of four (4) or more asterisks ****, or are defined by
typing their name into the Group selector in the Equation Edit tool. Group names are shown
preceded by a period . to prevent confusion with other variable names.
? Initial . Like a constant, except that it is the result of comb ining different variables at initialization
time. Initials all have INITIAL or REINITIAL equations, as described in Chapter 3.
? Level. The dynamic variables in the model. Levels all have INTEG equations as described in
Chapter 4.
? Lookup. Nonlinear functions with numerical parameters (where the parameters are the x- and y-
axis values). They are defined in equations beginning with a left parenthesis ( and ending with a
right parenthesis ).
? String Variable. String Variables (also called String Constants take on a character string as a
value. They are useful with the MESSAGE function and as labels in Venapps.
? Subscript Element. An element of a Subscript Range. These identify the meaning of specific
values of a subscript. The Subscript Elements appear on the right hand side of a Subscript Range
equation.
? Subscript Range. Rather than repeating the same equation with different names, you can write
one equation using a subscript that takes on different values. We refer to variables in such an
equation as subscripted, with one name representing more than one distinct concept. Subscript
Ranges are defined using a special equation that begins with a colon :.
? Time Base. Like an Auxiliary, but with some special output and data interpretation features.
These must use the TIME BASE equation as described in Chapter 4.
? Units. Units are defined as additional information about a model variable and can be used to
check the model for dimensional consistency. Units are entered as an expression in the units field
of an equation.
? Unchangeable Constants: These are Constants that can’t be changed during simulation
experiments. For example the number of days per year would sensibly be defined as an
Unchangeable Constant. Equations for Unchangeable Constants are the same as those for
Constants but use a double equal sign == for assignment.
Constants and Unchangeable Constants are almost the same. The only difference is that the value for
an Unchangeable Constant is determined from its equations, or read from a spreadsheet when a model
is checked, and never changed after that. If you include an Unchangeable Constant in a .cin file you
will get an error message. Unchangeable Constants are not given sliders in SyntheSim and are not
included in Constant lists for Sensitivity, Optimization or Setting of Parameters.

Rules for Variable Names


Variable names can be of any length and contain any characters. Variable names containing special
characters must be surrounded by double quotes "" when used in equations. If you use the Sketch and
Equation editors, Vensim will automatically add the quotes.
Variable names do not need to be surrounded by quotes if they start with a letter, or international
character, and contain only letters, international characters, numbers, single quotes ' and dollar signs $.
Variable names can contain spaces and underbars _ and the two are considered interchangeable. If two
or more spaces or underbars appear side by side, they will be collapsed to a single space (for example
Hello _ _ __ There will become Hello There). When you work
with Vensim you can choose whether to have variable names appear with a space or underbar _.

20
Variable names cannot contain an explicit line break. In the Equation Editor, this means that you
cannot add a Ctrl+Enter sequence within a variable name. Line wraps, entered automatically by the
Equation Editor, do not present a problem. In the Text Editor, lines ending with a backslash \ will be
assumed to be continued. Vensim will add line continuation characters automatically when you move
between the Text and Equation Editors.
Variable names are not case sensitive, but Vensim is case retentive. Vensim will use the capitalization
that first appears for a variable name. If you use the Text editor to enter a model, it is the first
occurrence (not the defining equation) of a variable that defines the case that will be retained. With the
Sketch editor it is the way you first enter it. You can change the capitalization of a variable name by
retyping it in the Sketch Editor or by replacing all occurrences of the variable in the Text Editor.
With the exception of String Variables, all variables in Vensim are treated as single-precision floating
point numbers. Vensim DSS is optionally available in configuration that uses double precision
computation (but single precision storage).

Examples
TOTAL_COST, total cost, Total _ Cost
The above would all be recognized as the same variable
"Color TV Sets & VCRS"
Color TV Sets[SONY]
"R & D"["Gov & Foreign"]
Using quotes in subscripts can be confusing and is not recommended.
"HiRes TV/Web Sets"[ASIA,country,SONY]
"The \"Final\" Frontier"
Quotes embedded within variable names must be preceded by a backslash \
érosion d'action
Uses international characters but does not require quotes.
For clarity, in this manual variable names will normally be presented in italic Courier font.

Equations

The Vensim modeling language allows you to define the model you want by writing a set of
mathematical equations and expressions. You can enter equations (or expressions) in any order.
When the model is simulated, the ordering of equations necessary for computation is determined as
described above. If this is not possible because of simultaneous initial or active equations, this will be
reported. See Chapter 3 "Model and Unit Checking," Chapter 5 "The Sketch Editor," Chapter 6
"The Equation Editor," and Chapter 7 "The Text Editor" for further descriptions of problems and the
correction process.

Equation Components
The equation for a variable shows how that variable is derived from other variables. When you specify
the equation for a variable you also have an opportunity to specify other important information,
including:
? Units of measure for the variable.
? Minimum and maximum values the variable would be expected to take on along with an
increment.
? A description of what the variable is and its importance.
? The group with which you want the variable associated.
? A flag to mark the variable as an output only variable (supplementary).

21
The way you enter this information depends on the tools you use to build your model. If you use the
Equation Editor there are fields for each of these inputs, as can be seen here.

Equation Supplementary Flag

Units Group Range Comment


Not that the Editor is usually used in conjunction with the Sketch tool which creates the structural
relationships between variables. The Equation Editor then adds in the equation, as well as the other
components.
If you are using the Text Edit tool - or storing the model in .mdl format, the different components are
delimited using tildes ~ and terminated using a vertical bar | as shown here:

********************
.Finance
Group
********************~| (by position)
{. . . intervening equations . . .}
net income = taxable income - taxes
Equation
~$/year [0,1E9] Range
~The flow rate of income accruing….
Units ~:SUP |
Comment
Supplementary Flag
The tilde ~ symbol separates the units from the equation, the comment from the units, and any
additional information from the comment. The vertical bar | signals that a new equation will follow.
Other than the equation, all of the components can be left empty, but you must explicitly recognize this
omission by including the delimiters ( ~ and most importantly |) after each equation, as in:

22
net income = taxable income - taxes~~ |
For economy of expression the tilde-tilde-bar ~~| notation will usually be used in the reference manual.
If you are working with the Equation Editor these delimiters will not appear, but the components they
delimit will appear in the Equation Edit window as shown above.

Equation Format and Conventions


Vensim uses standard algebraic expressions with the same rules for precedence as those used by
JAVA, DYNAMO, C, BASIC and other common languages. Vensim also supports standard
mathematical functions and has additional functions that make writing equations faster and simpler.
Every equation has a field for the units of measure and for a short description of the variable on the left
as in:
profit = revenue - cost
~$/year
~The profit of our company. |
If you include the units of measure and description, you can take advantage of Vensim's on-line
documentation and units -checking capabilities.
In addition to the units of measure, you can include the range that is allowable or definitionally
possible for a variable, as in:
cost = fixed cost + variable cost
~ $/year [0,500E6]
~ The total cost of operations.
|
During simulation any variable that goes outside of its range will be flagged with a warning message.

Increment
You can include the increment by adding a third number in the range as in:
Time to adjust workforce
~ Month [1,30,.5]
~ The time to adjust the workforce up and down.
|
The increment specified is only used for constants to determine the amount of change in response to
slider movements when SyntheSim is active. You can make the increment the same as the full range
as in
Switch for quality correction
~ Dmnl [0,1,1]
~ Switch to indicate that speed is adjusted when quality changes.
|
This will cause the slider in SyntheSim to have only two positions (on/off).

Supplementary
You can also mark a variable as supplementary in order to suppress the USE FLAG messages. When
working with the Equation Editor, you mark a variable as supplementary by clicking on the
supplementary checkbox. In the Text Editor, you can mark a variable as supplementary by using the
:SUP flag after the comment.

Examples
Spacing and line breaks are ignored within equations (except that line breaks are not allowed within a
variable name as described above). You can include comments in an equation by enclosing them in

23
paired braces { }. The examples below illustrate some different formats for defining equation
information.

Example 1 (Best Practice)


sales = salesmen * sales productivity
~ $/year [0,1.0E6]
~ Dollar volume of sales.
|

Quick and Dirty


sales = salesmen * sales productivity ~~|
No units or comment. It is always recommended that you include units.

Redundant Definition
Sometimes when variables are subscripted, you need to write more than one equation, because some or
all of the subscripts require a separate equation. Because comments and units are associated with
variable names, not with equations, you only need to fill in the units and comment once. In the
Equation Editor this is automatically taken care of for you. In the Text Editor you will need to end all
but one equation with a ~~| or simply a |. If more then one set of comments or units is specified for a
variable you will receive a warning message, and only the first will be used.
population[AgeGroup1] = INTEG(births – deaths[AgeGroup1] –
aging[AgeGroup1],init population[AgeGroup1])~~|
population[AgeOlder] = INTEG(aging[AgeYounger]-deaths[AgeOlder]-
aging[AgeOlder],init population[AgeOlder])
~ Rabbit
~ The population of rabbits – births only add to the first cohort
|

Example 2
{Formulation provided by
John Jackson (phone: 2-3433)}
unit cost = ( 1 + interest rate )
* ( investment / ( 1 - tax rate ) + operating cost -
tax rate * depreciation / (1-tax rate) )/
( ( 1 + interest rate ) *
quantity produced )
~ $ / unit
~ unit cost of product built up from definitions used by the company
cost accountants.
|
Example 2 illustrates an equation format that uses spacing and multiple lines to make a complicated
equation as transparent as possible. You can place braces { } anywhere inside of an equation. Vensim
ignores everything appearing within the braces when the equation is read in. Comments within braces
will appear in on-line model documentation.

Operators
Vensim supports standard unary and binary operators that observe conventional precedence. These
operators are (in decreasing order of precedence):

24
Assignment Operators
=, :=, == (numeric)
:, <->, :IS: (symbolic)

Unary Operators:
:NOT: (logical)
-, + (arithmetic)

Binary Operators
^ (arithmetic-power)
*, / (arithmetic)
+, - (arithmetic)
<, >, <=, >= (logical relational)
= (logical relational)
:AND: (logical)
:OR: (logical-non exclusive)
The relational and logical operators can only be used in function calls and are intended for use only
with the IF THEN ELSE, SAMPLE IF TRUE and SHIFT IF TRUE functions described in
Chapter 4. It is not permissible to use an arithmetic operator on a logical expression (an expression
using a logical operator). The first assignment operator (=, := or ==) appearing in an equation is the
unique assignment operator for that equation and must appear directly after the first variable name.
NOTE Precedence can be overridden using parentheses (). Reality Check statements are nonstandard
in their use of operators including the assignment operator.

:NA:
You can use the keyword :NA: where a variable name or number would normally appear. :NA:
takes on a special value (-2109 ) that can be used to test for the existence of data. "Data Equations"
below gives an example of how to test for the existence of data at a given time using :NA:.

If you assign a variable the value :NA: at any time the value will not appear in graphs (it will be
ignored or interpolated over) and will show up as only "—" in tables.

Data Equations
Data have two purposes in models. First, they can be used to compare the behavior of models to that
of real systems. Second, they can drive model variables that do not warrant explicit endogenous
modeling. No distinction is made between the two types of data, but actual practice often places the
two types into separate models or files. We will touch on this briefly below.
The equations defining data are largely the same as those defining other variables, except that a colon
equal := is used instead of an equal sign. Data equations also have some special features that
determine how the data will be used if they are referenced elsewhere in the model as exogenous inputs.
There are two ways to mark variables as Data variables.
1. Do not write any equation. If something is used it will be marked as not defined and thereafter
treated as exogenous. This approach is useful only in the Text Editor.
2. In the Equation Editor mark a variable as of type Data, possibly with an equation. In the Text
Editor enter the variable name with no equation,
fixed cost data ~~|
or write an equation using :-.
cost data := variable cost data + fixed cost data ~~|

25
Only other data and constants may appear on the right-hand side of the last type of equation. These
must either be computed using other := equations, or be read in directly as raw data.
When data variables are used as exogenous inputs, they will have values at distinct time points only.
Between these time points it is necessary to fix values for the exogenous inputs. There are four ways
of doing this.
? Interpolating a value (the default).
? Holding a value when it is passed until a new value is found.
? Looking forward to the next value and using it.
? Marking data as missing when not available.
These are invoked using keywords, as in the following example:
production ahead :LOOK FORWARD: := planned production raw
~ tons/year
~ The planned production figures for next year,
used in determining material acquisition.

|
Production held :HOLD BACKWARD: := planned production raw
~ The planned production for this year, used in
computing performance.

|
production smooth :INTERPOLATE: := planned production raw
~ tons/year
~ The interpolated values of planned production,
used for ramping output.

26
|
Outside of the range of the raw data, the three ways of dealing with data are exactly the same. Inside,
there are substantial differences which can be used to tailor the effect of exogenous inputs to your
needs.
The fourth manner of dealing with Data allows testing for the availability of data in model equations.
For example:
PRODUCTION raw :RAW: := PLANNED production raw
~ tons/year
~ The raw amount of production used to test availability of data
inside of a model.
|
This data would take on the value 2 in 1981, 4 in 1982 and 1 in 1984. At all other times it would take
on the special value :NA:. There are a number of uses for :RAW: data, but the most common is as a
means of selecting between model generated data and actual data. For example the equations:
DEMAND data :RAW: ~~|
demand = IF THEN ELSE(DEMAND data = :NA:,model demand,DEMAND
data)~~|
allows you to use historical demand in part of a simulation, and model generated demand in another
part. If you are using this technique you need to be sure that TIME STEP is set so that the data for
demand is only missing when you want it to be. If you think doing this will cause integration problems
you might consider experimenting with other integration techniques.

When data are used for historical comparison, no use is made of the different models for dealing with
data. Rather, the actual data are used at the closest time points.

Getting Data from Spreadsheets


Details for importing data from spreadsheets are covered in Chapter 9. It is also possible to directly
get data from a spreadsheet using the GET 123 DATA or GET XLS DATA functions. For example,
the equation
sales data := GET XLS DATA('ourstore.xls','sales','1','B5')
tells Vensim to look to the Excel file ourstore.xls on the tab labeled sales. Vensim will read values for
Time from row 1 and get values for sales data starting in cell B5 (from the 5th row starting in the
second column).

Shifting Time Points


Since data might contain measurements of both stocks and flows, it is sometimes desirable to shift data
earlier or later in time to ensure that the proper correspondence between model and data is maintained.
Infrequently, you might also want the model to look a short time ahead when using exogenous data.

27
You can shift time points by shifting the data in time. This shifting must be done within a model. For
example:
TROUBLE coming := time shift(TROuble,TROUBLE HORIZON) ~~|
TROUBLE HORIZON = 2 ~~|
would create the data variable TROUBLE coming that is to take on the same value as TROuble two
months before TROuble does. A time-shifted data variable can only depend on one other data
variable. Time shifts can only use numbers and constants as the second argument to the function (the
amount of the shift). The use of a time shift actually results in a new data series on a new set of time
points. This data series is stored along with the run results and can be viewed using any of the analysis
tools.

Subscripts†
Subscripts are only available in Vensim Professional and DSS.

Subscripts allow a single variable to represent more than one thing. All variable types except Groups,
Units, String Constants, Subscript Ranges, Subscript Elements, and Time Bases can have subscripts.
Subscripts are enclosed in square brackets [ ] directly following the variable name. A variable can
have up to eight subscripts separated by commas ,. You must use subscript values for a variable
consistently throughout the model. If you do not, Vensim returns error messages.
NOTE Subscript Elements are also sometimes referred to as Subscript Constants.

Subscripts do not appear in sketches. Sketches represent structure, and subscripts are a convenient
way of replicating structure. The sketch maintains a simpler and less cluttered view of a model by not
distinguishing subscripted and unsubscripted variables. When there are multiple equations for a
subscripted variable, the sketch represents the interaction implied by all of the equations (the union of
interactions). You define and edit subscripts from the Subscript Control which, in turn, opens the
Equation Editor. You can also change the definition of a subscript anytime the Equation Editor is open
by choosing the name of the subscript to edit. Subscripts are applied to variables by editing their
equations of using the Edit>Set Subscripts command.
To indicate the specific set of "values" which a subscript will take on, it is necessary to define a
Subscript Range as a series of Subscript Elements.

Example
country : MEXICO, USA, CANADA
~ index
~ The list of countries represented in the model
|
births[country] = Population[country] *
BIRTH FRACTION[country]
~ people / year
~ Total live births in a specific country.
When you use a Subscript Range in an equation it must appear on the left hand side. For example the
equation:
deaths = Population[country]/average lifetime ~~|
would generate an error message. In this equation deaths takes on only one value, while
Population[country] takes on three different values. There is no way to determine how to
assign those values in the above equation.

It is not, however, true that every variable on the right hand side of an equation needs to have the same
subscripts . For example the equation

28
deaths[country] = Population[country]/average lifetime ~~|
is completely valid. Here the equation says that deaths in a country depend on the population in that
country, but that each country has the same death rate.

Multiple Equations
For an unsubscripted variable you only need a single equation to define the variable. With subscripts,
however, it is sometimes desirable to have more than one equation. There is an Add Eq button in the
Equation Editor that allows you to do this. In the text editor you simply enter a number of equations as
in:
capacity utilization[toledo] = production *
fraction production to toledo / capacity[toledo] ~~|
capacity utilization[bismark] = production * (1 -
fraction production to toledo) / capacity[bismark]
~ Dmnl
~ The fraction of capacity used.
|
Normally all but the last equation are left with empty units and comment fields. If you enter more than
one set of units or comment you will get a warning message and all but the first will be ignored.

In the above example both equations used the same variables, but in a different way. In general
different equations for a variable may use different variables. The Causal Tracing functionality of
Vensim looks at the causality for each individual subscript. For symbolic relationships such as those
used for the Tree diagram and Sketch operations the union of all inputs over all equations is used when
representing causes.

Subscripting Constants
Typically, subscripted constants will take on a number of values. For example:
birth fraction[MEXICO] = 0.03 ~~|
birth fraction[USA] = 0.02 ~~|
birth fraction[CANADA] = 0.02
~ fraction
~ Fertility as a fraction of population.
|
You can replace these three equations with:
BIRTH FRACTION[country]=0.03,0.02,0.02 ~ fraction ~|
In this notation the order is that of the defining equation for country.

It is also possible to define two dimensional arrays of values by separating the rows with semi colons.
For example:
blood type : A, B, O, AB ~~|
initial population[country,blood type] = 1,2,3,4;5,6,7,8;
9,10,11,12; ~Person~|
This is a compact way of setting up arrays of numbers. There are also two functions that can make it
convenient to set up arrays of numbers from spreadsheets. One is the TABBED ARRAY function. It
allows you to write an array list using tabs between numbers and carriage returns between rows as in:
initial population[country,blood type] = TABBED ARRAY(
1 2 3 4
5 6 7 8
9 10 11 12) ~Person~|

29
This has the same meaning as the first equation but has the advantage that it can simply be pasted from
a spreadsheet into the inside of the TABBED ARRAY function.
Closely related to this are the functions GET 123 CONSTANTS and GET XLS CONSTANTS that
allow you to query Lotus 123 or Microsoft Excel to get values to fill an array. These constants are
updated whenever the model is simulated so that any changes in the source spreadsheets will be seen in
the simulation.
initial population[country,blood type] = GET XLS DATA(
'mymod.xls','PopTab','G8') ~Person~|
This will read values from the tab 'PopTab' in the spreadsheet mymod.xls starting in cell G8. Just as for
the earlier examples blood type will be read across (columns G, H, I and J) and country will be
read down (rows 8,9 and 10).
If you have a constant with more than 2 subscripts it will be necessary to write multiple equations for it
with each equation having no more than 2 subscript ranges. For example:
sex : female,male ~~|
ini population[country,blood type,female] = 1,2,3,4;5,6,7,8;
9,10,11,12; ~~|
ini population[country,blood type,male] = 1,2,3,4;5,6,7,8;
9,10,11,12; ~ Person ~|
The position of the Subscript Ranges is arbitrary. male/female could have gone first, second or
last as it does above. The last Subscript Range (blood type) determines the meaning of the values
within a group or row, the first (country) the meaning of the different groups or rows.

Unchangeable Constants
All of the above discussion applies to Unchangeable Constants as well. In each case the = assignment
is replace by == as in:
initial population[country,blood type] == GET XLS DATA(
'mymod.xls','PopTab','G8') ~Person~|
Note that when defined this way initial population will only be read from the spreadsheet
when the model is checked. If, for example, the model is saved as a .vmf file then Vensim will not even
open the spreadsheet when the model is simulated.

Subscript Functions
There are five predefined Vensim functions that have been designed to make common subscript
operations easy to perform. These functions are:
SUM, which takes a sum over the indicated subscript values.

PROD, which takes a product over the subscript values.

VMIN, which takes a minimum over all subscript values.

VMAX, which takes a maximum over all subscript values.

ELMCOUNT, which returns the number of elements in a Subscript Range.

These functions are described in Chapter 4, but they perform the obvious action. The ELMCOUNT
function takes a single Subscript Range as its argument. For the others an exclamation point ! is used
to denote on which Subscript Ranges the function should operate. You can take sums, products,
minimums and maximums over any number of subscripts, and arithmetic expressions are allowed
within the functions.

30
Exampl e 3
efficiency = PROD( factor efficiency[types!] )
~ dimensionless
~ Production efficiency derived from several
factor efficiencies.
--equivalent to--
efficiency = factor efficiency[TYPE 1]
* factor efficiency[TYPE 2]
* factor efficiency[TYPE 3]
* .....
* factor efficiency[TYPE N]
|
US population = SUM( population[state!, county!] )
~ person
~ US population built up from the county level, i.e.
sum over all counties of all states.
|
Revenue[country,brand] = SUM(
sales[country,product!]* price[product!,brand])
~ $/Year
` ~ Revenue by country and brand.
|
The last of these is equivalent to an inner product and is a very common way to use the SUM function.

Mixed Variables Types†


Adding subscripts to a variable allows that variable to mean more than one thing. In some cases it is
desirable to have a variable fit into more than one of the defined variable types. Such variables are
called mixed variables. This redefinition occurs automatically, but there are restrictions.
? If a subscript of a variable is a Level, other subscripts can be Data or Constants, but not
Auxiliaries.
? If a subscript is an Auxiliary, other subscripts can be Data or Constants (but not Levels).
? If a subscript is an Unchangeable Constant other subscripts must also be Unchangeable Constants.
? If a subscript is a Lookup other subscripts must also be Lookups.
? If a subscript of a variable is not defined, you cannot use it.
If you do define a mixed variable, the variable will typically be typed as a Level or Auxiliary (for
example in the Variable tab of the Control Panel). When it is used in the computation it will be used as
the appropriate type.

Advanced Subscript Manipulation†

Subscripting allows you to write a single equation instead of many. This is efficient, but can be
frustrating, and often reveals the need for further improvements. Vensim has a number of advanced
features that are intended to increase the efficiency of working with subscripts.

Numeric Ranges
When dealing with large numbers of subscripts, such as you might encounter in manufacturing or
detailed project models, it is convenient to not have to write out all Subscript Element values. To
facilitate this you can specify numeric ranges, as in:

31
lot : (LOT1-LOT3),LOT12,(LOT14-LOT16) ~~|
which is exactly equivalent to:
lot : LOT1,LOT2,LOT3,LOT12,LOT14,LOT15,LOT16 ~~|
You must enclose ranges in parentheses. Everything preceding the numbers must match, and the
numbers must increase. Vensim does not allow purely numeric subscripts (i.e., 1,2,3… ).

VECTOR ELM MAP


Vensim does not allow the use of numeric subscripts. Sometimes, however, it is convenient to be able
to refer to a subscript numerically. For example the previous element in a subscript range, or an
element that might depend on the value of another variable. Vensim's VECTOR ELM MAP function
allows you to do this. For example if you want to represent a simple aging chain you could use the
equations:
stage : (stage1-stage9) ~~|
inflow[stage] = IF THEN ELSE(stage=stage1,start,
VECTOR ELM MAP(outflow[stage],-1)) ~~|
The first argument to VECTOR ELM MAP is the name of the subscripted variable that you want to
map, the second argument is the amount of offset. Thus VECTOR ELM MAP(var[stage],0) is
just the same as var[stage] and also the same as VECTOR ELM MAP( var[stage1],
stage-1).

You can also use the VECTOR ELM MAP function to match values between different subscripts. For
example:
personnel : joe,jen ~~|
task : design,prototype,test,build ~~|
task assignment[task] = 1,0,1,0 ~~|
work quality[task] = VECTOR ELM MAP(personal quality[joe],
task assignment[task]) ~~|
The VECTOR ELM MAP function should be used with care in that it bypasses some of the normal
consistency checking that Vensim does. If you try to map outside of a variables values Vensim will
report an error message during run time.
There is another function VECTOR SELECT that can also be helpful for this type of situation – see
Chapter 4 for details.

Subranges
One Subscript Range is said to be a Subrange of a second Subscript Range if all of its elements
(Subscript Elements) are included in the second Subscript Range. The use of Subranges can often
simplify equation writing and improve the clarity of a model's structure. Subranges can overlap, and
need not be exhaustive (so that some Subscript Elements might belong to two Subranges, and others to
none). However, all the members of a Subrange must be contained in a single Subscript Range.
Subranges of other Subranges are permissible, but will simply be treated as additional Subranges of the
original Subscript Range.
You can build up a Subscript Range by using Subranges , or define the Subscript Range and the
subranges independently.

Example
A modeler wants to group seven models of General Motors cars into three categories
(compact,full size, and luxury) because each of these automobile groups requires a
substantially different equation to describe its performance and economics. (If the only specification
differences between auto types were para metric, the modeler could use subscripted constants to

32
represent the differences.) Further, suppose that four of the cars fall into a particular group with
respect to emission standards, and performance/economics aggregates for these vehicles frequently
need to be computed.
To define Subranges, the modeler writes a separate expression for each Subrange desired.
model : little, not too big, middle, center, half, big, excessive
~~ Different models of cars available.
|
compact : little, not too big
~~ Small cars
|
mid size : middle, center, half
~~ Medium cars
|
luxury : big, excessive
~~ Large cars
|
epa gp1 : little, not too big, center
~~ vehicles in EPA group 1
|
To build up subranges into a full range just define the different subranges and use those in the equation
for the full Subscript Range. For example the equation for model above could be replaced with
model : compact, mid size, luxury
~~ Different models of cars available.
|
This has exactly the same meaning as the first equation for model.

Note that the units of measure for the subscripts ranges have been left blank in this example. The units
of measure for Subscripts are not used. You can leave the units on Subscripts blank, or mark them
Nil or Index to remind anyone reading the model that Subscripts are not dimensioned variables.

Mapping of Subscript Ranges


In many practical situations, it is desirable to use different subscript families to mean the same thing.
If no special preparation is made, this leads to an error message (typically that a Subscript Range
appears on the right, but not on the left, of an equation). Mapping allows you to do this sort of thing
when you are very sure that you want to override the exact correspondences normally enforced.
Mapping is usually safer than using the VECTOR ELM MAP function because changes you might
make to Subscripts that would invalidate an equation are more likely to trigger error messages.
It is worth noting that the function VECTOR SELECT can also be used to accomplish many of the
same things as mapping can. See the discussion in Chapter 4 for details on VECTOR SELECT.
Quite simply a mapping is an indication to Vensim that a Subscript that appears on the right but not
the left of an equation has a valid interpretation. Normally, an equation such as
Quality[product] = work quality[worker type]
would generate an error. If, however each product is made by a single worker type then the
equation does have a sensible interpretation. To signal this to Vensim we would use a Subscript
Mapping as in:
worker type : wtclay, wtplastic, wtwood -> product
where

33
product : clay,plastic,wood
In this case the equation for Quality would not cause an error and the quality of the clay
product would be the work quality of wtclay and so on. This mapping works because both
the order and number of subscripts match up. In practice, this is often the case, but the more general
mapping formulation is:
Rhsub:rh1,rh2->(Lhsub:lh1,lh2), (Lhbigger:Lhbsubr1,Lhbsubr2),
(lhopposite:lho2,lho1)
Where
Lhsub : lh1,lh2,
Lhbigger : lhb1,lhb2,lhb3,lhb4
Lhsubr1 : lhb1,lhb3
Lhsubr2 : lhb2,lhb4
Lhopposite: lho1,lho2
In this we use commas to delimit the lists of map-to choices. There is no limit on the number of map-
to choices, but it is most common to just have one or two. The map-to choices consist of the name of
the map-to subscript range, followed by a colon : and the elements or subranges in the order the
mapping should occur. The number of elements or subranges must match the number of elements in
the definition for the subscripts.

Example 1
Suppose your model includes both personnel and manufacturing. For clarity, personnel are broken
down by skill type, and manufacturing is broken down by product. If there is a one-to-one
correspondence between skill sets and products, you could use:
MFG SKILLS : MACHINERS, ASSEMBLERS -> PRODUCTS
~ index
~ Skill categories specific to manufacturing.
|
PRODUCTS : PARTS, SYSTEMS
~ index
~ Different phases of manufacturing.
|
WORK FLOW[PRODUCTS] = WORK FORCE[MFG SKILLS] *
PRODUCTIVITY[MFG SKILLS]
~ Part/year
~ Rate of progress in manufacture phases.
|
The mapping symbol ( -> in the statement for MFG SKILLS in the above example) shows that you
are mapping the subscripts of the range MFG SKILLS onto the subscripts of the range PRODUCTS. In
other words, MACHINERS map to PARTS and ASSEMBLERS map to SYSTEMS. Obviously the
number of subscripts must match (here, two in each subscript range).
The mapping symbol -> simply makes it legal for MFG SKILLS to appear on the right side of an
equation whose left side uses PRODUCTS. This means that it is not necessary to write two separate
equations for PARTS and SYSTEMS, as in:
WORK FLOW[PARTS] = WORK FORCE[MACHINERS]
* PRODUCTIVITY[MACHINERS] ~~|
WORK FLOW[SYSTEMS] = WORK FORCE[ASSEMBLERS]
* PRODUCTIVITY[ASSEMBLERS]
~ Part / year

34
~ Rate of progress in manufacture phases.
|
Multiple equations that occur when equations are duplicated only to indicate subscript mappings can
be an annoying source of boring work and hard-to-find errors.
When the subscripts have many values, subscript mapping becomes almost indispensable, as in the
following example:

Example 2
AGE : INFANT, CHILD, TEEN, MIDDLE, OLD
~ index
~ Age cohorts of a population
|
ALL BUT YOUNGEST : CHILD, TEEN, MIDDLE, OLD
~ index
~ Age cohorts except infant
|
PREVIOUS COHORT : INFANT, CHILD, TEEN, MIDDLE
-> ALL BUT YOUNGEST
~ index
~ Age cohorts preceding each member of
ALL BUT YOUNGEST
|
POPULATION[INFANT]= INTEG ( births- aging[INFANTS],
INITIAL POPULATION[INFANT]) ~~|
POPULATION[ALL BUT YOUNGEST] = INTEG (
aging[PREVIOUS COHORT]
- aging[ALL BUT YOUNGEST] ,
INITIAL POPULATION[ALL BUT YOUNGEST] )
~ People
~ Age cohorts of a population
|
See the model age.mdl in the directory \models\sample\other for the complete example, and see the
model tubs.mdl in the same directory for another example.
Thanks to the mapping of PREVIOUS COHORT onto ALL BUT YOUNGEST, we need only two
equations for POPULATION. Further, if we were to use 70 age groups instead of 5, we would still
require only two equations. Without mapping, we would require as many equations for POPULATION
as there were age groups.
Sometimes a set of Subscript Elements maps onto itself. For example, in a project-management
model, any of several tasks can be a prerequisite of each task. Vensim offers a convenientnotation for
making a second copy of a subscript range, using the notation <->. This is frequently useful when you
want to use a particular subscript twice in the same variable.
As an example, consider a work accomplishment structure for which prerequisite quality depends on
prerequisite tasks.

Example 3
TASKS : CLEAR,DIG,BUILD
~ index
~ The tasks for completion of the project.
|

35
PTASKS <-> TASKS
~ index
~ The prerequisite tasks for other tasks.
|
These equations make PTASKS a full Subrange of TASKS. The second equation above is the same as
the equation:
PTASKS : CLEAR,DIG,BUILD -> TASKS
~ index
~ The prerequisite tasks for other tasks.
|
You can use ptask to define, for example, prerequisite quality as:
prereq qual[task,ptask] = quality factors[ptask]
~ dimensionless [0,1]
~ Prerequisite quality.
|
This will work even though quality factors is actually defined by task, not by ptask.
Composite quality can then be defined as defined as:
quality[task] = PROD( prereq qual[task,ptask!] )
~ dimensionless
~ composite quality taken as the scalar product
of prerequisite quality factors
|
The above conventions allow great economy in equation writing where two dimensional matrix sums
or products are needed.

The above examples deal with direct mappings, where the number and order of subscripts match
exactly. There is a more general mapping that allows greater flexibility in equation writing. For
example, suppose that you are modeling a project in which there are 100 deliverables and 2
subcontractors. Each deliverable is handled by a single subcontractor. We might write the following
equation to determine quality:

Example 4
quality[del] = norm qual[del] *
eff qual fatigue[subcon]
~ dmnl ~ The quality of the deliverable.
|
del : (DEL1-DEL100)
~~All deliverables.|
subcon : subcon1,subcon2 -> (del:del con1,del con2)
~~ Subcontractors|
del con1 : (DEL1-DEL50)
~~ Deliverables that are the responsibility of subcontractor 1.
|
del con2 : (DEL51-DEL100)
~~ Deliverables that are the responsibility of subcontractor 2.
|
In this case, a single equation for quality replaces what could potentially become many such equations.
The mapping symbol specifies not only a Subscript Range, but the particular Subranges that the
mapping should be made to (del:del con1,del con2). The number of Subscript Ranges or

36
Constants in the list must match the number in the defining equation (both 2 in this case). Also, the
Subscript Ranges (and possibly Subscript Elements) making up the mapping must not overlap and
must completely exhaust the second group.

Example 5
Consider two classes of metal products for both us and a competitor where each of us has one product
in each class. In this case there are 4 products, but 2 classes. Still it will be convenient to use class
attributes when computing some things for the metals.
class1 metal: ourC1, theirC1
class2 metal: ourC2, theirC2
our metal: ourC1,ourC2
metal: class1 metal,class2 metal
class: class1,class2->(metal:class1 metal,class2 metal),
(our metal:ourC1,ourC2)
attractiveness[metal] = class attractivness[class] *
effect of price attractivness[metal]
margin[our metal] = our class margin[class]
Here the use of mapping makes it easy to pass between a class and a particular product. Note that
while metal has 4 elements class only has two. The mapping of class to metal determines
which class to use for each metal. In this case two elements of metal belong to each element of
class, but it could also have been 3 and 1.

Simulation Control Parameters


The simulation process requires specification of control parameters for a simulation run. The
specification control parameters are model variables that must be included in a model for it to simulate.
These parameters are often Constants, though they need not be. The mandatory control parameters
are:
TIME STEP = 0.5
~ month
~ The integration solution interval.
|
INITIAL TIME = 0
~ month
~ The time at which the simulation begins.
|
FINAL TIME = 80
~ month
~ The time at which the simulation will end.
|
SAVEPER = TIME STEP
~ month
~ The frequency with which values are saved for later display
|
The units of measure for the simulation control parameters define the units of Time, and should
match. Simulation control parameters can be defined with any equation, though they are typically
constants. It is also common, though not required, for SAVEPER and TIME STEP to be equal.
When you start a new model Vensim will query you for the initial values of the simulation control

37
parameters, but you can change them anytime. If you are using the Sketch tool you can change the
simulation control parameters with the Model>Time Bounds… command.

Special Variable Names

In addition to the simulation control parameters there are a number of variables with special meaning.
These variables do not have to appear in a model, but when they do Vensim will reference them for
certain actions.

SIMULATION PAUSE
Normally simulations are performed as quickly as possible. You can, however, cause the speed with
which a simulation occurs to be slowed by adding the variable SIMULATION PAUSE to the model.
This gives the number of seconds that need to elapse between each successive SAVEPER in the model.
For example if SIMULATION PAUSE was .5 and SAVEPER was .5 Months then for each month of
simulated time 1 second of time would pass. If the computations themselves take longer than
SIMULATIONPAUSE then no pause will occur, otherwise computation will be paused for the
difference between the specified time and the time the computations took. SIMULATION PAUSE is
ignored in SyntheSim and during optimization and sensitivity simulations.

NOISE SEED
NOISE SEED is used to change the behavior of the random number generator. If it is not included in
a model it is the same as if it had a value of 4487556. Use a number between 0 and 2^31.

ABSOLUTE TOLERANCE
Use ABSOLUTE TOLERANCE to specify that amount of error in all levels that is acceptable to
confirm convergence of the variable step size Runge Kutta integration techniques. If this is not
included it is the same as giving it a value of 0.001. If the error in a Level exceeds ABSOLUTE
TOLERANCE it is checked to see if it also exceeds RELATIVE TOLERANCE.

RELATIVE TOLERANCE
Use RELATIVE TOLERANCE to specify that amount of relative error in all levels that is acceptable
to confirm convergence of the variable step size Runge Kutta integration techniques. If this is not
included it is the same as giving it a value of 0.001. When performing the variable step size
integration the step size is decreased until for every Level, the error in its computation is less than
ABSOLUTE TOLERANCE or RELATIVE TOLERANCE * Base Level Value.

RC START TIME
Use RC START TIME to specify the time at which the various RC… functions activate. If this is
not specified then the activation will occur at INITIAL TIME + TIME STEP.

MAX TIMES
Use MAX TIMES for models used for gaming where one or more of SAVEPER, INTIAL TIME or
FINAL TIME is a variable. Normally Vensim computes the number of times data will be saved as
(FINAL TIME-INITIAL TIME)/SAVEPER + 1. If, however, any of these are variable this
computation may need to be adjusted. MAX TIMES should be the maximum number of saved values
that will occur.

GAME INTERVAL
Use GAME INTERVAL to specify how far a model should advance during gaming. This value can be
changed later using the Gaming Control Dialog or GAME commands. If it is not included the value of
SAVEPER is used.

38
Acceptable Integration Errors
If you use Runge-Kutta integration with automatically adjusted step size, you can specify the
acceptable integration error. The acceptable error is used to determine whether decreasing the step size
is necessary to achieve the desired integration accuracy. You can specify the absolute and relative
tolerances:
ABSOLUTE TOLERANCE = .001
~ Dmnl
~ Absolute change allowed within a TIME STEP.
|
RELATIVE TOLERANCE = .001
~ Dmnl
~ Relative change allowed within a TIME STEP.
|
The default values for the parameters of .001 will be used if you do not define them within a model.
See Chapter 8 for more discussion of the integration techniques.

Alternative Time Bases


Frequently, it is desirable to compute time on a monthly basis but survey model results on a yearly
basis. In this case variables can be added to the list above to make the month-to-year conversion, and
Vensim can be instructed to report results on a calendar (and/or fiscal) year basis, e.g.,
Decimal year = TIME BASE(INITIAL YEAR,YEARS PER MONTH)
~ year
~ decimal year date.
|
INITIAL YEAR = 1980
~ year
~ Start simulation on January 1, 1980.
|
YEARS PER MONTH = .083333
~ year/month
~ The number of years in a month.
|
When using different Time Bases, be careful to specify the basis on which data is entered. If data is on
an annual basis and the model is in months an equation such as the one above must be included, and
the data must be marked as using the time base Decimal year.

RC START TIME
RC START TIME is used to determine when the Reality Check functions take effect. The Reality
Check functions are described in more detail in Chapter 4 and in Chapter 9 of the Modeling Guide.
Normally RC START TIME would be a constant
RC START TIME = 10
~ Year
~ The time to start Reality Check testing.
|
If a model does not include RC START TIME then it is assumed to be INITIAL TIME plus TIME
STEP.

39
Groups
As noted above, you can specify the groups or categories into which variables fall. Since Vensim
allows you to search subscript range names by group, the specification of groups frequently permits
quicker inspection of model results.

In the Text Editor, a group is defined by placing the group name between two lines of four or more
asterisks (****), followed by a tilde ~, including an optional comment and ending in a bar |. The final
bar | is very important. For example:
********************************
Financial
********************************~
Variables relating to financial performance
|
All variables defined following a group definition are then automatically included in the group. A new
group definition marks the beginning of a new group (i.e., groups are not hierarchical).
In the Equation Editor you can use the group selection area to choose an existing group from a list, or
type in the name of a new group.

A default model group (given the name of the model) is always created and used if no other groups are
explicitly named. The default group appears first in the model and the comment associated with it is
the comment that is displayed in the Info/Sketch tab of the Model Settings dialog.

Definition of Ranges

As noted above, you can define limiting values or ranges for any variable. In the Equation Editor there
are separate windows for these two values. In the Text Editor, the ranges are defined on the line
containing the units of measure by enclosing the lower and upper limits in square brackets [LOWER,
UPPER] after the units. During simulation, Vensim will report any violations of these limits.
sales = Salesmen * sales productivity
~ $ / year [0,1.0E6]
Dollar volume of sales
|
In this example sales is defined to be in the range of 0 to $1 million per year. With this
specification, any points in time where sales are above $1 million (or negative) will be reported.

The motivation for using a range could be uncertainty of the equation's accuracy outside the range,
implausibility of going outside the range, or interest in knowing when the range has been exceeded.

Macros†

Macros are a way to repeat model structures without retyping equations. To do this, the macro is first
defined by writing equations, then invoked by calling them as you would call a function. In many
cases, they can simplify the modeling process, but they are also dangerous in that they can allow
dynamics to "creep into" a model. The implementation of macros in Vensim overcomes much of this
hidden dynamics problem. Still, it is recommended that macros be used sparingly, if at all.
NOTE The macro definition must occur before the macro is referenced.

This is the only equation ordering rule in the Vensim modeling language. If you do not define a macro
before you use it, you will receive a syntax error message.

40
You cannot nest macros. A macro definition cannot contain a reference to another macro. A macro
call, on the other hand, can contain another macro call as well as function calls and other algebraic
manipulations of variables.
While macros can use Vensim functions, they can't use functions that are themselves macros. These
functions are: DELAY1, DELAY1I, DELAY3, DELAY3I, DELAYP, FORECAST, NPV, NPVE,
SMOOTH, SMOOTH3, SMOOTH3I and TREND.

Defining Macros
To define a macro, use the format:
:MACRO: macroname(inarg1,inarg2,inarg3:outarg1,outarg2)
macroname=inarg1+inarg2~~|
...
:END OF MACRO:
Where macroname is any valid unquoted Vensim name (starting with a letter and containing letters,
numbers, spaces, underbars _ and dollar signs $). The arguments can have any valid unquoted name
and there can be any number of them. The arguments cannot be subscripted, but you can use
subscripted values when calling the macro.
The output arguments are variables that are defined inside of the macro, in addition to the output of the
macro itself. These are optional and must be separated from input arguments by a colon :. Their use
is discouraged. When no outputs are specified, omit the colon :.
The macroname and output arguments each must have a single equation inside of the macro
description. Variables can also be defined internal to the macro description. In this way macros define
a self-contained world that can be accessed only through the macro call itself. This means that if your
model has a variable name population, and you use population inside of a macro, no
connection will be made between the two names. The variable names inside of a macro relate to
nothing outside the macro or in other macros. You can use, for example, L1 in as many macros as you
like.
The one exception to the local nature of macro variables is that you may specify a model variable by
following its name with a dollar sign $. For example you can use TIME STEP$ inside of a macro to
refer to the model variable TIME STEP. Only unsubscripted variables may be referred to in this
manner.

The Units inside of a macro definition can include either the standard sorts of Units in use in your
model ($, People, etc.) or the names of input variables. If the units are the name of an input variable,
the units from the input will be substituted wherever the macro is invoked. You can also use a name
such as Time$ to specify the units for Time.

Example
:MACRO: VSMOOTH(input,SMOOTH TIME)
Vsmooth = INTEG((input - Vsmooth)/SMOOTH TIME,
input)
~ input
~ The first order smoothed value of a variable.
|
:END OF MACRO:
:MACRO: MYNPVE(str,dr,in,f)
MYNPVE=(NCUM+str*TIME STEP$*df)*f~str/dr~|
NCUM=INTEG(str*df,in)~str/dr~|
df=INTEG(-df*dr/(1+dr*TIME STEP$),1/(1+dr*TIME STEP$))~Dmnl~|
:END OF MACRO:

41
NOTE You must use the Text Editor to define macros. Macros cannot be defined using the Equation
Editor, although they can be used within the Equation Editor.
When you start a new model you can specify an input file using the Advanced tab in the Option dialog.
You can fill this file with macros that you routinely use so that you do not have to paste them into a
new model every time you start one.

Using Macros
Once a macro is defined, you can use it any number of times. To use it, call it just like a function,
separating the output list (if any) from the input list with a colon :. When the macro is encountered,
variables and equations will be made up so that causal tracing will continue to function properly.

Example
diddle[house]=daddle+vsmooth(tadum[house],20)
~blip/hour
~Hey.
|
This uses the smooth macro defined above, and is exactly the same as
diddle[house]=daddle+vsmooth tadum[house]
~blip/hour
~Hey.
|
vsmooth tadum[house]=integ(
(tadum[house]-vsmooth tadum[house])/20,
tadum[house]) ~~|
except that in the case of the macro the name would be
#vsmooth(tadum[house],20)#[house] instead of vsmooth tadum[house]. Macro
expansion uses the expression you used to invoke the macro enclosed in sharp # signs. This is
completely descriptive of the meaning of the macro and clearly not a proper model variable. This
allows you to recognize immediately that you are dealing with a macro, and prevents conflicts with
other variable names.

42
3 Model Settings to Units Checking

Vensim is designed to make it as easy as possible for you to build models and to find and fix the errors
that occur in the models you build. Some of these errors can be very subtle and can be uncovered only
through simulation analysis or the application of Reality Checks. There are a number of errors,
however, that can be detected by the direct inspection of a model and Vensim will do this inspection
for you automatically.
This chapter:
? Shows how to set and get information about a model including time bounds and units synonyms.
? Outlines Vensim's model checking sequence.
? Provides guidance for correcting errors that Vensim detects.
? Describes alternative techniques for dealing with simultaneous equations.
? Outlines units checking.
? Discusses strategies for correcting units errors.
? Demonstrates how to reformat and clean a model.

Model Settings
Sketches and equations define most of the structure of a model. There are also some settings that are
conveniently made using the model settings dialog. Some of these settings can also be made using the
Equation Editor and Text Editor when this is more convenient.
The Model Settings dialog opens each time you start a new model. When you are working with an
existing model you can open the Model Settings Dialog use the Settings command on the Model menu.
The Model Settings Dialog is a tabbed dialog that will let you choose between setting time bounds,
defining unites equivalence and getting information about a model and editing comment or copyright
info for the model.

Time Bounds
All Vensim models, whether simulation models or not, have Time Bounds. These are the INITIAL
and FINAL TIMEs over which the simulation will occur, the TIME STEP for integrating and the
SAVEPER for saving results.
NOTE If you are using the Text Editor the Time Bounds tab will not be available and you will need to
go to the equations for the control parameters and modify them directly.

43
INITIAL TIME is the time at which the simulation will begin.
FINAL TIME is the time at which the simulation will end.

TIME STEP is the time interval for the simulation. You can type in a value or select one from a list
by clicking on the drop-down button at the right. The best choice for time step is normally a power of
1/2, to prevent rounding errors from distorting the Time axis. You should choose a TIME STEP small
enough to prevent serious integration error. See the discussion of TIME STEP under "Selecting an
Integration Technique" later in this chapter.
Save results every TIME STEP, if checked, sets SAVEPER to be equal to TIME STEP. This is the
default and normally quite acceptable.
SAVEPER is frequency with which simulation results are saved. If you take away the check above
this you can fill in a value. If the formula (FINAL TIME-INITIAL TIME)/TIMESTEP gives a value
bigger than 1000 you will probably want to use a different SAVEPER than TIME STEP. Making
SAVEPER bigger decreases the size of simulation files and increased the speed of simulations.
Units for Time, lets you specify the units of measure for time. These are used in checking the units of
Levels which are accumulations of their inflows and outflows. All of the number in the other fields are
measured with this unit. You can click on the drop-down arrow to the right to get a list of commonly
used units or type in any units you like.
NOTE All of the control parameters that you set from this dialog can also be set directly by writing
equations for the control parameters. By default all except SAVEPER are constants, but they do not
need to be constants. The example model ball.mdl demonstrates the writing of an equation for TIME
STEP that depends on conditions detected in the model. If you do make changes to control parameters
in this model, you will get a message that there were problems updating and that you should use the
Equation Editor. Some of the changes you make might still hold.

Info/Sketch
The Info/Password and Sketch Appearance tabs allows you to make notes about a model, set what
should be shown in a sketch and get information about a model. For .vmf (binary) files you can also
set a password that will be required to open the model. There is also a button that allows you to create
a .cin format changes file that contains all model constants and their values or a .dat format data file
with a list of variables requiring data.

44
Info/Psswd

Model Notes are arbitrary notes you want to make about the model. They are stored with the model
as comment information for the first group and should not contain and tildes ~ or vertical bars |. Model
notes can include author and copyright information.
Display model notes when model is opened, if checked, will cause a message box to appear when the
model is opened. The message box will contain whatever notes have been entered. This is an effective
way to display copyright information about a model.
Password and Verify allow you to set the password required to open a model. These are grayed
except when the model is saved in binary (.vmf) format. To enter or change a password just type in the
same things (case sensitive) in both boxes. IMPORTANT If you use a password, do not forget it.
There is no way to recover a password from a password protected model.
NOTE Password protection does not encrypt your model. It is provided only as a safeguard against
casual observation. Data security is a serious concern and remains your responsibility.
Note that it is usually more effective to set passwords on model archive and not on the model itself.

Model Info displays some basic measurements on model size. The number of symbols includes all
model variables, subscripts and units of measure. The numbers for the different variable types are
shown after expanding all subscripted variables fully out as is the total. Thus a variable
Pop[age,country,sex] with 5 ages, 2 countries and 2 sexes would add 20 (5x2x2) to this count.

Model->Data writes all model data variables to an empty .dat format data file. This is a convenient
way to get a list of variables requiring data for the model to simulate.
Model->Cin writes all model constants to a .cin format changes file. This is a convenient way of
saving all constants in a model in a format that can be edited and used to make simulations.

45
Sketch

Show initial causes on model diagrams , if checked, will cause arrows to be drawn indicating initial
causes. If it is not checked there will be no arrows from initial causes into variables. Initial cause
arrows are shown in a different color from other arrows (by default gray), but some people prefer to
have them hidden.
Show Lookup variables on model diagrams , if checked, will causes Lookup variables to appear on
model diagrams with an arrow into the variables they are used for.
Suppress SyntheSim during slider moves (big models), if checked, causes SyntheSim simulations to
occur only when the button is released during a slider move. Normally SyntheSim will simulate the
model continually as the slider is dragged. For bigger models this option can make SyntheSim
perform more smoothly.
Use disk storage for all SyntheSim runs (big models), if checked, causes SyntheSim simulations to
be stored on disk rather than in memory. For bigger models this will decrease memory use, but will
also slow things down.
Model uses far eastern (2 byte) characters, if checked, causes Vensim to treat character strings as
having a far eastern encoding when wrapping variable names. This is helpful for models written in
Chinese, Japanese, Korean and other far eastern languages.
Model uses far eastern (2 byte) characters, if checked, causes Vensim to treat character strings as
having a far eastern encoding when wrapping variable names. This is helpful for models written in
Chinese, Japanese, Korean and other far eastern languages.
Use hard underbar _ (do not convert to space), if checked, causes Vensim to treat an underbar _ in a
variable name differently from a space. Normally Vensim treats these two interchangeably and you set
the way names are display from the Settings tab of the Global Options dialog.

Units Equiv
Vensim treats units of measure literally. Thus, Person, Persons, and People are considered to
be different units. Since you might want to use different names for the same things, you can define

46
synonyms to prevent errors when units checking is done. Suppose, for example, that you write the
equations:
nails shipped = boxes shipped * nails per box ~ Nails/Month ~~|
nails per box = 1000 ~Nails/Box ~|
boxes shipped =50~ Boxes/Month ~|
Upon checking the units this will generate the error message:
Right hand and left hand units do not match
nails shipped
Has units: Nails/month
boxes shipped
* nails per box
Has units: Nails*Boxes/(month*Box)
The problem is that Boxes and Box are not canceling one another even though they mean the same
thing. To make them cancel, you could correct one to match the other. Often it is better to define
Units Synonyms .
Units Synonyms are simply lists of units that mean the same thing. Click on the Units Equiv tab to set
them for your model.

The list displays all of the existing synonym groups. Click on one of these to select it, then use the
Delete Selected or Modify Selected buttons to remove or change it. Double-c licking on an entry is
equivalent to clicking on the entry and clicking the Modify Selected button.
Delete Selected deletes the selected synonym group from the list. If no group is selected, nothing
happens.
Modify Selected moves the selected synonym group to the editing line so that you can change it. If no
group is selected, nothing happens. The editing line has the normal simple editing capabilities found in
dialog boxes. If you ask to modify a group while the editing line has something in it, you will be asked
if you want to overwrite this entry.
Add editing adds the contents of the editing line to the list of synonyms. No checking is done to
ensure that the synonym group is well formed.

47
Replace these with the New Model default synonyms discards the current list of synonyms and loads
the synonyms defined using the Units tab of the Global Options dialog (see Chapter 16). If you do
this you can still cancel.
Make these synonyms the New Model default synonyms makes the current units synonyms list the
defaults that will be used when starting a new model. You will be prompted to be sure you want to do
this. If you respond yes to this prompt the defaults will be changed immediately - even if you cancel
out of the dialog afterward.
NOTE Units Synonyms are model specific. The default set of synonyms is used only when you start a
new model.

Dimensionless Synonyms
When Vensim is first installed it includes a short list of synonyms for new models so most models do
have units synonyms associated with them. However, even if the synonyms list is empty, Vensim will
treat the units: Dimensionless, Dmnl, Fraction, Nil and 1 as synonyms.
Dimensionless is a very special unit because it does not change units on multiplication. All numbers
are treated as dimensionless unless it is obvious from context that they are not.
NOTE If you want to change the synonyms for Dimensionless, you must specify your own list and
begin it with Dimensionless (spelled out completely) This list will replace the built in list.

Error Checking

Vensim tests a model for errors automatically whenever you try to use an Analysis tool or simulate the
model. You can also ask Vensim to test for errors by using the Model>Check Model command or
holding down the Control key and pressing the T key. If you have the Equation Editor open, you can
also check the model by clicking on the Check Model button.

If you do not explicitly ask to check a model, Vensim will only report errors that prevent it from
completing the current task. To see all messages you must explicitly ask to check the model.
The way in which you navigate error messages depends on the mode in which you are working on the
model. Before going into detail on the types of messages, an overview of this is helpful.
NOTE Vensim has a function to perform partial simulation of a model. This will allow you to
simulate a model that still contains errors in some parts. See Chapter 8 for more details.

Equation Editor
When you are working with the Sketch Editor and perform a Model Check, any error messages will
cause the Equation Editor to be opened. Error messages will appear in the Combo Box at the bottom
of the window.

Syntax error messages will be displayed in the Combo Box and the box will be disabled as shown
above. The cursor will be positioned in the equation at the point where the syntax error was detected.
For other errors Vensim will try to identify the equation associated with the first error it finds and
display that equation. A list of errors will also appear in the drop-down box at the bottom of the
Equation Editor. You can click on any error message to go to the equation associated with that error.
If the list is not visible click on the button to the right of the displayed error to see the list.

48
NOTE For some types of errors, not all the errors in the list get attached to a specific equation. If you
click on an error and the Equation Editor does not reposition itself properly, open up the list again and
try clicking on an error below it.
For more information on the Equation Editor refer to Chapter 6.

Text Editor
Syntax errors will be shown on the line at the bottom of the screen and the cursor will be positioned at
the place the syntax error was detected.

For other errors a secondary window will open showing the errors. By clicking on the error once - the
Text Editor will automatically reposition itself to the place where the error occurred.

NOTE If clicking on an error does not reposition the Text Editor try clicking on an error below it.
You will also need to be sure that the Text Editor's Status Bar says Entrain.
For more information on the Text Editor see Chapter 7.

Error Checking Sequence


Vensim performs error checking in the following order:
1. Syntax checking. Vensim looks for any syntax errors that can be detected and reported locally.
Vensim also checks for incomplete equations at this point. If Vensim finds a syntax error or an
incomplete equation, it will not continue with any further error checking. See "Syntax Errors and
Incomplete Equations" below.
2. Equation type checking. Vensim uses the equations for variables to assign them a variable type as
discussed in Chapter 2. †For models containing subscripts, errors can occur if different variable
types are incorrectly mixed within a single variable. See "Problems with Variable Types" below.
3. †Subscript Range checking. If a model contains subscripts with subranges or mappings, then
mappings are checked to make sure the number of elements match and subranges are checked to
be sure they are completely contained within the parent range.
4. Lookup usage checking. Vensim checks that any variables defined as Lookups are not used in a
different manner, and that other variable types are not used in the way a Lookup function would be
used.
5. †Subscript usage checking. If a variable is used in different places with different Subscript
Ranges, or with a different number of Subscripts, an error will be reported. Vensim also checks
that the subscripts appearing on the right and left hand sides of each equation are consistent. See

49
"Subscript Errors" below.
6. Uses checking (message only). This flags variables that are not used anywhere in a model and
also variables that are marked as Supplementary but also used. See "Usage Messages" below. If
Vensim detected an error in stages two through five above, error checking will stop at this point.
7. Not defined checking (message only). If any variable appearing in a model does not have a
defining equation Vensim will issue a message at this point and treat the variable as a Data
variable. See "Usage Messages" below.
8. Constant checking. If an unsubscripted variable has a list of values (as in 1,1) an error is reported.
†For subscripted variables the subscripts are checked to be sure they contain a single Subscript
Range and the number of elements in the range is checked against the number of entries in the list.
To fix the error, correct the number of entries in the list for this variable. Constants retrieved from
spreadsheets using the GET 123 CONSTANTS or GET XLS CONSTANTS functions are also
checked at this point and an error is reported if the values cannot be retrieved.
9. Lookup definition checking. Lookups are checked to make sure that they have at least two pairs
of numbers. To fix the error, correct the number of entries.
10. Multiple equation checking. Unsubscripted variables are checked to be sure that they do not have
more than one equation defined for them. †For subscripted variables, every element that is used is
checked to make sure it is defined. Any duplicate definitions for elements are reported. See
"Multiple Equations" below. If Vensim detects an error in stages eight through ten, error checking
will stop.
11. Computational Sequence checking. The equations for the model are tested to make sure that they
can be properly ordered for computation. Any Data equations are checked first, then Auxiliary
definitions and finally the initialization equations. See "Simultaneous Equations" below.
A number of the above errors that Vensim checks for will never occur if you are building a model
using only the Sketch and Equation Editors. Since Vensim allows models to be built in a number of
different ways, it checks for errors significantly beyond the scope of what would normally occur.
The following sections provide more detail on how to work with any problems that Vensim uncovers
during error checking. In cases where there are significant differences, if you are working with the
Text Editor (or loading in a model as text), these differences are discussed in a subsection.

Syntax Errors and Incomplete Equations

Syntax errors can be detected by looking at a single equation; these local errors are typically easy to
fix. The Text Editor and Equation Editor both position you at the point where the error occurred so
you can correct it.
NOTE In some cases, syntax errors are discovered after incorrectly interpreting part of an equation
and the error messages Vensim displays might not indicate the true problem. If an error message
doesn't make sense, look at the point in the equation where the error was detected and try to determine
the cause. The most common errors are extraneous punctuation or misplaced parentheses () or
brackets [ ].
Incomplete equations are normally the result of making changes to the expected inputs in the Sketch
Editor. When you perform a model check, Vensim will bring up the Equation Editor positioned at the
incomplete equation. The equation might not have any errors, but it might not have the same inputs as
marked on the sketch. Clicking on the "Check Syntax" button in the Equation Editor will tell you what
the problem is, and then you can correct it.

Syntax Errors and the Text Editor†


If you are working with the Text Editor and have a model with syntax errors, the equations with errors,
and all those that follow, will not be used by Vensim. The first time you try to use an Analysis tool
after entering an equation with a syntax error the you will see the prompt:

50
If you answer yes you will be positioned at the error. A description of the error will appear in the
prompt line at the bottom. If you answer no, Vensim may not be able to recognize the variables in the
model following the syntax error.
When you perform a model check on a model containing syntax errors Vensim will tell you that you
have syntax errors, position you at the error and place a description of the error in the prompt line at
thebottom. If the reason for the error is not obvious check for check for missing tildes ~ or bars | in
the equation above the one for which the error was detected.
If there are syntax errors in a model you will not be able to simulate and each time you try to use a tool
you will be asked if you want to correct them.
NOTE You will not be able to view the model as a Sketch until you have corrected all the syntax
errors.

Syntax Errors in a .mdl File


If you try to open a model that contains syntax errors other than those marked as incorrect/incomplete
equations by the Equation Editor you will not be able to view the model in the Sketch Editor. In
Vensim Professional and DSS, the model will automatically be opened in the Text Editor so you can
correct errors.
The other Vensim configurations do not have a Text Editor and you will be asked if you want to try to
open the model anyway. If you answer yes, the equations with syntax errors will be ignored.
If a model will not open, start a new model and then look at the error history window (Windows>Error
History). Scrolling to the bottom of this window will tell you why the model load failed. If you want
to make changes to a .mdl file you can do so in any editor but be sure to save the results as a plain text
file.

Problems with Variable Types†

In Vensim, subscripts allow a single variable to represent multiple types. This can cause problems if
you mix incompatible types, as exemplified by the following equation:
income[USA] = workers[USA]*wage_rate[USA] ~~|
Income[USSR] = INTEG( (planned_income[USSR] -
Income[USSR])/PLAN_TIME,
planned_income[USSR]) ~~|
Here, income attempts to act as both Auxiliary and Level, which is not permissible. Here are
permissible mixtures with the arrow showing how variables of mixed types will be treated:
Data, Constant ----> Data
Auxiliary, Data, Initial, Constant ---> Auxiliary
Level, Constant, Data ---> Level
You cannot mix Levels with initial conditions. However, you can accomplish the same thing with
INTEG(0,initial_condition).

You cannot mix Lookups with anything else.

51
In addition to the variable types defined in Chapter 2, there is an implicit type called missing. Missing
simply means that there are no equations defining some components for the variable. Although you
can sometimes use missing types intentionally, if you refer to a missing component of a variable, you
will receive an error message.
For example:
country: CANADA,USA,MEXICO ~~|
population[USA] = 240E6 ~~|
population[CANADA] = 23E6 ~~|
births[country] = .02*population[country] ~~|
yields the error message
ERROR: Used, not Computed - POPULATION[MEXICO]
If you do not define any component of a variable with an equation, Vensim assumes the variable is
exogenous in all its subscripts regardless of whether all of its subscripts are used. Thus, if you have
the equation
profit[GM] = revenue[GM] - COSt[gm] ~~|
PROfit[other] ~~|
and no equation for COSt, you must enter values for COSt for all manufacturers. If you add the
equation
COSt[GM] ~~|
you no longer need to do so.

Subscript Errors†

Using an equation with a Subscript Range is like using a "for" or "do" loop. Although you do not need
to specify this loop explicitly, the loop concept determines what you can and cannot do. For example,
consider the following equation:
births[country,income] =
frac_birth_rat[country,income] *
population[country,income] ~~|
This equation is really saying
for each country {USA,CANADA,MEXICO}
for each income {LOW,MIDDLE,HIGH}
births[country,income]=
frac_birth_rat[country,income] *
population[country,income] ~~|
end for each income
end for each country
The equations for country and class determine the meaning of each country and each income as
indicated by the comments.
The Subscript Ranges on the left-hand side of an equation determine the implicit "for each"
components. Thus the equation
births[country,HIGH] =
frac_birth_rat[country,income] *
population[country,income] ~~|

52
would be wrong. The left-hand side implies only a single "for each" loop on country, but the right-
hand side requires one for country and one for income. In this case, you will get a message
reporting that the Subscript Range income appears on the right but not on the left of the equation.

Family mismatches are another common problem with subscripts. All variables must have the same
number of subscripts from the same family. For example, the equation that contains both
population[country] and population[country,income] will cause a problem since
population must be broken down either by country, or by country and income. It cannot be
broken down by country sometimes and by country and income at other times.

Even when the number of subscripts match, there can be problems if the families do not also match.
Suppose that population[country,income] appears in one place and
population[country,region] in another. It makes no sense for population to be broken
down in two different ways, both by income and by region.

Tracing Subscript Errors


Subscript errors can be hard to trace because the equation that Vensim flags as having the error might
be correct, and another equation in error. Generally the best strategy for finding subscript errors is to
select the variable name that is causing problems as the Workbench Variable and then click on the
Uses Tree tool to show where it is used. By looking at the equation for the variable, and then at each
equation in which it is used, you should be able to determine the source of the problem.
HINT When working with the Sketch Editor, select a variable into the Workbench and click on the
Equation Edit tool contained in the Analysis Toolbar to directly open the equation for a variable.
When working with the Text Editor, turn on Entrain before you select variables into the Workbench.

Usage Messages

Because Vensim is focused on building feedback models, it flags variables that are not used anywhere
(and therefore not part of any feedback loop). These flags are intended to help you catch omissions
you might have made. They do not prevent simulation of the model.
If you have defined a variable and the variable is not used you will get a message:
USE FLAG: "profit" is not used in the model.
You can stop this message from being reported by marking the variable as a Supplementary variable
either by checking the Supplementary box in the Equation Editor or adding in a Supplementary field in
the Text Editor as in:
profit = revenue - cost
~ $ ~ Companies Profits - not used ~ :SUP |
If you use a variable that has been marked as Supplementary (even in the equation for another
Supplementary variable) you will get a message when you check the model as in:
USE FLAG: The supplementary variable "profit" is used.
Simply remove the supplementary marking from the variable.

Not Defined
Not defined messages are usage messages that indicate a variable is used somewhere, but no equation
has been defined for it. This condition does not usually occur when you are working with the Sketch
Editor since inputs are defined as you enter the equations for them.
Variables that are not defined are assumed exogenous and must therefore be entered as data for a
simulation to proceed. This is designed as a convenience to allow you to cut and paste sectors of a
model without having to rewrite input equations. Thus, if the NOT DEFINED messages you get are

53
all expected, you can proceed without difficulty. If not, you need to correct the problem either by
adding in the variable that is not defined or correcting spelling inconsistencies.
A common source of NOT DEFINED messages is variable name misspellings. For example suppose
you get the two messages :
USE FLAG: "profit" is not used in the model.
NOT DEFINED: "profits" not defined - assumed exogenous.
You have used profit in some places and profits in others for the same concept. In this case,
you should correct the spelling to be consistent. Such paired messages as those above are not always
on contiguous lines, and you will not receive the USE FLAG message if you have used profit
elsewhere already.

Multiple Equations
Sometimes Vensim will detect that more than one Equation has been defined for a variable that does
not have any subscripts. This is normally the result of entering the same equation twice in the Text
Editor. It is not possible to generate this condition using the Sketch Editor. To fix this you must go to
the Text Editor and find the two equations for the variable. Using Entrain mode will help you find the
first equation.
If you run into this problem in Vensim PLE, PLE Plus or Standard, it may be necessary to edit the
model (.mdl) file in a separate text editor.

Multiple Definitions
Vensim will detect if more than one equation computes a value for a subscript element. Suppose, for
example, you have the equations:
store: s1,s2 ~~|
profit[store] = revenue[store] - cost[store] ~ ~|
profit[s1] = revenue[s1] - cost[s1] - pothole tax ~ $/Year ~|
In this case there are two equations that compute a value for profit[s2]. Vensim will report this
as an error. The first equation should use s1 instead of store as a subscript. You will need to look
carefully at each equation for a variable and see which need to be corrected.

Used but Not Defined
It is permissible to only define a subset of the elements of a subscripted variable. Consider for
example the equations:
plant : p1,p2,p3 ~~|
pp : p1,p2 ~~|
morale[pp] = normal moral * effect of fatigue[pp] ~ Haps~|
In this set of equations morale for p3 is simply not defined. If morale is only used with the
Subscripts p1, p2 or pp this will not cause a problem. Suppose however you have the equation:
quality[plant] = norm quality[plant] *
morale funct(morale[plant]/ normal morale) ~ Dmnl ~|
This equation uses morale[p3] and Vensim will report the error message:
ERROR: Used, not Computed "morale[p3]".
Selecting this error will position you on the first equation where the variable was used. In this case the
equation defining morale needs to be generalized.

54
Simultaneous Equations
The errors we have looked at so far are errors that make a model incomplete. Even after a model is
complete, simulation might not be possible because of computational problems. In order to simulate a
model, the model's equations must be ordered in a well-defined manner. Vensim does this by figuring
out what variables in an equation are dependent on other variables until it finds terminal variables that
are already known.
Suppose for example we have the equations:
fraction bad apples = bad apples / total apples ~ Dmnl~|
total apples = good apples + bad apples ~ Apple ~|
good apples = 8 ~ Apple ~|
bad apples = 2 ~ Apple ~|
In this case the two terminal variables are constants and in order to simulate the model Vensim will
first compute bad apples, then good apples, then total apples and then fraction
bad apples. Because this ordering automatically occurs it does not matter the order equations are
added.
The types of variables that are treated as terminal variables depends on the type of equations being
ordered. For initial conditions, the terminal variable types are Data and Constants. For computation of
the active equations, the terminal types are Data, Constants, Initials, and Levels. For Data equations,
the terminal types are raw (non-computed) Data and Constants.
Unfortunately, it is not always possible to unravel equations to such terminal variable types. When it
is not possible Vensim will report a simultaneous equation error. The simplest example of a
simultaneous equation is:
self = self ~~|
In a programming language, this would be a legitimate, albeit vacuous, statement. In Vensim it is an
error. It says that you need to know the value of self in order to compute self. This is a non
causal model. When Vensim encounters simultaneous equations, it reports an error, such as
ERROR: Simultaneous initial value equations involving : Population
: income
: avg income
: Population
In terms of computation, the above list should be read backwards. To compute Population it is
necessary to have the value for avg income which require the value for income which requires the
value for Population. If you prefer to look at things causally, the list can be read forward as
Population causes income which causes avg income which causes Population. In either
direction it is a circle and that is the source of the problem.

Subscripts and Simultaneous Equations


When Vensim orders the equations for simulation, it first tries to do this variable by variable. If it fails
to do this, it then expands subscript equations and attempts to order equations element by element. For
example, the equations:
age : baby,young,mid,old ~~|
ageh : young,mid,old->agel ~~|
agel : baby,young,mid ~~|
flexibility[ageh] = prev flex[ageh]*.7 ~~|
flexibility[baby] = 1 ~Dmnl ~|
prev flex[ageh] = flexibility[agel] ~ Dmnl ~|

55
Would result in the computation of flexibility[baby], pref flex[young],
flexibility[young], prev flex[mid], flexiblity[mid], prev flex[old] and
flexibility[old]. Because Vensim does checking in this manner, apparent simultaneities such
as the one shown above will not result in simultaneous equations being reported.
If, having attempted an expansion such as that shown above, Vensim still finds a simultaneous loop, it
will report it with a fully subscripted set of variable names.

Fixing Simultaneous Equations


Although active, initial, and data equations all result in the same form of error, the true source and
solution of the errors might differ.
? Active simultaneous equations represent some genuinely incorrect representation, often a
conceptual error. Somewhere there are additional dynamics separating things and you must
explicitly include these. If the simultaneity is intentional, you must either solve the equation
outside of Vensim or make use of an iterative solution technique.
? Simultaneous initial condition equations usually result from a need to initialize the model in
equilibrium or a representative condition. You can usually solve such equations by breaking the
chain and setting one of the variables to a known or reasonable value using, for example, an
ACTIVE_INITIAL function (in the Equation Editor you specify the variable to be an Auxiliary
with Initial).
? Simultaneous data equations are generally the result of typographical errors, although they can
bear some resemblance to simultaneous active equations.
To get an understanding of simultaneous equations, it often helpful to just walk through the list of
equations by clicking on the different variables mentioned in the list. Another trick that can sometimes
be helpful is to make a new view and add in the variables involved in the loop leaving other variables
as shadow variables.
When you do make changes to resolve a set of simultaneous equations, you might uncover another set.
This happens because when a simultaneous equation is first identified, the variables involved will not
be searched further until the problem has been corrected. Once corrected, another search might
uncover another set of simultaneous equations.

Iterative Solutions to Active Simultaneous Equations


Vensim can find iterative solutions to some simultaneous equations. There are a limited number of
situations where such solutions can be helpful. The first, and simplest solution is to use the
SIMULTANEOUS function which effectively tells Vensim to try running around the loop until
nothing in the loop changes any more. The second approach uses the FIND ZERO function and is
somewhat more difficult to set up. The FIND ZERO function is discussed in Chapter 4.

SIMULTANEOUS Function
Suppose that you have the equations:
phone calls = Customers * normal call rate *
effect qualit function(quality)
quality = quality function(capacity utilization)
capacity utilization = phone calls/Capacity
As these equations stand, phone calls depends on quality which depends on capacity
utilization which depends on phone calls. The logic is circular and Vensim will report a
simultaneous active equation error. These equations are aimed at the minute to minute and day to day
response of people to slow dial tone responses, busy circuits and bad connections. If you pick up a
phone it takes a couple of seconds for you to realize the dial tone is slow. You need to dial to hit a
busy circuit. You have to start talking to get a bad connection. You could create a well formed cause

56
and effect model of this, but the time scale is very, very short. In a model aimed at understanding how
Capacity, Customers and other things interact over several years such short time scales are not
helpful and are likely to cause integration problems.
Vensim will report the error messages:
ERROR: Simultaneous equations involving: capacity utilization
: quality
: phone calls
: capacity utilization
Vensim has detected this error in attempting to compute capacity utilization. This can be
removed by adding a SIMULTANEOUS function to the variable as in:
capacity_utilization = SIMULTANEOUS(phone_calls/Capacity,.8)
The SIMULTANEOUS function must appear first on the right hand side as a defining function. The
first argument is the expression you would like to be computed. The second argument is an initializing
expression, which is usually just a constant. The initializing expressions cannot, themselves, contain
any simultaneous equations. At the initial time Vensim will initialize the variable using the second
argument and then compute all the equations in the loop iteratively until the values of the loop
variables no longer change significantly. At other times Vensim will compute iteratively starting from
the values at the previous time step.
There is no guarantee that the iterative computation will converge. If it fails to do so you will receive a
warning message and intermediate variable values will be used. You can often adjust equations, even
introducing a pseudo integration step, in order to get convergence. The model kidney.mdl that ships
with the sample models gives an exa mple of how to do this.

Units Checking
The units check feature checks the model equation for the consistent use of units of measurement. You
can check the units in a model using the Model>Units Check command or by holding down the Ctrl
key and pressing U (Ctrl + U). Depending on how you have configured your Analysis Toolset or
which toolset you have loaded, there might also be a tool that you can click on to check units.

When you check the units in a model, Vensim will report a list of errors that have been found. Units
check errors do not prevent simulation, but fixing units problems can sometimes find problems that
might otherwise have been overlooked. If you do not specify units of measurement for model
variables, checking the units will simply report the name of each variable that has not had its units
specified.
The most common sources of units errors are mistyped units names and missing synonyms. After
correcting these, however, there are likely to remain errors of a more substantive nature. If you have
multiplied instead of dividing, units checking will find that quickly. The potential for finding serious
problems quickly, combined with the value and clarity that come from specifying units, make
performing units checking a very worthwhile activity.

Units Check Output


When you invoke the Units Check tool, it reports the number of errors encountered:

57
Errors are displayed in a scrollable text window which contains an analysis of the errors. If the output
from a previous use of the Units Check tool is still open when you invoke Units Check, the old output
window is deleted.

There are two types of messages that report problems with units:
? Errors indicating dimensional inconsistency.
? Warnings indicating that you have not defined the units of measure for a variable, or that you are
using a dimensioned variable as input to a Lookup table. Using dimensioned inputs to Lookups is
potentially dangerous since changing the units of measure influences the Lookup's output.
Lookups are recommended to be dimensionless.
You can print or export the output from a Units Check by clicking on the appropriate button.

Source of Units Check Errors


Units checking proceeds from the inside out, starting with variables and building up to expressions. If
there is an error detected in any sub-expression, the remainder of the expression can only be partially
checked. Thus, if you try to add Miles and Kilometers, then divide by Hours, the resulting units
are treated as units in error. The following are the most common sources of errors:
? The left and right hand side of an equation do not have the same units of measure.
? Addition, subtraction, and comparison (<, = and so on) are performed on variables (or
expressions) having different units of measure.
? Functions are called with arguments having units of measure inconsistent with what the function
requires. See Chapter 4 for details on individual functions.
Because much of the units checking is performed on expressions, it is necessary to determine the units
of measure for an expression. Multiplication causes the units of measure to be multiplied. Division
causes the units of measure to be divided. Each of the functions has defined units of measure for its
output. (Lookup functions also have defined units of measure for their output.)

Units are compared according to the exact names of the units. Thus, Person and People are treated
as different units, as are Mile and Miles. If you are using plurals and different names with the same

58
meaning, you must explicitly set up an equivalence as part of Vensim's startup procedure. The section
on Units Synonyms below describes this.

Units and Lookup Functions


Vensim will report a warning during units checking if you call a Lookup function with an argument
that is not dimensionless. Suppose price is measured in $/Widget and you have a demand function
such as:
demand = demand f(price) ~Widget/Month ~|
demand f((0,1000),(5,100),(10,10),(20,1)) ~Widget/Month ~|
This formulation is weak because a change in the units of measure for price will invalidate the
relationship used. A Units Check will report that the input the to Lookup demand f is not
dimensionless. You could get around this by dividing price by unit price a dimensioned
constant with value 1. This however, does not remove the fundamental weakness. A far more robust
formulation is:
demand=normal demand*demand f(price/reference price)~Widget/Month~|
reference price=5~$/Widget~|
normal demand=100~Widget/Month~|
demand f((0,10),(1,1),(2,.1)(,4,.01)) ~Dmnl~|
This formulation scales easily and is not sensitive to changes in the units of measure for price or
demand. The extra detail added is likely to prevent problems in the long run.

Correcting Units Errors


One dimensional problem can lead to a number of errors being reported. Because units checking is so
quick, a good strategy for dealing with units errors is to fix the first one that appears, and then check
the units again.
If you are working with the Sketch Editor, it is helpful to have the Equation Edit tool loaded onto the
Analysis Toolset. The Equation Edit tool opens the Equation Editor positioned on the workbench
variable. After reviewing the output of units checking, decide which variable is in error and double
click on that variable. This will put the variable into the workbench. Clicking on the Equation Edit
tool on the Analysis Toolbar will open the Equation Editor on that variable.
†If you are working with the Text Editor then be sure the status bar has Entrain showing:

If you do not see Entrain, click on the button that says No-entrain to move the Text Editor into entrain
mode. After performing units checking, review the errors and double click on the variable that you
think needs fixing. The Text Editor will automatically position the cursor at this variable. Correct the
units then check again.
Often checking the units of measure for a single variable can remove several errors. However,
sometimes fixing one error will cause several others. Thus the number of units errors reported can
actually go up. Nonetheless, if you are persistent and keep at it you will eventually get the message:

59
Reforming and Cleaning Models
The Model>Reform/Clean command allows you to reformat and reorder model equations. This is very
useful if you are moving between the Equation Editor and Text Editor and want to put equations in
alphabetical order, or order them by group. It can also be a good way to document a model for
archival purposes.
If you are storing a model in binary (.vmf) format and end up with a long list of units you are no longer
using, or run into unexpected problems working with the model, you can use Reform/Clean to clean up
any internal problems. If you are working with models in text (.mdl) format, this process (with no
reordering or character set translation) is automatically performed each time you close and reopen the
model.

Equation Order determines the order the equations will be presented in the Text Editor, and when
saved in .mdl format. You can choose to retain the order entered, or to reorder alphabetically by group.
Equation Format determines the format the equations are presented in. As Originally Entered retains
the format that you originally entered the equation in; Verbose attempts to maximize clarity; Terse
attempts to minimize space consumed.
Character set conversion… Prior to Version 5.6 of Vensim models and supporting files were
encoded using the default character sets of the computers used. From version 5.6 on Vensim uses the
Unicode character encoding UTF-8. This means that independent of where a model or file is developed
it will work the same on other computers as long as they can support the characters used. With
Unicode, every character and letter in every language is assigned a unique number. The low numbers
(< 128) are the standard ASCII encoding. This means that files and models containing only a-z, A-Z,
numbers and normal punctuation are the same in almost every encoding.

However, if you use symbols beyond these, letters from other alphabets or characters from languages
such as Chinese the different encodings give very different results. If you get a .vmf file from an older
version of Vensim you may need to convert the character set. To do this specify in the From selection
the character encoding originally used (if you need to exp eriment to determine this be sure to save a
copy of the original model as information can be lost if the incorrect encoding is specified).
Alternatively, if you want to give a model to someone with an older Vensim version you can change
the To encoding.
Click on OK to complete the reformat.

60
4 Functions and Keywords

A variety of functions are available in the Vensim modeling language. This chapter:
? Contains a full description of all the predefined functions and keywords in Vensim.
? Explains the syntax and usage of each function.
? Shows how each function treats units of measure.
? Discusses Lookup functions, with which you can specify an arbitrary nonlinear relationship.
The functions in this chapter are listed in alphabetical order, but there are a number of different
categorizations that can be useful. To simplify selection, the Equation Editor uses:
? Common functions are the most often used and this is the default list the Equation Editor presents.
? Simple functions have no inherent dynamics. They determine the value of output based solely on
the current values of inputs. A function, in mathematical usage, usually refers toa simple function.
? All lists all the built-in and external functions - essentially everything in this chapter plus any
external function that might have been created. It does not list Lookups or User Macros.
? Dynamic functions impart some dynamics, so that the output depends on more than the current
value of inputs. Dynamic functions in Vensim are implemented as Macros to enable comp lete
causal tracing.
? Discrete/Delay functions are functions that introduce delays and are useful for tracking discrete
elements including attributes in queues.
? Financial functions are functions that allow the adding up and manipulation of things within a
fiscal period that might be different from the Time Step of the model. These functions operate like
both Dynamic and Simple functions at the same time.
? Lookup functions are those that have been defined for the model.
? Reality Check functions are those that relate to writing Reality Check Equations. These can only
be used in Reality Check equations.
? Data Only functions are only used with data. Data equations relate to vectors of values over time,
and the data-only functions allow some additional manipulation of those vectors.
? Array† functions are those that relate to arrays (SUM and so on).
? Macros † are Macros that you have entered into the model using :MACRO: definitions.
? User Defined‡ function are ones that have been added through the use of an external function
DLL.
There are a number of functions which define what a variable is. Defining functions must appear first
on the right hand side of an equation. The most important defining function is the INTEG function,
which defines a variable as a Level variable. Defining function are accessed in the Equation Editor by
selecting the type and subtype for the variable.
The keywords listed in the following table are described in detail in the chapters referenced in their
descriptions.

Summary List of Functions


Table 4-1 is a summary table of the predefined functions, which you can use as a quick reference tool.
Not all functions are available in all configurations. The indented functions are not available in

61
Vensim PLE or PLE Plus. The functions marked with a plus + are not available in Vensim PLE. The
functions marked with a dagger † are only available in Vensim Professional and Vensim DSS.
Table 4-1. Summary of Predefined Functions and Keywords.
A FUNCTION OF(#,A,B,C,,,) Shows "generic" relationships -automatically
generated by Sketch tool.
ABS(A) Returns the absolute value of A.
ACTIVE INITIAL(A,N) Defines an Auxiliary with distinct active and initial
values.
ALLOCATE AVAILABLE(r,pp,a) † Allocates a scarce resource based on the
request r, the amount available a and a preference
profile pp.
ALLOCATE BY PRIORITY(req,prio,siz,wid,sup)† Allocates a scarce
resource based on the request, priority and supply
over size elements with width determining sharing.
ALLOC P(req,prio,wid,mp)† Like ALLOCATE BY PRIORITY but using mp
from MARKETP.
:AND: Logical AND (Chapter 2).
ARCCOS(X) Arc-cosine of X in radians.
ARCSIN(X) Arc-sine of X in radians
ARCTAN(x) Arc-tangent of X in radians.
:AT LEAST ONCE: Relation must be true at least once for a Reality
Check.
COS(X) Cosine of X.
COSH(X) Hyperbolic cosine of X.
:CROSSING: Lines must cross for Reality Check Consequence.
CUMULATE(A) Cumulates values for the data series A.
CUMULATEF(A) Cumulates data series A and stores only the final
value as the result.
DELAY BATCH(X,S,T,IS,IT,IB) Holds the input X till S cumulates then
delays T. First batch IS output at IT with IB already
cumulated for the next batch.
DELAY CONVEYOR(X,T,L,IP,I,IT) Delays the input X on a conveyor for
time T with leakage L. IP is the time profile of the
initial material I which will has an initial convey time
IT.
DELAY FIXED(X,T,I) Delays the input X for a fixed time T starting with I.
DELAY INFORMATION(X,T,I)Delays the input X for a variable time T starting
with I discarding inputs if T decreases and holding
inputs if T increases.
DELAY MATERIAL(X,T,I,M) Delays the input X for a variable time T starting
with I and conserving X except that M is used if no
delayed inputs are available.
DELAY N(X,T,I,N) N'th order exponential delay of the input X starting at
I and conserving X.
DELAY PROFILE(P,X,T,I,G) An arbitrary delay of X with average delay
time T distributed over a profile P (a Lookup) with

62
initial value I initially growing at rate G.
DELAY1(X,T) First order exponential delay of X for time T
conserving X.
DELAY1I(X,T,I) Same as DELAY1 but starting at I.
DELAY3(X,T) A third order exponential delay of X for time T
conserving X.
DELAY3I(X,T,I) Same as DELAY3 but starting at I.
DELAYP(X,T:P) Same as DELAY3 but also returning P the amount in
the pipeline.
DEMAND AT PRICE(q,pp,pr) † The quantity demanded given a satiation
demand q, preference profile pp and price pr.
DEPRECIATE BY SCHEDULE(P,S,I,T,FS) † Depreciate a payment stream P
over time T according the to schedule S with initial
values I and the fiscal period starting at FS.
DEPRECIATE STRAIGHTLINE(P,T,F,I) † Depreciate a payment stream P
over time T with Fiscal Period F and having initial
output I.
ELMCOUNT(sub) † Returns the number of elements in the Subscript
Range sub.
:END OF MACRO: † Marks the end of a macro definition (Chapter 2).
EXP(X) Returns e(2.718...) to the X power.
FIND ZERO(...) † Used to find a zero value for a vector.
FORECAST(I,A,H) Forecast for I over the time horizon H using an
averaging time A.
GAME(X) X except during gaming mode when the user input is
used.
GAMMA LN(X) Returns the natural log of GAMMA function on X (log
of (X-1) factorial for integers).
GET 123 CONSTANTS('f','t','c') Constants from tab 't' of the 123 file 'f' starting
at cell 'c'.
GET 123 DATA('f','t','r','c') Data from tab 't' of the 123 file 'f' starting at
cell 'c' time in row or column 'r'.
GET DATA AT TIME(D,T) The value for the data variable D at time T or
:NA: if not available.
GET DATA BETWEEN TIMES(D,T,M) The value for the data variable D at T
using interpolation rule M :NA: if out of range.
GET DATA FIRST TIME(D) The first Time at which the data variable D has
a value.
GET DATA LAST TIME(D) The last Time at which the data variable D has
a value.
GET DATA TOTAL POINTS(D) The total number of values for the data
variable D.
GET XLS CONSTANTS'f','t','c') Constants from tab 't' of the Excel file 'f'
starting at cell 'c'.
GET XLS DATA('f','t','r','c') Data from tab 't' of the Excel file 'f' starting at

63
cell 'c' time in row or column 'r' (if 'r' is a number
time is read across, if a letter time is read down).
:HOLD BACKWARD: Specifies that data should be used by holding the last
value (Chapter 2).
IF THEN ELSE(cond,X,Y) Returns X if condition is non-zero, otherwise Y.
:IGNORE: Separate causes not yet used (Chapter 8). Also used
in Reality Check.
:IMPLIES: The implication portion of a Reality Check.
INITIAL(A) Returns the value of A at initialization time and holds
it constant.
INTEG(R,N) Performs numerical integration of R starting at N
(defines a Level).
INTEGER(X) Returns the integer part of X.
:INTERPOLATE: Specifies that data should be interpolated between
points (Chapter 2).
INTERNAL RATE OF RETURN(s,f,I,t) Computes the internal rate of return of
stream s with fiscal period f and initial
investment/payment I made at time t.
INVERT MATRIX(M,n) † Inverts the Matrix M of dimension n.
:IS: Used for assignment of string constants (Chapter 2).
LN(X) Natural logarithm of X.
LOG(X,Y) Base Y logarithm of X.
:LOOK FORWARD: For data look forward to the next value (Chapter 2).
LOOKUP AREA(L,X1,X2) Area under the lookup L between X1 and X2.
LOOKUP BACKWARD(L,X) The y value of L from to the largest x value
smaller than or equal to X.
LOOKUP EXTRAPOLATE(L,X) Returns a lookup value determined by
extrapolating the extreme entries.
LOOKUP FORWARD(L,X) The y value of L from to the first x value
greater than or equal to X.
LOOKUP INVERT(L,Y) The x value that would return Y when used in the
Lookup L.
LOOKUP SLOPE(L,X,M) The slope of the lookup L at X interpolating
with mode M out of range.
:MACRO: † Begins a macro definition (Chapter 2).
MARKETP(req,prio,siz,wid,sup)† Returns the market priority (mp) for use
with the ALLOC P function.
MAX(A,B) The larger of A and B.
MESSAGE('msg',d) Displays the Message 'msg' with display type d.
MIN(A,B) The smaller of A and B.
MODULO(X,B) The remainder resulting from dividing X by B.
:NA: Special symbol denoting the missing value (C hapter
2).
:NOT: Logical NOT (Chapter 2).

NPV(S,D,I,F) Net Present Value of S with discount rate D starting at

64
I multiplied by F.
NPVE(S,D,I,F) End of period net Present Value of S with discount
rate D starting at I multiplied b y F.
NET PRESENT VALUE(S,D,F,FS,FO) Compute the net present value of S
usind discount factor D on fiscal period F starting at
FS and discount FO into the period.
:OR: Logical OR (Chapter 2).
POWER(A,B) Raises A to the B power (same as A^B).
PROD( X[r!])† The product of all instances of X in the Subscript
Range r.
PULSE(S,D) A pulse of height 1.0, starting at time S and lasting D
time units.
PULSE TRAIN(S,D,R,E) A repeated pulse of height 1.0, starting at time S,
lasting B time units and repeating every R time unit
until time E.
QUANTUM(A,B) Largest number <= A that is an integer multiple of B.
QUEUE AGE AVERAGE(Q,X) Average age of oldest X elements in
the queue Q.
QUEUE AGE IN RANGE(Q,M,X) Number of elements in a queue
between ages M and X inclusive.
QUEUE AGE OLDEST(Q) Age of the oldest element of the queue Q.
QUEUE ATTRIB AVERAGE(Q,X) Average attribute value of the oldest X
elements in the queue Q.
QUEUE ATTRIB IN RANGE(Q,M,X) The number of elements of Q with
attributes between M and X inclusive.
QUEUE ATTRIB MAX(Q) Returns the maximum value of the attribute in
the queue Q.
QUEUE ATTRIB MIN(Q) Returns the minimum value of the attribute in
the queue Q.
QUEUE ATTRIB QUANTITY(Q,X) Number of elements in queue Q required
to have a total attribute of X.
QUEUE FIFO(I,O,P,N,T) Performs numerical integration of input I and
output O tracking age with initial age distribution
profile P (a Lookup) of quantity N over time T. The
attrib
QUEUE FIFO ATTRIB(I,O,A,R,P,Q,N,M,T) variation adds in an incoming
attribute A, a rate R at which existing attributes
change, an initial distribution multiplier Q of the initial
attribute M.
RAMP(S,T1,T2) 0 till T1 then a ramp with slope S until T2 and then
constant.
RANDOM ... Return random variable. Almost all RANDOM
functions have the common
RANDOM BETA(m,x,A,B,h,r,s) arguments m -minimum, x-maximum,
h-shift relative to the referenced
RANDOM BINOMIAL(m,x,P,N,h,r,s) distribution, r-stretch relative to

65
reference, s-seed. Additional arguments are:
RANDOM EXPONENTIAL(m,x,h,r,s) BETA alpha=A and beta-B.
BINOMIAL on N trials of probability P (always
RANDOM GAMMA(m,x,O,h,r,s) an integer). EXPONENTIAL starting at
0 with mean 1. GAMMA of order O.
RANDOM LOOKUP(l,m,x,h,r,s) LOOKUP using the supplied lookup
function as a probability density
RANDOM NEGATIVE BINOMIAL(...) function. NEGATIVE BINOMIAL
for N successes with probability P (integer
RANDOM NORMAL(m,x,h,r,s) >= N). NORMAL with mean 0 and variance 1.
POISSON with mean M
RANDOM POISSON(m,x,M,h,r,s) (always returns an integer).
TRIANGULAR between S and T with peak at
P.
RANDOM TRIANGULAR(m,x,S,P,T,s) WEIBULL with shape S starting
at 0 with mean 1. The obsolete function
RANDOM UNIFORM(m,x,s) RANDOM 0 1 takes no arguments and returns
a number uniformly
RANDOM WEIBULL(m,x,S,h,r,s) distributed between 0 and 1.
:RAW: Marks data as raw so :NA: is reported for missing
values (Chapter 2).
RC COMPARE('r',var,f[,s[,d]]) Set output to f times var's value in run 'r' with
optional start time and duration
RC COMPARE CHECK('r',var,g,f[,s[,d]]) After grace period g compare to f
times var in 'r'.
RC DECAY(e,t[,s[,d]]) Set output to e decaying over t with optional start time
and duration.
RC DECAY CHECK(g,e,t[,s[,d]]) After grace period g compare to e decaying
over time t.
RC GROW(e,g[,s[,d]]) Set output to e growing at rate g with optional start
time and duration.
RC GROW CHECK(g,e,t[,s[,d]]) After grace period g compare to e growing at
rate g.
RC RAMP(e,f[,st]) Set output to ramp to f times e over t with optional
start time and duration.
RC RAMP CHECK(g,e,f[,st]) After grace period g compare to a ramp to e
times f over ramp time t.
RC STEP(e,f[,st]) Set output to f times e with optional start time and
duration.
RC STEP CHECK(g,e,f[,st]) After grace period g compare to e times f.
REINITIAL(A) Holds first value of A but, unlike INITIAL, recomputes
on resumed run.
SAMPLE IF TRUE(B,X,N) Returns X if B is true otherwise holding the
value. Starts with N.
SHIFT IF TRUE(V,B,N,A,I)† Shifts N elements of V if B is true accumulating
if A is non-zero. The first element of V is replaced by

66
I.
SIN(X) Returns the sine of X measured in radians.
SINH(X) Returns the hyperbolic sine of X measured in radians.
SINTEG(R,I,m,x,Q,S,T) Performs numerical integration of R starting at I
but stays bigger than m, smaller than x, is quantized
by Q and is S when within T of S.
SMOOTH(X,T) Returns a first order exponential smooth of X over
time T.
SMOOTH N(X,T,I,N) Returns a N'th order exponential smooth of X over
time T starting at I.
SMOOTH3(X,T) Returns a third order exponential smooth of X over
time T.
SMOOTH3I(X,T,I) Returns a third order exponential smooth of X over
time T starting at I.
SMOOTHI(X,T,I) Returns a first order exponential delay of X over time
T starting at I.
SQRT(X) Returns the square root of X.
STEP(H,T) Returns 0 till time T and then H.
SUM( X[r!] )† Returns the sum of instances of X in the Subscript
Range r.
SUPPLY AT PRICE(q,pp,pr) † The quantity supplied given a capacity q,
preference profile pp and price pr.
TABBED ARRAY( a b
x y)† Used to input tab delimited numbers as
arrays of constant values.
TAN(X) Returns the tangent of X (radians).
TANH(X) Returns the hyperbolic tangent of X.
:TEST INPUT: Defines a test i nput equation for use with Reality
Check.
:THE CONDITION: Precedes the predicate condition of a Reality Check.
TIME BASE(start,slope) Defines a time base for output customization.
TIME SHIFT(data,shift) Shifts data in time.
TIME TRANSITION(T1,...) Obsolete.
TREND(I,H,N) Returns the fractional change rate of I over horizon H
starting with N.
VECTOR ELM MAP(vec,offset) Extracts elements of a vector without directly
using their subscripts.
VECTOR RANK(vec,dir) Returns the rank values for a vector in increasing or
decreasing order.
VECTOR REORDER(vec,svec) Reorders the vector according the specified
sort order.
VECTOR SORT ORDER(vec,dir) Returns the sort order for a vector in
increasing or decreasing order.
VMAX(X[r!])† Takes the maximum of X over the subscript range r.
VMIN(X[r!])† Takes the minimum of X over the subscript range r.

67
WITH LOOKUP(x,L#) Returns the y value of the xy pairs L# corresponding
to x.
X IF MISSING(expr,X)† Replaces missing data with X specified value.
XIDZ(A,B,X) Returns X if dividing by zero (B =0) otherwise returns
A divided by B.
ZIDZ(A,B) Zero (0.0) if dividing by zero (B=0) otherwise returns
A divided by B.

Lookups
In addition to the predefined functions, you can specify an arbitrary nonlinear relationship with a
Lookup. Put simply, a Lookup is a list of numbers representing an x axis and a y axis. The inputs to
the Lookup are positioned relative to the x axis, and the output is read from the y axis. You use
Lookups to create your own specialized functions.
Lookups are also referred to as "Lookup Functions," "Tables," "Lookup Tables," "Table Functions,"
and sometimes "Graphical Functions."
Lookups can be declared as x,y pairs or by specifying the x-axis followed by the y-axis. The format
for declaring a Lookup is:
LOOKUP NAME([(Xmin,Xmax)-(Ymin,Ymax),(Xref1,
Yref1),(Xref2,Yref2),...(Xrefn,Yrefn)]
(X1, Y1), (X2,Y2), . . .(Xn, Yn) )
~ Units ~ Description |
or:
LOOKUP NAME( X1, X2, X3,....Xn, Y1, Y2, Y3,....Yn)
~ Units ~ Description |
In the second case, the number of entries for X needs to match the number of entries for Y. For all
Lookups, a minimum of two values must be specified for both the x and y axis.
Lookups are most commonly defined using the Graph Lookup Editor:

68
The Graph Lookup Editor allows you to enter x,y pairs, or to trace the shape of the Lookup using the
mouse. The Graph Lookup Editor is described in detail in Chapter 6.
When you use the Graph Lookup Editor, it will put additional information on scaling in the lookup
definition as in:
effect of energy function([(0,0)-(4,2)],(0,0),(0.501742,0.596491),
(1,1),(1.44948,1.34211),(2,1.6),(2.99652,1.7807),(4,1.8))
The range shown in square brackets [(0,0)-(4,2)] is used by the Graph Lookup Editor to determine the
scaling. It can also be followed by optional reference point information. There is no need to enter a
scale or reference point information when typing in Lookup values.

Using Lookups
The use of a Lookup function is the same as that of the predefined functions that take one variable, as
in:
outvar = lookup name(invar) ~~|
Units NOTE: Variables coming into a Lookup function are recommended to be dimensionless, and a
warning message is given during units checking if they are not. The output of a Lookup function has
the dimensions specified in the definition of the Lookup.
When used in the above manner the value of the output is determined by linear interpolation of the
lookup, as in:

69
Here the dark circles represent the points on the Lookup, corresponding to
((0,0),(1,2),(2,3)). The dashed line connecting the points shows how the lookup is
interpolated. The dashed lines to the right and left show that if the input is below 0, the output will be
0, and if the input is above 2, the output will be 3. Three sample inputs (.67,1,1.7) and their respective
outputs (1.3,2.0,2.7) are shown.
Lookups in Vensim will always hold the first or last value when the input goes outside the range of the
Lookup. You will receive a warning message whenever this happens.
If you wish to have Lookups extrapolate, you should use the LOOKUP EXTRAPOLATE function
described earlier in this chapter, or define a large minimum or maximum input value as in:
extrap up lookup ((0,0),(.5,7),(.75,.9),(1,1),
(2,2),(1E6,1E6))

Example 1
effect energy tab (
(0.0,0.0), (0.1,0.2), (0.2,0.4),(0.3,0.6), (0.4,0.7), (0.5,0.8),
(0.6,0.85), (0.7,0.9), (0.8,0.95), (0.9,0.98), (1.0,1.0),
(1.2,1.02), (2,1.02) )
~dimensionless
~ The effect of energy availability on industrial production.
|
production = nominal production
* effect energy tab( US energy
* fraction available - energy losses )
~ quads / year
~ energy-availability limited production rate
|

Example 2
effect energy tab(0, 0.5, 1.0, 2.0,
0, 0.7, 1.0, 1.1)
~ dimensionless
~ The effect of energy availability on industrial production.
|
production = nominal production
* effect energy tab( energy availability )
~ quads / year
~ production rate limited by energy availability

70
|
The x,y pairs for a Lookup can be altered at runtime, and the number of x,y pairs specified in a Lookup
can be increased or decreased.

Special Interpolation Modes (Not PLE or PLE Plus)


The functions LOOKUP BACKWARD, LOOKUP EXTRAPOLATE and LOOKUP FORWARD
provide alternative interpolation and extrapolation techniques for using Lookups. If you are using
these functions you must explicitly denote that. For example the equations:
look((0,0),(10,0),(20,55),(30,76),(40,50),(50,50))
y = look(x)
y2 = LOOKUP EXTRAPOLATE(look,x)
would make y and y2 the same for all input values. The only difference being that no warning
messages would be issued for y2 when x is out of range.

Detailed Function Descriptions

A FUNCTION OF (#,A,B,C,...) A "Generic" causal FUNCTION


NOTE This function is created automatically by the Sketch tool, is not intended for use in writing
equations, and precludes simulation.
A FUNCTION OF indicates only that variables are related. It does not describe the form of the
relationship. (As a result it cannot be calculated.) In the Text Editor, an equation using the A
FUNCTION OF function may be followed by one or more equations containing syntax errors or
incomplete causal lists. This function does not appear and cannot be used in the Equation Editor.
Unlike all other functions, A FUNCTION OF has an indeterminate number of arguments.

If you are using placeholder values, the first argument for A FUNCTION OF may be a number. This
value will be displayed within curly brackets in the Equation Editor.
NOTE No units checking occurs on this function since it is intended to represent arbitrary functional
relationships.

ABS(x)ABSolute value [variable]


Returns the absolute value of X.
Same as IF THEN ELSE (X < 0, - X, X).

Units: ABS(any unit) ? same units


Examples
ABS (5.0) is equal to 5.0.
ABS (-5.0) is equal to 5.0.

ACTIVE INITIAL(active eq, initial eq) Distinct ACTIVE and INITIAL Equations

Returns the active equation during simulation, except when needed for determining initial conditions,
when the initial equation is returned. Normally this function is used to break a loop of simultaneous
initial value equations.

NOTE In the Equation Editor the ACTIVE INITIAL function is automatically entered when you
select the variable type Auxiliary and the subtype with Initial.

71
Restrictions: Must appear first on the right of the = sign. It defines a variable as an Auxiliary variable
with a separate initialization condition.

Units: ACTIVE INITIAL(input units,input units) ? same units


Example
Capacity = Integ(capacity adjust,target capacity) ~~|
target capacity = Capacity * adjust from utilization ~~|
This would simulate properly, except that the initial conditions cannot be computed correctly: the
initial conditions of Capacity require a value for target capacity, which in turn requires a
value for Capacity. Since Vensim does not support the implied simultaneous computation, you
need to use the following equation for target capacity:
target capacity = ACTIVE INITIAL(Capacity * adjust from utilization,
100) ~~|
This will cause Capacity to be initialized at 100; then the first value of target capacity will
be Capacity * adjust from utilization. In general, this will not be 100; the initial
expression is used only to compute the initial conditions of State variables.

ALLOCATE AVAILABLE(request,pp,avail)† ALLOCATE AVAILABLE

This function is used to allocate the available amount of a scarce resource to requesters based on the
priority of those requests. It requires that the left hand side variable and request have the same final
subscript and that pp have that subscript second last, and a ppriority subscript last. This function is a
generalization of ALLOCATE BY PRIORITY and is described more completely in Appendix E of this
manual.

request must be a subscripted variable, and its final Subscript must match that of the left hand side. It
represents the (satiation) quantity requested by different agents.

pp is the priority profile. It is used to define the shape of the curve that defines how much of the
available amount a request receives under conditions of shortage. It must have as its final subscript a
pprofile subscript as discussed in Appendix E. All elements should be positvive.
avail is the total quantity available to fulfill all requests. If this exceeds total requests, all requests are
filled, but none are overfilled.

IMPORTANT NOTE ALLOCATE BY PRIORITY is sensitive to the order of subscripts! If you


have more than one subscript range in the variables you are using, the request elements must be last on
the left hand side and request, and second last on pp.
See also: FIND MARKET PRICE, DEMAND AT PRICE, SUPPLY AT PRICE, Appendix E.

Units: ALLOCATE AVAILABLE(units, dimensionless, units) ? units


Example
branch : Boston,Dayton,Fresno
pprofile : ptype, ppriority, pwidth, pextra
demand[Branch] = 500,300,750
Units: Widget/Month
priority[Boston,pprofile] = 1,5,2,0
priority[Dayton,pprofile] = 1,7,4,0
priority[Fresno,pprofile] = 1,3,4,0
Units: Dmnl

72
Shipments[branch] = ALLOCATE AVAILABLE(demand[branch],
priority[branch,ptype],supply available)
Units: Widget/Month
Restrictions: ALLOCATE AVAILABLE must directly follow the equal sign.
Availability: DSS and Professional only.

ALLOCATE BY PRIORITY(request,priority,size,width,supply) † ALLOCATE BY PRIORITY


This function is used to allocate a scarce supply to a number or requests based on the priority of those
requests. It works only when the left hand side, request and priority all have the same final subscript.
If supply is bigger than the sum of request over size elements then the requests are fulfilled (none are
overfilled). If supply is smaller then rationing occurs. The way in which the rationing works is
determined by the relative priorities and the width parameter. Appendix E in this manual details the
algorithm used for this function.

request, priority
The first two arguments must be vectors (of length size). That is, the (last) Subscript of request and
priority must vary across the different demand elements. The left hand side variable must also have
its last subscript varying across the different demand elements.
IMPORTANT NOTE ALLOCATE BY PRIORITY is sensitive to the order of subscripts! If you
have more than one subscript range in the variables you are using, the demand elements must be the
last subscript for the left hand side variable, request and priority.
size is the number of elements across which allocation is being made. Normally this is done using the
ELMCOUNT function as in the example. It can also be a number or a subscript constant.
width specifies how big a gap in priority is required to have the allocation go first to higher priority
with only leftovers going to lower priority. When the distance between any two priorities exceeds
width and the higher priority does not receive its full request the lower priority will receive nothing.
supply is the total supply available to fulfill all requests. If the supply exceeds total requests, all
requests are filled, but none are overfilled. If you wish to conserve material you must compute supply
minus total allocations explicitly.
See also: ALLOC P, MARKETP, Appendix E.

Units: ALLOCATE BY PRIORITY(units, dimensionless, dimensionless,


dimensionless, units) ? units
Example
country : US, CHINA, RUSSIA
~ index
~ countries over which a scarce resource
are to be allocated |
desired[country] = 10, 2, 8
~ tons / month
~ desired amount of scarce resource |
priority[country] = 10, 10, 10
~ dimensionless
~ priority for receiving the resource; higher number indicates
higher priority |
SUPPLY = 10
~ tons / month

73
~ available supply of resource |
WIDTH = 1
~ dimensionless
~ width for each priority rectangle |
delivered[country] = ALLOCATE BY PRIORITY( desired[country],
priority[US],RUSSIA, WIDTH, SUPPLY )
~ tons/month
~ amount of supply delivered to a specific country |
In this example, the supply of 10 tons/month is allocated to three countries having a total request for
supply equaling 20 tons/month. Because the priority of each is the same, each country will get the
same fraction of their request (50% in the example). If the priority had been higher for a specific
country it would have received a greater than proportional share of the resource.
Availability: DSS and Professional only.

ALLOC P(request, priority, width, mp)† ALLOCate by Priority

Same purpose as ALLOCATE BY PRIORITY but used in conjunction with the MARKETP function.
Returns the amount of a request allocated to a sector with the given request and priority.

See also: ALLOCATE BY PRIORITY, MARKETP, Appendix E.

Units: ALLOC P(request units, dimensionless, dimensionless, dimensionless)


? request units
Availability: DSS and Professional only.

ARCCOS(x)ARC COSine of X

Returns the arc-cosine of X in the range -?/2 to ?/2. If X is bigger than 1 or less than -1 a floating
point error is generated.

Units: ARCCOS (dimensionless) ? dimensionless


Availability: Not PLE or PLE Plus

ARCSIN(X)ARC SINe of X

Returns the arc-sine of X in the range -?/2 to ?/2. If X is bigger than 1 or less than -1 a floating point
error is generated.

Units: ARCSIN (dimensionless) ? dimensionless


Availability: Not PLE or PLE Plus

ARCTAN( X )ARC TANgent of X

Returns the arc-tangent of X in the range -?/2 to ?/2.

Units: ARCTAN (dimensionless) ? dimensionless


Examples
ARCTAN( 0.0 ) is equal to 0.0.
Availability: Not PLE or PLE Plus.

74
COS( X ) COSine of X
Returns the cosine of X. Sometimes useful to test the dynamic response of a system. COS is periodic
on X in the range of 0 to 2? radians.

Units: COS (dimensionless) ? dimensionless


Examples
COS( 0.0 ) is equal to 1.0.
COS( ?/2 ) is equal to 0.0.

COSH( X )Hyperbolic COSine of X

Returns the hyperbolic cosine of X.

Units: COSH(dimensionless) ? dimensionless


Example
COSH( 0.0 ) is equal to 1.0.
COSH( 1.0 ) is equal to 1.54.
Availability: Not PLE or PLE Plus.

CUMULATE(X) CUMULATE data series


CUMULATEF(X) CUMULATE but only retain Final value

Takes input data X and returns the accumulation of that data (i.e., the first data point, the first data
point plus the second, … the sum of all the data points). CUMULATEF reports only the final sum at
the time of the last data point. The accumu lation is pure, no attempt is made to multiply by the time
interval.

Units: CUMULATE(units) ? units


NOTE This units convention may cause trouble if you are attempting integration.

Restrictions: Valid only in data := equations. Must appear first on the right of the := sign. It defines a
variable as being manipulated data.

Example
cum sales data := cumulate(sales data)
Availability: Not PLE or PLE Plus

DELAY BATCH(input,bsize,btime,inibatch,initime,inibacklog) BATCHed DELAY

Returns the value of input collected into batches of size bsize after processing for time btime. A zero
is returned for all times a batch is not being completed. The initial batch in process is specified by
inibatch and is returned at initime. The initial amount of material already accumulated for processing
is specified by inibacklog.
Batches are not released for processing until the amount of material accumulated is at least bsize and
no batch is currently being processed. This function takes a continuous input stream and converts it to
distinct pulses while conserving the total amount of material. bsize and btime can both be time
varying and the time at which a batch is completed, and a nonzero value returned, is determined by the
value of btime when the batch started. If initime is less than or equal to the initial time for the
simulation then inibatch is returned when the simulation starts.

Units: DELAY BATCH(units, units*time, time, units, time, units*time) ?

75
units
Example
return from anodize=DELAY BATCH(assembly,100,3,100,2,20)
For more detailed examples see Chapter 9 of the Modeling Guide.
Availability: Not PLE or PLE Plus.

DELAY CONVEYOR(input,ctime,leak,initprofile,inittot,initctime) CONVEYOR DELAY


Returns the value of input delayed by conveyence time ctime. While material is on the conveyor the
fractional leakage per unit time is given by leak. The initial amount of material on the conveyor is
giving by inittot and is distributed according the the time profile in the Lookup initprofile. The initial
value returned by the function is determined by initctime (it is equal to inittot/initctime ). initctime is
normally, but does not have to be, equal to ctime.

You can speed up or slow down a conveyor by changing ctime. If leak is 0 then material on the
conveyor is conserved. When leak is nonzero than the amount of material is decreased proportionally
across the entire conveyor, including newly added input. If you want to compute the quantity of
leakage in a conveyor it is given by:
total leakage = ahead level * leak rate
ahead level = convey total + TIME STEP*(input - convey out)
convey total = INTEG(input - convey out - total leakage,init stuff)
convey out = DELAY CONVEYOR(input,ctime,leak rate,icp,init
stuff,ctime)

Units: DELAY CONVEYOR(units,time,1/time,dmnl,units*time,time) ?


units
Example
finished assembly=DELAY CONVEYOR(assembly start, assembly time,0,
flat lookup, in assembly init, assembly time)
For more detailed examples see Chapter 9 of the Modeling Guide.
Availability: Not PLE or PLE Plus.

DELAY FIXED (input, delay time,initial value) FIXED period DELAY

Returns the value of the input delayed by the delay time. The initial value is the value of the variable
on the left-hand side of the equation at the start of the simulation. The delay time can be an
expression, but only its initial value is used.
See also: DELAY MATERIAL, DELAY INFORMATION, SAMPLE IF TRUE

Restrictions: DELAY FIXED must directly follow the equal sign. Vensim treats the variable on the
left-hand side of the equation as a Level variable. In the Equation Editor choose type Level, subtype
Fixed Delay.

Units: DELAY FIXED ( unit , time, unit ) ? unit


The input, initial value and output must all have the same units. The delay time must have the same
units as TIME STEP.

Examples
DI = DELAY FIXED(I,22,I)
DM = DELAY FIXED( MAX( A, B ), C,A)

76
Invalid
D = A + DELAY FIXED( R, 3.2, 0.0 )
D = DELAY FIXED( B, T, B) + 1
DELAY FIXED must follow the equal sign, and it cannot be part of a more complex mathematical
expression. These formulations can be made valid by defining an auxiliary variable to perform the
indicated operations.
NOTES The minimum delay time is TIME STEP and shorter delay times will have the same effect as
a delay time of TIME STEP. DELAY FIXED and the other DELAY functions are discrete event
functions and do not change except at TIME STEP intervals regardless of the integration technique
used.

DELAY INFORMATION (input, delay time, initial value) discrete INFORMATION DELAY
The same as DELAY FIXED except that delay time can be a variable. If delay time is decreasing
some values of the input will be discarded and replaced by more recent inputs. If delay time is
increasing existing values will be held.
Restrictions: DELAY INFORMATION must directly follow the equal sign. Vensim treats the variable
on the left-hand side of the equation as a Level variable. In the Equation Editor choose type Level,
subtype Information Delay.
See also: DELAY MATERIAL, DELAY FIXED, SAMPLE IF TRUE

Units: DELAY INFORMATION ( unit , time, unit ) ? unit


The input, initial value and output must all have the same units. The delay time must have the same
units as TIME STEP.

Examples
R = RAMP(1,10,60) ~~|
SS1 = DELAY INFORMATION(R,15+STEP(15,40),0) ~~|
SS2 = DELAY INFORMATION(R,15-STEP(10,40),0) ~~|

Availability: Not PLE or PLE Plus.

DELAY MATERIAL (input, delay time, initial value, missval) discrete MATERIAL DELAY

The same as DELAY FIXED except that delay time can be a variable. If delay time is decreasing,
some values of the input will be added to more recent inputs for output. If delay time is increasing,
missval will be used when no output is available at a time. This function is particularly useful for
modeling queues and production processes with varying and often random processing times.

Restrictions: DELAY MATERIAL must directly follow the equal sign. Vensim treats the variable on
the left-hand side of the equation as a Level variable. In the Equation Editor choose type Level,
subtype Material Delay.
See also: DELAY FIXED, DELAY INFORMATION, SAMPLE IF TRUE

Units: DELAY MATERIAL ( unit , time, unit, units ) ? unit

77
The input, initial value, missing value and output must all have the same units. The delay time must
have the same units as TIME STEP.

Examples

test starts = 1.0 ~~|


test time = RANDOM UNIFORM(4,6)~~|
test completions = DELAY MATERIAL(
test starts,test time,
test starts,0.0) ~~|
Availability: Not PLE or PLE Plus.

DELAY N(input,delay time, initial value, order) N'th order exponential delay
Returns an N'th order exponential delay. If order is 1 this function is almost the same as DELAY1I
and if order is 3 it is almost the same as DELAY3I. The most significant difference is that the output
of the DELAY N function depends on delay time from the previous Time Step while output from the
DELAY3I function depends also on the value of delay time for the current time step.
The DELAY N function is treated as a discrete delay function, so that its output is constant for each
Time Step. If you are using Euler or Diff integration this is true of all variables. However, if you are
using Runge-Kutta integration this is different from functions such as DELAY3.
The DELAY N function will conserve quantities so the integral of the input will be the same as the
integral of the input except that with 0 input the total output will be initial value times delay time as
evaluated by the first active computation at initial time. In addition, if TIME STEP is a variable
minor discrepancies may arise between the total input and total output.

Note that for the DELAY N function to make sense delay time must be bigger than order* TIME
STEP. If this is not the case Vensim will issue a warning and automatically reduce the order so that
this is true. When this happens the behavior of the DELAY N function is essentially the same as the
behavior of the DELAY MATERIAL function.
Restrictions: DELAY N must directly follow the equal sign. It signals Vensim that the variable on
the left-hand side of the equation is a Level or State variable. In the Equation Editor select Variable
type Level, subtype Delay/Queue and enter DELAY N as the function.

Units: DELAY N( unit, time unit, unit, dmnl ) ? unit


Examples
delayed production = DELAY N(production, delay time, production, 12)

DELAY PROFILE(profile,input,delay time,init,init grow) DELAY with response PROFILE


Returns the delayed value of input, where the delay response is specified, using a Lookup function, as
an arbitrary profile. The delay time specified is the average delay time (some inputs will emerge
before delay time has elapsed and some will emerge after). The delay response is the response that the

78
output will show when given a pulse as an input. If you look at a first order exponential delay you will
see that the response is biggest immediately after the pulse, and then falls off exponentially. A 3rd
order delay responds slowly at first, then more quickly, then the response falls of exponentially. An
n'th order delay, with N very large, approaches the response of a fixed delay - a pulse of the same
height after the delay time.
DELAY PROFILE allows you to break out of this family of delays to anything you want. Simply
draw the shape of response you would like to see and Vensim will allocate the input over this profile.
The profile should be a Lookup that is everywhere nonnegative, and has at least one positive value.
Vensim will automatically scale this to a probability distribution so that the input is a conserved
quantity.
Since the DELAY PROFILE distributes values over time when it is initialized you can specify an
initial growth rate. For example if the input is growing at 5% you would specify an initial growth rate
of .05. When you do this you should also adjust the initial value down as is demonstrated in the
example.
Please note that the DELAY PROFILE function was designed to encourage the exploration of different
response profiles. Most models developed depend heavily on exponential delays, and explicitly build
up structure to represent more complex responses. While the DELAY PROFILE function may prove
to be a useful addition to the set of functions for building models it should be used with care.

Restrictions: The DELAY PROFILE function must follow directly after the = sign. It defines a
variable as a Level. In the Equation Editor choose type Level and Subtype Delay/Queue then type in
DELAY PROFILE or select it from the function list (Class Discrete/Delay).

Units: DELAY PROFILE(units, dmnl, time, units*time, 1/time) ? Units


Example
boxxy ((0,0),(2,0),(3,1),(6,1),(7,0))
delayed input = DELAY PROFILE(boxxy,input,delay time,input,0)
This is similar to a DELAY MATERIAL except that it spreads the response out over a period
approximately equal to 1/2 of the delay time.
delayed input = DELAY PROFILE(boxxy,input,
input/exp(grow rate*delay time),delay time,grow rate)
Availability: Not PLE or PLE Plus.

DELAY1(input,delay time) exponential DELAY


DELAY1I(input,delay time, initial value) exponential DELAY with Initial
Returns a exponential delay of the input. Equivalent to the equations:
DELAY1=LV/delay time
LV=INTEG(input-DELAY1,input*delay time)
DELAY1I=LV/delay time
LV=INTEG(input-DELAY1I,initial value*delay time)
See also: DELAYP, DELAY3, SMOOTH, SMOOTH3

Units: DELAY1(units,time) ? units


DELAY1I(units,time,units) ? units
The input units match the output units. The units of delay time must match those of TIME STEP.
For DELAY1I units for the initial value must match those of the input.

79
DELAY3(input,delay time) 3rd order exponential DELAY
DELAY3I(input,delay time, initial value) 3rd order exponential DELAY with Initial
Returns a 3rd order exponential delay of the input, conserving the input if the delay time changes.
Equivalent to the equations:
DELAY3=LV3/DL
LV3=INTEG(RT2-DELAY3,DL*input)
RT2=LV2/DL
LV2=INTEG(RT1-RT2,LV3)
RT1=LV1/DL
LV1=INTEG(input-RT1,LV3)
DL=delay time/3

DELAY3I=LV3/DL
LV3=INTEG(RT2-DELAY3I,
initial value*DL)
RT2=LV2/DL
LV2=INTEG(RT1-RT2,LV3)
RT1=LV1/DL
LV1=INTEG(input-RT1,LV3)
DL=delay time/3
See also: SMOOTH, SMOOTH3, DELAYP

Units: DELAY3(units,time) ? units


DELAY3I(units,time,units) ? units
The input units match the output units. The units of delay time must match those of TIME STEP.
For DELAY3I units for the initial value must match those of the input.

Example
S = STEP(10,40)
DS = DELAY3(S,20)
DSI = DELAY3I(S,20,5)

DELAYP(input,delay time:pipeline) 3rd order exponential DELAY with Pipeline

Returns a 3rd order exponential delay of the input and computes the in progress pipeline, conserving
the input if the delay time changes. Equivalent to the equations:
DELAYP=LV3/DL
pipeline=LV3+LV2+LV1
LV3=INTEG(RT2-DELAYP,DL*IN)
RT2=LV2/DL
LV2=INTEG(RT1-RT2,LV3)

80
RT1=LV1/DL
LV1=INTEG(input-RT1,LV3)
DL=delay time/3
See also: SMOOTH, SMOOTH3, DELAY3

Units: DELAYP(units,time,units) ? units


Input units match output and pipeline units. The units of delay time must match those of TIME
STEP.
Example
product completions = DELAYP(product starts,
production time:work in progress)
(note there is no equation for work in progress in the model)
NOTE DELAYP is supported as a convenient shorthand, but is not recommended for widespread use.
The following equations have the same effect, and are easier to understand:
product completions = DELAY3(product starts,production time)
work in progress = INTEG(product starts - product completions,
product starts * production time)

DEMAND AT PRICE(q,pp,price) quantity DEMANDed AT PRICE

Computes the quantity that is demanded at a given price based on the satiation demand quantity q and
the demand preference profile pp. The price argument will normally be computed using the FIND
MARKET PRICE function. Both q and pp must be Subscripted variables and the subscripts for pp
must be the subscripts for q followed by a pprofile subscripts. See Appendix E for more details.
See also: SUPPLY AT PRICE, FIND MARKET PRICE, ALLOCATE AVAILABLE, Appendix E.

Units: DEMAND AT PRICE(units,punits,punits) ? units


The output units are those of q. Those units for pp and price must match.
Example
amount demanded[demander] = DEMAND AT PRICE(
demand satiation[demander],
demand curve[demander,ptype],
market price)
Availability: DSS and Professional only.

DEPRECIATE BY SCHEDULE (str,sch,init,dtime,fs) Schedule Depreciation

DEPRECIATE BY SCHEDULE is used to compute depreciation of str against the schedule specified
by sch which is an array of depreciation fractions or percents. The depreciation occurs over dtime
with the fiscal period for depreciation determined by the ratio of dtime to the number of elements of
sch. sch must be a subscripted variable and it must be used with the first element of the final subscript
in the function. You can specify the initial amount of depreciation that will occur in init which is also
an array that should be the same length as the array sch. If there is nothing in the initial depreciation
you can just use a scalar variable here, but it has to be a variable and not simply a number.
The final argument fs can be used to determine when there is a changeover from one fiscal period to
the next. Normally this argument will just be Time (or equivalently INITIAL TIME). However, if you
have a model that does not start at the beginning of a fiscal period you can use fs to adjust for this. For
example if you have a weekly model with an annual fiscal period and week 12 is the first week of 2005
then you would use 12 as the value for fs. Weeks 0-11 would be treated as part of the fiscal year
associated with 2004, 12-55 the fiscal year 2005, 56-107 fiscal year 2006 and so on.

81
The depreciation fraction specified by init will be scaled so that they add to 1. Thus having them add
to 1 or 100 will both work fine.
Restrictions: Must appear directly following the equal sign = and not be followed by anything else.

If you want to initialize this function to return a constant nonzero value from the beginning you will
need to adjust the initial values to account for the investment that will be coming in. For example the
following will return a constant value:
Syear : y1,y2,y3,y4,y5
Dsched[syear]=.2 ~ Dmnl
Init[syear]=0.8,0.6,0.4,0.2,0.0 ~ $
Invest = 1 ~$/Month
Dtime = 60 ~ Month
Depr=DEPRECIATE BY SCHEDULE(invest,dsched[y1],init[y1],5,Time)
Basically the first initial value is 1- the first depreciation fraction, the second that minus the second and
so on. In many cases the initial values will be 0 and you won’t need to worry about this detail. It is
also worth nothing that, for the above example, the DEPRECIATE STRAIGHTLINE function would
have worked.
See also: DEPRECIATE STRAIGHTLINE, NET PRESENT VALUE, INTERNAL RATE OF
RETURN

Units: DEPRECIATE BY SCHEDULE(units/time, dmnl, units, time, time)


? units/time
The output units are the same as the units of the first argument and the initial quantity units must be the
input units times the units for time. sch must be dimensionless while both dtime and fs must has the
same units as Time.
Availability: Professional and DSS only.

DEPRECIATE STRAIGHTLINE (str,dtime,fisc,init) Straight Line Depreciation


DEPRECIATE STRAIGHTLINE is used to compute straight line depreciation on an investment
stream str over some depreciation lifetime dtime. Depreciation is computed by lumping all payments
made within the fiscal period specified by fisc together. You can also specify an initial value for
stream that will initialize the different accumulations as if the function had been called with a constant
value of init in place of the str argument over the previous dtime. This means that if str continues to
take on the value init that the output of the function will continue to be constant at that value.
To use this function dtime must be an integer multiple of fisc. If it is not Vensim will automatically
adjust it so that it is. The ratio of dtime/fisc determines the number of different fiscal periods that are
involved. For an investment made at a particular time, DEPRECIATE STRAIGHLINE will return
dtime/fisc of that investment in the first fiscal period and each that follows. To guarantee that this will
work the function actually includes dtime/fisc of the current value of str in its returned value. This
can lead to somewhat odd behavior when there is a decrease in the value of str within a fiscal period,
but guarantees that all outflows will occur in the correct fiscal periods.
Restrictions: Must appear directly following the equal sign = and not be followed by anything else.

The DEPRECIATE STRAIGHTLINE function creates a variable that acts like both an Auxiliary and a
Level. The return value depends on the current value of str, and also on its past values.

Units: DEPRECIATE STRAIGHTLINE(units/time time ftime/time


units/time) ? units/time

82
The output units are the same as the units of the first argument and must also match the initial quantity
units. The depreciation time dtime has the same units as time while fisc converts from time units to
fiscal time units (eg 12 Month/Year). The fiscal time units are not used elsewhere.
Availability: Not PLE or PLE Plus.

ELMCOUNT(Range) ELeMent COUNT of Subscript Range


ELMCOUNT returns the number of elements in a subscript range. It takes only the name of a
subscript range as an argument. It is the same as using the last element of the subscript range, but will
be automatically updated if you add elements to the subscript range.

Units: ELMCOUNT(dimensionless) ? dimensionless


Example
place : boston,paris,london
ELMCOUNT(place) is equal to 3
Availability: Professional and DSS only.

EXP(X) EXPonential [variable]


Returns "e to the power of X".

Same as function, POWER(e,X), where e=2.718...

See also: LN, LOG, and POWER.

Units: EXP(dimensionless) ? dimensionless (the argument must be


dimensionless)
Examples
EXP(1.0) is equal to 2.718282.
EXP(0.0) is equal to 1.0.
EXP(-10.0) is equal to 4.540E-5.
EXP(10.0) is equal to 22026.46.
EXP(LN(10.0)) is equal to 10.0 (by definition).

FIND MARKET PRICE(dq,dp,sq,sp) † FIND the MARKET clearing PRICE

Returns the price at which the market supply and market demand are equal. This function can be used
in situations where both the demand for a good or service and the supply of it can vary. This is in
contrast to the ALLOCATE AVAILABLE function which is appropriate when only one of supply or
demand can vary. Though the function has "price" in its name it can be applied in situations where it is
not price, but some other prioritization mechanism that is active.
The function is passed the satiation demand quantity for the different demanders in dq and the demand
profiles in dp. The supply capacities are contained in sp with the associated profiles in sp. Details on
how the quantities and profiles are constructed are contained in Appendix E. dq must has as its last
subscript a range for the demanders and dp must have this followed by a pprofile range as its last two
subscripts. Similarly, sq must have the list of suppliers as its last subscript and sq this followed by a
pprofile range. The result should not have the supplier, demander or pprofile subscripts and the
arguments must be passed with the first element in the Subscript Range rather than the name of the
Subscript Range.
The result of this function is normally passed to the DEMAND AT PRICE and SUPPLY AT PRICE
functions to compute the actual demands and supplies.

83
See also: ALLOCATE AVAILABLE, DEMAND AT PRICE, SUPPLY AT PRICE, Appendix E.

Exampl es
supplier : s1,s2
demander : d1,d2,d3
pprofile : ptype, ppriority, pwidth, pextra
demand satiation[demander] = 500,300
Units: Widget/Month
Supply capacity[supplier] = 200,300,450
Units: Widget/Month
demand curve[d1,pprofile] = 3,5,2,0
demand curve[d2,pprofile] = 3,7,4,0
Units: $/Widget
supply curve[s1,pprofile] = 3,1,2,0
supply curve[s2,pprofile] = 3,3,4,0
supply curve[s3,pprofile] = 3,5,4,0
Units: $/widget
market price = FIND MARKET PRICE(
demand satiation[d1],demand curve[d1,ptype],
supply capacity[s1],supply curve[s1,ptype])
Units: $/Widget
amount supplied[supplier] = SUPPLY AT PRICE(
supply capacity[supplier], supply curve[supplier,ptype],
market price)
Units: Widget/Month
amount demanded[demander] = DEMAND AT PRICE(
demand satiation[demander], demand curve[demander,ptype],
market price)
Units: Widget/Month
Availability: Professional and DSS only.

FIND ZERO(xs,z,zs,xi,n,skip,tol,max iter,method)† FIND the value of x that makes z ZERO


Returns a vector of values that make z zero.
See also: SIMULTANEOUS

The FIND ZERO function is used to solve nonlinear simultaneous algebraic equations. It is designed
to be used in situations where the SIMULTANEOUS function will not work. FIND ZERO solves for
the value of the vector x that will make z zero (where x is the variable on the left hand side of the
equation). It can only be used with subscripted variables.
NOTE The FIND ZERO function actually takes over the control of the last subscript loop. Because of
this the variable on the left hand side of the equation (x) can be thought of as a hidden argument to the
function. If you want to use this function with variables having more than one subscript the function
will operate on only the final subscript.

Arguments
xs is a scaling vector for x. After multiplying x by this vector all of the values of then product should
be of the order of magnitude of 1. xs must be a vector of the same length as x and will often be a
vector of ones.

84
z is the vector of values that should be set to zero by the appropriate selection of x. If the functional
form being solved is y = f(y) then z would be set to y - f(y) in another equation. z must be a vector of
the same length as x.
zs is a scaling vector for z. After multiplying z by this vector the results should all be of the order of
magnitude of 1. zs must be a vector of the same length as x and will often be a vector of ones.
xi is the initial set of values that x will start with in the search for the solution. Depending on the
problem, a good initial guess can be essential for finding a solution. xi must be a vector of the same
length as x. In some cases a vector of ones will suffice.
n is the number of vector elements in the vectors. This is almost always ELMCOUNT(z), though a
smaller number can be used if appropriate. Note that skip should be used to mark systems that are
homogeneous of degree 0, you should not decrease the value of n.
skip specifies how many elements of the vector should be skipped in solving x. For systems of
equations that are homogenous of degree 0, this should be set to 1 to skip the first element, or -1 to
skip the last element. If it is zero, no elements will be skipped. There may be situations were other
values could be used. All elements of x will be initialized using xi whether they are to be skipped in
the active computation of x or not.

tol specifies the tolerance that must be achieved in zeroing z. If this is set too small numerical
problems may prevent it from being reached. In general .001 is probably a reasonable choice.
max iter specifies the maximum number of iterations that will be taken before failure will be declared.
A value of 100 is reasonable for this. More frequently failure will result when it is not possible to get
closer to 0 within an iteration.
method determines the method that will be used to find the zero.

0 Indicates the use of a Broydn search.


1 is the same as zero except that the initial search value is reset each time. This
can sometimes help when there are convergence problems though it will, in
general, slow simulation down considerably.
Any other value will be treated the same as a 1.
Restrictions: The FIND ZERO function must appear first on the right hand side. There can be no
simultaneous loop enclosed within the loop from x to z (put another way, given x it must be possible to
compute the value of z in a simple chain).
Subscript Note: The FIND ZERO function is designed to work with a vector of values but will also
work with scalar values.

Examples
x = FIND ZERO(one,z,one,one,1,0,0.01,100,0)
z = (x-target)^2
one = 1
Solution to the above FIND ZERO usage will result in x being set equal to target.
commod : c1,c2,c3
ones[commod] = 1
price[commod] = FIND ZERO(ones[commod],excess demand[commod],
ones[commod],ones[commod],3,0,.01,100,0)
excess demand[commod] = demand[commod] - supply[commod]
supply[commod] = price[commod]
demand[commod] = 100 - price[commod]

85
Solution to the above will result in a price of 50 for each commodity.
Availability: Professional and DSS only.

FORECAST(input, average time, horizon) A trend extrapolating FORECAST


Returns a forecast of the value the input will take on at Time + Horizon. Equivalent to the equations:
FORECAST=input*(1+TRD*horizon)
TRD = ZIDZ(input-AV,average time*AV)
AV=INTEG((input-AV)/average time,ininput)
The FORECAST function provides a very simple trend extrapolation forecast of the future value of a
variable based on its past behavior. Like any trend extrapolator it performs very badly at turnarounds.
See also: TREND,SMOOTH

Units: FORECAST(units,time,time) ? units


The input units match the output units. Units for the average time and the horizon must match those of
TIME STEP.

Example
R = 10 + RAMP(1,10,60)
RD = DELAY FIXED(R,10,R)
FR = FORECAST(RD,5,10)

GAME(X) use X except when running a GAME

Returns X during normal simulation with X being any expression. When in gaming mode (interactive
simulation) the value of the right hand side is left constant until changed by the user. Gaming mode is
discussed in detail in Chapter 8.
Restrictions: GAME must directly follow the equal sign and not be followed by anything. In the
Equation Editor select Variable type Auxiliary and subtype Game .

Units: GAME (units) ? units


Units for the input and output must match.

Examples
hiring = GAME((desired workforce - workforce)/adjustment time)
Availability: Not PLE.

GAMMA LN(X)Natural Log of the GAMMA function

Returns the natural log of the GAMMA function of X. The GAMMA function is a generalization of
the factorial function that works on all positive values of X. For an integer N the factorial of N is equal

86
to the GAMMA function of N+1. The GAMMA LN function is very useful for computing
combinitorial factors.

Example
EXP(GAMMA LN(4)) is equal to 6 or 3 factorial
EXP(GAMMA LN(things to pick from+1) -
GAMMA LN(things to pick from-things picked+1) -
GAMMA LN(things picked+1)) is the number of combinations possible

Units: GAMMA LN(dmnl) -> dmnl


The input to the GAMMA LN function must be dimensionless.
Availability: Not PLE or PLE Plus.

GET 123 CONSTANTS('file','tab','cell') GET CONSTANTS from 123


Returns a number, vector or 2-dimensional array of Constant values by querying Lotus 123 for the
values. The number of values brought in is determined by the subscripts that are used in the left hand
side.
Restrictions: Must appear directly following the equal sign = (or the == sign for Unchangeable
Constants) and not be followed by anything else.
When a model is checked, GET 123 CONSTANTS queries Lotus 123 for the values. If Lotus 123 is
not running Vensim will attempt to start it. If Lotus 123 does not have the specified file open Vensim
will try to get Lotus 123 to open it. If Vensim cannot get values from Lotus 123 it reports an error.
For normal Constants the values are also queried each time a simulation is made and a warning is
given if the values are not obtainable. This query does not occur with Unchangeable Constants. If
Vensim has trouble getting values with this function you should try opening the named file in Lotus
123 first.
All of the arguments to GET 123 CONSTANTS are literals and must be enclosed in single quotes '.
'file' names a file with complete extension to be used. This can be a 123 file or any other type of file
Lotus 123 is capable of opening. If no directory is specified (best practice) Vensim will append
directory information for the current model. 'tab' names the tab that contains the Constants. This
function will not work with older versions of 123 that do not support tabs. 'cell' names the cell that
the first Constant value is on. Vensim will read additional cells to the right and down if necessary to
get all values.
See also: GET 123 DATA, GET XLS CONSTANTS, GET XLS DATA, TABBED ARRAY

Units: GET 123 CONSTANTS is not part of units checking. Specify units for
the left hand side variable.
See GET XLS DATA for examples of how to use this function.
NOTE GET 123 CONSTANTS is not available on the Macintosh.
Availability: Not PLE .

GET 123 DATA('file','tab','time row or col','cell') GET DAT from 123


Returns time series data from Lotus 123 for a Data variable or a vector of Data variables.
Restrictions: Must appear directly following the data equals sign := and not be followed by anything.

The GET 123 DATA function is invoked during simulation setup, before the active simulation begins.
If Lotus 123 is not running Vensim will attempt to start it. If Lotus 123 does not have the specified file
open Vensim will try to get Lotus 123 to open it. If Vensim cannot get values from Lotus 123 it

87
reports an error. If Vensim has trouble getting values with this function you should try opening the
named file in Lotus 123 first.
All of the arguments to GET 123 CONSTANTS are literals and must be enclosed in single quotes '.
'file' names a file with complete extension to be used. This can be a 123 file or any other type of file
Lotus 123 is capable of opening. If no directory is specified (best practice) Vensim will append
directory information for the current model. 'tab' names the tab that contains the Data. This function
will not work with older versions of 123 that do not support tabs. 'time row or col' is either the
number of the row containing Time values (Time running across) or the letter of the column containing
Time values (Time running down). Note that the spreadsheet file must contain values for Time and
these values must be Time values and not those of an alternate Time Base. 'cell' names the cell that
the first Data value is on. Vensim will read values for different times across or down depending on the
'time row or col' argument. Vensim will also read additional subscript elements in the other direction.
See also: GET 123 CONSTANTS, GET XLS CONSTANTS, GET XLS DATA.

Units: GET 123 DATA is not part of units checking. Specify units for the left
hand side variable.
See GET XLS DATA for examples of how to use this function.
NOTE GET 123 DATA is not available on the Macintosh.
Availability: Not PLE.

GET 123 LOOKUPS('file','tab','x row or col','cell') GET LOOKUPS from XLS


Returns Lookup x,y pairs from Microsoft Excel for a Lookup variable or a vector of Lookup variables.

Restrictions: Must appear directly following the left parenthesis ( that indicates the beginning of a
Lookup definition.
When a model is checked, GET 123 LOOKUPS queries 123 for the values. If 123 is not running
Vensim will attempt to start it. If 123 does not have the specified file open Vensim will try to get 123
to open it. If Ve nsim cannot get values from 123 it reports an error. The values are also queried each
time a simulation is made and a warning is given if the values are not obtainable. If Vensim has
trouble getting values with this function you should try opening the named file in 123 first.

All of the arguments to GET 123 LOOKUPS are literals and must be enclosed in single quotes '. 'file'
names a file with complete extension to be used. This can be a 123 file or any other type of file 123 is
capable of opening. If no directory is specified (best practice) Vensim will append directory
information for the current model. 'tab' names the tab that contains the Data. This function will not
work with older versions of Excel that do not support tabs. 'x row or col' is either the number of the
row containing x values (x running across) or the letter of the column containing x values (x running
down). Note that the spreadsheet file must contain values for x. 'cell' names the cell that the first y
value is on. Vensim will read successive values across or down depending on the 'x row or col'
argument. Vensim will also read additional subscript elements in the other direction.
Note that you can substitute named Excel ranges for 'x row or col' and 'cell'. To do this just create the
named ranges in Excel and use those names in place of the Letter/Number designators.
See also: GET 123 CONSTANTS, GET 123 DATA, GET XLS CONSTANTS, GET XLS DATA,
GET XLS LOOKUPS

Units: GET 123 LOOKUPS is not part of units checking. Specify units for the
left hand side variable.
Example See GET XLS LOOKUPS
NOTE GET XLS LOOKUPS is not available on the Macintosh.

88
Availability: Not PLE.

GET DATA AT TIME(datavar,time) GET the value of a DATA variable at a specific TIME

Returns the value of the data variable at the time specified, or :NA: if there is no data at that time of the
variable passed as an argument is not a Data variable.
If you pass :NA: as the argument the function will return the first Data value available and only return
:NA: if there are no values or the variable passed as an argument is not a data variable.
Note that GET DATA AT TIME is slow compared to other functions on data. For example GET
DATA AT TIME(datavar,Time+1) is the same as defining an additional data variable
tshift datavar :RAW: := TIME SHIFT(datavar,1)
and then using that tshift datavar. Defining the extra variable will give better performance.

Units: GET DATA AT TIME(units,time) ? units


Example
sales at time 20 = GET DATA AT TIME(sales data,20)
Availability: Not PLE or PLE Plus.

GET DATA BETWEEN TIMES(datavar,time,mode)GET DATA value interpolated BETWEEN TIMES


Returns the value of a data variable at a time using the specified interpolation mode or, or :NA: if the
time is before the first or after the last data point. :NA: is also returned it variable passed as an
argument is not a Data variable. If mode = 0 the value is computed by interpolating. If mode = 1 the
value returned is the later time value (same as :LOOK FORWARD:). If mode is -1 the value returned
is the earlier time value (same as :HOLD BACKWARD:).
Note that GET DATA BETWEEN TIMES is slow compared to other functions on data. For example
GET DATA BETWEEN TIM ES(datavar,Time+1,0) is the same as defining an additional data variable
tshift datavar := TIME SHIFT(datavar,1)
and then using that tshift datavar. Defining the extra variable will give better performance.

Units: GET DATA BETWEEN TIMES(units,time,dmnl) ? units


Example
sales at time 20 = GET DATA BETWEEN TIME(sales data,20,0)
Availability: Not PLE or PLE Plus.

GET DATA FIRST TIME(datavar) the FIRST TIME DATA exists

Returns the time at which the first data point occurs for the data variable datavar. If there is no data
for datavar or it is not actually a data variable then :NA: is returned.
NOTE GET DATA FIRST TIME is relatively slow and is best used inside of INITIAL equations.

Units: GET DATA FIRST TIME(units) ? time units


Example
first sales data time = INITIAL(GET DATA FIRST TIME(sales data))
Availability: Not PLE or PLE Plus.

89
GET DATA LAST TIME(datavar) the LAST TIME DATA exists
Returns the time at which the last data point occurs for the data variable datavar . If there is no data
for datavar or it is not actually a data variable then :NA: is returned.
NOTE The GET DATA … functions are relatively slow and best used inside of INITIAL equations.

Units: GET DATA LAST TIME(units) ? time units


Example
last sales data time = INITIAL(GET DATA LAST TIME(sales data))
Availability: Not PLE or PLE Plus.

GET DATA MAX(datavar,start,end) the MAX of DATA over a time range


Returns the maximum value that a Data variable takes one over a time range. If there is no data in the
time range, or the variable is not a Data variable then :NA: is returned.
NOTE The GET DATA … functions are relatively slow and best used inside of INITIAL equations.

Units: GET DATA MAX(units,time,time ) ? units


Example
Max Sales in Data = INITIAL(
GET DATA MAX(sales data,Initial Time, Final Time))
Availability: Not PLE or PLE Plus.

GET DATA MEAN(datavar,start,end) the MEAN of DATA over a time range

Returns the mean value that a Data variable takes one over a time range. If there is no data in the time
range, or the variable is not a Data variable then :NA: is returned.
NOTE The GET DATA … functions are relatively slow and best used inside of INITIAL equations.

Units: GET DATA MEAN(units,time,time) ? units


Example
Mean of Sales Data = INITIAL(
GET DATA MEAN(sales data,Initial Time, Final Time))
Availability: Not PLE or PLE Plus.

GET DATA MIN(datavar,start,end) the MIN of DATA over a time range


Returns the minimum value that a Data variable takes one over a time range. If there is no data in the
time range, or the variable is not a Data variable then :NA: is returned.
NOTE The GET DATA … functions are relatively slow and best used inside of INITIAL equations.

Units: GET DATA MIN(units,time,time) ? units


Example
Min Sales in Data = INITIAL(
GET DATA MIN(sales data,Initial Time, Final Time))
Availability: Not PLE or PLE Plus.

90
GET DATA STDV(datavar,s,e) Standard DeViation of DATA over a time range
Returns the standard deviation of a Data variable over a time range. If there are less than 2 data points
in the time range, or the variable is not a Data variable then :NA: is returned.
NOTE The GET DATA … functions are relatively slow and best used inside of INITIAL equations.

Units: GET DATA STDV(units,time,time) ? units


Example
Standard Deviation of Sales Data = INITIAL(
GET DATA STDV(sales data,Initial Time, Final Time))
Availability: Not PLE or PLE Plus.

GET DATA TOTAL POINTS(datavar) the TOTAL number of POINTS in a DATA series
Returns the total number of points for the data variable datavar. If datavar is not actually a data
variable then :NA: is returned.
NOTE GET DATA TOTAL POINTS is relatively slow and is best used inside of INITIAL equations.

Units: GET DATA TOTAL POINTS(units) ? dmnl


Example
sales data points = INITIAL(GET DATA TOTAL POINTS(sales data))
Availability: Not PLE or PLE Plus

GET VDF CONSTANTS('file','varname',attime) GET CONSTANTS from VDF

Returns a number, vector or 2-dimensional array of Constant values by querying the named vdf file.
The number of values brought in is determined by the subscripts that are used in the left hand side. If
subscripts are used on the left hand side then ‘varname’ must also be subscripted so that the total
numb er of values matches that as determined by the left hand side (normally these subscripts would be
the same). The argument attime is used when the variable in the .vdf file is not a constant to determine
which value to use. If attime is before the beginning of the times in the file the first is used, if after
then end the last is used. If file is empty then attime is returned.
Restrictions: Must appear directly following the equal sign = and not be followed by anything else.
‘filename’ and ‘varname’ must be either Literals or String variables. attime must be a number
(constants and expressions are not allowed).
When a subscripted variable name is passed in varname the subscripts are expanded in the context of
the current model. For example, if varname is pop[age,gender] then Vensim will look at the
subscripts age and gender in the model to determine what elements they have. The variable will
then be expanded (say to pop[young,male], pop[young,female], pop[old,male] and
pop[old,female]) and the .vdf file will be queried for these names. If a Subscript is not a
Subscript range in the model, it will be treated as a Subscript Element (even if it does not appear in the
model at all). The variable name itself does not need to appear in the model, nor be subscripted in any
specific manner in the model. Subscript range definitions, if any, associated with the vdf file being read
are not used.
When a model is checked, GET VDF CONSTANTS reads the values from the .vdf file returning an
error if the values are not available. The values are also read each time a simulation is made and a
warning is given if the values are not obtainable. In this case Vensim will use the values obtained
during the last model check.

91
NOTE if you make changes in setup mode or specify constant input (.cin) files these values will
override the values from the .vdf file. If Stringvars are used to specify the file or variable name to
query the model value of these will be used even if these values have been updated using a changes file
(or through a Venapp command).
See also: GET 123 CONSTANTS, GET VDF DATA, GET VDF LOOKUPS, GET XLS
CONSTANTS, TABBED ARRAY

Units: GET VDF CONSTANTS is not part of units checking. Specify units for
the left hand side variable.
Example
size : small,med,large ~~|
shape : round,square ~~|
Init Inventory[shape,size] = GET VDF CONSTANTS('base.vdf',
'Inventory[shape,size]',80) ~~|
Availability: Not PLE.

GET VDF DATA('file','varname',start,slope) GET DATA from VDF


Returns time series data from an existing model run or imported data file.

Restrictions: Must appear directly following the data equals sign := and not be followed by anything.
‘filename’ and ‘varname’ must be Literals or String variables. start and slope must be numbers, not
variables or expressions.
When a subscripted variable name is passed in varname the subscripts are expanded in the context of
the current model. For example, if varname is pop[age,gender] then Vensim will look at the
subscripts age and gender in the model to determine what elements they have. The variable will
then be expanded (say to pop[young,male], pop[young,female], pop[old,male] and
pop[old,female]) and the .vdf file will be queried for these names. If a Subscript is not a
Subscript range in the model, it will be treated as a Subscript Element (even if it does not appear in the
model at all). The variable name itself does not need to appear in the model, nor be subscripted in any
specific manner in the model. Subscript range definitions, if any, associated with the vdf file being read
are not used.
The GET VDF DATA function is invoked during simulation setup, before the active simulation
begins. It reads values from the existing .vdf file as time series Data. You can adjust the time base for
the data using the start and slope arguments according to the equation
time (in model) = start + slope * time (in vdf)
Normally slope =1 and start=0. If slope is <= 0 both slope and start are ignored.

There are no restrictions on the number of Subscript Ranges used on the left hand side, but ‘varname’
must have the same number of elements. Be very careful when using subscript ranges that do no match
exactly as no check is made on the order or families of the subscript elements.
If String variables are used the values of these as modified in any changes files, or though any Venapp
commands, will be used.
Normally, if GET VDF DATA runs into any problems, it will return an error and prevent simulation.
However, if ‘filename’ is empty then a data value of slope will be returned at time start. This is a
useful construct if you want to compare model results with a base run and have not yet mate the base
run.
See also: GET 123 DATA, GET VDF CONSTANTS, GET VDF LOOKUPS, GET XLS DATA.

Units: GET VDF DATA is not part of units checking. Specify units for the left

92
hand side variable.
Example
size : small,med,large ~~|
shape : round,square ~~|
Baserun Inventory[shape,size] := GET VDF DATA('base.vdf',
'Inventory[shape,size]',1,0) ~~|
Availability: Not PLE.

GET VDF LOOKUPS('file',varname',start,slope) GET LOOKUPS from VDF


Returns Lookup x,y pairs from a.vdf file for a Lookup variable or a subscripted set of Lookup
variables.

Restrictions: Must appear directly following the left parenthesis ( that indicates the beginning of a
Lookup definition. ‘filename’ and ‘varname’ must be Literals or String variables. start and slope
must be numbers, not variables or expressions.
When a subscripted variable name is passed in varname the subscripts are expanded in the context of
the current model. For example, if varname is pop[age,gender] then Vensim will look at the
subscripts age and gender in the model to determine what elements they have. The variable will
then be expanded (say to pop[young,male], pop[young,female], pop[old,male] and
pop[old,female]) and the .vdf file will be queried for these names. If a Subscript is not a
Subscript range in the model, it will be treated as a Subscript Element (even if it does not appear in the
model at all). The variable name itself does not need to appear in the model, nor be subscripted in any
specific manner in the model. Subscript range definitions, if any, associated with the vdf file being read
are not used.
When a model is checked, GET VDF LOOKUPS reads the values from the .vdf file returning an error
if the values are not available. The values are also read each time a simulation is made and a warning is
given if the values are not obtainable. In this case Vensim will use the values obtained during the last
model check.
NOTE if you make changes in setup mode or specify constant input (.cin) files these values will
override the values from the .vdf file. If Stringvars are used to specify the file or variable name to
query the model value of these will be used even if these values have been updated using a changes file
(or through a Venapp command).
The values in the .vdf file can actually be either Lookups or regular dynamic variables. In the latter
case the x axis will be the time axis for the simulation or data in the .vdf file. The x values are adjusted
as
x (in model) = start + slope * x (in vdf)
See also: GET 123 LOOKUPS, GET VDF CONSTANTS, GET VDF DATA, GET XLS LOOKUPS

Units: GET XLS LOOKUPS is not part of units checking. Specify units for the
left hand side variable.
Example
regular lookup((0,0),(1,1))
vdf lookup(GET VDF LOOKUPS('current.vdf','regular lookup',1,0) ~~|
subbed vdf lookup[shape](GET VDF LOOKUPS('current.vdf', 'subbed
lookup[shape]',1,0) ~~|
Availability: Not PLE.

93
GET XLS CONSTANTS('file','tab','cell') GET CONSTANTS from XLS
Returns a number, vector or 2-dimensional array of Constant values by querying Microsoft Excel for
the values. The number of values brought in is determined by the subscripts that are used in the left
hand side.
Restrictions: Must appear directly following the equal sign = (or the == sign for Unchangeable
Constants) and not be followed by anything else.
When a model is checked, GET XLS CONSTANTS queries Microsoft Excel for the values. If no
values are available from Microsoft Excel an error is reported. For normal Constants the values are
also queried each time a simulation is made and a warning is given if the values are not obtainable. For
Unchangeable Constants there is no query performed at simulation time. If Vensim has trouble getting
values with this function you should try opening the named file in Microsoft Excel first.
All of the arguments to GET XLS CONSTANTS must be Literals (enclosed in single quotes ') or
String Variables. 'file' names a file with complete extension to read from (use '?Tag' to indirectly
reference a file and resolve the reference in Model>Settings>XLS Files). This can be an Excel file or
any other type of file Microsoft Excel is capable of opening. If no directory is specified (best practice)
Vensim will append directory information for the current model. 'tab' names the tab that contains the
Constants. This function will not work with older versions of Excel that do not support tabs. 'cell'
names the cell that the first Constant value is on. Vensim will, as necessary, read additional cells to the
right (on last subscript range) and down (on the second last subscript range) to get all values. You can
force Vensim to transpose this reading by ending the ‘Cell’ name with a *.
NOTES
? If Microsoft Excel is not running Vensim will attempt to start it.
? If Microsoft Excel does not have the specified file open Vensim will try to get Microsoft Excel to
open it.
? The constants read from Excel will be overwritten if you make changes in setup mode or specify
constant input (.cin) files.
? Changes to String Variables made in .cin files (or through Venapp commands) will not be used
when determining file, tab or cell.
? You can substitute named Excel ranges for 'time row or col' and 'cell'. To do this just create the
named ranges in Excel and use those names in place of the Letter/Number designators.
? If you have defined only Unchangeable Constants Excel is not queried for simulations and
providing a .vmf file or published mo del to someone without the associated spreadsheet will not
generate any messages.
See also: GET 123 CONSTANTS GET VDF CONSTANTS, GET XLS DATA, GET XLS
LOOKUPS, TABBED ARRAY

Units: GET XLS CONSTANTS is not part of units checking. Specify units for
the left hand side variable.
Example
A B C D
1 Test for GET…
2 Cap Cost 100

3 Small Med Large

4 Material Consumption 10 20 30

5 Init Inventory Small Med Large

94
6 Round 33 19 12

7 Square 24 13 44

size : small,med,large ~~|


shape : round,square ~~|
Cap Cost = GET XLS CONSTANTS('test.xls','Sheet1','B2') ~~|
Material Consumption[size] = GET XLS CONSTANTS('test.xls',
'Sheet1','B4') ~~|
Init Inventory[shape,size] = GET XLS CONSTANTS('test.xls',
'Sheet1','B6') ~~|
Init Small Inventory[shape] = GET XLS CONSTANTS('test.xls',
'Sheet1','B6*') ~~|
NOTE GET XLS CONSTANTS is not available on the Macintosh.
Availability: Not PLE.

GET XLS DATA('file','tab','time row or col','cell') GET DATA from XLS


Returns time series data from Microsoft Excel for a Data variable or a vector of Data variables.
Restrictions: Must appear directly following the data equals sign := and not be followed by anything.

The GET XLS DATA function is invoked during simulation setup, before the active simulation begins.
If Microsoft Excel is not running Vensim will attempt to start it. If Microsoft Excel does not have the
specified file open Vensim will try to get Microsoft Excel to open it. If Vensim cannot get values from
Microsoft Excel it reports an error. If Vensim has trouble getting values with this function you should
try opening the named file in Microsoft Excel first.
All of the arguments to GET XLS DATA must be literals (enclosed in single quotes ') or String
Variables. 'file' names a file with complete extension to read from (use '?Tag' to indirectly reference a
file and resolve the reference in Model>Settings>XLS Files). This can be an Excel file or any other
type of file Microsoft Excel is capable of opening. If no directory is specified (best practice) Vensim
will append directory information for the current model. 'tab' names the tab that contains the Data.
This function will not work with older versions of Excel that do not support tabs. 'time row or col' is
either the number of the row containing Time values (Time running across) or the letter of the column
containing Time values (Time running down). Note that the spreadsheet file must contain values for
Time and these values must be Time values and not those of an alternate Time Base. 'cell' names the
cell that the first Data value is on. Vensim will read values for different times across or down
depending on the 'time row or col' argument. Vensim will also read additional subscript elements in
the other direction.
NOTES
? If Microsoft Excel is not running Vensim will attempt to start it.
? You can substitute named Excel ranges for 'time row or col' and 'cell'. To do this just create the
named ranges in Excel and use those names in place of the Letter/Number designators.
? Vensim will continue to read the Time row or column to the end of the spreadsheet, ignoring any
blank or nonnumeric cells. If you want to have it read only a specific range use a named range.
? Changes in String Variables from .cin files (or from Venapp Commands) will be used when
determining file, tab, time and cell.
See also: GET VDF DATA, GET XLS CONSTANTS, GET XLS LOOKUPS.

Units: GET XLS DATA is not part of units checking. Specify units for the left
hand side variable.

95
Example
profit := GET XLS DATA('test.xls','Sheet2','1','B2') ~~|
shape sales[shape] := GET XLS DATA('test.xls','Sheet2','1','B3') ~~|
sales[round,shape] := GET XLS DATA('test.xls','Sheet2','1','B5') ~~|
sales[square,shape] := GET XLS DATA('test.xls','Sheet2','1','B8')~~|
The contents of the spreadsheet are shown below. Note that the variable names do not need to match
and that the order of subscripts determines how the data in the spreadsheet are interpreted.
A B C D E
1 Time 0 10 80 100

2 Profit 8 9 6 12

3 Sales by Shape[round] 30 44 55 42

4 Sales by Shape[square] 22 13 77 30

5 Sales[round,small] 10 12 11 20

6 Sales[round,med] 10 12 11 15

7 Sales[round,large] 10 10 33 7

8 Sales[square,small] 5 10 30 10

9 Sales[square,med] 5 10 30 12

10 Sales[square,large] 12 24 17 8

NOTE GET XLS DATA is not available on the Macintosh.


Availability: Not PLE.

GET XLS LOOKUPS('file','tab','x row or col','cell') GET LOOKUPS from XLS


Returns Lookup x,y pairs from Microsoft Excel for a Lookup variable or a vector of Lookup variables.

Restrictions: Must appear directly following the left parenthesis ( that indicates the beginning of a
Lookup definition.
When a model is checked, GET XLS LOOKUPS queries Microsoft Excel for the values. If Microsoft
Excel is not running Vensim will attempt to start it. If Microsoft Excel does not have the specified file
open Vensim will try to get Microsoft Excel to open it. If Vensim cannot get values from Microsoft
Excel it reports an error. The values are also queried each time a simulation is made and a warning is
given if the values are not obtainable. If Vensim has trouble getting values with this function you
should try opening the named file in Microsoft Excel first.
All of the arguments to GET XLS LOOKUPS must be either literals (enclosed in single quotes ') or
String Variables. 'file' names a file with complete extension to read from (use '?Tag' to indirectly
reference a file and resolve the reference in Model>Settings>XLS Files). This can be an Excel file or
any other type of file Microsoft Excel is capable of opening. If no directory is specified (best practice)
Vensim will append directory information for the current model. 'tab' names the tab that contains the
Data. This function will not work with older versions of Excel that do not support tabs. 'x row or
col' is either the number of the row containing x values (x running across) or the letter of the column
containing x values (x running down). Note that the spreadsheet file must contain values for x. 'cell'
names the cell that the first y value is on. Vensim will read successive values across or down
depending on the 'x row or col' argument. Vensim will also read additional subscript elements in the
other direction.

96
Note that you can substitute named Excel ranges for 'x row or col' and 'cell'. To do this just create the
named ranges in Excel and use those names in place of the Letter/Number designators.
NOTE Vensim will continue to read the x row or column to the end of the spreadsheet, ignoring any
blank or nonnumeric cells. If you want to have it read only a specific range use a named range.
See also: GET VDF Lookups, GET 123 LOOKUPS, GET XLS CONSTANTS, GET XLS DATA.

Units: GET XLS LOOKUPS is not part of units checking. Specify units for the
left hand side variable.
Example
regular lookup((0,0),(1,1))
excel lookup(GET XLS LOOKUPS('test.xls','Sheet2','1','B2')) ~~|
subbed excel lookup[shape](GET XLS LOOKUPS('test.xls', 'Sheet2','1'
, 'B2')) ~~|

The contents of the spreadsheet are shown below. Note that the variable names do not need to match
and that the order of subscripts determines how the data in the spreadsheet are interpreted.
A B C D E
1X 0 10 80 100

2 Lookup 1 8 9 6 12

3 Lookup2[round] 30 44 55 42

4 Lookup2[square] 22 13 77 30

NOTE GET XLS LOOKUPS is not available on the Macintosh.


Availability: Not PLE.

IF THEN ELSE(cond, tval, fval) Traditional If-Then Statement


Returns first value (tval) if condition (cond) is true; second value (fval) if condition is false.
cond must be a Boolean expression or an expression or variable that can be interpreted as Boolean.
Only the value returned is evaluated, so the other value could be an expression that would lead to an
error.

Units: IF THEN ELSE( dimensionless,units, units) ? units


Note that expressions such as (a>b) require that a and b have the same dimension and the resulting
expression is considered to be dimensionless

Examples
IF THEN ELSE( 1.0<2.0, 3.0, 4.0 ) is equal to 3.0.
IF THEN ELSE( 1.0>2.0, 3.0, 4.0 ) is equal to 4.0.
IF THEN ELSE( X = 0.0, 1.0, 1.0 / X ) is equal to 1/X unless X is
0.0 when it is equal to 1.0. If X is 0.0, Vensim will not try to
compute 1/X and there will be no error.

INITIAL(A)INITIAL value of variable

Returns the value A at initialization and does not change it during a simulation. INITIAL is used to
record and hold or "remember" a variable's starting value.

97
Restrictions: Must appear first on the right of the = sign. It defines a variable as being an Initial
variable.
See also: REINITIAL, SAMPLE IF TRUE

Units: Initial (unit) --> unit


Example
x init = INITIAL (x) - x init is set equal to the first value of x.

INTEG (rate, initial value) Numerical INTEGration

Returns the integral of the rate. The rate is numerically integrated. The initial value is the value of the
variable on the left-hand side of the equation at the start of the simulation.
Restrictions: INTEG must directly follow the equal sign. It signals Vensim that the variable on the
left-hand side of the equation is a Level or State variable. In the Equation Editor selecting Variable
type Level, subtype Normal (the default for variables with boxes around them) will automatically
select the INTEG function.

Units: INTEG ( unit / time, unit ) --> unit


The units of the integral must be the same as the units of the initial condition. The rate must have the
same units, divided by the units of TIME STEP.

Examples
Valid
L = INTEG( R * SUM( A[ S1! ]), 0.0 )
L = INTEG( MAX( A, B ), C )

Invalid
L = A + INTEG( R, 0.0 )
L = INTEG( B, 0.0 ) + 1
L = 2.0 * INTEG( R, 0.0 ) + 1.0
INTEG must follow the equal sign, and it cannot be part of a more complex mathematical expression.
These formulations are made valid by defining an auxiliary variable to perform the indicated
operations, e.g.
L = INTEG( R, 0.0 )
aux = A + L

INTEGER(x)INTEGER part of x
Returns the largest integer smaller than or equal to X. Same as QUANTUM(X,1).
See also: QUANTUM

Units: INTEGER(units) -> units


Output and input units must match.

Example
INTEGER(5.4) is 5.0

INTERNAL RATE OF RETURN(stream,fisc,init,it) Solve for IROR

Returns the internal rate of return for stream using the fiscal averaging period fisc. You can also
specify an initial investment or receipt init that was made at time i t. The value returned represents the

98
factional return per fiscal period. If the internal rate of return can’t be solved for either because it does
not exist, or is too big (or to large a negative number) the function will return :NA:. There is no
attempt made to detect multiple solutions. The number returned is the fractional interest rate per fiscal
period and will always be in the range of -1 to +1. A negative value indicates that future payments and
receipts are given more weight than current ones.
The Internal Rate of Return is the interest rate that makes the net present value of a cash flow stream 0.
This number is well defined for any stream that has a sequence of negative values followed by a
sequence of positive values or vice versa. For streams that intermix positive and negative values there
may be one, many or no interest rates giving a 0 net present value. For streams that are always 0, only
positive, or only negative, the internal rate of return is not defined.
The use of a fiscal period allows the internal rate of return to be computed on a different time base than
the model is on. For example with a monthly model you might use a fiscal period of 12 in order to
find the annual internal rate of return as measured annually. This change both scales the result, and
also aggregates the flows within each fiscal period treating them as if they had all occurred at the end
of the fiscal period.
Restrictions: INTERNAL RATE OR RETURN must directly follow the equal sign and there can be
nothing else on the right hand side of the equation.
Note that stream is the net payment stream. Normally negative values indicate that more money is
being spent than income received (investments are being made) and positive values indicate that
income exceeds current expenses. Setting an initial value with init is useful for cases where the
investment was made as a lump sum, possibly in the past, though typically it would just be Time (or
INITIAL TIME). It is also possible to have it represent a future period as would occur with the
repayment of a loan.
If the fiscal period fisc is less than TIME STEP then the initial value of TIME STEP is used as the
fiscal period. The fiscal period should be a multiple of TIME STEP. If this is not true, or if TIME
STEP is not a constant, the computations may end up being made on irregularly quantized flows with
some fiscal periods averaging over a large number of measured flows than others. The results will still
be useable but should be reviewed carefully.
The values for fisc, init and it are all used to initialize the function. Changes to these values at later
times during the simulation will not have any impact on the behavior of the function. This is why it is
fine to use Time for it.
Computation discounts the stream as if all payments in the fiscal period were made in a lump sum at
the end of the period. This assumption is only important when init is nonzero since otherwise it is only
the difference in discounting that matters and this is the same whether payments are assumed at the
beginning, middle or end of the period. If you have an initial value and you want to discount at the
middle of the period you should add .5 to the initial time. If you want to discount at the beginning of
the period you should add 1 to the initial time.
Because the INTERNAL RATE OF RETURN function can return :NA: (and usually will at the
beginning of a simulation) it is best to check its value if you wish to use it in another variable.

Units: INTERNAL RATE OF RETURN(units/Time,Time/Ftime,units,Time) ?


1/FTime
Where FTime is a fiscal time units. For example you might use Month_per_year
(=12 Month/Year) as the fisc argument to get annual results.
Example
INTERNAL RATE OF RETURN(.05,Unit Year,1.0,Time)starts negative then
asymptotes to .05

99
NOTE The INTERNAL RATE OF RETURN function stores all values of the stream at all times. For
very long runs this can become quite a large number of values. By selecting a larger fiscal period (for
example annually instead of monthly) you can reduce the memory requirements and increase
simulations speed.
NOTE The INTERNAL RATE OF RETURN creates a variable that acts as an auxiliary, but also has
some built in dynamic behavior. The value is held constant within a TIME STEP when using the
Runge Kutta integration techniques.
Availability: Not Vensim PLE or PLE Plus.

INVERT MATRIX(mat,n) INVERT a MATRIX


Returns the inverse of the nxn matrix mat.
This returns the inverse of a two dimensional array.

Restrictions: INVERT MATRIX must appear first on the right hand side of an equation. Both mat
and the left hand side variables must be Subscripted variables with the last two Subscripts each having
n elements.

Units: INVERT MATRIX(units,dmnl) ? units


Example
sub : s1,s2
ssub <-> sub
a[s1,sub] = 1,2
a[s2,sub] = 3,4
ainverse[sub,ssub] = INVERT MATRIX(a[sub,ssub],2)
Would result in an inverse of:
-2, 1
1.5, -.5
Availability: Vensim Professional and DSS only.

LN(X) Natural Logarithm of [variable]


Returns the natural logarithm of X.
Same as LOG( X, 2.718282 ).
See also: LOG, EXP, POWER.

Units: LN(dimensionless) ? dimensionless (the argument must be


dimensionless)
Examples
LN( 2.718282 ) is equal to 1.0.
LN( -5.0 ) causes an error (LN of a number <= 0 is not defined).
LN( EXP(2.0)) is equal to 2.0 (by definition).

LOG( X, base)LOGarithm [X]

Returns the logarithm of X for a given base.

See also: LN, EXP, and POWER.

100
Units: LOG(dimensionless, dimensionless) ? dimensionless (all terms must
be dimensionless)
Examples
LOG( 4,2 ) is equal to 2.0, LOG( 4,16 ) is equal to 0.5
LOG( 0,5 ) is an ERROR (LOG of a number <= 0 is not defined).
LOG( POWER( A, 5 ), A ) is equal to 5.0 (by definition).

LOOKUP AREA(lookup,start,end) AREA under a LOOKUP table

Returns the area under a Lookup table between start and end. This is useful for normalizing lookups in
problems such as determining the intensity of effort in a project given the fraction of work that has
been completed.

Units: LOOKUP AREA(units1,units2,units2) ? units1 * units2


Start and end must have the same units and the units of the Lookup times the units of the input are
returned.

Example
LOOK((0,1),(1,1),(2,2))
LOOKUP AREA(LOOK,0,1) is equal to 1.0
LOOKUP AREA(LOOK,2,4) is equal to 4.0
LOOKUP AREA(LOOK,.5,2.5) is equal to 1.25
Availability: Not PLE or PLE Plus.

LOOKUP BACKWARD(lookup,x) LOOKUP looking BACKWARD between vals

Allows you to control the interpolation mode of a lookup table so that the previous y value is held
between x values instead of interpolated.

Units: LOOKUP BACKWARD(units1,dimensionless) ? units1


Just as for normal Lookup usage the x argument is expected to be dimensionless. If not, a warning is
issued, but not an error.

Example
LOOK((0,1),(1,1),(2,2))
LOOKUP BACKWARD(LOOK,-1) is equal to 1.0
LOOKUP BACKWARD(LOOK,1.5) is equal to 1.0
LOOKUP BACKWARD(LOOK,2.5) is equal to 2.0
Availability: Not PLE or PLE Plus.

LOOKUP EXTRAPOLATE(lookup,x) LOOKUP and EXTRAPOLATE beyond vals


Allows you to specify extrapolation of the extreme Lookup pairs when the input is out of range of the
Lookup. This also suppresses any out of range warning messages that might be generated.

Units: LOOKUP EXTRAPOLATE(units,dimensionless) ? units


Just as for normal Lookup usage the x argument is expected to be dimensionless. If not, a warning is
issued, but not an error.

Example
LOOK((0,1),(1,1),(2,2))

101
LOOKUP EXTRAPOLATE(LOOK,-1) is equal to 1.0
LOOKUP EXTRAPOLATE(LOOK,1.5) is equal to 1.5
LOOKUP EXTRAPOLATE(LOOK,2.5) is equal to 2.5
Availability: Not PLE or PLE Plus.

LOOKUP FORWARD(lookup,x) LOOKUP looking FORWARD between vals


Allows you to control the interpolation mode of a lookup table so that the next y value is used between
x values instead of interpolated.

Units: LOOKUP FORWARD(units,dimensionless) ? units


Just as for normal Lookup usage the x argument is expected to be dimensionless. If not, a warning is
issued, but not an error.

Example
LOOK((0,1),(1,1),(2,2))
LOOKUP FORWARD(LOOK,-1) is equal to 1.0
LOOKUP FORWARD(LOOK,1.5) is equal to 2.0
LOOKUP FORWARD(LOOK,2.5) is equal to 2.0
Availability: Not PLE or PLE Plus.

LOOKUP INVERT(lookup,y) INVERT the LOOKUP and return input

Finds the input that, when used in the Lookup lookup would return y. That is, if x = LOOKUP
INVERT (lookup,y) then lookup(x) would return y.
LOOKUP INVERT will find the first value that satisfies this inverse relationship. If the lookup is not
monotone (always increasing or always decreasing) there may actually be more than one value that
would work as an inverse. Vensim will return the smallest such value. If y is outside the range of
lookup (bigger than the biggest y value or smaller than the smallest y value in lookup) the function
will return :NA:. In general it is wise to test to see if this has happened.

Units: LOOKUP INVERT(units1,units1) ? dmnl


Example
LOOK((0,0),(1,1),(3,2))
LOOKUP INVERT(LOOK,-1) is equal to :NA:
LOOKUP INVERT(LOOK,0.5) is equal to 0.5
LOOKUP INVERT(LOOK,1.5) is equal to 2.0
Availability: Not PLE or PLE Plus.

LOOKUP SLOPE(lookup,x,m) Find the SLOPE in LOOKUP

Finds the slope at x in the lookup lookup according to the mode m. Between points on a Lookup the
slope is just the change in y divided by the change in x from one point to the next. If x is the same as a
point in lookup then the average of the slope before and after x is returned, unless there is more than
one point with that x value in which case :NA: is returned.

If the value for x is outside the domain of lookup (bigger than the biggest x point or smaller than the
smallest x point) what is returned depends on m, If m is 0 then 0 is returned, this is analogous to a
normal lookup. If m is 1 then the slope of the closes segment is used (this is analogous to LOOKUP
EXTRAPOLATE). If m is -1 then :NA: is returned.

Units: LOOKUP SLOPE(units,dmnl,dmnl) ? units

102
Example
LOOK((0,1),(1,1),(2,3))
LOOKUP SLOPE(LOOK,-1,-1) is equal to :NA:
LOOKUP SLOPE(LOOK,-1,0) is equal to 0
LOOKUP SLOPE(LOOK,-1,1) is equal to 1
LOOKUP SLOPE(LOOK,1,0) is equal to .75
LOOKUP SLOPE(LOOK,0.5,0) is equal to 1
LOOKUP SLOPE(LOOK,1.5,0) is equal to .5
Availability: Not PLE or PLE Plus

MARKETP† (request[FIRST],priority[FIRST],size,width,supply) MARKET Priority


The MARKETP function is used in a two step process with the ALLOC P function. You can get the
same effect using the ALLOCATE BY PRIORITY function and this is recommended.

MARKETP returns a priority to pass to ALLOC P so that total allocations of a scarce resource will
exactly match the supply of this resource. More detailed discussion on this and ALLOC P are
contained in Appendix E.
For a discussion of the arguments to MARKETP see the ALLOCATION BY PRIORITY function.
The same arguments are passed, except that MARKETP requires that Subscript Elements instead of
Subscript Ranges be specified for request and priority. Normally the first Subscript Element in the
Subscript range is specified.

Units: MARKETP(units, dimensionless, dimensionless, dimensionless, units) ->


units
Example
Using the example for ALLOCATE BY PRIORITY we would replace that one equation with the
following two equations:
mp = marketp( demand[US],priority[US],ELMCOUNT(country),
WIDTH, SUPPLY )
~ dimensionless
~ market priority |
delivered[counry] = alloc p( demand[country],
priority[country],WIDTH, mp )
~ tons / month
~ amount of supply delivered to a specific country |
Availability: Only Professional and DSS.

MAX(A,B)MAXimum of Two Alternatives


Returns the larger of A and B.
Same as IF THEN ELSE(A > B, A, B).

See also: MIN.

Units: MAX(unit, unit) --> unit (all arguments must have the same units)
Examples
MAX(1,2) is equal to 2.0.

103
MAX(1,1) is equal to 1.0.

MESSAGE('msg',display) Display a MESSAGE


Returns 0 if display is less than or equal to 0, 1 otherwise.
'msg' is the message to be displayed. It must be either a literal surrounded by single quotes ' or a
String variable.
The MESSAGE function is used to pass a message to the user in response to some condition in the
model. It can, for example, be used to put up a dialog informing the user that a certain condition has
been met. The way in which the message is displayed depends on the value of the display parameter.
If display is equal to 1 the message will go to the scrolling list of warnings. If it is 2 a message box
will come up with a informational prompt, 3 with a warning prompt and 4 with a stop prompt.
Because the MESSAGE function is most useful for putting up a single message it is typically used in
conjunction with the SAMPLE IF TRUE function to be sure that the message only appears a single
time. The example below demonstrates how to do this. The MESSAGE function is designed to work
with any integration technique. If you are using a Runge-Kutta integration technique it will not put up
a message or return a non-zero value within an integration step.

Example
msg = SAMPLE IF TRUE(:NOT: msg,IF THEN ELSE(:NOT: msg :AND:
project is started > 0,MESSAGE('Project Started',5),0),0)
This will put up a message the first time the variable project is started takes on a non-zero
value.
Availability: Not PLE or PLE Plus.

MIN(A,B)MINimum of Two Alternatives


Returns the smaller of A and B.
Same as IF THEN ELSE(A < B, A, B).

See also: MAX.

Units: MIN(unit, unit) ? unit (all arguments must have the same units).

MODULO(A,B)MODULO of A relative to B
Returns the remainder when A is divided by B.
Same as A-QUANTUM(A,B).
See also: QUANTUM, INTEGER

Units: MODULO(unit, unit) ? unit (all arguments must have the same units)
Examples
MODULO(9,5) is equal to 4.0.
MODULO(76.5,70) is equal to 6.5.
MODULO(8.3,7.3) is equal to 1.0

NET PRESENT VALUE(stream,dr,fperiod,fstart,foffset) Net Present Value


Returns the net present value of stream computed using the discount rate dr. Unlike the NPV and
NPVE functions the NET PRESENT VALUE actually accumulates things over a fiscal period fperiod
and allows you to specify where in that fiscal period to do the discounting by setting foffset to a

104
number between 0 and 1. You can also specify what time the value should be reported with respect to
bye setting fstart to something different from Time.
Restrictions: NET PRESENT VALUE must directly follow the equal sign and there can be nothing
else on the right hand side of the equation.
The NET PRESENT VALUE function is most useful for working with models that are written with
time units that are different from those for fiscal reporting. For example, suppose you have a model
with time unites of Week then you would use
Npv proj1 = NET PRESENT VALUE(proj1 stream,dr,
Week Per Year,Time,1)
dr = .08 ~ 1/Year
Week Per Year = 52 ~ Week/Year
The important thing to note is that the discount rate is in units 1/Year – not 1/Week. It is helpful to use
a model constant such as Week Per Year rather than just a number to help support units checking.

If the fiscal period fperiod is less than TIME STEP then the initial value of TIME STEP is used as the
fiscal period. The fiscal period should be a multiple of TIME STEP. If this is not true, or if TIME
STEP is not a constant, the computations may end up being made on irregularly quantized flows with
some fiscal periods averaging over a large number of measured flows than others. The results will still
be useable but should be reviewed carefully.
The values for fperiod, fstart and foffset are all used to initialize the function. Changes to these
values at later times during the simulation will not have any impact on the behavior of the function.
This is why it is fine to use Time for fstart.
All values are discounted as if they had occurred at the point in the fiscal period specified by foffset.
Use 1.0 to discount at the end of the period (the most common usage), .5 for the middle and 0 for the
beginning.

Units: NET PRESENT VALUE


(units/time,1/Ftime,time/Ftime,time,dimensionless) ? units
Where Ftime is a fiscal time units. For example you might use Month_per_year (=12
Month/Year) as the fperiod argument to get annual results. In this case the discount
rate would have units 1/Year. If fperiod is dimensionless then the discount rate is in
the units of time the model is in.
Example
NET PRESENT VALUE(1,.1,1,Time,1.0) asymptotes toward 10.
NOTE The NET PRESENT VALUE function creates a variable that acts as an auxiliary, but also has
some built in dynamic behavior. The return value is held constant within a TIME STEP when using
the Runge Kutta integration techniques.
Availability: Not Vensim PLE or PLE Plus.

Examples
NPV(cash flow,discount rate,0,1) returns the net present value
relative to the initial time for the cash flow to Time.
NPV(cash flow,discount rate,0,exp(discount rate*(Time-INITIAL TIME))
returns the net present value at Time for the cash flow to Time.
Note that NPV does not discount the current period value of the stream. If you are used to using NPV
as computed by Excel you will want to use NPVE insead.

105
NPV(stream,discount rate,init val,factor) Net Present Value
Returns the net present value of stream computed using discount rate. The initial value is
determined by init val (usually 0) and the value is reported after multiplying by factor (usually
1). Equivalent to the equations:
MYNPV = (Npv Accum + TIME STEP*stream*df) * factor
Npv Accum = INTEG(stream*df,init val)
df = INTEG(-df*discount rate,1)

Units: NPV(units,1/time,units*time,dimensionless) ? units*time


Examples
NPV(cash flow,discount rate,0,1) returns the net present value
relative to the initial time for the cash flow to Time.
NPV(cash flow,discount rate,0,exp(discount rate*(Time-INITIAL TIME))
returns the net present value at Time for the cash flow to Time.
Note that NPV does not discount the current period value of the stream. If you are used to using NPV
as computed by Excel you will want to use NPVE insead.

NPVE(stream,discount rate,init val,factor) Net Present Value End of period


Returns the net present value of stream computed using discount rate. The computation done
assumes that the stream is valued at the end of the period and that the discount rate is intended as a
discrete period rate. This is the same set of assumptions that Excel uses and can be helpful if you are
trying to get some basis for comparison. Equivalent to the equations:
MYNPVE = (Npv Accum + TIME STEP*stream*df) * factor
Npv Accum = INTEG(stream*df,init val)
df = INTEG(-df*discount rate/(1+discount rate*TIME STEP),
1/(1+discount rate*TIME STEP))

Units: NPVE(units,1/time,units*time,dimensionless) ? units*time


Examples
NPVE(cash flow,discount rate,0,1) returns the net present value
relative to the initial time for the cash flow to Time.
NPV(cash flow,discount rate,0,(1+discount rate*TIME STEP)^
(Time-INITIAL TIME)) returns the net present value at Time for
the cash flow to Time.
The difference between NPV and NPVE is quite small. For models that do not have TIME STEP=1 it
is best to stick with NPV.

POWER(BASE, X) Value Raised to a POWER

Returns BASE to the power of X. Same as BASE^X

The power function and the exponentiation operator both test the exponent to see if it is an integer. If
it is an integer, it computes the result exactly. If the exponent is not an integer, the power function is
equivalent to EXP(X*LN(BASE)).
See also: LN, EXP, and LOG.

Units: POWER(dimensionless,dimensionless) --> dimensionless (all arguments


must be dimensionless).

106
If the power is .5, 1, 2, 3 or 4 the units are taken to the power (if possible). Any other powers require
dimensionless units.

Examples
POWER(1,100) is equal to 1.0.
POWER(-2,2) is equal to 4.0.
POWER(2,3) is equal to 8.0.
POWER(A,LOG(X,A)) is equal to X (by definition).
Availability: Not PLE or PLE Plus – use ^ instead.

PROD(x[i!])† PRODuct of Subscript Range


Returns the product of an array over the Subscript Range(s) marked with the exclamation ! mark(s).

See also: SUM, VECTOR SELCT, VMIN and VMAX.

Units: PROD(dimensionless) ? dimensionless (the argument mus t be


dimensionless)
Examples
PROD (x[i!]) is equal to x[one] * x[two] *...* x[n]
PROD ( x[i,j!] * A[j!] ) is equal to
( x[i,one] * A[one] ) *
( x[i,two] * A[two] ) *
. . . *
( x[i,n]*A[n] )
PROD (x[i!,j!] is equal to
x[one,one] * x[one,two] *...* x[1,m] *
x[two,one] * x[two,two] *...* x[two,m] *
. . .
x[n,one] * x[n,two] *...* x[n,m]
PROD (x[i!,i!] is equal to
x[one,one] *
x[two,two] *
...*
x[n,n]
Availability: Only Professional and DSS.

PULSE(start,width) PULSE

Returns 1.0, starting at time start, and lasting for interval width; 0.0 is returned at all other
times.
Same as:
IF THEN ELSE (time plus > start
:AND: time plus < (start + width)),1.0,0.0 )
time plus = Time + ( TIME STEP / 2.0 )
With PULSE, Vensim Creates time plus internally to avoid rounding errors in comparing Time
with start+width.

NOTE The value returned by PULSE does not change except at TIME STEP intervals regardless of
the integration technique used.

107
Units: PULSE(time, time) ? dimensionless (start and width have the same
units as Time, the result of PULSE is dimensionless)
Example
task active = PULSE( task start, task duration )

PULSE TRAIN(start,width,tbetween,end) PULSE TRAIN

Returns 1.0, starting at time start, and lasting for interval width and then repeats this pattern every
tbetween time; 0.0 is returned at all other times. If the value of tbetween is smaller than width then 1
will be returned between start and end. If width is less than or equal to TIME STEP the pulses will
only last one TIME STEP.
The value returned by PULSE TRAIN depends only on te arguments passed to it. Normally, this
function is called with Constants. However, you can call it with dynamic variables or expressions in
which case the actual output pattern may not be regular.
With PULSE, Vensim Creates time plus internally to avoid rounding errors in comparing Time
with start+width.

NOTE The value returned by PULSE TRAIN does not change except at TIME STEP intervals
regardless of the integration technique used.

Units: PULSE(time, time) ? dimensionless (start and width have the same
units as Time, the result of PULSE is dimensionless)
Example
is daytime = PULSE TRAIN(8,12,24,FINAL TIME)

QUANTUM(A,B) QUANTize A by B

Returns the number smaller than or equal to A that is an integer multiple of B (B * integer
part of(A/B)). A common use of QUANTUM is to remove the non-integer part of a value (e.g.,
QUANTUM(3.456,1.0) is equal to 3.0). If B is less than or equal to zero, then A is returned.

Units: QUANTUM(unit,unit) ? unit (both arguments have the same units)


Examples
QUANTUM(1.9,1.0) is equal to 1.0.
QUANTUM(0.9,1.0) is equal to 0.0.
QUANTUM(-0.9,1.0) is equal to 0.0 (note behavior around 0.0).
QUANTUM(-1.9,1.0) = -1.0.
QUANTUM(A,B) is equal to -QUANTUM(-A,B) (the general rule).
QUANTUM(112.3,10.0) is equal to 110.0.
QUANTUM(50,12) is equal to 48.0.
QUANTUM(423, 63) is equal to 378 (378 = 6 * 63).
QUANTUM(X,0) is equal to X.

QUEUE AGE AVERAGE(queue,quant) AVERAGE AGE in the QUEUE

Returns the average age of the oldest quant elements in queue. This is useful for tracking
performance. If quant is less than or equal to zero, or bigger than the total amount in the queue the
average is taken over all elements in the queue.

108
Restrictions: The argument must be the name of a variable defined using QUEUE FIFO or QUEUE
FIFO ATTRIB. If you use any other variable as an argument QUEUE AGE AVERAGE will return
:NA:.
NOTE For attribute queues this function assumes that TIME STEP is constant and will return an
incorrect number if this is not the case.

Units: QUEUE AGE AVERAGE(queue,queue) ? time (returns the same


units as Time)
Example
Waiting= QUEUE FIFO(Arriving,Servicing,Init Profile,100,20)
Overtime Mult= IF THEN ELSE(QUEUE AGE AVERAGE(Waiting) > 25,1.25,1)
In this example a 25% overtime would be applied any time the average waiting time exceeded 25.
Availability: Not PLE or PLE Plus.

QUEUE AGE IN RANGE(queue,minage,maxage) Number in QUEUE with AGE IN RANGE

Returns the number or elements in a queue at least as old as minage and not older than maxage. You
can use :NA: in place of minage or maxage to return the number of elements no older than maxage or
no younger than minage respectively.
NOTE To prevent numerical surprises you might want to increase the range somewhat by, for
example, using a minimum of 4.95 instead of 5.0.
NOTE For attribute queues this function assumes that TIME STEP is constant and will return an
incorrect number if this is not the case.
Restrictions: The first argument must be the name of a variable defined using QUEUE FIFO or
QUEUE FIFO ATTRIB. If you use any other variable as an argument QUEUE AGE IN RANGE will
return :NA:.

Units: QUEUE AGE IN RANGE (queue units) ? queue units (returns the
same units as the queue)
Example
Waiting= QUEUE FIFO(Arriving,Servicing,Init Profile,100,20)
Overtime Mult= IF THEN ELSE(
QUEUE AGE IN RANGE(Waiting,19.95,:NA:) > 50,1.25,1)
In this example a 25% overtime would be applied any time that more than 50 people have been waiting
for 20 minutes or more.
Availability: Not PLE or PLE Plus.

QUEUE AGE OLDEST(queue) OLDEST AGE in the QUEUE


Returns the oldest age of elements in queue. This is useful for tracking performance.

NOTE For attribute queues this function assumes that TIME STEP is constant and will return an
incorrect number if this is not the case.
Restrictions: The argument must be the name of a variable defined using QUEUE FIFO or QUEUE
FIFO ATTRIB. If you use any other variable as an argument QUEUE AGE OLDEST will return
:NA:.

Units: QUEUE AGE OLDEST(queue units) ? time (returns the same units

109
as Time)
Example
Waiting= QUEUE FIFO(Arriving,Servicing,Init Profile,100,20)
Overtime Mult= IF THEN ELSE(QUEUE AGE OLDEST(Waiting) > 25,1.25,1)
In this example a 25% overtime would be applied any time the longest waiting time exceeded 25.
Availability: Not PLE or PLE Plus.

QUEUE ATTRIB AVERAGE(queue,quant) AVERAGE ATTRIBute in the QUEUE


Returns the average attributes of oldest quant elements in queue. If quant is less than or equal to 0,
or if quant is bigger than the total number of elements in the queue the average over all elements is
returned.
Restrictions: The first argument must be the name of a variable defined using QUEUE FIFO
ATTRIB. If you use any other variable as an argument QUEUE ATTRIB AVERAGE will return
:NA:.

Units: QUEUE ATTRIB AVERAGE(queue,queue) ? attrib (returns the


same units as attribute of the queue)
Example - see QUEUE FIFO ATTRIB
Availability: Not PLE or PLE Plus.

QUEUE ATTRIB IN RANGE(queue,min,max) Quantity in QUEUE with ATTRIBute IN RANGE


Returns the amount in the queue with attribute between min and max.

Restrictions: The argument must be the name of a variable defined using QUEUE FIFO ATTRIB. If
you use any other variable as an argument QUEUE ATTRIB AVERAGE will return :NA:.

Units: QUEUE ATTRIB IN RANGE(queue,attrib,attrib) ? queue (returns


the same units as queue)
Example - see QUEUE FIFO ATTRIB
Availability: Not PLE or PLE Plus.

QUEUE ATTRIB MAX(queue) MAXimum ATTRIBute in the QUEUE


Returns the maximum attribute value for elements in queue.

Restrictions: The argument must be the name of a variable defined using QUEUE FIFO ATTRIB. If
you use any other variable as an argument QUEUE ATTRIB AVERAGE will return :NA:.

Units: QUEUE ATTRIB MAX(queue units) ? attrib (returns the same units
as attribute of the queue)
Example - see QUEUE FIFO ATTRIB
Availability: Not PLE or PLE Plus.

QUEUE ATTRIB MIN(queue) MINimum ATTRIBute in the QUEUE


Returns the minimum attribute value for elements in queue.

110
Restrictions: The argument must be the name of a variable defined using QUEUE FIFO ATTRIB. If
you use any other variable as an argument QUEUE ATTRIB AVERAGE will return :NA:.

Units: QUEUE ATTRIB MIN(queue units) ? attrib (returns the same units
as attribute of the queue)
Example - see QUEUE FIFO ATTRIB
Availability: Not PLE or PLE Plus.

QUEUE ATTRIB QUANTITY(queue,quant) MINimum ATTRIBute in the QUEUE


Returns the oldest elements in queue such that the sum of their total attributes add up to quant. For
example, suppose you have a queue of orders (Order) with an attribute of order size (Item/Order). You
would pass this function the processing capacity (Item/Day) times TIME STEP (Day) to determine
how many orders could be processed today.
Restrictions: The first argument must be the name of a variable defined using QUEUE FIFO
ATTRIB. If you use any other variable as an argument QUEUE ATTRIB QUANTITY will return
:NA:.

Units: QUEUE ATTRIB QUANTITY(queue units,attrib units*queue units) -


-> queue units
Example
in process = QUEUE FIFO ATTRIB(orders,completions,order size,0,
flat,flat,100,1,10)
flat ((0,1),(1,1))
completions = QUEUE ATTRIB QUANTITY(in process,capacity * TIME STEP)
/ TIME STEP
Here flat is simply a flat Lookup so that the age distribution is even and the attribute distribution is
constant at 1.
When necessary, this function will allocate part of the inflow from a later time to meet the quantity. If
there is not enough in the queue to meet the target quant then the total amount in the queue will be
returned.
Availability: Not PLE or PLE Plus

QUEUE FIFO(inflow,outflow,profile,initial,age range) First In First Out QUEUE


Defines a variable to be a Level with the specified inflow, outflow and initial value. At the initial
time to content of the queue (initial) is distributed over age TIME STEP to age range + TIME STEP
with a profile given by the Lookup function profile. profile is effectively a probability distribution
function that is automatically renormalized to have an x axis running from 0 to age range and an area
of 1. All of the y values in the Lookup should be greater than or equal to 0.
A queue is the same as a Level defined using an INTEG equation except that you can use the functions
QUEUE AGE AVERAGE, QUEUE AGE IN RANGE and QUEUE AGE OLDEST to get information
about what is in the queue. Also, unlike an ordinary Level the value of a queue will never change
within a time step so that using Runge-Kutta integration will give different results if queues are used
instead of ordinary Levels.
Restrictions: QUEUE FIFO must appear directly after the = sign. To make sense both inflow and
outflow should be positive and outflow should be controlled so that the queue never goes negative.
Behavioral Notes: Queues are slower to compute and require more memory than ordinary levels and
thus should only be used when you need to apply a QUEUE... function. If inflow is negative it is

111
treated as a positive outflow. Similarly, if outflow is negative it is treated as a positive inflow. If a
queue goes negative it is treated as having entries only from the previous time step (both the average
and oldest age will be equal to TIME STEP).
Note that because a queue is like a level, the value depends on the inflow and outflow from previous
times, not the current inflow and outflow. This means that if you want to allow the current period's
inflow to be used as part of the current period's outflow you need to add it in. For example:
max outflow = queue/TIME STEP + inflow
For continuous models this is usually a minor point. However, for discrete time (difference equation)
models this can be significant.

Example
Waiting= QUEUE FIFO(Arriving,Servicing,Init Profile,100,20)
is the same as
Waiting= INTEG(Arriving-Servicing,100)
Availability: Not PLE or PLE Plus

QUEUE FIFO ATTRIB(in,out,inatt,attchg,profile,aprofile,init,initatt,age range)First In First Out QUEUE with ATTR


QUEUE FIFO ATTRIB is like QUEUE FIFO except that it provides a mechanism for tracking
attributes associtated with a Level that are changing over time. For example suppose you are modeling
order processing and want a simple way to keep track of the complexity of pending orders. You could
input the order complexity as the attribute and then use the QUEUE ATTRIB ... functions to get
information. See QUEUE ATTRIB QUANTITY for an example that uses the capacity to process
attributes to determine the quantity in the queue that can be processed.
In addition to the active in and out argument, QUEUE FIFO ATTRIB has an incoming attribute inatt
and a rate at which the existing attributes change over time attchg. The change in attributes is applied
both to the elements that are already in the queue, and to the incoming elements. The change rate is
multiplied by TIME STEP before being added. Suppose that one element is put into the queue at time
10 with an attribute of 7. If TIME STEP is 0.5 and the change rate is 2, then at time 10.5 this one
element will have an attribute of 8, and at time 11 it will have an attribute of 9.

Because the attribute queue has a distribution of attributes over its elements it also requires more
arguments to be initialized. In addition to profile, init and age range you need to specify the profile
of attributes over age range. This is done by specifying the initial attribute value initatt and a
multiplier for this attribute aprofile that is applied over age range. Unlike profile, the y values of
aprofile are used directly, so that a value of 1 gives the attribute initatt, a value of 2 gives 2*initatt
and so on. If these initial conditions are not important, you can simply specif a flat profile ((0,1),(1,1))
for both the time and attribute distributions as we do in the example below.

Restrictions: QUEUE FIFO ATTRIB must appear directly after the = sign. To make sense both
inflow and outflow should be positive and outflow should be controlled so that the queue never goes
negative. If you are going to use the QUEUE ATTRIB QUANTITY function the attribute should also
always be positive.
Behavioral Notes: The notes on QUEUE FIFO also apply here.

Example - Conveyor
in process = QUEUE FIFO ATTRIB(arriving,finishing,0,
is work day,flat,fortyfive,100,1,10)
flat((0,1),(0,1))
fortyfive((0,1),(10,11))

112
business oldest = QUEUE ATTRIB MAX(in process)
calender oldest = QUEUE AGE OLDEST(in process)
Here business oldest is measured in business days and is always less than or equal to
calendar oldest.

Example - Quality
work in process = QUEUE FIFO ATTRIB(
arriving,finishing,material quality,0,
flat,flat,100,material quality,10)
flat((0,1),(0,1))
product quality = assembly quality *
QUEUE ATTRIB AVERAGE(work in process,finishing)
Availability: Not PLE or PLE Plus.

RAMP(slope,start time,end time) RAMP test input


Returns 0 until the start time and then slopes upward until end time and then holds constant.
Same as:
IF THEN ELSE ( Time > start time,
IF THEN ELSE ( Time < end time :AND: end time > Time,
slope*(Time - start time),
slope*(end time - start time),
0)
NOTE The value returned by RAMP does not change except at TIME STEP intervals regardless of the
integration method used.
See also: STEP, PULSE

Units: RAMP(units,time, time) ? units*time (start time and end time have
the same units as Time, the result of RAMP has the product of the
slope and Time)
Example
RAMP(1,10,25) is 0 till time 10, then a line to 15 at time 25, then 15 afterwards.

RANDOM 0 1( )RANDOM number between 0 and 1


RANDOM BETA(m,x,A,B,h,r,s) BETA distribution alpha=A and beta =B
RANDOM BINOMIAL(m,x,P,N,h,r,s) BINOMIAL on N trials of probability P
RANDOM EXPONENTIAL(m,x,h,r,s) EXPONENTIAL starting at 0 with mean 1
RANDOM GAMMA(m,x,O,h,r,s) GAMMA with order O
RANDOM LOOKUP(look,m,x,h,r,s) RANDOM number using LOOKUP PDF
RANDOM NEGATIVE BINOMIAL(m,x,P,N,h,r,s) NEGATIVE BINOMIAL N successes prob P
RANDOM NORMAL(m,x,h,r,s) NORMAL with mean 0 and standard deviation 1
RANDOM POISSON(m,x,M,h,r,s) POISSON and mean M
RANDOM TRIANGULAR(m,x,S,P,T,s) TRIANGULAR between S and T with peak at P
RANDOM UNIFORM(m,x,s) UNIFORM between m and x
RANDOM WEIBULL(m,x,S,h,r,s) WEIBULL with shape S starting at 0 with mean 1
Each of these routines returns a random number. The numb er returned is different on each successive
invocation. These functions are used to introduce noise into a simulation.

113
Arguments
With the exception of the obsolete function RANDOM 0 1, which takes no arguments, all of the
RANDOM functions take a common set of arguments (The TRIANGULAR and UNIFORM don’t use
all the common arguments because they are simpler).
m is the minimum value that the function will return. Where necessary the distributions will be
truncated to return values above this. Truncation occurs after the output has been stretched and shifted.
x is the maximum value that the function will return. Where necessary the distributions will be
truncated to return values below this. Truncation occurs after the output has been stretched and
shifted.

h is a shift parameter that indicates how much the distribution will shifted to the right after it has been
stretched (but before being truncated).
r is a stretch parameter that indicates how much the distribution will be stretched before it is shifted
and truncated. Note that for the NORMAL distribution h and r correspond to the mean and standard
deviation.
s is a seed for the distribution to use. If s is set to 0 the default noise stream will be used. The default
noise stream can be controlled using the NOISE SEED variable described below. For each distinct
non-zero value of s a separate noise stream will be created. You can couple noise streams by giving
them the same seed, but such streams will not be the same. See the examples below.
NOTE The noise seed for a random variable should be a number or a constant. If you make the seed
a variable a new noise stream will be started each time the value of that variable changes.

Units: RANDOM...(units,units...dmnl) ? units


The minimum, maximum arguments should have the same units and the RANDOM functions will
return these units. If there is a shift argument it should also have these units. The seed argument
should be dimensionless. If there is a stretch argument it should be dimensionless. Except as noted
below, the remaining arguments should be dimensionless. If all inputs are numbers the output will be
dimensioned by usage.

Specifics
RANDOM 0 1() is uniformly distributed on the range 0 to 1. It is obsolete and will return exactly the
same noise stream as RANDOM UNIFORM(0,1,0). It is retained to maintain backward compatibility
only.
RANDOM BETA(m,x,A,B,h,r,s) provides a BETA distribution with alpha having the value A and
beta having the value B before it is stretched, shifted and truncated.

RANDOM BINOMIAL(m,x,P,N,s) provides a binomial distribution where P is the underlying


selection probability and N is the number of draws. Before stretching and shifting, RANDOM
BINOMIAL always returns an integer between 0 and N. If N is not an integer it will be rounded to the
nearest integer.
RANDOM EXPONENTIAL(m,x,h,r,s) provides an exponential distribution starting at 0 with a mean
of 1 before being stretched, shifted and truncated.
RANDOM GAMMA(m,x,O,h,r,s) provides a gamma distribution of order O before it is stretched,
shifted and truncated. When O is 1 RANDOM GAMMA is the same as RANDOM EXPONENTIAL.
If O is less than 1 a warning will be generated and 1 used.
RANDOM LOOKUP(look,m,x,h,r,s) provides an arbitrary distribution with a probability density
function specified by the Lookup function look. Note that the Lookup does not need to have an area of
one - this will be automatically managed when the random numbers are generated. Before being
stretched and shifted the output will have the same range as the X-axis of the Lookup function. The
dimensions of look should match m, x, and h.

114
RANDOM NEGATIVE BINOMIAL(m,x,P,N,s) same as binomial except N is the number of
successes required so that random negative binomial returns an integer from N to infinity.
RANDOM NORMAL(m,x,h,r,s) provides a normal distribution of mean 0 and variance 1 before it is
stretched, shifted and truncated. This is equivalent to a normal distribution with mean h and standard
deviation r. The units of r should match m, x and h.
RANDOM POISSON(m,x,M,h,r,s) provides a Poisson distribution with mean M. The value returned
is always an integer before it is stretched and shifted. The units for M should match m, x and h.
RANDOM TRIANGULAR(m,x,S,P,T,s) provides a triangular distribution from S to T with a peak at
P. You can shift and stretch the triangular distribution by adjusting S, P and T. The units for S, P, and
T, should match those of m and x.
RANDOM UNIFORM(m,x,s) provides a uniform distribution between m and x.

RANDOM WEIBULL(m,x,S,h,r,s) provides a Weibull distribution with shape S starting at 0 and


having a mean of 1 before it is stretched, shifted and truncated. When S is 1 the Weibull distribution is
the same as the exponential distribution.

NOISE SEED
When the seed passed to the RANDOM functions is zero, they will use the default noise seed. You
can control this by creating a variable in the model (usually a constant) called NOISE SEED. When
this variable exists in the model its value is used to initialize the noise streams. Changing NOISE
SEED will then generate alternative noise streams in different simulations.

Examples
driving error1 = RANDOM NORMAL(0,20,12,5,2)
driving error2 = RANDOM NORMAL(0,20,12,5,2)
Will generate two distinct noise streams with the same statistical characteristics. Adding
driving error3 = RANDOM TRIANGULAR(0,20,0,5,15,2)
to the first two will change the first two noise streams. In contrast adding
driving error3 = RANDOM TRIANGULAR(0,20,0,5,15,0)
to the first two equations will leave the first two noise streams unchanged.
Availability: PLE and PLE Plus only support RANDOM UNIFORM and RANDOM NORMAL.

RC COMPARE('runname',var,mult[,start[,duration]])
RC COMPARE CHECK('runname',var,grace,mult[,start[,duration]])
RC DECAY(basis,decaytime[,start[,duration]])
RC DECAY CHECK(grace,basis,decaytime[,start[,duration]])
RC GROW(basis,growrate[,start[,duration]])
RC GROW CHECK(grace,basis,growrate[,start[,duration]])
RC RAMP(basis,mult,ramptime[,start[,duration]])
RC RAMP CHECK(grace,basis,mult,ramptime[,start[,duration]])
RC STEP(basis,mult[,start[,duration]])
RC STEP CHECK(grace,basis,mult[,start[,duration]])
The RC and RC CHECK functions all work in the same manner. Each keeps a variable at its normally
generated model value until a specified time, and then defines a new trajectory. The RC functions are
used in test inputs (in :THE CONDITION: part of a Reality Check) and the RC CHECK functions are
used in the consequence (:IMPLIES:) portion of a Reality Check . Each of the functions allows you to
specify the time at which the change to a new trajectory should occur, or use the value of the model
variable RC START TIME to begin the test. Normally RC START TIME is a constant that is set to a
time shortly after the beginning of the simu lation. If RC START TIME is not present in the model the

115
trajectory changes are made at time INITIAL TIME + TIME STEP. Chapter 9 of the Vensim Modeling
Guide contains more information on Reality Check.
Restrictions: The RC functions can not be used outside of Reality Check equations. They are valid
only for comparison to a variable and must be used in the form:
rc example
:THE CONDITION: var1 = RC STEP(var1,0)
:IMPLIES: var2 <= RC STEP CHECK(shorft grace,var2,0)
Note that each of the RC functions has two optional arguments start and duration. start is the time
at which the trajectory change takes place, and duration the length of time the trajectory remains
changed. If duration is missing the trajectory change will continue to the end of the simulation. If
start is missing the trajectory change will start at RC START TIME as described above.
The following arguments are common to all, or almost all, the functions:
basis is the value against which the trajectory change will take place and will be multiplied by mult
when the trajectory change begins. basis can be an expression, though normally it will just be the
name of the variable on the left hand side of the comparison operator as it is in the above example.
The value that basis takes on at RC START TIME is used to perform the trajectory changes (except
for the RC COMPARE functions).
grace is the amount of time that can pass before the RC...STEP function actually begins checking for
compliance. This makes it easy to specify that an effect takes place after a delay. Note that the value
of basis is frozen at RC START TIME so that RC STEP CHECK(5,inventory,.3,5) and RC STEP
CHECK(0,inventory,.3,10) have quite different meanings.

mult determines the amount that basis will be multiplied by to get the new value. This can be an
expression, though in many cases it will just be a number such as 0 or 2. Unlike basis, the current
value of mult is used at all times and thus can provide arbitrary time profiles.
RC COMPARE( 'runname', var, mult [,start[,duration]])
RC COMPARE CHECK( 'runname', var, grace, mult [,start[,duration]])
compares the values of a variable from a different run - normally a base case. var replaces basis and
can only be a variable name, not an expression. 'runname' is a single quoted literal or a string
variable that names the run against which the comparison will be made. The COMPARE functions
useful for Constraints that say things like if we raise our price sales will be smaller than they would
have been.
RC DECAY( basis, decaytime [,start[,duration]])
RC DECAY CHECK( grace, basis, decaytime [,start[,duration]])
forces an exponential decay to zero with a time constant decaytime. This function is useful when you
want to make sure something goes to zero, but you don't care if it does so as an exponential decay and
therefore would technically never actually get to zero.

RC GROW(basis, growrate [,start[,duration]])


RC GROW CHECK(grace, basis, growrate [,start[,duration]])
forces exponential growth at growrate. This is useful for making sure variables grow sufficiently fast.

RC RAMP(basis , mult , ramptime [,start[,duration]])


RC RAMP CHECK(grace, basis, mult, ramptime [,start[,duration]])
force a ramp to basis*mult over ramptime . This is a more continuous change than RC STEP and is
useful for checking to see that variables make monotone adjustments to a new value. The value of the
RC RAMP functions after RC START TIME is basis*(mult*(Time-RC START TIME)/ramptime +
(1-(Time-RC START TIME)/ramptime)) until RC START TIME + ramptime when it just takes
on the value basis*mult.

116
RC STEP(basis, mult [,start[,duration]])
RC STEP CHECK(grace, basis, mult [,start[,duration]])
forces a step to a new trajectory at RC START TIME. A step is a strongly disruptive shock to a
system and has, therefore, been the most commonly used. Step changes are abrupt and will often cause
formulations that are not completely robust to fail. The idiomatic way to use the RC STEP function is:
var = RC STEP(var,.5)
This causes the variable to jump to 50% of its value at RC STEP TIME and then remain constant.
Note that mult may be time varying, but that basis is evaluated only at the step time (more precisely
one TIME STEP prior to the step time). The idiomatic way to use the RC STEP CHECK function is:
no pop no production :THE CONDITION:
population = RC STEP(population,0) :IMPLIES:
production <= RC STEP CHECK(1,production,0)
This would drop population to 0 at RC STEP TIME and then check that production goes to zero 1 year
(assuming the model is in years) thereafter.

Units: The RC functions are not part of units checking.

REINITIAL(X) REINITIAL value of X


REINITIAL is the same as INITIAL except when a simulation is restarted from another simulation.
In this case REINITIAL will be computed whereas INITIAL will not.

Availability: Same as INITIAL in PLE or PLE Plus

SAMPLE IF TRUE (condition, input,initial value) SAMPLE IF TRUE and then hold
Returns input when condition is true and otherwise remains constant. The function initially holds
constant at the stated initial value. This function is useful for retaining information about a variable's
behavior.
Restrictions: SAMPLE IF TRUE must directly follow the equal sign and not be followed by
anything. If you are using the Equation Editor, select Variable type Level and subtype Sample if True.

Units: SAMPLE IF TRUE (dmnl, unit, unit ) --> unit


Units for the input and initial value must match and are returned.

NOTE The variable defined by SAMPLE IF TRUE is like an Auxiliary in that it will change
depending on the current value of the inputs. However, the variable is also like a Level in that the
value at the present time may depend on the values of variables at a previous time. Vensim reports
variables defined using SAMPLE IF TRUE as Auxiliaries.
The SAMPLE IF TRUE function allows you to use the same variable on the left and right side of an
equation. When the same variable appears on the right it is the previous value of the variable that is
used. For all other variables it is the current value of the variable that is used.

Examples
max workforce = SAMPLE IF TRUE(Workforce > max workforce,
workforce,workforce) {retains the maximum value of workforce}
starting cash = SAMPLE IF TRUE(MODULO(Time,12)<.5,cash,cash)
{retains the cash position at the beginning of the year
throughout the year (Time in months)}

117
starting time = SAMPLE IF TRUE(:NOT: starting time :AND:
project is started,Time,0) {retains time at which project starts}
If you are using an integration technique other then Euler, the value of the output of the SAMPLE IF
TRUE function will change within the integration step, though the reported value will always be
computed on an even time step. Thus if TIME STEP is 1 and using RK4 Auto integration project
is started becomes non-zero at time 3.25, starting time will be reported as 4.0. If any other
variables use starting time they may receive a value of between 3.25 and 4.0 within the
integration step.
Availability: Not PLE or PLE Plus.

SHIFT IF TRUE(var,cond,size,accum,inval) SHIFT elements of var IF cond is TRUE


Shifts size elements of var when cond is true. If accum is non-zero then the second to last
element of var is added to the last element, otherwise the second to last element replaces the last
element. Shifting occurs relative to the rightmost subscript of var. If a shift does occur, then the first
element of the rightmost subscript of var is replaced with inval. SHIFT IF TRUE returns the
amount that has been removed from the last element of var. If accum is non-zero then SHIFT IF
TRUE always returns 0.

SHIFT IF TRUE is useful for managing aging chains or cohorts. The most common application would
be to populations in which maintaining an accurate age distribution is important.

Units: SHIFT IF TRUE(units,dmnl,dmnl,dmnl,units) ? units


NOTE Be very careful when specifying the size argument to SHIFT IF TRUE. IF this argument is
too big it can change other variables. In general, since SHIFT IF TRUE modifies the values of the
variable it is called with, it should be used with care.
NOTE Be sure that the subscript order of var is set up so that the final subscript is the one to be
shifted over.

Example
age : IN VITRO,(AGE 1-AGE 65) ~~|
ageh :(AGE 1-AGE 65) ~~|
country : usa,mexico ~~|
gender : male, female ~~|
Population[country,gender,IN VITRO]=
INTEG(conceptions[country]-deaths[country,gender,IN VITRO],
INIT POP[country,gender,IN VITRO]) ~~|
Population[country,gender,ageh]=INTEG(-deaths[country,gender,ageh],
INIT POP[country,gender,ageh]) ~Person~|
a[country,gender]=SHIFT IF TRUE(Population[country,gender,IN VITRO],
MODULO(TIME,1)=0,ELMCOUNT(AGE),1,0)~Person~~:SUP|
Note that for all but IN VITRO, Population has no inflow. Population in cohorts beyond the
first is increased by the aging process implicit in SHIFT IF TRUE.
Availability: Professional and DSS only.

SIN( X ) SINe of X

Returns the sine of X. Sometimes useful to test the dynamic response of a system. SIN is periodic on
X in the range of 0 to 2 pi radians.

Units: SIN (dimensionless) ? dimensionless

118
Examples
sin( 0.0 ) is equal to 0.0.
sin( 1.0 ) is equal to 0.84147.

SINH( X ) Hyperbolic SINe of X


Returns the hyperbolic sine of X.

Units: SINH (dimensionless) ? dimensionless


Examples
sinh( 0.0 ) is equal to 0.0.
sinh( 1.0 ) is equal to 1.17
Availability: Not PLE or PLE Plus.

SINTEG(rate,initial,min,max,quant,spec,thresh) Special numerical INTEGration

Returns the integral of rate but puts special restrictions on the value it can take on. SINTEG will
never go below min or above max. SINTEG will always return a multiple of quant. If the value
SINTEG would return is within thresh of spec, then SINTEG will return spec.

Restrictions: SINTEG must directly follow the equation sign. It signals Vensim that the variable on
the left-hand side of the equation is a Level or State variable. The last five arguments must be numbers
or :NA:.
See also: INTEG
NOTE The SINTEG function is non-conservative and should be used with care.

Units: INTEG(unit/ time, unit, #,#,#,#,#) ? unit


The units of the integral must be the same as the units of the initial condition. The rate must have the
same units, divided by the units of TIME STEP. The remaining arguments must all be numbers.

Examples
SINTEG(rate,initial,:NA:,:NA:,:NA:,:NA:,:NA:) is equal to
INTEG(rate,initial)
SINTEG(rate,inital,0,:NA:,:NA:,:NA:,:NA:,:NA:) is always >= 0
SINTEG(rate,initial,0,100,1,:NA:,:NA:) is an integer between 0 and
100
SINTEG(rate,initial,:NA:,:NA:,:NA:,0,.01) is 0 whenever it would
otherwise be < .01 and > -.01.
Availability: Not PLE or PLE Plus.

SMOOTH N(input,delay time, initial value, order) N'th order exponential delay

Returns an N'th order exponential smooth. If order is 1 this function is almost the same as SMOOTHI
and if order is 3 it is almost the same as SMOOTH3I.
The SMOOTH N function is treated as a discrete delay function, so that its output is constant for each
Time Step. If you are using Euler or Diff integration this is true of all variables. However, if you are
using Runge-Kutta integration this is different from functions such as SMOOTH3.
The SMOOTH N function does not conserve quantities. See DELAY N if you want to conserve
flows..

119
Note that for the SMOOTH N function to make sense delay time must be bigger than order* TIME
STEP. If this is not the case Vensim will issue a warning and automatically reduce the order so that
this is true. When this happens the behavior of the SMOOTH N function is essentially the same as the
behavior of the DELAY INFORMATION function.
Restrictions: SMOOTH N must directly follow the equal sign. It signals Vensim that the variable on
the left-hand side of the equation is a Level or State variable. In the Equation Editor select Variable
type Level, subtype Delay/Queue and enter SMOOTH N as the function.

Units: SMOOTH N( unit, time unit, unit, dmnl ) ? unit


Examples (12th order Smooth)
perceived quality = SMOOTH N(quality,delay time,quality,12)

SMOOTH(input,delay time) exponential SMOOTH


SMOOTHI(input,delay time,initial value) exponential SMOOTH with Initial
Returns a exponential smooth of the input. Equivalent to the equations:
SMOOTH=INTEG((input-SMOOTH)/delay time,input)
SMOOTHI=INTEG((input-SMOOTHI)/delay time,initial value)
See also: DELAY1, DELAY3, SMOOTH3,DELAYP

Units: SMOOTH(units,time) ? units


SMOOTHI(units,time,units) ? units
The input units match the output units. The units of delay time must match those of TIME STEP.
For SMOOTHI units for the initial value must match those of the input.

Example

S = STEP(10,40)
SS = SMOOTH(S,20)
SSI = SMOOTHI(S,20,5)

SMOOTH3(input,delay time) 3rd order exponential SMOOTH


SMOOTH3I(input,delay time,initial value) 3rd order exponential SMOOTH with Initial
Returns a 3rd order exponential smooth of the input. Equivalent to the equations:
SMOOTH3=INTEG((LV2-SMOOTH3)/DL,
input)
LV2=INTEG((LV1-LV2)/DL,input)
LV1=INTEG((IN-LV1)/DL,input)
DL=delay time/3

120
SMOOTH3I=INTEG((LV2-SMOOTH3I)/DL,
initial value)
LV2=INTEG((LV1-LV2)/DL,
initial value)
LV1=INTEG((IN-LV1)/DL
initial value)
DL=delay time/3
See also: DELAY3, SMOOTH,DELAYP

NOTE The SMOOTH3 function does not conserves material when the delay time is changing. It is
intended to be used for information delays.

Units: SMOOTH3(units,time) ? units


SMOOTH3I(units,time,units) ? units
The input units match the output units. The units of delay time must match those of TIME STEP.
For SMOOTH3I units for the initial value must match those of the input.

Example
S = STEP(10,40)
SS = SMOOTH3(S,20)
SSI = SMOOTH3I(S,20,5)

Smooth3 Output with Step input


10

7.5

2.5

0
0 10 20 30 40 50 60 70 80 90 100
Time

S - CURRENT
SS - CURRENT
SSI - CURRENT

SQRT(X)SQuare RooT of X
Returns the square root of X.
Same as: POWER(X,0.5).

Units: SQRT(units*units) ? units


If argument has units that are a perfect square the result will be the square root of the units. If the
argument is dimensionless, the result should be dimensionless.
Example: SQRT(9.0) is equal to 3.0.

STEP(height,step time) STEP test input


Returns 0 until the step time and then returns height. It is the same as:

121
IF THEN ELSE ( Time plus > step time,height,0)
time plus = Time + ( TIME STEP / 2.0 )
NOTE The value returned by STEP does not change except at TIME STEP intervals regardless of the
integration method used.
See also: RAMP, PULSE

Units: STEP(units,time) ? units (step time has the same units as Time, the
result of STEP has the units of the step height)
Example
STEP(10,20) is 0 till time 20, then 10.

SUM † (x[i!])SUMmation over Subscript Range


The sum of an array over the Subscript Range(s) with exclamation ! mark(s).
See also: PROD, VECTOR SELCT, VMIN,VMAX.

Units: SUM(unit) ? unit (output has same units as the input)


Examples
SUM (x[i!]) is equal to x[one] + x[two] +...+x[n].
SUM (x[i,j!] * A[j!] ) is equal to ( x[i,one]*A[1] ) +
( x[i,two]*A[two] ) + ... +
( x[i,n]*A[n] ).
SUM (x[i!,j!] is equal to x[one,one] + x[one,two] +...+ x[one,m] +
x[two,one] + x[two,two] +...+ x[two,m] +
... + ... + ...
x[n,one] + x[n,two] +...+ x[n,m].
SUM (x[i!,j]*y[i!]) is equal to x[one,j]*y[one] + x[two,j]*y[two]
+ ... + x[n,j]*y[n].
Availability: Professional and DSS only.

SUPPLY AT PRICE(q,pp,price) quantity SUPPLied AT PRICE

Computes the quantity that is supplied at a given price based on the capacity quantity q and the supply
preference profile pp. The price argument will normally be computed using the FIND MARKET
PRICE function. Both q and pp must be Subscripted variables and the subscripts for pp must be the
subscripts for q followed by a pprofile subscripts. See Appendix E for more details.
See also: DEMAND AT PRICE, FIND MARKET PRICE, ALLOCATE AVAILABLE, Appendix E.

Units: SUPPLY AT PRICE(units,punits,punits) ? units


The output units are those of q. Those units for pp and price must match.
Example
amount supplied[supplier] = SUPPLY AT PRICE(
supply capacity[supplier],
supply curve[supplier,ptype],
market price)
Availability: DSS and Professional only.

122
TABBED ARRAY(row1...rown) TABBED ARRAY of constants
TABBED ARRAY is used as a convenient mechanism to enter vectors or arrays of Constants into
Vensim.
Restrictions: TABBED ARRAY must immediately follow the equal = sign and cannot have anything
following it. In the Equation Editor Tabbed Array appears as a subtype for variable type Constant.
The input to the TABBED ARRAY function is 1 or more rows of number separated by tabs with each
row being on its own line. This function is designed to make it easy to paste number from
spreadsheets directly into the Equation Editor. Each row must contain the same number of values as
the last Subscript Range has Elements. The number of rows must match the number of elements in the
first Subscript Range that appears. No more than two subscript ranges can appear.

Units: TABBED ARRAY is not part of units checking. Define the units for the
Constant.
Example
country : MEXICO, USA, CANADA
blood type : A, B, O, AB ~~|
initial population[country,blood type] = TABBED ARRAY(
1 2 3 4
5 6 7 8
9 10 11 12) ~Person~|
Availability: Professional and DSS only.

TAN( X )TANgent of X

Returns the tangent of X. Periodic on 0 to 2* ?.

Units: TAN(dimensionless) ? dimensionless


Example
tan( 0.0 ) is equal to 0.0.
Availability: Not PLE or PLE Plus

TANH( X )Hyperbolic TANgent of X

Returns the hyperbolic tangent of X. Sometimes useful for generating S-curve parametric relationships
when lookup functions are not appropriate, e.g., when shape parameters need to be estimated using
data.

Units: TANH(dimensionless) ? dimensionless


Example
tanh( 1.0 ) is equal to 0.76159.
tanh( 0.0 ) is equal to 0.0.
tanh( 6.4 ) is equal to 0.99999.
Availability: Not PLE or PLE Plus.

TIME BASE( START,SLOPE) Defines an additional TIME BASE

Returns a new time base having the value START when Time is 0 and increasing by SLOPE relative
to Time.

123
The TIME BASE function allows different time units to be used in a model (e.g., months and years).
This can make output more attractive, and allow easier data entry.

Restrictions: TIME BASE must directly follow the equal sign. It signals Vensim that the variable on
the left-hand side of the equation is a Time Base. START and SLOPE must be numbers or constants,
not expressions or computed variables. The left-hand variable cannot have subscripts. In the Equation
Editor select variable type Time Base.
Same as: (START + Time*SLOPE) except it marks the left -hand variable as a Time Base rather
than an Auxiliary.

Units: TIME BASE(newtime,newtime/time) -> newtime (SLOPE is


essentially a units converter)
Example
Decimal year = TIME BASE(1970,.0833333) (defines a
yearly time base for a monthly model).

TIME SHIFT( DATA,SHIFT) SHIFTs data in TIME

Returns data that is shifted in time. The TIME SHIFT function allows manipulation of the time axis
of data. If, for example, you want the model to see the data in the future, you would shift the data by a
positive amount. The second argument is measured using Time as the Time Base, regardless of the
Time Base used to input the raw data.
Restrictions: TIME SHIFT must directly follow the colon equal := sign. It is only valid in data
equations. The SHIFT argument must be a number or a constant; other model variables are not valid.
The DATA argument must be a single variable name, and cannot be an expression. TIME SHIFT
cannot be combined with any other function.

Units: TIME SHIFT(units,time) ? units (i.e., the units of the first argument
are attained, the second argument has the same units as time)
Example
sales next month := TIME SHIFT(sales data,1)
allows a glimpse into the future of sales.
Availability: Not PLE or PLE Plus.

TIME TRANSITION(x1,x2,...) Perform a TIME TRANSITION


The TIME TRANSITION function is obsolete. Use the RC ... functions instead.

TREND(input, average time,initial trend) Compute the TREND of input


Returns the average fractional growth rate (negative for decline) in the input. Equivalent to the
equations:
TREND=ZIDZ(input-avval,average time*ABS(avval))
avval=INTEG((input-avval)/average time,input/(1+ini*averate time))
The TREND function provides a very simple trend estimate for a variable. It really only makes sense
for numbers that are always positive and don’t get very close to zero. If you want to trend a number
that may be positive or negative the TREND function is not very useful. Instead, you s hould use the
fractional trend relative to a quantity that is always positive (for example change in profit as a fraction
of gross income).
See also: FORECAST,SMOOTH

124
Units: TREND(units,time,1/time) ? 1/time
Units for the average time must match those of TIME STEP.

Example
R = 10 + RAMP(1,30,70)
TR = TREND(R,5,.08)

VECTOR ELM MAP † (vec,offset) MAPS an ELeMent of a VECTOR

The VECTOR ELM MAP function is a convenient way of moving back and forth between disparate
subscript ranges. In many cases it is possible to accomplish the same thing using the mapping
capabilities of subscripts (see Chapter 2) which can improve error checking.

The VECTOR ELM MAP function returns the value of the variable that is offset from vec by the
specified amount. For example, when sub : s1,s2,s3 is a subscript, the following two equations would
be the same:
var2[sub] = var1[sub] ~~|
var2[sub] = VECTOR ELM MAP(var1[s1],sub-1) ~~|
Note that in this case we use sub-1 because offset is effectively 0 based. One obvious use for this
function is in situations where you want to have a variable with one subscript map to a variable with a
different subscript. For example:
task : dig,build,test ~~|
skill : brawn,brain ~~|
task skill[task] = 0,1,1 ~Dmnl~|
avg task skill[task] =
VECTOR ELM MAP(avg labor skill[brawn],task skill[task]) ~Qua~|
Because you can do arbitrary mappings in this manner it is a very flexible function for managing
nonstandard subscript use.

Units: VECTOR ELM MAP(units,dmnl) ? units


The offset expression should be dimensionless.

If you try to use an offset that would take your mapping outside the range of the variable an error
message will be issued and :NA: will be returned.
Note that for variables that have more than one subscript the VECTOR ELM MAP function can be
used to move between all subscripts but will require multiplication. For example the following two
expressions are the same:
v2[sub,tub,gub] = v[sub,tub,gub] ~~|
v2[sub,tub,gub] = VECTOR ELM MAP(v[s1,t1,g1],
(sub-1)*ELMCOUNT(tub)*ELMCOUNT(gub) +
(tub-1) * ELMCOUNT(gub) + (gub-1)) ~~|
Availability: Professional and DSS only.

125
VECTOR LOOKUP †(vec,x,xmin,xmax,mode) Preforms a Lookup on a VECTOR
Allows the specification of a nonlinear function by specifying the y values in vec and giving the
minimum and maximum values for x in xmin and xmax. The specified range for x is broken up into n
equal intervals where n is one less then the length of the vector vec. If vec is a multidimensional array
then the length used is the number of elements in the last subscript. This function should always be
called with the first element of vec as shown in the example.
The function VECTOR LOOKUP encompasses the behavior of all the regular lookup function with
the results of using the function determined by the value of mode which should be an integer between
0 and 9.
0 a normal lookup function determining y from x.
1 the equivalent of LOOKUP AREA
2 the equivalent of LOOKUP BACKWARD
3 the equivalent of LOOKUP EXTRAPOLATE
4 the equivalent of LOOKUP FORWARD
5 the equivalent of LOOKUP INVERT
6 the equivalent of LOOKUP SLOPE
7 the equivalent of LOOKUP AREA with extrapolation
8 the equivalent of LOOKUP INVERT with extrapolation
9 the equivalent of LOOKUP SLOPE with extrapolation

Note that 7,8 and 9 do not have equivalent functions using regular Lookups. Also note that for 1 and 7
the area returned is the area from xmin. If you want to get the area between two values use
Area for LV = VECTOR LOOKUP(LV[s1],xend,xmin,xmax,1) –
VECTOR LOOKUP(LV[s1],xstart,xmin,xmax,1)
Also note that in mode 7 if x is less than xmin the, assuming vec is all positive, a negative number will
be returned. This means that the above formula for area between two points is still valid.
There are no restrictions on the type of variable that vec is. This means you can have time varying
lookups and allows for a variety of flexible ways of specifying functions. For example, you can specify
a 2 dimensional Lookup function using
XDim : (x1-x3)
YDim : (y1-y5)
xmin = 0
xmax = 10
ymin = 0
ymax = 100
lookup vals[XDim,YDim] = 1.1,1.2,1.3,1.4,1.5;
2.1,2,2.2.3,2.4,2.5;
3.1,3.2,3.3,3.4,3.5;
output = VECTOR LOOKUP(xslice[x1],x,xmin,xmax,0)
xslice[XDim]=VECTOR LOOKUP(lookup vals[XDim,y1],y,ymin,ymax,0)

Units: VECTOR LOOKUP(units,units1,units1,units1,dmnl) ? units

126
The mode expression should be dimensionless and x, xmin and xmax must have the same units. This
is appropriate for the most common uses but it is likely that when mode is 1, 5 7 or 8 you will need to
use units multipliers, or leave everything dimensionless, to pass units checking.
If you call this function with vec a scalar or with an element that is not the first element on the vector’s
last subscript an error will occur during simulation.
NOTE that VECTOR LOOKUP does not give any warning messages when the input is outside of the
specified range.
Availability: Professional and DSS only.

VECTOR RANK† (vec,direction) MAPS an ELeMent of a VECTOR

The VECTOR RANK function returns a new vector that specifies the rank of the elements in vec. If
direction is greater than 0 the entries are ranked from smallest to biggest, otherwise from biggest to
smallest. The first ranked element has a rank of 1, the second of 2 and so on. If two elements are the
same the will arbitrarily be assigned contiguous ranks. Do NOT use the result of this function with
VECTOR REORDER as this will return meaningless results.

Example
company : (c1-c5)
revenue[company] = 5000,3000,8000
revenue rank[company] = VECTOR RANK(revenue[company],1)
Will return 2,1,3 for revenue rank.

Units: VECTOR RANK(units,dmnl) ? dmnl


Restrictions: Must appear first on the right and can’t be followed by anything else.
Ranking is done on the complete vector relative to the last subscript.
Subranges will not work.
See Also: VECTOR REORDER, VECTOR SORT ORDER
Availability: Professional and DSS only.

VECTOR REORDER† (vec,svec) REORDERs the elements of a VECTOR

The VECTOR REORDER function returns a new vector with the same values as vec but in the order
specified in svec. Normally svec will be the result of a call to VECTOR SORT ORDER but it can als o
be specified by another means. Note that svec is 0 based not 1 based (that is a value of 0 corresponds
to the first index in the vec).

Example

See VECTOR SORT ORDER.

Units: VECTOR REORDER(units,dmnl) ? units


Restrictions: Must appear first on the right and can’t be followed by anything else.
Sorting is done on the complete vector relative to the last subscript.
Subranges will not work.
Availability: Professional and DSS only.

127
VECTOR SELECT† (sarray,vexp,mval,act,err) SELECT some elements of a VECTOR
The VECTOR SELECT function provides a convenient mechanism for selecting (getting the sum,
product, min, max or average) from a relatively small number of elements in an array. sarray
specifies a selection array with, normally, a large number of 0’s and a relatively small number of 1’s or
other non-zero values. vexp is the expression that elements are being selected from. mval is the value
to use in the case where there are only 0s in the selection. act is the action to take with 0 meaning sum,
1 product, 2 minimum, 3 maximum and 4 average. err indicates how to treat too many or too few
entries in the selection. If err is 0 then no errors are raised; if err is 1 then a floating point error is
raised if sarray has no nonzero elements in the computation being performed (that is a zero row or a
zero column); if err is 2 then an error is raised is more than one element is included; if err is 3 then
both no and more than one element raise an error.
The VECTOR SELECT function is very similar to formulations such as:
result[row] = SUM(sarray[row,col!]*expr[col!])
but has two important differences. The first is that causal tracing, instead of indicating that every
element of expr is a cause of every element of result will only display those elements where there
is a nonzero element in sarray. The second is that the expression that appears as the second
argument is only evaluated when it will contribute to the computation and not for every possible row
and column combination.
Related to the second of these, since some elements of vexp might not be used, Vensim does not verify
that all are actually computed. Thus "Used not computed" error messages will not be generated for
variables involved in the vexp argument of the VECTOR SELECT function (all other arguments,
including sarray are tested). If an array element is not computed it has the value :NA: which will
normally lead to a floating point error or visibly anomalous results during simulation should it be used.
However, extra caution is called for when making use of the VECTOR SELECT function.
Note that causal tracing is only changed for the Strip Graph and Table tools. The structural tools do not
reference subscripts. When tracing causes using simulation results if there are no runs loaded, or if the
loaded runs do not contain values for sarray, then no causes will be listed. If sarray is different in
different runs then the union of all possible causes will be displayed. In this case some of the causes
will not be applicable to some of the runs, you will need to check the values of sarray to see which
apply.

VECTOR SELECT is very useful for prerequisite mapping as well as compression and expansion of
array sizes as shown in the examples. For the first two of these err would normally be set to 1 while
for vector expansion err would normally be set to 3. If err is 0 or 2 and there are no non-zero elements
then the function will return mval. If err is 1 or 3 then mval will never be used and a value of :NA: is
recommended.
If sarray is an Unchangeable Constant (defined using ==) then the causality of VECTOR SELECT
used in determining equation order is based on only the nonzero elements of sarray. This provides a
convenient mechanism for propagating dependencies between subscript elements. An example of this
for a project is included below.

Example
In order to determine whether all prerequisite tasks are completed:
task : t1,t2,t3,t4
prereq <-> task
prereq map[task,prereq] ==
0,0,0,0;
1,0,0,0;
1,1,0,0;
0,0,1,0;

128
prereqs are complete[task] = VECTOR SELECT(
prereq map[task,prereq!],
task is complete[prereq!],1,2,0)
Note that the first row of prereq mat is all 0s – so for t1 prereq is complete will use the 3rd argument to
the function or 1 which is what we want since t1 does not have any prerequisites.

Example
Quality depends on both work quality and the quality of prerequisite work products. Using the above
task and prerequisite definitions:
task quality[task] = work quality[task] * prereq quality[task]
work quality[task] = .8,.9,.7,.9
prereq quality[task] = VECTOR SELECT(
prereq map[task,prereq!],
task quality[prereq!],1,1,0)
For this to work we depend on prereq map being defined as an Unchangeable Constant. If it
weren’t, then there would be a simultaneous equation involving work quality and task
quality.

Example
To move between cohort aggregations and disaggregations:
Age : a1,a2,a3,a4,a5,a6
AgeGroup : ag1,ag2,ag3
age grouping map[AgeGroup,Age] =
1,1,0,0,0,0;
0,0,1,1,0,0;
0,0,0,0,1,1;
population grouped[AgeGroup] = VECTOR SELECT(
age grouping map[AgeGroup,Age!],
population[Age!],
:NA:,0,1)
effect pollution deaths by age[Age] = VECTOR SELECT(
age grouping map[AgeGroup!,Age],
effect pollution deaths by age group[AgeGroup!],
:NA:,0,3)

Example
Simplified heat transfer on a two dimensional surface. This uses two subscripts to select from and also
treats the edge determination using VECTOR SELECT. The
x:(x1-x3)
y:(y1-y4)
edge : left,right,top,bottom
xp <-> x
yp <-> y
average adjacent temp diff[x,y] = (
VECTOR SELECT(adjacency matrix[x,y,xp!,yp!],
temp[xp!,yp!]-temp[x,y],:NA:,0,1) +
VECTOR SELECT(edge matrix[x,y,edge!],
edge temp[edge!]-temp[x,y],0,0,0)
) / 4

129
adjacency matrix[x,y,xp,yp] = INITIAL(
IF THEN ELSE((yp = y+1 :AND: xp = x) :OR:
(yp = y-1 :AND: xp = x) :OR:
(xp = x+1 :AND: yp = y) :OR:
(xp = x-1 :AND: yp = y),
1,0))
edge matrix[x,y,edge] = INITIAL(
IF THEN ELSE((y = 1 :AND: edge = top) :OR:
(y = elmcount(y) :AND: edge = bottom) :OR:
(x = 1 :AND: edge = left) :OR:
(x = elmcount(x) :AND: edge = right),
1,0))
Note that the VECTOR SELECT function does not use average but sums for this computation. Since
some of the 4 adjacent positions might come from edges and some from other cells the averaging is
done outside of the function (with simply /4).

Units: VECTOR SELECT(unit1,unit2,units,dmnl,dmnl) ? units=units1*units2


Restrictions: Both sarr and vexpr must have at least one subscript with an !.
Normally there will be one subscript acted on with the ! and that subscript
will be that is the same in both sarr and vexpr but this is not a
requirement.
Availability: Professional and DSS only.

VECTOR SORT ORDER †(vec,direction) MAPS an ELeMent of a VECTOR

The VECTOR SORT ORDER function returns a new vector that specifies the order of the elements in
vec. If direction is greater than 0 the entries are sorted from smallest to biggest, otherwise from
biggest to smallest. The returned vector contains the zero based index number for the elements in
sorted order (that is 0 is the first element, 1 the second and so on). Normally this is used in
conjunction with VECTOR REORDER but it can also be used with VECTOR ELM MAP to find min,
max and median values.

Example
company : (company1-company5)->scompany
scompany : (sort1-sort5)-> company
so[scompany]=VECTOR SORT ORDER(revenue[company],1)
minrev = VECTOR ELM MAP(revenue[company1],so[sort1])
maxrev = VECTOR ELM MAP(revenue[company1],so[sort5])
medrev = VECTOR ELM MAP(revenue[company1],so[sort3])
sorted rev[scompany] = VECTOR REORDER(revenue[company],so[scompany])

Note that it is not really necessary to define scompany in this example. However, the order of values in
sorted rev is no longer by company so it prevents possible confusion to use a different subscript range.

Units: VECTOR SORT ORDER(units,dmnl) ? dmnl


Restrictions: Must appear first on the right and can’t be followed by anything else.
Sorting is done on the complete vector relative to the last subscript.
Subranges will not work.

130
Availability: Professional and DSS only.

VMAX †(x[i!])MAXimum Over Subscript Range

Returns the maximum value of the elements of an array over the Subscript Range(s) marked with
exclamation ! marks.
See also: PROD,SUM, VECTOR SELECT, VMIN.

Units: VMAX(unit) ? unit (the output has same units as the input)
Example
VMAX (x[i!]) is equal to
MAX(x[one] ,
MAX(x[two] ,
MAX...,
x[n]))...).
Availability: Professional and DSS only.

VMIN†(x[i!]) MINimum Over Subscript Range

Returns the minimum value of the elements of an array over the Subscript Range(s) marked with
exclamation ! marks.
See also: PROD,SUM,VECTOR SELECT, VMAX.

Units: VMIN(unit) ? unit (the output has same units as the input)
Example
VMIN (x[i!]) is equal to
MIN(x[one] ,
MIN(x[two] ,
MIN...,
x[n]))...).
Availability: Professional and DSS only.

WITH LOOKUP(x,(L#)) LOOKUP the y value in the xy pairs L# corresponding to x


Specifies a nonlinear relationship between the input x and the output by passing the input through a
series of x,y pairs specified as numbers. It is the same as L(x) where L is defined by the equation
L(L#).
Restrictions: Must appear first on the right hand side of the equation and can not be followed by
anything else.
The WITH LOOKUP function is a convenient way to specify a nonlinear relationship without
explicitly naming the Lookup function to be used. This can reduce clutter and be somewhat quicker
than naming a separate Lookup variable but is not as flexible.

Units: WITH LOOKUP(dmnl,#) ? units


Just as for normal Lookup usage the x argument is expected to be dimensionless. If not, a warning is
issued, but not an error. The output units are those for the left hand side variable.

Example
X=WITH LOOKUP(1.5,((0,1),(1,1),(2,2)) is equal to 1.5.

131
X IF MISSING(expr,NUMBER) Replace with X IF datum is MISSING
Returns a data combination filling missing data points with NUMBER. Normally, if some but not all
data for an expression is available at once, the expression will not be computed at all. If you want to
force computation at all times when any data is available for the variables in the expression, then use
the X IF MISSING function. This will cause NUMBER to be substituted for the value of the
missing data.

NOTE X IF MISSING of a single data series simply returns the data series regardless of the value
of NUMBER.

Units: X IF MISSING(units,units) ? units


Restrictions: Valid only in Data := equations. Must appear first on the right of the = sign. The
NUMBER argument must be a numerical value.

Example
tot output data := X IF MISSING(SUM(output data[plant!]),0)
Availability: Note PLE or PLE Plus.

XIDZ(A,B,X)X If Divided by Zero (otherwise A/B)


Returns A divided by B. If B is zero, then returns X. XIDZ is normally used to express some limit of
A/B, as B approaches 0 (which would normally be undefined for B = 0).
Same as: IF THEN ELSE ( ABS(B) <1E-6, X, A/B ) (Both XIDZ and ZIDZ actually test the absolute
value of B against a small (1E-6) number and use X(0) if B is less than this small number.)
See also: ZIDZ.

Units: XIDZ(units of A, units of B, units of A/B) ? units of A/B (i.e., same


unit behavior as the division operator)
Examples
XIDZ( 3, 4, 1) is equal to 0.75.
XIDZ( 3, 0, 1) is equal to 1.0.

ZIDZ(A,B)Zero If Divided by Zero (otherwise A/B)

Divide A by B. If B is zero (actually smaller than 1E-6), then return 0.0. ZIDZ is normally used to
express the special case where the limit of A/B, as B approaches 0, is 0.
Same as: XIDZ(A,B,0.0).

Units: ZIDZ(units of A, units of B) ? units of A/B (i.e., same unit behavior


as the division operator)
Examples
ZIDZ( 3, 4 ) is equal to 0.75.
ZIDZ( 3, 0 ) is equal to 0.

132
5 The Sketch Editor

The Sketch Editor allows you to visually design and modify the feedback structure of a model. This
chapter describes how to:
? Create and modify models using the Sketch Editor.
? Represent different views of a model.
? Manipulate different model components on a sketch.
? Use the draw-like capabilities of the Sketch Editor.
? Control the interactions between the model you are sketching and the Workbench model.
? Use the Sketch Editor to build informal models and do data-based causal tracing.
The Sketch Editor is a visual aid and gives you substantial control over appearance. You can display
words by themselves or centered within a box, circle, or other shape. You can change the font and
color of words and the sizes of surrounding boxes and circles for emphasis. You can display arrows as
straight lines, arcs, or polygonal line segments, and you can set their color and polarity for emphasis.

Starting the Sketch Editor


When you start a new model or open an existing model, the model will normally open in the Sketch
Editor. With Vensim Professional and DSS, models can also open in the Text Editor. You can move
from the Text Editor to the Sketch Editor using the View>As Sketch or View>As Text commands.

Notes on Sketch Behavior


? You cannot have a Text Editor and a Sketch Editor open on the same model at the same time.
? When you exit Vensim, you are prompted to save any changes you have made to sketches you
have open.
? †In Vensim Professional and DSS, you can have as many models open as you like, but you cannot
open more than one sketch on a given model.
? If you are making large models, be sure to break them up into a number of different views.
Putting everything on one view will make your model hard to understand, really slow things
down, and you might run into capacity limitations for some Vensim configurations.

133
Models and Views
A model is a set of causal dependencies and equations defining the mathematical relationship among
variables. A view is a visual representation of some subset of those relationships. Models are
complete but might be complicated. Views, even for the most complicated model, can be made simple
and clean. Most models are a collection of overlapping views, each view showing a simple portion of
the underlying model.
Every view can have different content and different visual characteristics. Most commonly views are
used to represent different parts of a model, but they can also be used to represent the same part in
different ways. For example, it is possible to have one view that is a stock and flow representation and
a second that is a causal loop representation of the same structure.
NOTE For models with one view the model and the view are essentially the same thing.
Having many views allows you to:
? Represent complex models with combinations of simple diagrams.
? Visualize local structure accurately and completely without having to worry about disturbing other
clearly presented structures.
? Make distinct representations of the same concepts for different purposes.
? Localize structure for making and testing changes.
When you make changes to a view you might, or might not, affect other views. Changes that affect
only the appearance of a view and do not change the logical structure of the model do not influence
any other view. Thus, you can remove variables from a view, change the colors and fonts in a view, or
reposition variables within a view without affecting any other views.
On the other hand, changes that do affect the logical structure of a model will change related views.
For example, if you introduce a new causal connection between two variables, then that causal
connection will be duplicated in all views containing those variables. Similarly, if you delete a
variable from the model, it will be deleted from all views.
When you look at a view, it will be updated with changes you have made to other views. Vensim
introduces any necessary changes in the simplest possible way. For example, if you have added a
causal connection from Population to births, a straight arrow will connect these two variables
in other views. If another view has the variable births but not Population, then Population
will be added as a Shadow variable to that view, with a straight line connection made between the two.
The continual updating of views guarantees that every view is always completely accurate without
your intervention.

Sketches and Views


When you work with the Sketch Editor, you are working with a view, and this view is implicit and
usually not mentioned when discussing the Sketch Editor. When you open the Sketch Editor, it will
show the first view. By default this view is called "View 1", but you can rename it to anything you
want. You can have as many views as you want, but only one view will be visible at one time.
You can add anything that exists in the model to a view. If you add a new variable to a view, it is
automatically added to the model. Shadow variables can appear any number of times in a view, but a
variable can be defined only once within a view (though it can also be defined in other views with
Vensim making sure the definitions match). If a variable is defined in a view, then all of its causes will
automatically be included in the view, although you can hide them if you want. There is no limit to the
size and complexity of a view, but simple and easily understood views are preferable to comprehensive
but hard-to-follow views.

134
Sketches and Equations
The Sketch Editor allows you to work on the structure of a model, but there is no restriction that the
model be well formed or complete. Incomplete equations, equations with syntax errors, simultaneous
equations, and other problems will be reported when you attempt to check, load, or simulate the model.
Error reporting for problems relating to equations is shown in the Equation Editor (discussed in
Chapter 6).
Changes made to a model using the Equation Editor are transferred to all views to keep them
completely up to date. New and modified variables or causal relationships are added to views in the
simplest possible manner.

In Vensim PLE and PLE Plus causal relationships can only be changed on the View. If you attempt to
change these in the Equation editor you will receive an error message.

Variables, Words and Arrows


A short note on terminology is helpful at this point. We have spoken of models and introduced them
formally in Chapter 2. We have spoken of a sketch as a partial representation of a model, with the
equations hidden except for basic causality.
A sketch is also a model in its own right. You can build a model without ever entering equations.
Such a model can be very useful for communication, organization, etc., but cannot be used for
simulation. These word-and-arrow models can be causal loop diagrams, stock and flow diagrams, or
other visual models. If you think of the Sketch Editor as a tool for building word-and-arrow diagrams,
you will find it is powerful, flexible, and consistent with a number of different modeling paradigms.
We will use the terms "word" and "variable" largely interchangeably in this chapter. Comments and
junction nodes are "words" that are not "variables" since they do not form a structural part of a model.

The Edit Menu

or for PLE/PLE Plus


The Edit menu allows you to manage cutting, pasting and selection. Depending on the state of
activities, many entries in this menu will be grayed. Undo is only active if you have made a change
and Redo is only active is you have used Undo. Copy, Cut, Hide to Depth and Set Subscripts† are
only active if you have made a selection using the pointing tool. Paste is only active if you have
Copied or Cut something from another View.

135
Undo/Redo
The Undo and Redo commands allow you to Undo changes you have recently made. Vensim keeps a
running log of changes you have recently made and the labels on these menu items will reflect the
changes that can be undone or redone. For simple changes like moving variables Vensim will grow
the Undo buffer to an unlimited depth. For other changes involving model structure such as Grouping,
Setting Subscripts, Editing Equations and Merging Variables Vensim will only allow you to undo a
single change. You can use Ctrl+Z as a shortcut for Undo, and Ctrl+Y for Redo.

Copy
Copy copies the currently selected words (and structure) into the clipboard. The full sketch
information (positioning, arrows, etc.) is stored privately by Vensim for use with the Paste command.
The appearance of the sketch is also sent to the clipboard as a Windows Metafile, clipped to the
selection rectangle. You can paste this Metafile into most other applications (word processors, etc.).
The Options Settings for Export as Printed and Export in Color are used in creating this Metafile.

Cut
Cut copies the selected words to the clipboard and also removes them. When you use this command
you will be queried as to what you want to do:

The default action is to Remove from this view but do not change model structure. The selected
words will be removed. Any arrows connecting two selected words will also be removed. A selected
arrows connected to a word that is not selected will be hidden. If a word has an arrow leaving it and
going into a word that is to be retained, the word is made a shadow variable and hidden from the view,
but not deleted. This option is not available for Vensim PLE or PLE Plus.
Delete variables, shadow variables and arrows changing model structure deletes each of the
selected words from the model. For variables and shadow the variable, its equations, comment and
units of measure will be deleted from the model and all views.

Delete variables and arrows but leave shadow variables in model will delete all selected normal
variables and all selected arrows from the model. Shadow variables will not be deleted from the
model, but only removed from the view or. Note that a shadow variable that is also selected as a
variable will be deleted. Also, if a shadow variable is used in the view it will just be hidden, not
removed from the view.
If you cancel out of this dialog no action is taken and nothing is copied to the clipboard.
NOTE Pressing the Del key is the same as Cut except that nothing will be placed in the clipboard.

Hide to Depth (Not PLE)


Hide to Depth allows you to set a hiding depth for the selected words and arrows. There are 10 levels
of hiding: Unhidden, followed by 1 through 9. Choose one of these from the menu that appears when
you highlight Hide to Depth. You can use the View menu to choose to which depth you want hidden

136
elements to be visible. For example is you hide to Depth 5 and then View Depth 5 you will see the
elements.
Hiding elements to different depths allows you to unfold model structure by successively showing
more hidden elements. The Magic Wand tool can also be used to control hiding. The Magic Wand
hides elements to one depth greater than the current depth shown.

Paste
Paste causes the selection that was last cut or copied to be placed into the current view, and can also be
used to place graphics copied from other applications into the current view. In Vensim PLE and PLE
Plus, past will replicate the structure and add it to the model as described below (with no prefix or
suffix specified). In other configurations when you execute the Paste command, you will be prompted
to determine how you want to paste the clipboard information.

Replicate makes an additional copy of the model structure you have copied, creating new variables
and equations in the model.
For each variable that is defined in the structure you have copied, Vensim will add the prefix and
suffix specified then check to see if the variable is defined in the current model. If it is, Vensim adds a
zero (0) at the end of the variable name (Population becomes Population 0). If the variable
with the 0 appended is also in the current model, Vensim adds a 1 (Population 1). If this variable
is also defined Vensim adds a 2,3 ... 9, A, B, ... Z until it finds a variable that is not yet defined, then
uses this name.
You can leave both the prefix and suffix blank to get just the numbering as described above. Typically,
you would only use one or the other and you might want to end the suffix with a space or begin the
prefix with a space. For example if you were making a copy of a population structure for different
species you might use "Rabbit " as a prefix, then Population would become Rabbit
Population.

For each shadow variable that is in (but not defined in) the structure you have copied, Replicate checks
to see if that variable is in the current model. If the variable exists in the current model, Vensim uses
the existing variable. If not, Vensim adds the variable to the model, gives it an empty equation, and
brings it into the view as a shadow variable without making any changes to its names..
For Lookups and Subscripts used in the source equations, Vensim checks to see if they are defined in
the target model. If so, the existing Lookup or Subscript is used. If not, the Lookup or Subscript is
copied from the originating model and no change is made to the variable name.
For each variable defined in the structure you have copied, Replicate replaces its equation with one
that uses the renamed variables.

137
These rules provide a simple mechanism for joining models together and repeating pieces of structure.
They do present a potential problem, however, in that a variable name intended to represent one
concept can replace a variable name intended to represent another concept when a structure is
replicated between models. Care should be taken in naming variables to guard against this possibility.
Picture works only at the visual level, and will not alter the structure of the model. It is useful for
repeating a visual representation of a structure in different views, or between distinct but similar
models. Vensim expects the variable names contained in the picture to also be in the current model,
and will not allow you to enter a second definition for a variable. If any problems are detected, you
will be asked if you want to continue.
If you do a Select All followed by a Copy, then create a new view (View>New) and do a Paste
selecting Picture, you will have a copy of a view that you can further modify. This is useful for
building two visual representations based on a common foundation.
Annotation is used to place a graphic copied from another application onto a sketch. It is the same as
using the Sketch Comment tool and selecting the Metafile or Bitmap options.

Select All
Select All selects all sketch objects in the view you are working with. This is useful for copying and
for making global modifications to word and arrow characteristics. The command View>Font is
preferred for making global font changes.

Or Select

All but Shadow allows you to select all variables except those that appear as shadow variables. This
is quite useful for applying groups and simulating subsets of the model as described below.
Aux/Const/Data allows you to select everything except rates and levels. This is useful if you want to
apply separate attributes to these variables.
Visible Items selects everything you can see. It is the same as using the Pointer tool and dragging
over the whole sketch, starting in the upper left hand corner and fin ishing in the lower right.
Information Arrows selects all the information arrows but not the rates. This is useful for changing
attributes. Note that perpendicular information arrows will not be selected.
Levels selects all Levels in the view.
Rates selects all the rates in the view as well as the associated valves and pipes. Note that
perpendicular information arrows will also be selected.

Group
Group places all the selected variables into a group. This is useful for documenting the model and
managing equation order when the model is reformatted. When you select this command you will be
queried for the name of a group. You can select an existing group, or enter a new group name. All
selected variables will then be made part of that group. The Document tool has an option to document
all members of a group.

138
Set Subscripts†
The Set Subscripts command lets you set subscripts on the selected variables. This is a convenient
way to add subscripts to the model variables without having to modify individual equations. It is, of
course, still possible to modify individual equations and this is often necessary when you have multiple
equations for a variable or want to use a vector function.
When you choose the Set Subscripts command the Subscript Modification dialog will appear:

The title bar indicates that name of the variable being changed or, if you have selected more than one
variable, the number of variables being changed.
Subscript 1 through Subscript 8 allow you to set the subscripts. Normally you will only use one or to
of these but it is possible to use all 8 so they are included for completeness. Click on the dropdown
box to select a Subscript Range. When you open this dialog with a single variable selected the
subscripts showing will be those for the variable. If you open it with more than one variable selected
and each selected variable has the same subscripts (in the same order) these will be shown. If the
subscripts are not the same for the existing variables the dialog will appear as it does above, with --
none showing for each subscript.
Apply to selected variables by lets you specify how you want to modify the equations for the selected
variables.

Setting causes the selected variables to take on the new set of subscripts. The subscripts for these
variables are changed to be the ones specified in the order specified. If a variable already has any of
these subscripts the usage will not be changed. For example if Pop was subscripted by age and
there was an equation with SUM(Pop[age!]), then changing the subscripts to [country,age]
would change the expression to SUM(Pop[country,age!]). Similarly if you have multiple
equations with Subscript Constants these will be retained. If a variable has additional subscripts not in
the list these will be removed.
Adding at end causes the selected subscripts to be added at the end of the existing subscripts for a
variable. Thus existing subscripts will not be removed. If the variable already has one of the chosen
subscripts it will be moved, if necessary so that it appears at the end. For example adding age to a
variable subscripted [age,sex,country] will change the subscripts to [sex,country,age].
Just as for setting any existing occurrences of the subscript will be maintained in their current form.
You can add one or more subscripts with this option.
Adding at beginning is the same as adding at end except the chosen subscripts appear first, instead of
last.
Removing will remove the chosen subscripts from the selected variables. If the variables do not have
any of the subscripts nothing will happen.

139
Include subranges in subscript lists, when checked, allows you to add subranges to variables. This
can sometimes be handy if some variables will only be computed and used on a Subrange.
Replace subranges with the specified subscript allows you to override the default behavior for
setting and adding subscripts. When this is checked if Vensim finds a subrange for one of the chosen
subscripts it will replace it with the chosen subscript, rather than leaving it alone. Note that Vensim
will still leave Subscript Elements alone. If you want to change these first remove them, then add the
subscript range.
Add a new subscript to the model allows you to add subscripts. This can also be done from the
Subscript Control or from the Equation Editor and this button is just a convenient alternative to those
techniques.

Find
Find can be used to search for the occurrence of a model variable in a sketch view. When you use this
command, the Variable Selection dialog will prompt you for the name of a variable. Choose a variable
and click OK. The current view will be searched for the variable, and that variable will be highlighted
and the sketch repositioned if necessary. If the current view does not contain the variable, the
remaining views will be searched in a circular fashion. You will receive a message if the variable does
not appear on any views, otherwise you will be positioned at the first variable found in one of the
views.
NOTE All of the Find commands will find both visible and hidden variables.

Find Workbench
Find Workbench is the same as Find except that instead of prompting you for a variable it uses the
currently selected Workbench variable.

Find Again
Find Again repeats the search for the last Find command. Since the variables in a sketch do not have
an obvious order, you can use Find and Find Again to find all appearances of a variable. The variable
appearances are reported in the order stored internally by Vensim.

The View Menu

or in PLE/PLE Plus
The View menu gives you control over the appearance of the sketch you are working with. Not all of
the commands are available in Vensim PLE and PLE Plus.

140
As Text †
As Text causes the Text Editor to be open on the model you are working with. If you have made any
changes you will be asked if you want to save them. If you don't save, the Text Editor will not be able
to make a proper backup, and the Undo/Redo commands will be grayed in the Text Editor.

Zoom

Zoom lets you pick a percent to zoom to. In addition to the percent values there are two special
options.

Fit to Screen will cause the sketch to be zoomed until the entire view will fit in the current screen.
The resulting zoom percentage will depend on the size of the current sketch. The zoom will never
exceed 100% in Fit to Screen is selected.
Custom will query you for a percent to zoom to. You can enter any number between 10 and 500
percent.
When you zoom a sketch, all views for the model will be zoomed the same way. The zooming will
also be remembered when you close and later open the model. If you choose Fit to Screen, each view
is likely to zoom to a somewhat different percent, but all will be visible as you move through them.
Zooming does not permanently change the sketch and the zooming percent is always relative to the
normal sketch size.

Show Arrows
Show Arrows shows and hides arrows. When it is checked arrows are visible and will therefore be
hidden by the command. When it is not checked arrows are invisible and will therefore be shown by
the command.
Hiding the arrows removes clutter and can make rearranging somewhat simpler. Arrows that are
explicitly marked as hidden will not be shown unless you have selected the command Show Hidden.

Show Behavior
Show Behavior , when checked, will display a graph of the behavior of each variable on the sketch.
This is the same type of graph that is displayed when using SyntheSim. Displaying the graphs can be
helpful in doing model analysis. The B key will also toggle this display setting.

Show Hidden
(Not PLE) Allows you to specify the hiding depth to which you want to see words. When you
highlight this you will get a menu of depths include None to show no hidden elements, Depth 1 to
show elements hidden to Depth 1 up to All (which is the same ad Depth 9) to show all hidden
elements.
You can use the H key to toggle between All and None. You can use the Home key to decrease the
hide depth and the End key to increase it. By repeatedly pressing the End key you can successively
reveal more structure (pressing the Home key will successively hide more structure).

You can use the Magic Wand tool or the Edit>Hide to Depth command to change the depth to which
different elements are hidden.

141
If you want to set up a sketch to do successive hiding start at depth 8, hide what you want, move to
depth 7 hiding more, then depth 6 and so on.

Rescale
Rescale allows you to rescale the X and Y components axis of a view, or of all views in the model.
This makes a permanent change in the width of the view. When you invoke the X Rescale command
you will see the Rescale dialog.

Percent is the amount to change the scale by. Bigger than 100% will make things bigger and further
apart, less than 100% smaller and closer together.
Positions, if checked, will cause the positions of words and arrows to change.
Sizes , if checked, will causes the sizes of words to change.
Maintain Aspect Ratio, if checked, will force the vertical values to match horizontal.
Apply to, allows you to either select application to the current view, or all views in the model.
Rescale has no effect on font size.

The rescale command is useful for making small adjustments to the overall size of a view. It is also
useful if you are moving a sketch to a computer with different display characteristics, though Vensim
will probably prompt to see if you want to perform an automatic rescaling in this event.

New
New creates a new view, which will be added to the bottom of the list of views and will be given a new
number corresponding to its position. If you have deleted or reordered views, the new number will be
adjusted accordingly. The Sketch Editor will be positioned at the new and empty view.

Rename
Rename allows you to rename the current view. You can name your views anything you want, with a
maximum length of 32 characters. The names of views are not used in the model itself, and will not
conflict with Variable or Group names even if they are the same.

Reorder
Reorder allows you to reorder the Views in a model. This is done using the List Reorder dialog
discussed in Chapter 16.

142
Delete
Delete deletes the current view (but not any variables from the model). You will be asked if you really
want to delete the view. Deleting a view has no effect on the model or on other views, but once you
delete a view you cannot recover it.

Font and Colors

Font and Colors lets you set the View Default font and colors.
? Background Color sets the views background color. Use the default color as shown to just use
the standard Windows background color.
? Shape Color sets the default colors for Boxes and other shapes.
? Fill Color sets the default fill color. Use the default selection as shown for no fill color.
? Arrow Color sets the default Arrow color.
? Initial Arrow Color sets the color on Initial Arrows (arrow indicating a variable is used to
initialize another variable so that the link is not part of the active feedback structure).
? Font sets the default font. This font is used display all words that have not explicitly had a font
attached to them.
Changing the view's defaults makes it easy to make global changes to the appearance of a view and is
more efficient than changing attributes on individual words and arrows.

Refresh
Refresh forces a redrawing of the sketch view screen. Under some circumstances, some video drivers
will leave images on the screen that are not logically part of a sketch. The Refresh command will
remove these. If screen clutter becomes a recurring problem there is an option for continually
refreshing the screen (see Chapter 17).

143
The Layout Menu

The layout menu is used to adjust the size and position of words. If nothing is selected the entire menu
is grayed. If you have selected words by dragging over an area the Size to Default, Horizontal Spacing
and Vertical Spacing items will be active. To activate all items you need to select multiple words by
shift clicking. You can do this by first dragging over an area and then shift clicking on words to add
them to the selection set, or by clicking and then successively shift clicking. The last word you shift
click on is the Last Selected Word.
Size to Default causes the selected words to be sized to the defaults set in the Sketch Defaults tab of
the Global Options dialog (Tools>Options see Chapter 16).
Size to LastSel makes all of the words the same size as the Last Selected Word. This is useful for
making all levels the same size.
Height to LastSel makes all of the words the same height as the Last Selected Word. The widths are
not changed.
Width to LastSel makes all of the words the same width as the Last Selected Word. The heights are
not changed.
Center on LastSel positions all the selected words to have the same horizontal center as the last
selected word.
Left Align on LastSel positions all the selected words to be left aligned on the Last Selected Word.
Right Align on LastSel positions all the selected words to be right aligned on the Last Selected Word.

Vertical on LastSel positions the center of all selected words to have the same position as the center
of the Last Selected word.
Horizontal Spacing evenly spaces all the selected words horizontally without changing their vertical
position. Even spacing means the space between the words is made the same. The leftmost and
rightmost words are not moved.
Vertical Spacing evenly spaces all the selected words vertically without changing their horizontal
position. Even spacing means the space between the words is made the same. The top and bottom
words are not moved.

Status Bar
When you are using the Sketch Editor, the Status Bar at the bottom of the Workbench gives you
information about current settings, and allows you to change a number of them. Selecting one or more

144
Words and Arrows with the pointing tool and clicking on the Status Bar is a fast way to make font and
color changes to particular sketch objects.

moves you to the previous View in the sketch. If you are on the first view this has no effect.

View 1 (the viewname) displays the name of the current view. Clicking on this will display a list of
all views. Click on the one you want. The last entry in this list is always *New* and can be used to
create anew view.

moves you to the next view in the sketch. If you are on the last view nothing happens.

Times New Roman (font name) shows you the current font. If nothing is selected it is the default
View font. If you have selected one word it is the font for that word. Clicking on this with one or
more words selected allowsyou to set the font for those words.
14 (font size) shows you the size of the current font. Clicking on this with one or more words selected
allows you to change the size of the font for those words.
B,i,u,s show you the attributes of the current font - bold, italic, underline and strike-through. If the
attribute is on, the letter is upper case, otherwise the letter is lower case. Clicking on these with one or
more words selected allows you to change the attributes on those words.

Word Color shows the current word color. Click on this to get a choice of colors to apply to
selected words.

Shape Color shows the color of the current word shape. Click on this to get a choice of colors to
apply to the shapes of the selected words.

Word Shape lets you set the shape of the selected words. Click on this for a list of choices. The
second entry from the top causes the selected variables to have shape set based upon the Type of
variable they are. This option allows you to impose the shape conventions set in the Sketch Defaults
Dialog on all variables appearing in the view.

Word Position lets you set the position of words on selected words. Click on this for a list of
choices.

Arrow color lets you set the color on selected arrows.

Arrow width lets you set the width on selected arrows.

Arrow polarity lets you set the polarity on selected arrows. Choose from the built in list of
choices.

Add workbench variable adds the Workbench Variable to the current view. After you click on
this, clicking on the view will add the Workbench Variable. You can use this to add a variable as a
shadow variable or to add a variable and its causes. Use the shift key to toggle causes on or off, the
cursor will change shape to show you whether or not causes will be added. When you are adding a
Workbench Variable in this manner, the current Sketch Editor is temporarily suspended, and the Status
Bar becomes a cancel button.

push to background pushes the currently selected words and arrows to the background of the
sketch. This is useful if you have words that overlap or if you are using large shapes to contain

145
portions of a diagram. The words and arrows pushed to the background will appear behind other
words. You can select the words in the foreground by clicking on them, even when they are in the
same place as a background word.

The Sketch Layout


Shown below is a sample view of a small model.

The same view with the variable list shown (see Chapter 17) appears as:

? When it is not maximized, the Sketch Editor has a title bar, which names the model and view you
are working with. This title bar is not visible when the Sketch Editor is maximized. (You
maximize a window by clicking on the at the top right of the window.)
? The Sketch Tools bar across the top allows you to activate different tools within the Sketch Editor,
as described in the section "Sketch Tools." You can also set this bar to be vertical at the left (see
Chapter 16).
? The current view is a scrollable (both horizontally and vertically) window that shows the structural
model interconnections graphically.
? The Causes checkbox determines whether the causes of a variable are included when a variable is
placed in a view. See "Adding Variables to a View" below. This is visible only when the
Variable list is visible.
? The Variable list lets you select variables you want to add to a view. Double-clicking on an entry
in this list will select it into the Workbench.
The scroll bars allow you to see everything included in the view. The area that the scroll bars access is
increased automatically as you push things to the edge of the view. If you want to place something
outside of the currently visible area, place it on, or just beyond, the edge of the current view, then
scroll the current view.

Defined Variables and Shadow Variables


Before proceeding with the details of working with a sketch, it is important to distinguish between
Defined variables and Shadow variables. This distinction has nothing to do with the model or logical
interconnections, but only with the visual character of a sketch. When working with views, however,
the distinction is important.

146
Defined Variables
A variable is defined within a view if all of its causes are shown with arrows coming from them into
the variable. Vensim that makes sure that all of the causes are shown. If you add or remove arrows in
one view, Vensim will do the same in other views. Similarly, if you change the logical connection in
equations, Vensim will change the sketch to correspond. Thus, it is not possible to include only some
of the inputs to a Defined variable. You can, however, hide some of the causes of a Defined variable
to get the same visual effect.
A variable can only appear as a Defined variable once in a view, although a Defined variable can
appear elsewhere in the view as a Shadow variable. One variable can appear as a Defined variable in
any number of different views.
Defined variables are displayed in the sketch as just the name of the variable, and have arrows coming
from their causes. If a variable has no causes (such as a Constant), it can still be recognized as a
Defined variable because it lacks the angle brackets < > that are used to mark Shadow variables.

Shadow Variables
A Shadow variable is a variable that is defined elsewhere. No arrows can enter (cause) Shadow
variables. Arrows can leave Shadow variables. Shadow variables refer to variables defined elsewhere
in a view, in other views or in an equation and are useful in helping to reduce clutter and increase the
clarity of a sketch. Note that though Shadow variables do refer to variables defined elsewhere, the
associated Defined variable need not appear in the current or any view. Vensim lets you mix and
match visual representations with equations having no visual counterpart.
Shadow variables appear on a sketch surrounded by angle brackets < >. Thus Population would
appear as <Population>. By default Shadow variables are shown in gray, although you can change
their color if you want.
Shadow variables are simply a convenient substitute for Defined variables, and indicate that you need
to look elsewhere to find the definition. They are neither a different variable nor a different type of
variable from a Defined variable.

Sketch Comments, Valves and Junctions


Sketch Comments are words that are not variables. They can be used to annotate a sketch, but are not
given any structural meaning within the model.
There are no restrictions on the characters in a Sketch Comments. Comments do not need to include
text at all if a shape is being shown. Sketch Comments can also be icons, or Bitmaps or Metafiles
pasted from another application. This is detailed in the Comment Options dialog below.
Normally, you cannot draw an arrow into or out of a comment. Sometimes, however, drawing arrows
through comments can help improve the visual appearance of a sketch. To accommodate this, you can
mark a comment as a junction node. This provides a convenient mechanism for reducing clutter and
adjusting appearance. Consider, for example:

sales by mail fraction sales mail


sales by phone fraction sales phone
sales by sail fraction sales sail

Here there are three inputs and three outputs each using all three inputs. The above diagram states that
fraction sales mail depends on all three inputs, as does each of the other fractions. Though
quite natural algebraically, this is quite messy visually. By putting in two junction nodes (shown as
small circles) we can redraw the diagram as:

147
sales by mail fraction sales mail
sales by phone fraction sales phone
sales by sail fraction sales sail

This diagram has the same meaning. Following from left to right this diagram says that all of the types
of sales cause the first junction node, the first junction node causes the second junction node and the
second junction node causes all of the fractions. Thus, indirectly, all of the types of sales cause all of
the fractions. In determining causality Vensim simply passes through junction nodes looking for
variables from which a causal path can originate.
Junction nodes behave very much like "see also" markers in an index or dictionary. They direct you to
look further on, and this can save considerable space.
Sometimes you might want a comment to be attached to (rather than be positioned close to) an arrow.
You can use junction nodes to add commentary to arrows without adding variables to the model as in:

as overtime rises
people become
tired and make
mistakes
overtime quality

When you use a junction node Vensim traces the causes backward along the pathway to their ultimate
destinations. You can use this to create a variety of effects.
Valves are comments with no text that are used as junction nodes in showing material flows. Because
of their special purpose, Valves have a different choice of shapes than most other words. Valves are
discussed in more detail under Valve Options, and the Valve Tool below.
NOTE You if you want to have a loop passing through junction nodes you must mark at least one of
the comments as a no cause junction. Vensim will not allow a causal loop between comments.

Sketch Tools

There are a number of different Sketch tools in a Sketch Toolset. Except in PLE and PLE Plus, the
actual toolset that appears at the top of the Sketch Editor can be modified using the Tools>Sketch
Toolset commands, as described in Chapter 13. The toolset is made up of tools from the Pointer,
Variable, Arrow, Rate, Existing Variable, Merge, Sketch Comment, Input Output Object, Magic
Wand, Delete and Equations tool classes. The tool classes are described in more detail below. Within
a tool class, tools can be configured to give different default appearances and behavior. You change
the configuration of a tool on the toolset by clicking on it with the right mouse button or by Control-
clicking on it (Ctrl + Click).

The default Sketch Toolset shown above contains one or two tools from each Sketch tool class. From
left to right, the tools of the default Sketch Toolset are:
? Lock Pointer - used for variable selection no movement is possible.
? Movement Pointer - used for movement and selection.
? Variable - used to add variables to the sketch and edit the names of existing variables.
? Box Variable - used to add variables with a box shape to the sketch.
? Arrow - used to add arrows to the sketch.
? Rate - used to add rate constructs consisting of perpendicular arrows, a valve and, if necessary,
sources and sinks.

148
? Model Variable - used to add existing model variables to the sketch.
? Shadow Variable - used to add existing variables to the sketch without adding their causes.
? Merge - used to merge two distinct variables into a single variable.
? Input Output Object - used to add input sliders or output graphs and tables to a sketch.
? Sketch Comment - used to add comments to the sketch.
? Unhide Magic Wand - used to un-hide words and arrows
? Hide Magic Wand - used to hide words and arrows.
? Delete - used to delete comments from a sketch and variables from the model and all sketches.
? Equations - used to edit model equations using the Equation Editor (Chapter 6).
Select one of these tools by clicking on its icon. When you do, the mouse pointer will change shape
and the tool button you clicked on will appear indented. The selected tool remains active until you
choose another tool. When you position the mouse over the tool for a brief time without clicking any
buttons, a short description of the tool appears below it. You can then see descriptions of all the tools
by moving the mouse across the toolbar. This is helpful if you forget the exact meaning of a tool's
icon.
Tools can also be selected using the number keys (1,2,3 and so on as well as the QWERTYUIOP keys
if there are more than 10 available choices.
Clicking on a tool makes a permanent change to the tool in use. You can also select a tool for a single
use by pressing the mouse button on the tool and releasing the mouse button at the point you want to
apply the tool (where you would click after first clicking on the tool in permanent selection mode).
NOTE When you have the Variable List visible (see Chapter 17) and you click on a variable in it, the
selected tool is suspended until you place the variable in the current view, or cancel variable placement
by selecting a new tool, pressing the Esc key, or clicking on the Status Bar. If you are using the Delete
tool or the Magic Wand tool, when you add a variable, the Lock Pointer, described below, will be
selected when you have finished adding the variable.
The selected tool is indicated by the shape of the mouse pointer. The shapes correspond to the icons
for the different actions, as described below.

Pointer

The Pointer tool class has two members, the Lock tool and the Move/Size tool. The
Move/Size tool allows you to move, size and shape words and arrows as described later in this chapter.
The Lock tool prevents mouse based movement of sketch elements but still allows selection and menu
based modification of the sketch. It is designed to prevent accidental movement of words and arrows.
For both tools double-clicking on a word selects the corresponding variable into the Workbench. For
Navigation Comments, double-clicking with the Move/Size tool selected will move to the indicated
view whereas with the Lock tool selected only a single click is required.

You can use the Pointer to select one or more words or arrows. To select a single word click on it
without moving the mouse. To select a group of words press the mouse button (not on any words or
arrows) and drag the mouse over the group. A rubber band will appear, let go of the mouse button
when you have selected the words you want. Once you have selected one or more words Shift-clicking
on words and arrows will toggle them in and out of the selection.
With the Move/Size tool you can drag selected groups of words as a single group. Just press the
mouse button inside the selection box (rubber band) and move the mouse. Words and arrows will all
be moved together.

149
When the Move/Size tool is selected there will be visible sizing handles on words and positioning
handles on arrows. When the Lock tool is selected these will not be visible.

Pointer Options
The Pointer Options let you choose between the Lock tool and the Move/Size tool. The default sketch
toolset has one of each and this is all that are likely to be called for.

Variable Class

The Variable tool class contains the Variable tool, Box Variable tool, Circle Variable tool,
and all the other different possible shapes that can be associated with variables. The icon for the tool
will reflect that shape. The default toolset contains a plain Va riable tool, normally used to create
Constants, Auxiliaries, Data and Rates and a Box Variable tool normally used to create Levels.
The Variable tools allow you to modify variable names and add new variables to a model. When a
variable name is modified in one view, it will be modified in all other views. In addition, if the
variable appears in more than one place in the current view (because of Shadow variables), it will be
changed everywhere.
When you select the Variable tool, the mouse pointer will change to a vertical bar inside the shape
associated with the tool (such as a vertical bar inside a box for the Box Variable tool). If you click on
an existing variable, the variable name appears in an editing box, and you can edit the name but the
shape and other attributes of the variable will not be changed. If you click on a blank area, a blank
editing box will pop up, and you can type the new variable name to be placed at that location. Click
outside of the editing box or press the Enter key to record the new name and give it the shape and
attributes associated with the tool. If you enter a blank name, or press the Esc key, nothing will be
added to the sketch.

When you add a new variable or rename an existing variable, the Sketch Editor's variable list, if
visible, will be updated to reflect the change you have made. If you type the name of a variable that
already exists in the model — whether you are editing an old name or creating a new name — you will
be told that the variable already exists. It is not possible to have more than one variable with the same
name. You will need to change the name you have entered to avoid the conflict. Pressing the Esc key
will abandon your edits to a variable name or cancel the addition of a new variable.
If you want to put another copy of an existing variable in the current view, you must add it in the
manner described in "Adding Variables to a View" below, or use one of the Existing Variable tools
described below.
If you click on a valve with the Variable tool, you can create a new variable that will be attached to the
valve (i.e., the valve will be named). If you click on a valve that is already named, you can modify the
name of the valve.
If you click on a Sketch Comment when using the Variable tool the Comment Options box will appear.
You can change the text of the Comment or any other Comment options.

Variable Options
The options for the Variable tool class are the essentially same as the word options for a model
variable. These are discussed in the section "Changing the Appearance of a View" later in this chapter.

150
There are only small differences from the standard word options dialog. Use default font, if checked,
uses the default sketch font for the variable. This allows the appearance of the sketch to be easily
modified globally. The color buttons also have the default color option available (see Chapter 16) to
use the Sketch default settings. The Tool Icon Label, Background and Foreground settings are the
standard ones for tools (see Chapter 13).

Arrow Class

The Arrow tool class contains the Arrow tool, Polyline Arrow tool and Perpendicular
Arrow tool. Arrow tools allow you to create a link between one variable and another. The regular
Arrow tool creates either a straight or curved (arc) link, the Polyline Arrow tool creates a series of line
segments for the link, and the Perpendicular Arrow tool creates a series of perpendicular line segments
for the link.
After selecting the Arrow tool, click once on the variable you want the arrow to start from, then move
the mouse (without holding down the button). As you move the mouse, an arrow will follow your
pointer. Move to the variable you want to connect the arrow to, and click again. An arrow will be
drawn between the two variable.
With the regular Arrow tool if you can click once in an empty part of the sketch while creating an
arrow and a handle will be dropped at the point you click at. When you click on the destination word
this handle will be used to form a circular curve. If you do not click at an intermediate point a straight
line connection between the two words will be made.
With the Polyline Arrow tool and Perpendicular Arrow tool you can click on up to 16 intermediate
points before clicking on the second word. The points will be used to shape the resulting arrow, with
the Perpendicular Arrow tool forcing each line segment to be perpendicular. If you try to add more
than 16 points the Arrow will be dropped.
During the creation of an arrow, you cannot drag anything. If you press the mouse button and move
the mouse the motion will be ignored until you release the mouse button.
You can stop the creation of any Arrow by clicking twice in the same empty part of the sketch, or by
pressing the Esc key.
If you start an arrow on a variable and then click on the first handle of an existing arrow, this will
cause the existing arrow to start from the variable you first clicked on. This effectively moves the tail

151
of the arrow from one variable to another. The arrow will be the same type of arrow that already
existed. You can move the head of an arrow by dragging the arrowhead from one word to another.
NOTE Dragging on a word (pressing the left mouse button and moving the pointer) will move the
word, not start a new arrow.
NOTE After you click on the final word, you must release the mouse on the same word or the arrow
will be canceled.
When you have an arrow tool selected the arrow you create will have one or more handles that you can
use to reshape it. For regular arrows, you drag the handle in the middle to change the shape of the arc
it forms. For the Polyline arrows you can change the two line segments defined by a point.
The reshaping of perpendicular arrows is somewhat more constrained. You can only move the first
and last handles along a line parallel to their current connection. When you move other handles their
nearest associates will also move. Finally, if there is only one handle, your only choices are usually
horizontal then vertical or vertical then horizontal.

In this situation you can make Vensim move between the two positions. Press the mouse button on the
arrows handle and drag. Nothing will happen till you pass the halfway mark to the other corner, then
the arrow will flip.
You can draw arrows from any word to words representing Defined variables, Valves and Junction
Nodes. If you attempt to terminate an arrow on a Shadow variable or away from any words, no arrow
will be drawn, and the arrow you have been working on will disappear. Also, even though a variable
can depend on itself, as a matter of convention you cannot draw an arrow from a variable onto itself, or
into another word representing the same variable (you can, however, draw an arrow from a word into a
valve or junction node, and have an arrow run from that valve or junction node back to the word).

If you attempt to create an arrow connecting two variables that already have an arrow connecting them,
you will be told the connection exists and asked if you want to reshape the arrow. Answer Yes to
remove the old arrow and replace it with the one you have just drawn. Answer No to have both arrows
present. Answer Cancel to leave the old arrow where it was. This is a simple mechanism for changing
the type of arrow connecting two variables.
With unnamed valves and junction nodes, two variables can be connected through intermediate non-
variable nodes. If you attempt to create an arrow that connects, directly or indirectly, two variables
that are already connected, directly or indirectly you will be informed of this condition and asked if
you want to proceed. Creating redundant connections is allowed, but you will always be informed that
such a situation is going to arise and given the option of canceling.
NOTE Creating a new arrow changes the causal structure of the model. Reshaping existing arrows
influences only the appearance of the view.

Arrow Options
The options for the arrow tool class are essentially the same as the options for arrows discussed in the
section "Changing the Appearance of Views" later in this chapter.

152
There are only minor differences from the standard arrow options.
Arrowhead into junction determines whether or not the arrowhead is drawn when an arrow goes into
a junction node. This option is only active is Arrowhead itself is checked. Unchecking Arrowhead
into junction can be very useful if you often use junctions to break up arrows with text commentary.
The default font checkbox inside the Polarity box means the default font will be used for polarities.
Similarly, all of the color options have the default color selection available. You can also supply a
Tool Icon Label and control the color of the tool.

Rate Class

The Rate tool class contains the Rate tool and the Valve tool. The Rate tool adds a
complete rate (a Valve, two Arrows and Clouds if necessary), while the Valve tool adds just the Valve.
Rates and Valves are used to represent flows of materials into and out of Levels.
To use the Rate tool click on the variable you want to represent a flow out of, then move the mouse to
the Level variable you want to represent a flow into and click again. A rate construct will appear as in:

Work in Finished
Progress Inventory
By default the rate will have a single arrow and a editing box will appear so that you can name the
Valve. You can press the Esc key to stop naming the valve. You can change this behavior from the
Rate Tool Options dialog discussed below. Once you have created a rate you can add and remove
arrowheads by clicking with the right mouse button (or Ctrl+Click) on the arrow's head or handle and
checking or unchecking the Arrowhead checkbox. If you do not name a valve when the rate is first
created, you can name it by clicking on the valve with a Variable tool.
When you add a new rate, the valve that is drawn will depend on the options you have set and whether
the rate is drawn horizontally or vertically.
Once a valve is named it will always move with its name — dragging either the valve or the name
attached to the valve will drag the other.

153
If you start a rate by clicking away from a word, a source (cloud) for that rate will automatically be
created. Similarly if you end a rate by clicking away from a word a sink (cloud) will be created. If
you want a rate starting at a source, click first on a blank portion of the sketch, then on the Level
variable. If you want a rate finishing at a sink, click first on a Level variable, then on a blank portion
of the sketch. For example, a rate from no variable to no variable will appear as:

There is no distinction drawn between sources and sinks (both appear as clouds), since rates can be
both positive and negative. However, Vensim will keep track of the direction you draw rates when
first setting up the active part of Level equations.

To draw a rate that makes bends, hold down the Shift key and click where you would like the rate to
bend. By default the Valve will be placed in the middle of the rate, but you can force the valve to be
placed in another location by holding down the Ctrl key and clicking where you want the valve to be
placed.

Work to do Work Done

Rate Options
There are a number of options you can set on rates that control the initial appearance of rates.

Type determines if the tool will create a complete Rate or just a Valve.

Initial Valve Type determines the initial appearance of the valve. If you select either the vertical bow
type or vertical beam types the valve will be drawn horizontally when the rate itself is vertical. All the
others will always be drawn as they appear.
Attachment lets you set how words will be attached to the valve. If this type is Below and you have
selected the vertical bow or beam valve type the word will be attached to the right of the resulting
horizontal valve.
Valve Color determines the initial color of the valve. If you select the default — color the default
shape color for the view will be used.

154
Query Valve Name, if checked, causes the editing dialog to appear so that you can name each rate
valve as they are created.
Line Style lets you set the initial style of the valve line as well as its color.

One Way Flow, if checked, will cause the rates you create to have only one arrow head showing the
direction of flow.
You can also label the icon and set the background and foreground colors as with all tools.

Input Output Object

The Input Output Object tool class contains only a single member. It allows you to add input
sliders for Constants and Gaming variables and output graphs and tables to a sketch. Input objects are
active during on-screen simulation setup and during on-screen gaming.
Output objects are active when the Lock tool is selected and are automatically refreshed on the
completion of a simulation. This means that you can set up a model behavior cockpit that can be
accessed simply by going to the view that contains it. The resulting graphs can also be exported or
printed in the layout you choose for them.
To add an Input Output object to a view select the tool and click on a blank part of the view (not on a
word or arrow). This will open the Input Output Object Settings Dialog

Object Type lets you set whether you want an input object or an output object.

Input Slider creates a slider that can be used to set constants on screen when in simulation setup mode
and gaming variables when in gaming mode (see Chapter 8). To set a slider you need to choose a
Constant or Gaming variable and put its name in the Variable name field. You also need to set a
minimum and maximum value to define the slider range. You can optionally set an increment to
determine how the number changes when you move the slider.

The slider will appear in the screen, but will be active only when it is permissible to change its
associated value. To change the value associated with the slider drag the slider or type in a new
number.
Output Workbench Tool will cause the output of a Workbench tool (see Chapter 13) to be displayed.
You first need to choose the variable that needs to be in the Workbench when the tool is invoked, and

155
then the tool you want to invoke. A list of available Workbench tools is available under the Graph or
tool name for output label. You can also type in the name if you remember it.
Output Custom Graph will cause to output of a Custom Graph (see Chapter 14) to be displayed.
Choose the name of a Custom graph from the dropdown list or type it in.
Variable Name specifies the model variable to use. It is not active if you choose Output Custom
Graph. Use the buttons to the left of this to bring up the variable selection dialog to select a variable.
Note that for subscripted variables you will need to specify a complete set of Subscript Elements to get
the values you want.
Slider Settings are used to set the range for sliders. Enter a minimum value, a maximum value and an
optional increment. For Constants Vensim will display information about the units and base model
value of the Constant.
Label with varname, if checked, causes the variable name to appear below the slider. This is useful
for creating a quick label.

Graph or Tool name for Output lets you choose the name of a Workbench tool or Custom Graph.
The dropdown lists the available names.
Input Output Objects are not active when you are editing a sketch. Sliders will appear with no text and
outputs will appear as a box with a line running up through it. Output objects become active
when you click on the Lock tool. Both input and output objects are active when you are in simulation
setup and gaming mode.
Each time you complete a simulation all of the Output Objects will be reset and drawn with output
appropriate for the current results. This can make the output objects a very convenient way to review a
summary set of results for a simulation.
If the specification of an Output Object contains an error such as a bad variable or tool name, or if it is
a graph and there are no datasets loaded, nothing will be displayed and no message will be given.
NOTE Output Objects depend on the names tools in the Analysis Toolset. If you have edited your
Analysis Toolset (see Chapter 13) and pass a model to someone else some of the Output Objects may
not work properly.

The Vensim Model Reader presents Input Sliders and Output Objects in the same way as Vensim. The
Model Reader has a fixed toolset (the same as the built-in Vensim defaults). If you have Output
Objects that depend on a modified Toolset they will not work with the Vensim Model Reader.

Sketch Comment

The Sketch Comment tool class contains only a single member. It allows you to add
commentary, graphics and junction nodes to a view. The Sketch Comment tool is different from the
Variable tools. Comments added to the model are not part of the model structure. Comments are only
used for the purposes of presentation.
To add a comment to a view select the Comment tool and click on a blank part of the view (off any
words or arrows). The Comment Options dialog, which is discussed in more detail later in this
chapter, will appear. Type in a comment, or select a shape or graphical form to place on the screen and
click OK. The comment will appear in the sketch. You can move it around and operate on it just as
you could any other word. If you check the Use as Arrow Junction checkbox, you can also draw
arrows into it and out of it.

156
Existing Variable Class

The Existing Variable tool class has two members: the Model Variable tool and the
Shadow Variable tool. Both are used to add variables that already exist in the model to a particular
view. The Model Variable tool will include the causes of the variable being added, while the Shadow
Variable tool will not include the causes of the variable.
To add a variable, select the Model Variable tool and click on a blank part of the view (off any words
or arrows). The Variable selection dialog will appear.

Click on the name of the variable you want and click OK. The variable will be added to the sketch.

While using the Model variable tool, if a cause of the variable is on the sketch, an arrow will be drawn
from the cause to the to variable. If a cause is not on the sketch it will be added as a Shadow Variable.
NOTE You can toggle between the Model Variable tool and Shadow Variable tool on the fly by
holding down the shift key.
NOTE You cannot add a model variable if it is already defined in the view. You can use the
Edit>Find command to find where in the view a variable is defined.

Creating a Shadow Variable from a Variable


You can change a variable to a shadow variable by selecting the Shadow Variable tool and clicking on
the variable. You will be asked if you want to change it to a shadow variable. Answer yes, it will be
converted to a shadow variable and its causes, if they are not used elsewhere, will be removed.
You can change a shadow variable to a variable by selecting the Model Variable tool and clicking on
the shadow variable.

Existing Variable Options


The options on the Existing Variable tool class allow you to choose between Model Variable and
Shadow Variable.

Merge

The Merge tool class contains only a single member. It allows you to merge together two
model variables into a single model variable. This provides a convenient mechanism for combining
similar concepts that have arisen from pasting together different models, or for other reasons.
Suppose that you want to replace Urban Population with Population. To use the Merge tool
first select it, and then move to Population (the variable you want to replace Urban

157
Population with). Drag Population until the mouse pointer is on top of Urban
Population then release the mouse button. You will receive the message:

Answer yes. All variables using Urban Population will now use Population instead. The
variable Urban Population will be removed from the model.

The Merge tool is very useful when pasting models together because the sector linkages will often be
renamed during the replication operation. For example suppose you have two models. The first
computes crowding:

<POPulation>
crowding
LAND AREA

using population as an exogenous input and the second computes population.

population
births deaths

If you replicate the second into the first you get:

<POPulation>
crowding
LAND AREA

population 0
births deaths

Now we have population and population 0 in the view and we really want to keep
population 0, but name it population. Click on the Merge tool, drag population 0 on top
of population, answering yes to the prompt. Then reposition population 0 where it was
before, then click on a Variable tool and rename population 0 to population. You will have:
crowding
LAND AREA

population
births deaths

158
For this example, if you had replicated the crowding model into the population model, there would
have been no need for the extra effort. However, in general you can expect most partial models to both
compute and require variables in other sectors. There is likely to be a better order to merge models in,
but some amount of adjustment will almost always be required.

Splitting Arrows
Splitting arrows can be useful when you want to add an intermediate concept between two variables.
This can be done with the Merge tool by dragging the handle of the arrow you want to split onto the
new intermediate word. The direct connection previously made by the arrow will be removed and
replaced by a connection through the word you moved (two arrows).
For example suppose that you have:

Click on the Merge tool, and then drag the handle in the middle of the arrow over morale. When you
release the mouse button, the arrow from overtime to productivity is split as below:

Replacing Clouds
If you use the Merge tool and drag a variable onto a cloud, the variable will replace the cloud and any
rates coming into the could will come into the variable. This is a convenient way to add an additional
Level to a chain of flows.

Naming Rates
If you have an unnamed valve and you would like to attach an existing variable to that valve, you can
do so with the Merge tool. Simply drag the variable on top of the valve.

Splitting Valves and Variables


If you hold down the Shift key with the Merge tool selected it will act as a splitting tool and this will
reflected in the shape of the cursor . If you grab and drag a variable with a splitting cursor, a
shadow variable will be created for that variable. If you grab a valve that is attached to a word and
drag it the valve and word will be split apart, with arrows added in order not to change the causal
structure of the model.

Magic Wand

The Magic Wand tool class contains two memb ers, the Hide Wand and the Un-hide Wand.
These provide a simple mechanism for hiding words and arrows in order to remove clutter. The Magic
Wand changes the appearance of a sketch, but never changes the underlying causal structure or
equations for the mo del.

The Hide Wand appears solid while the Un -hide Wand appears hollow . The cursor shape
will also reflect this.

Hiding Words and Arrows


To hide a word or variable, select the Hide Wand tool and click on the word you want to hide. The
word will be hidden as will the arrows coming out of the word or the arrows going into the word.

159
To hide an arrow, select the Magic Wand tool and click on the arrowhead of the arrow you want to
hide. You will no longer see the arrow.
Hiding words and arrows with the Hide Wand is the same as selecting the words and arrows and then
setting the Hide Depth (Edit>Hide to Depth>) to be 1 greater than the currently displayed hide depth
(View>Hidden Elements>).

Un-hiding Words and Arrows


To un-hide a word or arrow you must first set the hide depth so that word or arrow is visible. You can
change the hide depth with the View>Hidden Elements menu item or by using the End key to show
more hidden things. You can also use the H key to toggle between everything hidden and nothing
hidden.
To un-hide a word select the Un-hide Wand and click on the word you want to un-hide. To un-hide an
arrow, click on the arrowhead. Nothing will change visibly, since hidden words and arrows are
already shown. When you decrease the hide depth (Home key) they will remain visible.

Un-hiding with the Un-hide wand is the same as selecting and setting the hide depth to be one less than
the currently displayed hide depth.
NOTE If you want to remove a variable from a sketch instead of just hiding it, select the word with
the Pointer tool and type the Del key. You can only remove words that are not used anywhere in the
sketch. If you remove a word that is used in the sketch, it will be replaced with a hidden Shadow
variable.

Delete

The Delete tool class has only one element. It allows you to permanently delete words
and arrows from the model. For arrows the causality they imply will be removed, invalidating
equations. For variables these will be deleted from the model and all views invalidating the equations
for any variables that used them.
Select the Delete tool and click on the word you want to delete or the arrowhead of the arrow you want
to delete. If you delete a shadow variable this will also delete any non-shadow instances of the same
variable.
If you delete a word that has arrows coming into it, those arrows will be deleted. Any Shadow
variables connected to the arrows will be removed from the view, but they will not be deleted from the
model.
NOTE Deletion changes model structure. It should be done carefully to avoid mistakes.

Equations Class

The Equations tool class consists of the Equations tool and the Variable Documentation
tool. The Equations tool provides a convenient way to open the Equation Editor from within the
Sketch Editor. The Variable Documentation tool brings up the documentation (comment) field for a
variable.
The Variable Documentation tool is most useful for models without any equations, such as causal loop
diagrams. The Equation Editor also has a documentation field. The advantage of the Variable
Documentation tool over the Equation Editor is that it has a simpler interface because it only enters
comments for a variable, rather than equations.

160
When you click on the Equations tool, the view you are working on will be checked to see which
variables have equations that are incomplete or incorrect. These variables will be highlighted. For
example you might have a partial model:

Pressing on the Equations tool would show:

indicating that you needed to write equations for all the variables. By clicking on a variable in the
sketch, the Equation Editor (see Chapter 6) is opened. You can also open the Equation Editor on a
variable using Shift-control-click when a different tool (such as the Variable tool) is active. Writing
the equation for the variable and clicking the OK button returns you to the Sketch Editor, and that
variable will no longer be highlighted. For small models, this is the simplest and most effective way of
working through all the equations.

Equations Options
The options for the Equations tools let you choose between the regular Equations tool and the Variable
Documentation tool.

Building Sketches from Models


You can build a sketch from any Vensim model including a text -only model. To add model variables,
you can use the Model Variable tool, the Add Workbench Var Status Bar button, or the Sketch
Variable List. To use the Model Variable tool, select it, click on an emp ty space, and select the
variable you want to enter. To use the Status Bar button, select the variable you want into the
Workbench, click on the Status button Add Workbench Variable and click on the sketch where you
want to add the variable. To use the Variable List, make it visible (see Chapter 16), click on the
variable you want to add in the list then click on the sketch where you want to add it. The model
variable is added with its causes shown as shadow variables.
Adding causal variables to existing variables is easy. Select the Model Variable tool and position the
mouse over a shadow variable (one surrounded by < >). As you position the mouse over a shadow

variable, the cursor will change shape from to . If you now click on the variable, it will be
converted from a Shadow variable to a Defined (model) variable, and its causes will be added as
shadow variables. Repeat this operation on each of the shadow variables (after you have repositioned
them on the sketch). When the cause of a variable is already defined in the sketch, an arrow will be
drawn from the cause and no shadow variable will be added. This provides a very easy method for
constructing a diagram out of the equations for a model.

161
Changing the Appearance of a View
To speed model building, the Sketch Editor has been designed to allow you to change the appearance
of sketch objects with any tool that is currently selected. This means, for example, if you are using the
Variable tool to rename variables, you can also reposition those variables without having to select the
Pointer tool.
NOTE The Magic Wand and Delete tools are destructive by nature and cannot be used to move
objects or customize appearance.
Many of the changes you make to a View affect only the appearance of a view and have no impact on
the structure of a model. The only changes that impact model structure are adding and removing
variables and the connections between variables.

Moving a Word
To move a word, drag it to a new location. (Position the pointer over the word, depress the left mouse
button and then move the mouse while holding the mouse button down.) As you drag the word, a
rectangle indicates where the word will be placed when you release the mouse button. When you
release the mouse, the word is repositioned and all arrows entering the word are redrawn.
You may also move one or more words by selecting them with the Move/Size tool active and then
using the arrow keys. Words will be move one pixel at a time or by the amount you have set for Snap-
to in Sketch tab of the Global Options Dialog (Chapter 17).

Reshaping an Arrow
To reshape an arrow, drag its handle. Arrow handles are visible when an Arrow tool is selected and
then the Move/Shape tool is selected. The arrow will be reshaped as you move the mouse. Release the
mouse when the arrow is the shape you want.

See the discussion of the "Arrow Class" above for more information on reshaping arrows.

Reattaching an Arrow
You can reattach an arrow that is going from one variable to another by grabbing the arrowhead and
dragging it to another word.

For example to change the connection from orders booked to cash flow into a connection
from orders booked to sales receipts you could just drag the arrowhead from cash
flow onto sales receipts.

You can reattach the origin (start) of an arrow by selecting an Arrow tool, clicking on the variable you
want to start from and clicking on the first handle in the arrow you want to redirect. In the above
example clicking on sales receipts and then the arrow handle would remove the link from
orders booked to cash flow and create a link from sales receipts to cash flow.

162
Resizing a Box or Circle around a Word
To resize a box or circle or other shape, drag the handle of the circle or box. The handle is visible
when you have selected the Move/Size tool and also for a short time after editing a variable name or
setting options on a word. When you press the mouse button, the size of the box in pixels will appear
in the Status Bar. As you drag, an outline of the new box or circle is drawn, and the size in pixels (at
100% resolution) updated in the Status Bar. Release the mouse when you are satisfied with the size
and shape.

For simplicity, all shapes are resized with a single handle. You can change the width and height of
boxes and triangles independently, but you can change only the radius of a circles, hexagons and
diamonds.
When you resize a box or circle around a word, the word will be broken into lines to fit within the
border. This wrapping will be displayed as you resize the word.

Wrapping Text
It is often convenient to wrap text appearing on a sketch, such as long variable names. The Variable
tool puts variables in a clear box by default. To place a word that is not in a clear box in one right
click (or Ctrl + Click) on the word and choose the Shape Clear Box. Vensim will automatically size
this to try to achieve a reasonable shape. You can also size the clear box as described above so that the
text wraps the way you want it to.
To remove word from a clear box just right click (or Ctrl+Click) on the word and select shape none.

Joining Words
If you have two words for the same variable in a view, you can join them into a single word. This
works with a Defined variable and a Shadow variable, or with two Shadow variables. (It is not
possible to have a variable that is defined more than once in a view so the third possibility is ruled out.)
To join two words, move the first word over the second (using any tool except the Lock tool, Magic

Wand or Delete). When the pointer is over the second word, its shape will change ( ) to indicate
that the words will be joined. When you release the mouse, the two words will become a single word
at the position of the second word. All arrows emanating from the two old words will now emanate
from the single new word. If you try to join two words representing different variables, the words will
overlap, but nothing else will happen.
The inverse operation of joining is accomplished by putting a new Shadow variable on the view, and
then using an Arrow tool to draw new connections.
The Merge tool allows you to join together words representing different variables, and also attach an
existing variable to a valve. The Merge tool is discussed in more detail above.

Variable Word Options


When you click with the right mouse button (or Ct rl + Click) on a word representing a variable, the
Options dialog for that word will be displayed, as shown here.

163
Hide Level sets the hide level for a word. Words that are not hidden have hide level None. When
you hide a word the arrows entering and exiting the words are also hidden. See the discussion of the
Magic Wand above.
Shape (None or By Type or Box or Clear Box or Circle or Hexagon or Diamond or Triangle or
Up Triangle) determines what shape, if any, will be drawn around the word. If you choose By Type, a
shape will be chosen based on the setting in the Sketch tab of the global options dialog (Chapter 17).
NOTE The Clear Box shape is used to force words to line wrap (without putting them inside a visible
shape).
Word Position (Inside or Below or Above or Right or Left) determines the position of the word
relative to the shape. This option only operates if you have selected a shape.
Shape Color allows you to select the color for the box or circle drawn around the word. Click on the
button to the right to select from a list of available colors. The word color is determined with the font
for the word.
Thickness allows you to set the thickness of the shape associated with the word. Thickness is
measured in Pixels. Setting a thickness bigger than 1 will result in an emphasized appearance of the
shape.

Background Color , if checked, will cause the shape associated with the word to be filled with a color.
This can be used for additional emphasis or visual contrast. Click on the button to the right to set the
color. Note that the color used does not need to be pure, and the color selection dialog can have a
different appearance than usual because of this.

Font Selection
The Word Options dialog contains a complete Font Selection dialog. You can choose a face, size and
attributes as well as setting color. More details on the Font Selection dialog are given in Chapter 15.
Use the color button of the Font Selection portion to change the color of the word. If you ask for a
word to be rendered Vertically it is usually best to use a True Type Font.
Equation closes the dialog box, applies any changes you have made, and opens the Equation Editor.
See Chapter 6 for more detailed information.

Sketch Comment Options


The sketch comment options are much like the standard word options, except there are some additional
choices.

164
Comment is the string that you want to appear. Type in any text you want. It will appear in the same
way a variable name would appear. This can be empty.

Graphics
You can make a comment that is a graphical element, with or without text. If you want to combine a
graphical element and text you must also choose a shape other than none, and a Text Position other
than center. The graphical element will be drawn inside the shape, and the text in the specified
position.
Image, if checked, is the image you want to appear. You can choose from a number of predefined
images. To select the image you want click on the drop-down arrow on the right.
Custom Bitmap, if checked, specifies the use of a custom Bitmap to be pasted from the clipboard.
This option is active only if an image is in the clipboard. Once you specify the use of a custom
Bitmap, you can no longer change this item (everything under comment type is grayed).
Custom Metafile, if checked, specifies the use of a custom Metafile to be pasted from the clipboard.
This option is active only if such an image is available. Once you specify the use of a custom Metafile
you can no longer change this item (everything under comment type is grayed). In general Metafiles
are preferable to Bitmaps because they can be scaled, and usually print better.
Import…, allows you to specify a bitmap file to be used for the image. This is more convenient then
using the clipboard with existing bitmap files. Once you specify the use of a custom Bitmap, you can
no longer change this item (everything under comment type is grayed).
Navigation (Navigate View, Load File, Open Web) allows you to select the type of navigation link
you would like. The content of the edit field to the right determines the destination for the navigation
action taken when the comment is clicked on with the lock tool selected. If the edit field to the right is
blank no navigation action exists.
? Navigate View, determines what view will be entered when you click on the comment. Use the …
button to select a view. If the view name is invalid nothing will happen.
? Load File, determines which file will be opened when you click on the comment. If the file is a
Vensim model (.mdl, .vmf), command (.cmd) or, for DSS only, interface (.vcd, .vcf) file Vensim
will open the file. If it is a graph definition (.vgd) file (Not PLE or PLE Plus) Vensim will load the
graph definitions. If it is a simulation (.vdf) file Vensim will simulate the model and put the results
in the specified file name. If it is a toolset (.vts, .sts) file Vensim will load that toolset (Not PLE or

165
PLE Plus). For all other files Vensim will ask the system to find the appropriate application to
open the file (this does not work on the Macintosh)
? Open Web, determines the web page that will be opened when you click on the comment. The
web page will be opened in the default browser. This does not work on the Macintosh.
Use as Arrow Junction, if checked, allows you to start and end arrows on this comment. This is
useful for splitting and joining arrows and making comments on arrows. If there are arrows coming
into a comment you cannot uncheck this but must first remove the arrows.
no cause, if checked, prevents an arrow junction from propagating causes. This allows you to create
loops with comment nodes for annotation purposes. If there are arrows coming into and leaving the
junction node this cannot be checked or unchecked. First remove the arrows if you want to do this.

Valve Options
The options for a valve relate to its shape, and the positioning of attached words (defined rates).

Shape
Valves can be vertical and horizontal bow ties, vertical and horizontal I beams, a circle with a cross
through it or invisible (the last option). This allows you make you to customize the appearance of your
diagram to meet your needs. Invisible valves are useful for naming rates or other concepts without
added visual complexity.

Valves can be resized by dragging the handle in their lower right hand corner. You can set the initial
size of valves from the Options dialog as discussed in Chapter 16.

Attachment
Attachment determines where the variable attached to the valve is placed. You can name a valve by
clicking on it with a Variable tool or using the Merge tool to merge an existing variable onto the valve.
When a valve is named, it moves whenever the name is moved.
The attachment positions are below, above, left and right. Note that the orientation of the word needs
to be changed from the word options.

Arrow Options
The arrow options are simpler than the word options. You can hide arrows or change their displayed
polarity and color. A right mouse button click (or Ctrl + Click) on the handle for the arrows, or on the
base of the arrowhead, (handles must be visible), brings up the Arrow Options dialog. Note that for
arrows going through valves and other junctions the dialog box will a title such as "Options for Arrow
from -junction- to Inventory." Here -junction- is the generic name for any word that is not a variable.

166
Arrowhead, if checked, causes the arrowhead to be displayed. For arrows going into junction nodes,
it is often useful to hide the arrowheads. Hiding arrowheads can also be useful as a means of
emphasizing the direction of physical flow.
Delay marking, if checked, causes a double line to pass through the arrow perpendicularly to the
arrow at the arrows handle. This is useful for marking a link as involving delays in Causal Loop
Diagrams.
Color allows you to select the color for the arrow. Click on the button to the right to select from a list
of available colors.
Line Style/Thickness lets you choose the line thickness you want, or dashed lines if appropriate. If
the arrow you are setting options for is a perpendicular line arrow, you can also choose among line
separation widths for the arrow. Click on the Radio Button to the left of the line you want.

Polarity (None or + or - or S or O or Other) determines the displayed polarity for an arrow. This can
be a useful ma rker in helping to identify the nature of causal connections as in:

+ births
population +

The displayed polarity is for appearance purposes only, and does not influence simulation. You can
choose + or S to indicate a link in the same direction and - or O to indicate a reversing link. You can
also use another character or characters by clicking on the other button and typing in what you want to
appear.
Font lets you set the font of the polarity associated with the arrow.

The polarity for an arrow will be shown at the Arrowhead or at the arrow's Handle depending on
which one you check. If the polarity is shown at the handle you can move it by moving the handle.
You can also set the polarity to be displayed inside or outside of the circle (or angle) formed by the
arrow.
Hide Level, sets the hide level for the arrow. See the discussion of the Magic Wand above for more
details on hiding.

167
Editing Equations
You can open the Equation Editor from the Word Options dialog or by Shift -control-clicking on a
word or by Shift-clicking with the right mouse button. Once the Equation Editor opens, you can
modify whatever equations you choose (see Chapter 6). When you finish with the Equation Editor, the
view you are working with will be updated with changes you have made.

The Check, Load, and Simulate commands will also start the Equation Editor if there are any hidden
warnings or errors in your model.

Sketch Workbench Interactions


When you are working with a Sketch Editor, many actions you take require the reevaluation of the
model. The most important of these are variable selection, navigation, tool invocation, and simulation.

Variable Selection
To select a variable into the workbench, select the Pointer tool and double click on the variable you
want to select into the workbench.
As you are adding new variables to the sketch, the types of those variables might not be known until
you actually enter equations. Thus the variable selection window will not always yield what you
would expect when searching by type. Searching by name and wildcard pattern matches (e.g..
*labor*) is more likely to give you the desired results.

Navigation
If you have filled in the navigation box on a comment, clicking on that comment with the Lock tool
selected will take you to the chosen view. You can also double-click with the Pointer tool, Arrow tool,
Rate tool, Existing Variable tool and Equation tool to move to the view.

Tool Activation
Tool activation assumes that a well-formed causal model with determinant dependencies exists. At
any time a sketch might or might not be well formed and complete. Each time you activate a tool, the
current sketch is checked to determine its conformance to these requirements.
If the sketch is lacking in any area (for example, missing an equation), Vensim applies interim patches.
You will not receive a message that something is wrong, but you might notice that, for example, the
Document tool shows an A FUNCTION OF equation indicating incomplete formulation. The menu
Model>Check Model command displays any hidden error messages.

Simulation
Simulation, unlike simple tool activation, requires a complete, well-specified model. When you ask to
simulate the current model, the model is checked, and if it is lacking the Equation Editor will be
opened for you to correct it. You will not be able to simulate the model until you correct all of the
errors. You can cancel out of correction and go on with other things. Nonetheless, it is impossible to
simulate a model that does not check out properly.
The Model>Check Model command performs the same checks as the Simulate command. If the
Model>Check Model command yields nothing more than WARNING and NOT USED messages, the
model can be simulated.
NOTE You can use the Model>Partial Simulation commands to simulate a model that is not fully
specified.

168
Free-Form Sketching
The Sketch Editor can be used to graphically build and modify models. But it can also be used as a
drawing tool to put up words and arrows that help structure thinking, discussion, or planning. In many
circumstances, the ability to attach equations to a sketch via the Equation Editor is not relevant. The
final product might simply be a word-and-arrow diagram, such as a Causal Loop diagram.
The Sketch Editor was designed to be flexible enough to work well in this forum. There is no
requirement that words correspond to model variables, or even that they correspond to a particular
variable type. Using only the Word and Arrow tools you can build up any form of diagram you
choose.

Sketching a Database
Combining Vensim's simple data entry mechanism with the Sketch Editor provides an elegant
mechanism for putting preliminary causal structure on a database. To do this, dump the database, run
the data through the Datasets Import command, and load the resulting dataset as a model. (See
Chapter 17 and Chapter 9 for discussion on the File>Open Model and the Model>Import Datasets
commands). Next, open the Sketch Editor on the model, adding arrows between data series you might
consider connected.
Select a data series name into the Workbench. The Strip Graph tool configured to show causes will
put that data series, and the data series you have marked as causing it, in one place and allow quick
evaluation of various hypotheses. You might also, if you wish, add additional intermediate variables
and equations to form a more complete mo del.

169
6 The Equation Editor

The Equation Editor lets you modify equations interactively and eases the burden of memorization
often associated with writing equations.
This chapter describes:
? The components of the Equation Editor.
? How to use the Equation Editor.
? The error-correction process.
? Graphical editing of Lookups using the Graph Lookup Editor.

Starting the Equation Editor


When you select the Equations tool in the Sketch Editor, clicking on a variable will open the equation
for that variable. When any other tool is selected, holding down the Shift and Ctrl keys and clicking
(or holding down the Shift key and right-clicking) on a variable will also open the Equation Editor on
that variable.
You can have an Equation Edit tool in the analysis toolset. When this tool is invoked the Equation
Editor will be opened on the Workbench Variable. This is most useful for units checking which
requires looking at the equations for a number of different variables.
Finally when you check the model (Model>Check Model) or attempt to simulate the model and
Vensim finds an error, if you ask to correct errors the Equation Editor will open.
When the Equation Editor is open, you will not be able to perform operations outside of the Equation
Editor until you close it. If equations are created that are inconsistent with the sketch, Vensim will
automatically update the sketch to keep it consistent.

NOTE You can resize the Equation Editor by dragging on the lower right-hand corner (though you
cannot make is smaller than its initial size). This will change the size of the editing window for
equations and can be useful if you have a big screen and a model with long equations.

Anatomy of the Equation Editor

The Equation Editor eases the process of writing equations by displaying the different things you
might want to put into an equation. In Vensim Professional and DSS, when you are working with a
model containing subscripts, the Equation Editor adds some features related to subscripting.

170
The top part of the window contains the equation, which is usually broken up into two or three
components. Below this are controls that let you select the type of equation you want to write, a
numeric keypad for entering numbers and the common operators, and a tabbed window that allows you
to enter variables, subscripts, functions, and a number of other items. You can enter the units of
measure for the variable, any comments you might with to make (on the meaning of the variable), and
assign the variable a group and a minimum and maximum range. A series of navigation buttons allow
you to move to other variables in the model. Buttons on the bottom let you close the dialog (OK and
Cancel), check the equation, check the model, and delete the current variable.
In discussing the functioning of the Equation Editor we will work our way down through the different
elements of the dialog box. When referring to a particular element, we will precede the discussion
with a picture of the element to clarify meaning and intention.

The Equation editor in Vensim PLE and PLE Plus is somewhat simplified and not all of the
functionality described below applies. Where the appearance of an element is significantly different in
Vensim PLE and PLE Plus the picture of the PLE appearance will appear to the right or below the
Standard, Professional and DSS picture.

Making Changes with the Equation Editor


From the Equation Editor, you can create or modify the equation, units, and comments for a variable,
and set other variable characteristics.

Entering Equations
The equation appears and can be modified in the Equation windows.

171
For normal Levels and for Auxiliaries being specially initialized, the equation is broken up into three
windows. The left hand side of the equation appears in the first window, the active part of the
computation appears in the second window, and the initial condition appears in the third window.
For most other variable types the equation is broken into two windows:

Here the left hand side of the equation appears in the first window and the right hand side appears in
the second window. Data variables that are not computed have only a single window representing the
left hand side of their equation (their name).
To the left of the equation, the assignment operator and Vensim functions used to define a particular
variable type are shown, such as = INTEG(. This part of the equation is placed automatically by
Vensim and shown only as a reminder of the functional form of the equation. Vensim will
automatically match any open parenthesis in this part of the equation and you will get a syntax error
message if you try to add one yourself.
You can edit the contents of the Equation windows directly by typing. In addition, to make
modification easier, variables, subscripts, operators, and functions that can be used in the equation are
displayed in different lists and buttons. These will enter values only into the Equation windows. If
you are editing a different field such as the units of measure these entry mechanisms will not function.

Positioning the Cursor


Clicking in one of the Equation windows places the cursor where you click, just as in other editing
windows in Vensim. You can also move between windows using the Tab key and the Shift+Tab keys.
Once inside a window you can move the cursor using the arrow keys or the mouse. You can select text
in the windows by dragging over it with the mouse or holding down the shift key and moving over it
with the arrow keys.
The first Equation window (variable name) will automatically scroll horizontally if you type a very
long variable name. The remaining windows will automatically wrap text horizontally and scroll
vertically. The active equation window always has a vertical scroll bar to allow you to position the
text.
NOTE If you want to start a new line in an equation, hold down the Ctrl key and press the Enter key.

NOTE Pressing the Enter key in the Equation Editor will activate the default control button, which is
normally the OK or Close button.

172
Selecting the Variable Type

The top window allows you to select the variable type, and the window below the subtype. You can
also mark a variable as Supplementary to indicate that it is not intended to be used in the model. The
type — subtype combinations are:
Auxiliary — Normal, Gaming to use the GAME function, with Initial to use the ACTIVE INITIAL
function, with Lookup to pass the entered equation through a built-in Lookup, Simultaneous to use
the SIMULTANEOUS function.
Constant — Normal, Tabbed Array to enter a tab delimited array of values.
Data — Normal (only a single window will appear), Equation to enter a := data equation.
Initial — Normal to use the INITIAL function, Reinitial to use the REINITIAL function.

Level — Normal to use the INTEG function, Sample if True to use the SAMPLE IF TRUE function,
Fixed Delay to use the DELAY FIXED function, Material Delay to use the DELAY MATERIAL
function, Information Delay to use the DELAY INFORMATION function, Special Integ to use the
SINTEG function.
Lookup — no subtypes.

Reality Check - Constraint to enter a condition and consequence, Test Input to define a test input
equation.
String — no subtypes.
Subscript — Normal to enter a normal Subscript, Equivalence to use the equivalence <-> mapping.
Time Base — no subtypes.

When you pick a type and subtype, the Equation windows will change appearance to reflect your
choice. If you make a choice that decreases the number of windows, going back to your old choice
will restore the content of the remaining window.
Supplementary, if checked, will prevent a Use Flag from being generated for a variable that is not
used in the model. If a model uses a variable marked as supplementary, a flag will be generated
informing you of this condition.

Editing Buttons

The {[()]} button matches delimiters and has no keyboard equivalent. If the cursor is on a delimiter —
a curly brace {}, bracket [] or parenthesis () — clicking on this button will move the cursor to the
matching delimiter. This is useful if you want to checknested function calls or long expressions. If the
cursor is not on a delimiter, nothing will happen. If you click twice on the Delimiter button you will be
positioned back where you started.
The Undo button undoes previous typing or variable additions in the window that has the focus. Undo
only stores one level of change information. That is, you can Undo your last action or, if you have just
clicked on the Undo button, Redo that action. Each Equation window keeps a separate Undo buffer. If
you are typing information and not clicking on names or buttons, you can use Control-Z to get the
same effect you get with the undo button.

173
Numeric Keypad

The numeric keypad allows you to enter numbers and the common operators into the equation.

Additional operators that are not contained in the keypad are available by clicking on the "More" tab to
the right (not shown here).

Variable List

The Variable list is displayed by default, and can also be accessed by clicking on the Variables tab to
the right of the keypad. the Variables list is used to enter variables from the model for use in the
equation. By default the Variables list will show the variables that are expected to be inputs, either
because arrows have been drawn in a sketch, or because an equation has previously been entered. The
variables are listed in alphabetical order. The exception is for Level equations in which the first
variable in the input list is always the variable for which an equation is being written.
If you are creating an equation and the Equation window contains the cursor, clicking on a name in the
Variables list will enter that variable at the position of the cursor. If you select a variable has
subscripts, the subscripts will also appear in the equation. Thus, clic king on the name task is
done in the Variable list might put task is done[task] into the equation. The appropriate
Subscripts for a given variable are determined from the equations (if any) for the variable and from
other equations that use the variable.
The Choose Variable... (Choose Initial Variable…) button at the top of the list will bring up the
Variable Selection dialog. This allows you to do wildcard searches on variable name. You can select
any variable from this dialog by clicking on the variable name and clicking OK. The Variable
Selection dialog does not limit the choice of variables to expected inputs. In Vensim PLE and PLE
Plus this button is only active when working on the initial value of a level.

174
(Not PLE or PLE Plus)

You can also use the Variable Type selector to see variables other than the expected inputs. Click on
the down arrow to the right of Inputs. A list of the different selections will appear. Select All to
display every variable in the model or another selection to display variables filtered by type. Just click
on the selection you want. If you use this technique to review model variables be careful not to click
in the list until you have chosen which variable to add. A single click in the variable list adds the
variable to the equations.
If you do include new variables as inputs to an equation, or omit old inputs, you will be informed of
this and asked if you want to update the input list. If you update the input list, the sketch information
will be modified accordingly. If you do not update the input list, the equation you are working on will
be marked as invalid even though it might contain no errors.
NOTE Subscripts and Functions do not appear in the Variable list since these can be accessed through
the Subscript and Function lists.

Subscript List †

To access the Subscripts List, click on the Subscripts tab to the right of the number pad. This will
only be available if you are working with a model that has subscripts. The list shows Subscript Ranges
and Subscript Constants in the model. You can use these to replace the default subscripting supplied
through the Variable list, specify new Subscripts for variables, or enter stand-alone Subscripts in an
equation in the limited number of places they are allowed.

As with the Variable list, you can use the Subscript Type selector to see different things. Select Range
to see all Subscript Ranges and Subranges. Click on a particular Subscript Range (such as Age) to see
all of its elements. You can also click on *All Elements* to see all elements of all Subscript Ranges.

175
Function List

To access the Functions List, click on the Functions tab to the right of the number pad. The Function
list shows a list of available functions of the class you have selected. When you click on the name of a
function it will appear in the Errors line at the bottom of the dialog with its list of arguments. You can
use the letters in the keyboard to move to different positions in the list. When you have found the
function you want click on the Add Sel button (or press the Enter key) to enter the function into the
equation. It will appear followed by parentheses ( and an argument descriptor list. The first argument
descriptor in the list will be highlighted. You can double click on the arguments descriptors to
highlight them and then replace them with the argument you want
(Not PLE or PLE Plus) If you have checked the No Arg List checkbox in the Sketch tab of the Global
options dialog the instead of argument descriptors a series of commas , will be placed in the equation
between parentheses ().
(Not PLE or PLE Plus) From the Show Class selector you can access up to nine types of functions:
Common, Simple, Dynamic, Defining, Lookup, Reality Check, Macros, Data Only and User Defined.
Click on the down arrow at the right of the selector to choose from the list.
? Common functions are the most commonly used functions. They are put into a relatively short
list for convenience.
? All is a comprehensive list of all functions and keywords.
? Simple functions are built in functions that have no dynamics. They take 0 or more inputs and
return an output that is independent of the values of the inputs at previous times.
? Dynamic functions depend on their inputs and the value of their inputs at previous times.
Dynamic functions are implemented as macros to allow you to look into the dynamics of the
function.
? Discrete/Delay are functions that support discrete event and entity modeling and include the
DELAY… and QUEUE… functions.
? Lookup functions lists those Lookups that have been defined for the current model. Lookups are
defined as a series of x,y pairs, most commonly using the Graph Lookup Editor described later in
this chapter. All Lookups take only one argument.
? Reality Check functions are those associated with reality checks as described in Chapter 9 of the
Modeling Guide.
? Data Only are functions and keywords that are used only in data equations. These are separated
out since their behavior is very different from that of other functions. See Chapter 2 for more
discussion of data equations.

176
? Array functions operate on Subscripted variables.
? Macros † are macros you have defined in the model. You must define these indirectly, as
discussed in "Modifying Macros" later in this chapter.

? User Defined‡ functions are external functions that you have defined for use with Vensim. This
menu Item is available only if you have specified an external function DLL.
Additional Input Buttons

To access additional input buttons click on the More tab to the right of the number pad. This tab
contains relational operators and logical keywords for use with IF THEN ELSE and SAMPLE IF
TRUE. It also contains the characters contained in subscript equations (including the ! for the SUM,
PROD, VMIN and VM AX functions).
The curly brackets {} can be used to comment out part of an equation.

:IGNORE: is intended to aid in using Vensim's partial simulation capabilities. If you have written an
equation that does not use all the inputs, but wish to keep the exis ting input list, click on the
:IGNORE: button and the excluded variables will be added after the :IGNORE: keyword. As you
change the equation the :IGNORE: button will update the list of ignored variables for the equation.
:AT LEAST ONCE: and :CROSSING: are keywords that are used in Reality Check definitions.

Ctrl + Enter will place a hard carriage return inside of an equation. The default behavior of the
Equation Editor is to simply wrap equation to fit in the editing window. You can break up lines by
holding down the Ctrl key and pressing Enter.

As Graph Button

The As Graph button is located just below the Supplementary checkbox and is only visible when the
equation type is Lookup or Auxiliary with Lookup. Clicking on this button will open up the Graph
Lookup Editor, discussed later in this chapter.

Help Button
The Help button is located just below the Supplementary checkbox. Clicking on it will open up the
help system on the Vensim Manuals. This is a convenient way to check such things as function usage.

Specifying Units

The units of measure are used to check a model for dimensional consistency. Type the variable's units
of measurement in the editing box. Units of measure are restricted to using only * / and ( ) operators.
When the units are checked using the Model>Check Units (or Ctrl + U) command, any errors are
reported.

177
In addition to being able to type in Units, a list of the existing units of measure is available (this list
also include the commonly used Dmnl). Clicking on the down arrow to the right of Units will display
this list, and you can then click on any element in the list to place it into the Units box. You can edit
the units of measure to modify whatever is in place.
The units of measure will be checked to be sure they are dimensionally consistent when you check the
equation. Problems with the units of measure are reported when problems with the equation are
reported.

To remove units of measure that are no longer used from the list of available units, you will need to
use the Model>Reform/Clean command, or close and reopen the model.

Setting the Range

You can specify the range for a variable by typing values in the Range boxes. During simulation, the
value the variable takes on will be checked against this range and a report will be issued whenever the
range is exceeded. See Chapter 8 for more discussion.
For Constants the range is used to set up sliders in SyntheSim. In this case the last element is the
Increment for the slider. The increment is ignored for other variable types. You can use an increment
equal to the range for variables that are intended to work as switches.
Leave the range elements blank to disable range checking. A blank minimum will disable low-value
checking, and a blank maximum will disable high-value checking. Entering an NA is the same as
entering a blank.

Specifying the Group (Not PLE or PLE Plus)

You can use the Group entry to specify the Group for a Variable. Clicking on the down arrow to the
right will open a list of Groups defined for the model. The default group name is the same as the
model name.
You can also type in the name of a Group. This will create a new group if no group of that name
already exists.

Adding a Comment

A comment is a explanatory statement that you can attach to a variable. A comment should not
include tildes ~ or bars |, but can include other symbols. The lines in the comment automatically wrap,
so you won't have to press the Enter key, but you can break them up by holding down the Ctrl key and
pressing the Enter key.

178
For Lookups a special delimiter \! is used to separate the comments into a title, y axis label and x axis
label. This punctuation is used and maintained by the Graph Lookup Editor and you do not need to
enter it yourself.
In addition to the Equation Editor, comments are used in the Document tool and appear in the Text
Editor. Adding comments can help others understand your model. For example, you might want to
include information about the reason for the chosen formulation, or other pertinent information.
There is no limit to the length of a comment.

Navigation inside the Equation Editor (Not PLE or PLE Plus)


You can use the Equation Editor to move between model variables without closing it and going back to
the sketch. Use the buttons near the bottom following Go To:.

Prev moves you to the equation for the variable preceding the current variable in alphabetical order.
You can use Ctrl+PgUp as a shortcut for this.
Next moves you to the equation for the variable following the current variable in alphabetical order.
You can use Ctrl+PgDn as a shortcut for this.
Hilite moves you to the variable that you have highlighted in the Equation, Comment or Units
windows. If it Vensim cannot find the variable you will be asked if you want to create it. If you have
not highlighted anything or Vensim cannot interpret what you have highlighted you will get an
Incomplete Selection message.
NOTE If you highlight a Subscript Element in then click on the Hilite button Vensim will ask you if
you want to rename it.
Choose allows you to choose from the list of variables. When you select the Choose button, a
Variable Selection dialog (see Chapter 15) will appear. Select the variable you want and it will be
brought into the Equation Editor. The Choose button can be used to move to any equation. If you type
in the name of a variable that does not exist you will be asked if you want to add that variable to the
model.
New allows you to create a new variable. The is useful if you wish to add variables within the
Equation Editor.
If you have made changes to an equation and use any of the Variable buttons, your equation will be
checked for Syntax Errors. If a syntax error is found it will be reported, and you will not be moved to
another equation. In this case, pressing the button again will move you to another equation. You can
also correct the syntax error.

Navigating Subscripted Equations†

The advantage of working with subscripted variables is that one equation can represent many different
elements. Nevertheless, it is sometimes desirable to have different equations. This is true if constant
values differ across instances of a variable, or less commonly, if different elements have distinct
structural relationships. If you open the Equation Editor on a variable with multiple equations the Title
Bar will show how many equations there are and which one you are working with (such as the first of
two in the diagram above). The two controls on the right allow you to move between these.

179
The combo box indicates the current equation number. Clicking on the down arrow will let you
choose which equation to move to. This list always ends with *New, and you can click on this to
create a new (and empty) equation for the variable.

Shortcut: You can also use Ctrl+? to move to the previous equation in the list and Ctrl+? to move to
the next.
Del deletes the equation you are currently working with. If you click on this you will be asked to
confirm the deletion.
If the current variable only has one equation, the Del button will be replaced with an Add Eq button.
If you are working with a model that does not have subscripts defined this button will be grayed.

The Errors Line

The Errors line displays error messages relating to the status of the current equations and the model as
a whole. The Errors line is updated when you click on the Check Syntax or OK buttons. If there is a
syntax error in an equation, the Errors line will report the nature of the error and the Equation with the
error will be put in the Equation window (if it is not already there). Since only one syntax error will be
reported at a time, the down arrow to the right is grayed when syntax errors are detected.
When there are semantic errors in a model, more than one error can be reported at a time. In this case,
clicking on the down arrow at the right of the Errors line will open the list of errors. (The error window
might open above the line as shown here if there is not sufficient room below the Equation Editor to
place it.)

Selecting any one of these errors will bring the associated problem equation into the Equation Editor.
You can move through the errors as you like using this mechanism until you make a change to an
equation. Once you have changed an equation, you must click the Check Model button again to get a
new list of the problem equations. See Chapter 3 for more discussion on finding and fixing model
errors.

Dialog Control Buttons


The buttons on the bottom have a different appearance depending on what has been done in the
equation editor. Three common appearances are:

Changes made through the Equation Editor are applied incrementally to the model. Because of this,
valid actions will depend on what you have done while in the Equation Editor, and the labeling and
availability of the Dialog Control buttons reflect this.

OK/Close
OK is the normal closing button for a dialog. It indicates that the changes you have made are to be
kept and the dialog closed. When you click OK the equation you have entered is checked for syntax
errors. If there are none, the dialog is closed.

180
If your equation has a syntax error, the error is reported. The OK button will change to a Close button.
Clicking on Close forces the Equation Editor to close, even though the equation contains a syntax
error. The variable will be marked as having a bad equation. The next time you open the Equation
Editor on this variable, the error window will contain:

If you have clicked on the Check Model button discussed below and semantic errors have been found
the OK button will be relabeled Close. Clicking on Close will close the Equation Editor. If the
Check Model button was reporting semantic errors you will not be able to simulate the model, but you
can continue to modify it and apply tools to it.
If the Check Model button was reporting only Use Flags and NOT DEFINED variables, you will be
able to simulate the model. Note that to simulate a model with NOT DEFINED variables, you must
load a dataset containing these variables (See Chapter 9).

Check Syntax
The Check Syntax button checks and internalizes the information you have entered for the current
equation without closing the Equation Editor. When you have an equation with existing errors (the
error line says Incorrect/Incomplete Equation), the Check Syntax button can be used to determine
what and where the errors are. Note that in some cases an equation marked incorrect might not have a
problem. This can happen if the cause of a variable is removed and then added back using the Sketch
Editor.
Check Syntax will record all the changes you have made to the equation, comment, units, range,
group, or supplementary status of the variable. What happens when you select it depends on whether
or not there are syntax errors in the equation or units definition you have entered.
? If there are no syntax errors, clicking on Check Syntax puts the message "Equation OK" in the
Errors line.
? If there are syntax errors, clicking on Check Syntax will report the error in the Errors line and
position you at the source of the error in the equation or units.
Check Model
Click the Check Model button to internalize changes you have made to the current equation, and
check for any semantic erro rs in the model. If the equation you are working on has been changed, the
Check Model button first checks the current equations for syntax errors. If there are syntax errors, the
Check Model button has the same effect as the Check Syntax button. You will be informed of and
positioned at the error. If there are no syntax errors, the model will be checked for any semantic errors,
variables that are not defined, and variables that are not used.
If there are any errors (syntax or semantic) or any USE FLAG or NOT DEFINED messages, the
Equation Editor will stay open. The problems will be reported and you will be positioned at the source
of the syntax error. If there are no syntax errors, you will be given the choice of a number of problems
to review. See "Syntax Errors" and "Semantic Errors" below for more detail. If there are syntax errors
the Check Model button will be grayed.

Delete Variable
The Delete Variable button deletes the variable you currently have in the Equation Editor from the
model. This is a global change that will delete the variable from every view it appears in. You will be
prompted to be sure you want to delete the variable.

Deletion of variables can be done in the Sketch Editor with the Delete tool. The Delete Variable
button is provided as a convenience for situations in which the variable you want to delete does not
appear on a view. You can, however, delete a variable with this button whether or not it appears on a
view.

181
Cancel/Revert
Clicking on the Cancel buttons cancels any changes you made in the Equation Editor and closes the
window without making changes to the model. The Equation Editor changes the model you are
working on directly, and the Cancel button is available only before you have made changes to the
model with the OK, Check Syntax, Check Model or Delete Variable buttons. The purpose of the
Cancel button is largely to assure you that nothing has been changed and to allow you to escape from
accidental keystrokes.

If you have made changes to the equation for a variable and ask to edit the equation for another
variable, the Cancel button will be relabeled "Revert." Revert allows you to return an equation you
are editing to the state it was in before any changes were made. The Revert button is available while
you are making changes but before you use the OK, Check Syntax or Check Model buttons. Once
you change the model relative to the equation you are working on, the Revert button is grayed.

Correcting Errors
The Equation Editor lets you easily correct errors in the equation you are working on, as well as in
other equations in the model. For a more complete discussion of error types and their meaning see
Chapter 3. The following relate to issues specific to the Equation Editor.

Syntax Errors
Syntax errors are reported when you click either the Check Syntax button or the Check Model button.
If there is an error, it will be reported in the Errors line, and you will be positioned as near as possible
to the occurrence of the error in either the Equation or Units window. If there are multiple equations,
you will be positioned at the equation with the error.

Adding Variables to a Model


If you have entered any variable names that are new to a model, when you click on Check you will be
asked if you want to add the variable to the model. If you have typed in the wrong name by mistake,
answer no. The equation will be treated as though it had a syntax error, and you will be positioned in
the Equation window at the location of the new variable. Correct the spelling and click on the Check
button again. If you did intend to add a new variable, answer yes, and the processing of the equation
will continue.
You cannot add a variable to a model in this manner with Vensim PLE or PLE Plus.

Changing the Input List


If you have left any variables in the input list out of the equations, or added variables that are not in the
input list to the equations, you will be asked if you want to update the input list. If you answer yes, the
input list will be changed, and the associated sketch, if any, updated. If you answer no, the equation
will be treated as though it had a syntax error, and you can remove or add variables as appropriate.
You cannot update the input list in this manner with Vensim PLE or PLE Plus.

Ignoring Syntax Errors


If you choose to ignore a syntax error, the equation(s) for the variable will be stored literally, with the
error included. Internally the equation will be kept as an A_FUNCTION_OF equation, meaning that
the equation is not complete, though a list of desired inputs might be available. If the incorrect
equation contains variables not on the input list, the equation will not be properly updated if you
change the names of these variables. For example, if the inputs to Population are births and
deaths, and you have the equation
Population = Integ(births-deaths,POPULATION_INIT + ?)

182
(which has an incomplete initial value), when you change the variable POPULATION INIT to
POPULATION INITIAL, the equation for population will not change. If, on the other hand, you
immediately correct the equation for Population and update the input list, then changes to the name
of POPULATION INIT will be reflected in the equation for Population.

Semantic Errors and Messages


A semantic error occurs when, even though each equation looks OK by itself, the equations do not fit
together. Generally this is because of problems with subscript usage and simultaneous equations.
Messages normally relate to variables that are used in a model but never defined, or variables that are
defined but never used. The OK and Check Syntax buttons do not report semantic errors or
messages, but the Check Model button does.
When you press the Check Model button, Vensim attempts to take the information in the equations
and coordinate it into a model that is well formulated and can be simulated. If there were any syntax
errors in any equations this is not possible, so the Check Model button acts like the Check Syntax
button and does not try to analyze the model as a whole.
If there are no syntax errors in the equation you are working on, but the mo del contains semantic
errors, incomplete equations, or USE FLAG and NOT DEFINED variables, a list of problems is
displayed. At this point you can click on one of the reported problems and the equation associated
with the problem will be brought into the Equation Editor. You can correct this equation, then again
select the Check Model button until all problems have been dealt with.
Note that USE FLAG messages are reported when you press the Check Model button, even though
they are usually benign. You can prevent USE FLAG messages from being reported by setting the
Supplementary flag, or ignore the messages.

Ignoring Semantic Errors


If there are syntax or semantic errors, the OK button is relabeled Close. Clicking on this button allows
you to close the Equation Editor and defer making changes to the equations, or make the changes with
other tools. The errors still exist, and you will not be able to simulate the model.

If there are no errors, but messages are reported, the OK button is also relabeled Close. Clicking on
this button closes the Equation Edit window. A model for which messages are reported can be
simulated. However, if a variable is reported as NOT DEFINED, you will need to supply data for that
variable before you can simulate the model.

Editing Lookups

Lookups are treated just like other variables in Vensim in that they can have subscripts, units
equations, and comments. You can type in the equation for a Lookup using the format described in
Chapter 2, as in:
((0,0),(.2,.1),(0.8,1),(1,1))
A graphical entry can be a desirable alternative because you can visualize the shape and nature of the
function. To create or manipulate Lookups in graph form, you use the Graph Lookup Editor.

The Graph Lookup Editor can be used from the Equation Editor, during simulation setup, while
running a Venapp and from the Text Editor. From from the Equation Editor, the Graph Lookup Editor
is opened by clicking on the As Graph button. This button is only visible if the variable type is
Lookup or Auxiliary with Lookup. If you want to change a variable to a Lookup, use the variable type
combo box to select Lookup or Auxiliary and subtype "with Lookup."

183
The Graph Lookup Editor is a graphical way of entering the x,y pairs for the Lookup. When you open
the Graph Lookup Editor on a new Lookup, the graph will be empty with scales running from 0 to 10.
You can type commentary into the editing window just below the graph title (e.g., "Graph
showing..." above). This commentary comes from, and goes into, the comment field in the Equation
Editor. If you open the Graph Lookup Editor from somewhere other than the Equation Editor this text
will be displayed, but will not be editable.
Export exports the lookup to the clipboard. The graph as it currently appears is exported as a
Windows Metafile (or in PICT format on the Macintosh). The values are exported as two tab
delimited lines of text. If you want to paste the graph into another application you might need to use
Paste Special in the application.

Print prints the graph as it currently appear. You will get the same print options as you would with
other Vensim graphs.
Input/Output provides a mechanism for typing in x,y pairs. Simply type in the numbers you want.
Pressing the Tab or Enter key or clicking outside the cell will make your entry official, and the
corresponding point will be changed. You can also add new numbers at the bottom of the list or just
below where it says New (the New pair is always empty). You can edit an entry but not delete it. To
remove or delete a point, you need to use the Clear Points button and click on the graph (see below).
The Input/Output pairs are always stored in ascending x order. Because of this, entering a new x-value
can cause things to jump around. If you try to enter a bad number, you will be notified.
The scroll bar to the right of the Input/Output pairs can be used to review all points when there are
more then 11 pairs. There is no limit to the number of pairs in a Lookup.
New is the same as the Input/Output pairs except that it allows you to add new points to the graph.
Just type in an x,y pair. The pair will go into the list above and the New entries boxes will be cleared.
Import Vals allows you to take data that is in the Clipboard and bring it into the Lookup Editor. This
data will replace whatever values currently exist. Vensim will look for Tab or Comma delimited data
in the Clipboard. If it finds two lines of data it will treat the first as X values and the second as Y

184
values. If it only finds one line, it will treat this as Y values and query you for an appropriate starting
value and increment for the X axis. If the first entry in the data is a name, it will be ignored.
The graph itself can be used to modify the Lookup. See "Moving Points" and "Tracing Lines" below.

The input is... appearing in the bottom window (under the X-axis) is an additional part of the comment
that describes the X axis. In the Equation Editor, it is separated from the comment at the top by the
special character sequence \!. You can type in what you want here. Just as with the comment at the
top, it will appear as uneditable text when the Graph Lookup Editor is used from someplace other than
the Equation Editor.
X-min and X-max allow you to control the horizontal scaling. This is useful if you want to focus on a
few points or add new points well outside of the old scales. Since lookups can have any interval
between x-axis points, it is often desirable to leave off one or both of the end points and concentrate on
the middle points. You can click on the down arrow at the right of the values or type in a value and the
graph will rescale. The values you set for X-min and X-max will be recorded for your next use of the
Lookup Editor, but they do not affect simulation output.
You can also change X-min and X-max by holding down the Shift key and dragging the pointer over
the range you want to zoom in on.

x= , y= shows the x and y values associated with the current pointer location when the pointer is on the
graph. This tells you what values will be associated with a point you place at the current location.
Y-min and Y-max allow you to control the vertical scaling. This is useful if you want to focus in on
a few points, or if you want to add points well away from the current scale settings.
You can type in any value you want for Y-min and Y-max. As you type the graph will automatically
adjust to the scale you are entering. Clicking on the down arrow to the right of the value allows you to
select from commonly useful values. The values you set for Y-min and Y-max will be recorded for
your next use of the Lookup Editor, but they do not affect simulation output.
You can also change Y-min and Y-max by holding down the Control key and dragging the pointer
over the region you want to zoom in on.
The values of existing points will not change when you change Y-min and Y-max.

Reset Scaling resets all of the scaling points (X-min, X-max, Y-min, Y-max) so that the Lookup fits
comfortably into the graph. You can set the separate scaling points individually to focus on certain
values.
Whenever you move a point outside of the visible graph, the graph will automatically be rescaled to
include that point. If, however, you have previously set any of the scaling points, not all the points in
the Lookup will necessarily be visible. The Reset Scaling button makes all points visible.
The output... appearing in the right hand window (under Y-max) is an additional part of the comment
that describes the Y axis. In the Equation Editor it is separated from the comment at the bottom by the
special character sequence \!. You can type in what you want here. Just as with the other comment it
will appear as uneditable text when the Graph Lookup Editor is used from someplace other than the
Equation Editor.

Clear Points/Add Points toggles between point deletion and point insertion modes. You can add new
points to a Lookup by clicking anywhere. To delete points, first click on the Clear Points button
(which will become an Add Points button), and then click on the points you want to delete. If you are
adding points, the standard pointer will be present. If you are clearing points, the delete pointer ( )
will appear.
Clear All Points clears all the points in the Lookup. This is useful if you want to start over.

Cur->Ref makes the current set of points the Reference Points. Reference Points appear in light gray
and can be useful as a baseline for drawing a graph. For example you might want to enter a straight

185
line from 0 to 1 to highlight the difference in the curve you are drawing from this straight line. You
can also use this to change record the previous graph for reference as you make adjustments. Note that
when you click on Cur->Ref you will not see the reference line since it will be beneath the current line.
Clear Ref causes the reference line, if any to be removed.

Ref->Cur causes the reference line to replace the current graph line. If there is no reference line
nothing will happen.
NOTE The Enter and Esc will not close this dialog. If you are deleting points the Esc key will put the
Lookup editor back in add-point mode. Otherwise there is no effect.

Moving Points
You can drag existing points up and down and back and forth by pressing the left mouse button down
while over a point and dragging the point. You cannot drag a point before the previous point on the X-
axis or after the next point on the X-axis.

Tracing Lines
You can trace a line by dragging the mouse across the screen. To do this press the left mouse button
away from all existing points and move the mouse. The x-axis positions of all the points will remain
fixed, but the points will jump up and down the y-axis to meet the pointer.

Creating Subscripts†
You can define and modify Subscripts from within the Equation Editor. Usually the Equation Editor is
open on Subscripts from the Subscript Control (Chapter 11) using either the New or Edit buttons. You
can also use the New and Choose buttons in the Equation Editor to go to subscript equations.
Once you have the Equation Editor open for a subscript, you can simply type in the subscript equation
as in:
v1,v2,v3,v4
Be sure that the variable type is set to Subscript !

The use of mappings and equivalences is governed by the rules discussed in Chapter 2. The mapping
symbol -> is available on the More tab next to the number pad.
There are no restrictions as to when you can add or modify subscripts, and nothing to prevent you from
typing one into an equation before it is defined. But as a general rule, it is probably a good idea to
define subscripts ahead of time, so that they are readily available for use in equations.
NOTE Before you define any subscripts, the simpler version of the Equation Editor will be used.
Once you define your first subscript you should close the Equation Editor and reopen it to make full
use of the subscript features of the Equation Editor. Thereafter, when you open the Equation Editor
with the model, the subscript features will appear in the Equation Editor.

Modifying Macros†
While you can freely use macros in the Equation Editor, there is no facility for entering or changing
them. To enter and alter macros, the Text Editor must be used. To do so, close the Equation Editor
and select View>As Text from the Sketch Editor's menu. Add and alter Macros as needed, then select
View>As Sketch from the Text Editor's menu. All of the sketch information will be retained through
this process.

As a general rule it is probably wise to define useful macros at the time you create the model. This
will keep the model development process much simpler. Generic catalogs of macros can, if desired, be
included in every model, to be invoked when needed.

186
Variable Types
As you enter and modify equations with the Equation Editor, they are incrementally added to the
model and classified as to type when possible. Still, determining the type of a variable cannot always
be done ahead of time and can be difficult when there are syntax errors and incomplete equations. If
you have trouble finding a variable for input using the Variable Type selector, you might need to try
the type All. If you want to get the equation for a variable, pattern matching is likely to be the most
effective way of finding the variable.

Because many variables types are determined by what appears on the right hand side after the equals
sign = it is possible to write an Auxiliary equation and have it open as a level. This would happen, for
example , if you entered a DELAY FIXED function into an Auxiliary equation. In fact, this can be a
convenient way to get prompts for the meaning of the different function arguments.

Returning from the Equation Editor


Whenever you close the Equation Editor, Vensim will try to make sense of what you have entered. If
the model has problems, these will be marked, and whatever causal structure can be interpreted will be
interpreted. In this manner it is always possible to do causal tracing, though for subscripted variables
the accuracy of the causal tracing can be limited.
When you use the Equation Editor to make a change to the structure of the model Vensim will check to
be sure that the sketch information for the model is also updated. If, for example you remove a
feedback link, Vensim will remove that feedback link in any views it may have appeared. When you
close the Equation Editor the Sketch Editor will sometimes flash because of this updating. This can
happen independent of whether you launch the Equation Editor with a Sketch tool or by clicking on an
Equation Editor tool on the Analysis toolset.

187
7 The Text Editor†

The Text Editor is a simple general-purpose editor that can be used to edit any ASCII text file. The
Text Editor has special features to speed and ease editing of Vensim models, Venapp files, data files,
command files and graph definitions.
The Text Editor is only available in Vensim Professional and DSS.
This chapter describes how to:
? Use the Text Editor to write and edit Vensim models.
? Use the Text Editor with Venapp definitions.
? Use the Text Editor with command files.
? Use the Text Editor with data files.
? Use the Text Editor with graph definition files.
? Create and interpret backup and history files.
? Use sketch information in the Text Editor.

Using the Text Editor

The text editor opens automatically if you start editing a model in text format. You can do this by
selecting the View>As Text command when working with the Sketch Editor or by using the File>New
Model command. The Text Editor will also open whenever you open a model that was last saved from
the Text Editor.
You can also start the Text Editor from the File>Edit File… command or by clicking on the Text
Editor icon in the Workbench if you have set up your toolset to contain the icon. When you use the
Text Editor icon, the File Selection dialog will open asking you for a file to edit. You can set options
on the Text Editor to determine the default file type displayed when the File Selection dialog opens.
Regardless of the options, however, you can edit any text file with any extension. If you attempt to
open a file with a .vmf or .mdl extension, Vensim will attempt to load the file as a model.

Notes on Text Edit Behavior


? You cannot have the Text Editor and the Sketch Editor open on the same model at the same time.
? When you exit Vensim, you are prompted to save any changes that you have made to models and
text files.
? Different versions of the Text Editor have their own menus for View and Edit as described below.
? You can open as many Text Editors as you like. If you try to open more than one Text Editor on a
given file you will be asked if you want to open it in read-only mode. Only one copy can be open
for modification at a time.
? You can have as many models open in the Text Editor as you want, but only one model can be in
the Workbench at a time. The Workbench model is the model you are working on unless you
have put Vensim in off-line mode.

Text Editor Tool Options


You can put one or more icons for the Text Editor into the Analysis Toolset. In so doing, you can set
up the Text Editor to open a particular type of file.

188
When you activate the Text Editor from the Analysis tools (or by using the File>Edit File command),
the File Selection dialog will appear, prompting you for a file to edit. The list of files in this dialog
will depend on which setting you previously chose. Once the File Selection dialog is open, however,
you can choose any type of file you wish. See Chapter 15 for a complete discussion of the File
Selection dialog.
? .dat data files loads a Data source file (.dat).
? .cin constant files loads a Constant Input file (.cin).
? .vgd graph desc loads a Vensim Graph Definition (.vgd) file.
? .prm optimization loads an optimization Parameter (.prm) file.
? .vcd Venapp loads a Venapp Custom Description (.vcd) file.
? .* Custom type allows you to specify your own file type for the initial setting on the File
Selection dialog.
File Extension, if you have selected Custom Type, allows you to type in the default file filter for the
File Selection dialog.
visual (wysiwyg), if checked, will cause the Venapp Editor to open on a .vcd file. The Venapp Editor
is discussed in Chapter 3 of the Vensim DSS Reference Supplement.
Font lets you set the font with which the Text Editor will open. You can also change the font from
within the Text Editor.

The File Menu


Several commands on the File menu work differently for the Text Editor.

Save As
Save As saves a copy of the file in the Edit window to another name. You are prompted for a file
name. If the file name you select already exists, you are asked if you want to overwrite the file. A
new history file is started for the renamed file containing changes relative to the original file the last
time it was saved.
‡ If you use Save As to save a .vcd file to a file with the .vcf extension, the file will be saved as a binary
Venapp description file. Such files are somewhat faster to load than .vcd files and also a little more
secure, but their main function is to create packaged applications as described in the Vensim DSS
Reference Supple ment.

Load/Load Custom/Run Venapp/Run Command/Dat2VDF


Load takes the model in the Text Editor and loads it into the Workbench. This option is only available
when Vensim is in off-line mode. Otherwise, the model you are working with in the Text Editor is
automatically loaded into the Workbench. If necessary, load will first check the model.

189
Load Custom takes Custom Graph descriptions and loads them into Vensim for use in the Custom
Graph control. Any errors are reported in a separate error window.

Run Ve napp‡ runs the file as a Vensim application. Errors, if detected, will be reported in a separate
window. You will be given the opportunity to abort the operation. See the Vensim DSS Reference
Supplement for more information.

Run Command‡ runs the file as a Vensim command script. Errors, if detected, will be reported in a
window and you will be given the opportunity of aborting the operation. See the Vensim DSS
Reference Supplement for more information.
Dat2VDF converts the data in the file into a .vdf file. The new file will have the same name as the file
with which you are working but with the .vdf extension. If this file exists, you will be queried for the
name of the .vdf file you want to create. An error window will appear showing any error detected, and
what data were written.

The Edit Menu

The Edit menu provides basic control over editing the file with which you are working. This Edit menu
is specific to the Text Editor and will be grayed out or look different if you are working in a different
window, such as the Sketch Editor.
Undo allows you to reverse any changes that you have made. The Text Editor records changes on a
line-by-line basis as discussed in the section on history and backup files. You can undo all changes
since your last save. Undo requires that the file be named and that the backup file has been
successfully opened. Ctrl-Z is the same as Undo.
Redo allows you to redo any changes that you have undone. You can Redo until you get back to the
first undo. This allows you to go through an entire sequence of changes. Redo only works directly
after an Undo.

If you undo some things and then make changes (such as typing in new information), Redo will not
work on the previous Undoes. Ctrl-A is the same as Redo.
Cut cuts the highlighted text to the clipboard, removing the text from its current position in the file.
All information goes to the clipboard as plain text. Ctrl-X and Shift-Del are both the same as Cut.
Copy copies the selected (highlighted) text into the clipboard, leaving the text in its current position in
the file. Ctrl-C and Ctrl-Ins are both the same as Copy.
Paste inserts the contents of the paste buffer (clipboard) into the current file at the cursor position. The
contents of the paste buffer remain unchanged. You can only paste text into the Text Editor. Ctrl-V
and Shift-Ins are both the same as Paste.
Select All selects the entire contents of the Text Editor. This is a shortcut to simplify placing
everything into the clipboard.

190
Find searches for text. You are prompted for the text at the bottom of the Text Editor window. The
search begins from the current position in the file.
Replace Var replaces the variable name specified with the new variable name. Vensim prompts you
for both old and new names. Variable names are recognized by the syntax of the model. The search-
and-replace operation begins from the current position in the file, and you are prompted to confirm
whether you want to make the change. Type or click on Y to make one change, N to skip one change,
A to change all occurrences, or Q to quit.
Replace String replaces a literal string, whether it is a variable name or not. For example replacing
"cust" with "customer" would change "cust_satisfaction" to "customer_satisfaction" and
"cust_demand" to "customer_demand." The search-and-replace operation begins from the current
position in the file. You will be prompted just as for Replace Var.

The Insert Menu

Insert brings down a submenu that allows you place some commonly used items into the text without
typing them. When you click on insert (or drag the mouse to it) a sub-menu will appear. The submenu
gives you four choices:
~..Formatted places tilde tilde bar formatted on new lines with tabs between them as in:
....... ~
~.
|
~~| No space places a ~~| directly at the current cursor position without creating any new lines.

Variable prompts you for the name of a model variable with the Variable Selection dialog and places
the name you select at the current location.
Font prompts you for a font using the Font Selection dialog and places the text specification for that
font at the current location in the text. It will take the selected text as the input for the current font.
This is primarily intended for use in .vcd files.
Lookup starts the Graph Lookup Editor. If you have selected the values for a Lookup table, the Graph
Lookup Editor will be started for those values, otherwise it will start empty. When you Click on OK in
the Graph Lookup Editor the corresponding numbers will be copied to the current location. Note that
the Graph Lookup Editor, when invoked in this manner, does not do any syntax or usage checking but
simply allows you to edit numbers graphically. This is useful in both models and .cin files.
Venapp Control opens the Venapp Control dialog for the current line. This is only useful in .vcd file.
The Venapp Control dialog is discussed in Chapter 3 of the Vensim DSS Reference Supplement.

191
The View Menu

The View menu allows limited control over appearance and also allows you to switch to a sketch
representation of the model you are working with.
As Sketch (models and Venapps only) allows you to view the model you are working with as a sketch
(in the Sketch Editor). The sketch information (stored at the bottom of the text -formatted equations) is
interpreted to create the views. Any changes you might have made to structure will also be
incorporated through the addition or deletion of links as necessary. If a model has Syntax errors, it
cannot be viewed as a sketch.
Horizontal Scroll Bar shows and hides the horizontal scroll bar in the Text Editor. Since the Text
Editor is automatically scrolled when the cursor is positioned off of the screen the scroll bar is not
completely necessary.
Set Font allows you to set the font in use by the editor. This is a local change and is not recorded
outside of the current instance of the Text Editor. You can also change fonts in the tool options, or
with the Options>Fonts command.

View Screen‡ (Venapp Definitions (.vcd files) only) allows you to view the current screen as it will
appear when the Venapp is run. This is a quick way to check layout and functionality. When you start
a Venapp in this way you can move up and down between screens using the Pg Up and Pg Dn keys. If
an error occurs, you will be asked if you want to suppress further errors.

The Status Bar

When you are using the Text Editor, the Status Bar at the bottom of the workbench gives you
information about current settings, and allows you to change a number of them.

Find will attempt to find the next occurrence of the text entered in the editing box to the right. To
enter text, click in the editing box and type.
Sub will attempt to find the text in the editing box to the left and replace it with the text in the editing
box to the right.
No Sens/Case Sens shows the current setting of case sensitivity. Clicking on it will toggle the setting.

Forward/Backward shows the current direction to be used in executing the find command. Clicking
on this will toggle direction.
No Entrain/Entrain (models only) shows whether or not the model is entrained. If entrained,
selection of a variable into the workbench will reposition the model to the equation for that variable.
Line # indicates the line number of the cursor. Clicking on this will allow you to enter a line to go to.
Position # indicates the character position of the cursor. Clicking on this has no effect.
>~... inserts a formatted multi-line tilde tilde bar at the current location.
>~~| inserts tilde tilde bar at the current location.

192
>Var prompts for a model variable using the Variable Selection dialog and places it at the current
location.
>Font allows you to select a font using the Font Selection dialog and places the string representing the
name of that font at the current location. Useful for .vcd files.
>Gr allows you to edit a Lookup function using the Graph Lookup Editor.
>Ctrl‡ allows you to edit a Venapp Control using the Venapp Control dialog.

When an error or information message is created, the contents of the Status Bar are changed to display
that message.

Clicking on the Status Bar or pressing any key will cause the status bar to revert to its normal
appearance.
When you drag the slider on the vertical scroll bar, the corresponding line number is immediately
displayed in the Status Bar line number area. This allows you to go quickly to the line you want.

Using a Mouse in the Text Editor


The Text Editor is designed to work well using just the keyboard. In addition, you can use the mouse
and menu items to perform most functions. Dragging the mouse, for example, is often the most
efficient way to select small areas of text.
To position the cursor in the Text Editor, just click in the window at the position you want to cursor to
go. You can also click on the scroll bars to reposition the file.
Double-clicking on a variable name will select that variable into the Workbench, or notify you if the
Workbench model does not contain the variable you double-clicked on. This is true whether or not the
file you are working with is a model.

Selecting Text
The Text Editor has two text selection modes. The first follows the standard Windows conventions for
selection of text. Using the mouse you can drag over a portion of text to select it. Alternatively you
can hold down the Shift key and move the cursor with the Arrow, Page Up, Page Down, Home and
End keys. The text you have selected will be highlighted from the point you began at, to the point you
stopped at — typically in the middle of a line. If you cut or copy this text and place it, it might be
placed in the middle of a line.
If you use the select by line key (Numeric Keypad *) then text is highlighted line by line. If you cut
and paste this it will always paste it at the beginning of the line, regardless of where you have
positioned the cursor. This is intended to make it easier to move equations around.
If, while you have highlighted text, you press any key other then a movement key, the text will be
removed and replaced with the key you pressed. This makes it easy to replace small sections of Text.
If you make such a replacement by accident, the Undo function will allow you to recover.

Search and Replace


Search and replace can be invoked using F2 or Shift -F2 key, from the menu items Edit>Replace Var or
Edit>Replace String or directly from the bottom menu. When you press F2 your cursor will be
displayed in the bottom menu next to find. Type in the string you want to find and press Enter. The
cursor will move to the replacement box — type the replacement string. The Status Bar will appear as:

193
Press enter again. The Status Bar will be replaced with:

While the word that was found will be highlighted in the text. You can click on the choices (Yes, No,
All or Quit) or type the first letter of the choice you want. After you are finished you will see the
message:

According to what was found.

The Text Editor Keys


The Text Editor uses keystrokes to perform most functions. In many cases there is more than one
keystroke available to perform a given function.

The following list describes the functions assigned to keys. Pressing two keys together is marked with
a - sign as in Ctrl-Z. For the numeric keypad characters to work (denoted Num Keypad * and so on)
NumLock must be off or keypad keys will enter numbers.
Function Key Description
Beginning Home Moves the cursor to the beginning of a line.
Two consecutive invocations place you at the
beginning of a page; three place you at the beginning
of a file.
Case Sensitivity Toggle F6 Determines whether the Find and Replace
commands match strings with or without case
sensitivity. The default is off.
Copy Num Keypad +
Ctrl-C
Ctrl-Ins Copies highlighted text to the clipboard
but does not remove it from its current position.

Copy Line Num Keypad + When no text is highlighted,


copies a line to the clipboard automatically, without
first highlighting it. This is a shortcut key.
Cut Num Keypad -
Ctrl-X
Shift-Del Erases highlighted text from its current
position and places it into the paste buffer.
Cut Line Num Keypad - When no text is selected,
removes a line from its current position and places it
in the paste buffer automatically, without first
highlighting it. This is a shortcut key.
Delete Right Del
Delete Deletes the character to the right of the
cursor (or the character the cursor is on if there
is a block cursor).
Direction Toggle Shift-F6 Indicates the direction of search for the
Find function.
Down Arrow Down Moves the cursor down a line.

194
End End Moves the cursor to the end of a line. Two
consecutive invocations position you at the end of the
page, three at the end of the file.
Entrain Toggle F7 For models only. When entrain toggle is on,
and a variable is selected into the Workbench, the
Text Edit window is repositioned to the beginning of
the first equation defining that variable. Also, when
you click in the Error Report window associated with
the model, the Text Edit window is repositioned at the
source of the error. This toggle is automatically set to
on if you choose the Check or Load command.
Find F5 Searches for a literal string in the text. The
search is forward from your current position unless
the direction toggle is set to backward.

Function Key Description


Find Again F3
Shift-F5 Repeats the search previously specified
with the Find command.
Left Left Arrow Moves left one character; at the
beginning of a line, moves to the end of the previous
line.
Matching Delimiter Num Keypad 5 Looks for a delimiter –
parenthesis (), brace {}, or bracket [] – complementing
the one the cursor is on. If found, the cursor is
repositioned. Two matching delimiter functions take
you back to where you started.
Page Down PgDn
Page Down Moves down a page. The bottom line
on the page becomes the new top line.
Page Up PgUP
Page Up Moves up a page. The top line on the
page becomes the new bottom line.
Paste Ins
Insert
Shift-Ins
Ctrl-V Copies the contents of the paste buffer
index to the current cursor position.
Redo Ctrl-Y Redoes a previously undone action. You can
Redo back to the state where you did your first Undo.
Replace String Shift-F2 Prompts for a string and replaces it with
another string. The string is replaced regardless of its
position inside of variable names.
Replace Var F2 prompts for a variable name and replaces it
with another variable name. Variable names are

195
distinguished by context, and might not be replaced in
comments.
Right Right Arrow Moves right one character; at the end of
a line, moves to the beginning of the next line.
Select Shift-motion Holding down the shift key and using
any of the motion keys selects the intervening text.
Select All Ctrl-A Selects all text in the current file or model.
Select by Line Num Keypad * Marks the beginning of a
selection range for line by line selection. If a range is
already selected, this function deselects it. Pasting
text selected i n this manner always replaces line by
line.
Undo Ctrl-Z Undoes previous editing. You can undo to the
last time you saved.
Up Arrow Up Moves up a line.
Interacting With Models
When you have a model in the Text Editor, you can translate the text into a collection of logical and
computable interconnections. The parts of the model that are successively translated in this manner
can then be used as the Workbench model.
Normally, this translation process is carried out automatically every time you use a tool, select a
variable, or invoke one of the main menu commands. With automatic translation, Vensim attempts to
hide the process. If there are syntax errors,this is not possible because large parts of what you perceive
to be your model might be unintelligible to Vensim. If this is the case, you are notified of the error and
asked if you want to correct it. If you do not correct a syntax error, the resulting causal structure as
understood by Vensim can be incomplete and incorrect. If you do correct a syntax error, you will need
to invoke the command that triggered the reporting of the error again.
When you explicitly ask to translate your equations using the Model>Check Model command, the
results of translation are reported. Translation will stop if there is a syntax error. In off-line mode, the
File>Load command also causes the model to be checked and the existing Workbench model will not
be replaced if there are syntax errors. If there are semantic errors (simultaneous equations or misused
subscripts), you will not be able to simulate. These two types of errors are discussed in the following
two sections. See also Chapter 3.

Syntax Errors
Syntax errors can be detected by Vensim quickly. Because the translation of a source model into the
internal Vensim representation is incremental, Vensim efficiently reports one syntax error at a time.
As errors are corrected, only changes in the model are retranslated.

On Check or Load
If there is a syntax error in your model, you will receive a Stop Box reading "syntax error." When you
acknowledge this Stop Box, you are positioned at the point in your model where the syntax error was
detected. The prompt line for the Text Editor will give you more details about the exact nature of the
syntax error.

196
The error message on the bottom line will disappear as soon as you move the cursor, or if you click on
the line, and you will return to the standard Status Bar. Correct the error and invoke the Check Model
or Load command again. Vensim will go to the next error (if any) and you can repeat the process.
Note that the real nature of an error is not always obvious from the error message. Look at the
message and the equation and it should become clearer. Errors resulting from the incorrect use of
function names can be confusing.

On-Line mode
When you activate a tool, select a variable, or invoke a command on the main menu, Vensim checks
the active model to be sure that its internal representation of that model is up to date. If necessary,
Vensim will translate those parts of the on-line model that have changed. During this translation
process, Vensim might detect a syntax error. If it does, you will be asked if you want to correct it. If
you respond yes, you will be positioned at the error and the prompt line will indicate the nature of the
error just as it would if you explicitly checked the model.
If you decide not to correct a syntax error, Vensim will use its partial internalization of the model and
might give an incomplete analysis. The next time you try to invoke a tool or command you will again
be asked if you want to correct the syntax error.

Semantic Errors
Once you get all of the syntax errors out of a model, it will be properly loaded into the Workbench.
The analysis tools will give the correct results for the model. However, the model might still contain
semantic errors, and such a model cannot be simulated. Semantic errors are reported only when you
invoke the Check Model, Load, or Simulate commands.

Error Report Window


The errors will be reported in a separate window that is much like an Analysis tool output window.
The Error Report window, however, has unique features.

The window in which you are editing the model is automatically put in Entrain mode when you invoke
the Check Model or Load command. The window must be left in Entrain mode to use the full
capabilities of the Error Report window. To correct a model error, position the cursor over the error in
the Error Report window and click once. The Text Editor will reposition the model at the location of
that error. Correct the error and move to the next error.
NOTE The Editor will lose its error positioning when you add and delete lines, so you will probably
want to repeat the Check or Load command after correcting a few errors.

197
NOTE There are certain errors that Vensim reports but cannot pinpoint the location of. If clicking in
the Error Report window has no affect, trace the error using the structural analysis tools.

The Error Report window will be replaced when you invoke the Check Model or Load command
again, and it will be deleted if you close the Text Editor.

Causal Tracing
When you edit a model, the Text Editor has two special features that allow you to do "within the
editor" causal tracing.
? As with all other windows, double-clicking a variable name selects that variable into the
Workbench.
? If you enable entrainment (by clicking on the Entrain/No Entrain button, or press F7, or numeric
keypad 7), double clicking on a variable on the right side of an equation moves you to the equation
defining that variable.
With these features, you can trace causes purely inside of the Text Editor by double-clicking on the
right-hand side of equations.

Using Sketch Information in the Editor


If a model contains sketch information, the information contained in a sketch about positioning and
connections will also be encoded into the Text Editor. If there are Sketch Views for the current model,
this information is stored at the end of the model equations. The beginning of the sketch information is
marked by the special character sequence \\\--///. Everything after this is treated as sketch information,
not model definition code.
The format for storing sketch information is simple, and described briefly in Appendix D. For the
most part it is not intended for user modification. You can modify the variable names. The Replace
Var command is the easiest way to do this.
NOTE If you add or remove variables from a model, the sketch information will be only partially
valid. Vensim uses any sketch information available, ignores information that is not applicable, and
adds in the necessary words and arrows to keep the sketch and model consistent. Because of this, you
can move back and forth between the Text Editor and Sketch Editor, making incremental changes in
each, without losing previous work.
If you have your own equation format, or if you prefer to keep your original model equations intact,
you can cut the sketch information from one file and paste it into another. This allows you to keep an
archived development history of model structure (see "Backup and History Files"), and at the same
time have a sketch of the model available for review and display.

Backup and History Files


The Text Editor keeps a running log of the changes you make to models in a backup file. If the system
crashes, or power is interrupted, or your editing session ends abnormally in some other way, you can
use this backup file to recover most of your changes. The recovery is performed the next time you
open a file that has a backup in place. If Vensim finds a backup file, it asks you if you want to attempt
recovery. If the recovery is successful, you are positioned on the last line that was modified.
The history file is a log of changes you have made to a file, which is added to each time you edit the
file. You can specify whether or not you want a history file with the Advanced tab of the Options
dialog (use the Tools>Options command).
The format for history and backup files is the same. Lines in each of these files begin with a character
to indicate what happened to a line.

! (comment) indicates a comment line.

198
- (delete) indicates that a line was deleted.

+ (insert) indicates that a line was inserted.

# (line count) displays the number of lines in a file before changes were made.

Examples
The first line in a backup file must show the line count # . This number reports how many lines were
in the file prior to any changes that were made. The format for a line count is as follows.
#314\File Length
This indicates that the file has 314 lines.
-122\This was line 122
This indicates that line 122 (which contained the text " This was line 122") was removed from the file.
+122\This is the new line 122
This indicates that a new line containing the text "This is the new line 122" was inserted before line
122.
-117\:GARPH test-graph-1
+117\:GRAPH test-graph-1
This indicates that line 117 was changed from ":GRAPH test-graph-1" to ":GRAPH test-graph-1."

Backup File-Naming Conventions


When you edit a file, Vensim creates three files in addition to the file you are editing.
? A temporary backup file.
? A history file, which is added to each time you edit a file (as long as you have not set Text Edit
History to Off in the Global Options dialog).
? An old version of the file you are editing. If a previous version of the file exists when you save
the file, the old version is saved.
Backup. The backup file has the same name as the file but the file extension is prefixed with the
number zero 0. Under Windows 3.1 if the extension has three characters, the last character is dropped
Thus world.vmf has a backup file named world.0vm (world.0vmf on Windows 95 and the Macintosh)
and mdl.c has a backup file named mdl.0c.
History. The history file has the same name as the file with the number one 1 at the beginning of the
extension. Under Windows 3.1 if the extension is three characters long, the last character is dropped.
Old Version. If you have set a backup path in the tab of the Options dialog, Vensim attempts to place
the old version of the file in that directory. If Vensim fails to do this, or if you have not specified a
backup directory, the old version has the same name as the file with the number two 2 at the beginning
of the extension. Under Windows 3.1 if the extension is three characters long, the last character is
dropped.
NOTE The backup path you specify should not contain a drive or volume name. Vensim will attempt
to put the file in the path on the drive you are currently using. If this path does not exist or is otherwise
not accessible, Vensim will fail to make the backup and make a local backup instead.

Recreating Versions of Files


In addition to providing a readable audit of what you have changed in a file, you can use history files
to automatically recreate different versions of a file. To do this, you must first archive an initial
version of the file, then begin a new history file. After you make changes to the file, go into the history
file and delete everything after the version you want to recreate. Rename this portion of this history

199
file as a backup, then edit the initial version of the file. The backup facility will be invoked
automatically.
For example, to track changes in world.cin, copy the file world.cin to world.one, which will be used as
the reference file. Delete world.1ci (the old history), so that the new history file is relative to the
reference file. Now make changes to world.cin. Suppose you create seven new versions. To use
version 5, edit world.1ci and cut the information for the last two versions (everything below the second
to last line beginning with #). Save this as world.0fi. Copy world.one to world.fiv, then edit world.fiv.
When you start the editor you will be asked if you want to attempt recovery. Answer yes. The result
will be the fifth version of world.cin.

200
8 Simulating Models

Simulation determines the dynamic behavior of a model. This chapter explains how to:
? Set up Simulations from the Main Toolbar.
? Use the Simulation Control dialog.
? Simulate a model from Vensim.
? Change Constant and Lookup inputs.
? Interpret simulation error messages.

Selecting the Time Range


The basic time range for a simulation is determined from the Time Bounds tab of the Model Settings
dialog or from the equations for Vensim's control parameters (see Chapter 3). Typically these are
model constants and can also be changed temporarily before simulating the model. You can control
the time range displayed in graphs independently using the Time Axis tab of the Control Panel (see
Chapter 12). If you make a simulation that is beyond the time range currently set in the Time Axis tab
this range will be expanded to show the whole simulation.

Simulating from the Toolbar

For most simulations it is easiest to simulate directly from the Toolbar. There are some settings that
are not available from the Toolbar (for example loading changes files) and for these you will need to
use the Simulation Control dialog discussed later in this chapter. Once you have set something in the
Simulation Control dialog it will remain set so you can simulate from the Toolbar and have additional
options included. For example, if you specify a changes file in the Simulation Control dialog each
time you simulate that changes file will be used.
NOTE Vensim PLE and PLE Plus only support simulation from the Toolbar, and not all of the options
described below are available.
To simulate the current model with the settings last used for a simulation (or the default settings if this

is the first simulation) click on the Simulate button or type Crtl+R. To enter SyntheSim mode
click on the SyntheSim button (for more details see Chapter 11). The name appearing in the
toolbar will be used for the simulation. If you want to change the integration method, data files to be

used or make temporary changes to Constants and Lookups click on the Set up a Simulation
button. The top Toolbar will change appearance:

If you are working in the Sketch Editor, the sketch view will also change appearance. All Constants
and Lookups in the current view will be highlighted. You can make temporary (for this simulation run
only) changes to their values by clicking on them.
? Clicking on an unsubscripted Constant will bring up the Constant's value in an editing box. Type
in a new value and press the Enter key to change it.

201
? Clicking on a subscripted Constant will bring up the Constant Changes dialog discussed under
"Changing Constant and Lookup Values" later in this chapter. You can use this to change any
element of the subscripted constant.
? Clicking on an unsubscripted Lookup will open the Graph Lookup Editor, allowing you to change
values.
? Clicking on a subscripted Lookup will bring up the Lookup Changes dialog allowing you to select
which element you want to change.
In addition to regular variables, any Input Objects that are attached to model Constants will be
activated. You can change the values of the corresponding Constants by dragging the slider or typing
in a new value. Note that it is a good idea to put labels near to these sliders to make it clear which
variables they are changing.
While in Simulation Setup model you can move from view to view and change any Constants and
Lookups you wish. You cannot, however, make any changes to views.
You can select the Integration method to be used in the simulation by clicking or shift clicking on the
left most button. If will cycle through Euler for Euler integration, RK4 for 4th order Runge Kutta,
Diff for difference equations, RK2F for 2nd order Runge Kutta with fixed step size, RK2 for 2nd
order Runge Kutta and RK4F for 4th order Runge Kutta with fixed step size (then start again). The
different integration techniques are discussed further below. Use Shift+Click to move backward
through the list.
If you have a model that uses data variables you will need to include the name of the driving datasets
in the first edit box. You can select a dataset by clicking on the : button to the right. The dataset you
select will replace the current selection in the editing box, or be added to the contents of the editing
box if nothing is selected. If you only want to use one dataset be sure to highlight the old one before
selecting a new one.

If you want to get a list of all model Constants and Lookups, you can click on the Constant and
Lookup buttons. These bring up the Constant Changes Dialog and Lookup Changes Dialog
for all the Constants and Lookups in the Model.

You can open the Simulation Control Dialog by clicking on the button. Any changes you have
made on-screen will be retained. You will need to start the simulation from this dialog as described
below.

Once you have made all your changes you can simulate the model by clicking on the Simulate
button. The simulation will be given the name appearing in Runname editing box on the Toolbar. In
addition to a regular simulation you can also start a gaming simulation , a sensitivity simulation

, an optimization or a Reality Check run . You can also cancel the simulation by
clicking on the Stop button. Gaming is discussed below. Sensitivity and Optimization are
discussed in Chapter 9. Reality Check simulations are discussed in Chapter 14 of the User's Guide.

When you set up a simulation from the Toolbar with a sketch open the Lock tool is automatically
selected into the sketch and any Output Objects are filled. After you simulate the content of all output
objects is renewed automatically ensuring that they are consistent with the latest simulation.

Running a Game
Gaming is not available in Vensim PLE.

A game is a simulation during which the user interacts with the model to make decisions as the
simulation progresses. You can run a Gaming simulation by clicking on the Game button. This

202
can be done with or without any prior simulation setup. If you have made simulation setup changes
those changes will be used in the Game.

The Toolbar will change and all gaming variables appearing on the current view will be highlighted..
These can be changed in the manner discussed above for constants, or by clicking on the button.

In gaming mode all Input Objects that you have assigned Gaming variables to will be active. Values
for the gaming variables can be changed from these sliders. You can move back and forth between
views if you have designed more than one input screen.

Use the buttons to move backward and forward through the game. Type in the amount you
want to move in the editing box to the right. The amount you will move is called the Game Interval. If
your model contains the constant GAME INTERVAL this value will be used to initialize the Game
Interval (which you can still change). If your model contains GAME INTERVAL the Game Interval
will be reinitialized each time you start a game. If not the Game Interval will be initialized at the Save
Period and then left at whatever value you last set it to when you start a new game.
Note that you can review graphs and make use of all of the Analysis Tools even during a game.

NOTE It is not possible to back up a game for a model that includes any of the pure delays (DELAY
FIXED, INFORMATION or MATERIAL).
NOTE Gaming does not use any data compression when recording results and this means that
simulation output from gaming simulations can take up much more disk space.

Simulation Control Dialog


The Simulation Control dialog is not available in Vensim PLE or PLE Plus.

The Simulation Control dialog allows you to specify all the available simulation options and perform
regular simulations, gaming simulations, Reality Check simulations, optimizations and sensitivity
simulations. To open the Simulation Control dialog use the Model>Simulate… command or click on
the Simulation Control button on the Toolbar. The Model>Partial Simulation (discussed later in
this chapter) will also open the Simulation Control.

Standard
The Standard Simulation Control tab allows you to set the same things that can be set from the Main
Toolbar.

203
Run Name lets you name the run you are about to make. After the simulation is completed, a dataset
with this name and extension .vdf will be created. You don't have to add the extension; Vensim adds
.vdf automatically. The default run name is Current. You can type in the name you want, or click on
the Run Name… button to get a File Selection dialog. The Run Name control is common to all the
Simulation Control tabs.
Reload Run (Gaming Only), if checked, lets you reload a run to continue playing a game that was
previously suspended. This option only has an impact if you close the dialog by pressing the Game
button. This option will only work if the game you are trying to reload is from the current model. If
you have made any changes to the model, you will not be able to reload the game.

Integration Technique
The integration technique is the method that Vensim uses to advance a model in time. The details of
the different techniques are discussed below in "Choosing an Integration Technique." The choices are:
Euler which performs Euler integration for the simplest, fastest (and least accurate) solution.

Diff which performs Euler integration but stores the values for Auxiliaries computed at the previous
save Time. Regular Euler integration stores the values of Auxiliaries computed at the current save
time. Diff, as its name suggests, is intended primarily for difference equations where this reporting
convention is often used.

RK4 Auto which performs fourth order Runge-Kutta integration with automatic adjustment of the step
size to ensure accuracy. This is the best choice if you want an accurate answer quickly.
RK4 Fixed which performs fourth order Runge-Kutta integration with a fixed step size specified by
TIME_STEP. This is usually very accurate, but does not detect its own inaccuracies.
RK2 Auto which performs second order Runge-Kutta integration with automatic adjustment of the
step size. This is less accurate, but sometimes faster than RK4 auto. It is not recommended unless you
feel there is a special reason to use it.
RK2 Fixed which performs second order Runge-Kutta integration with a fixed step size. This is faster
than RK4 but more accurate than Euler. It is useful when both speed and accuracy are important and
difficult to achieve.
Comment for run is any comment you might like to make for that particular run. It will be recorded
in the run and reported in the error log (Window>Error History) when you load the run.

Changes

Based On names a previous simulation for which this new simulation is to be based on. The Constant
and Lookup values from the previous simulation are used for the new simulation, and these values can
be modified using the Changes files, or any interactive changes you make. If the Resume check box is
On, the new simulation will start at the end of the prior simulation; otherwise it will start at the same
time as the prior simulation. To make a simulation based on another simulation, the prior simulation
must come from the current model. By default, the Based On item is blank, indicating that the

204
Constant and Lookup values in the model will be used, unless overridden by a Changes files or
interactive changes.
Resume , if checked, causes the simulation to take up where the simulation named in the Based On file
ended. If there is no file named in Based On then Resume will be grayed. If you do resume, you will
normally need to change FINAL TIME so that the resumed simulation will continue.
at time (blank for end) if filled in will cause the simulation to be resumed at a time other than the end
of the Based On simulation. If you are working with a model that uses any DELAY FIXED,
MATERIAL or INFORMATION this function will fail. Also, if you are simulating a model with a
Save List and that Save List does not contain all the Levels in the model, this function will fail.
Load Changes from... editing box names zero or more files (separated by commas) containing
changes to the values of Constants and Lookups in the model. Where you use more than one Changes
file and a Constant or Lookup is changed in more than one of the Changes files, the values are taken
from the last Changes file listed. Multiple Changes files are frequently used in optimization problems.
The content of and syntax for this file are described later in this chapter. By default, no Changes file is
named, so that the parameters from the model will be used directly. The Load Changes from... button
opens a File Selection dialog that lets you select an existing changes file.
Change Constants brings up a list of model Constants for you to change (see Changing Constants
below).
Change Lookups brings up a list of model Lookups for you to change (see Changing Lookups below).

NOTE When you press the Change Constants or Change Lookups button the Load Changes from
and Based on entries are read, with the Constant and Lookup changes made in them incorporated into
the changes to be made during the run. You can no longer modify the Load Changes from or Based
on items. If you change your mind, click the Cancel button and start over.
Save changes as .cin File allows you to record changes you have made interactively as a .cin file (the
format for .cin files is discussed further below). This can be very useful for documenting simulations,
and allowing easy repetition of previous simulations with slightly changed models.

Sensitivity
The Sensitivity tab allows you to set up and run Sensitivity Simulations. Sensitivity simulations are
discussed in more detail in Chapter 10.

Sensitivity Control… names a sensitivity control file for performing multivariate sensitivity analysis.
This will normally be a Vensim Sensitivity Control (.vsc) file. The Edit… button to the right allows
you to modify the sensitivity control file. Chapter 10 contains more details.
Sensitivity Save List… names the file containing the list of variables to save for Sensitivity
Simulations. This is required for sensitivity analysis but will not be used for other types of
simulations. The Edit… button to the right allows you to modify the save list. See the section
"Maintaining Save Lists" in Chapter 10 for a detailed description of save lists.

205
Advanced

Data Sources… names zero or more comma separated datasets containing values to be used as
exogenous inputs or to be compared with model simulation values. These datasets can contain Raw
Data from Dat2vdf, Tab2vdf or spreadsheet conversions, or can be the output of other simulations. If
multiple datasets are named and a data series appears in more than one dataset, the values from the
later dataset are used. See Chapter 9 for more information on creating and using input datasets. By
default, no dataset input is expected. The Data Sources… button allows you to select dataset names to
add to the list.
†Payoff Definition… names a file containing the variable names and the weighting assigned to them
in the optimization criteria. This will normally be a Vensim Payoff Definition (.vpd) file. The Ed…
button to the right allows you to modify this file. The content of and syntax for this file are described
in Chapter 10. By default, no payoff file is expected.
†Payoff Report, if on, saves the components of the optimization criteria that have been specified to
the file payoff.rep. This report includes the relative and absolute contributions to the log likelihood
payoff function for each of its components. It also generates a file called 1step.err (and 2step.err ... if
the Step option has been set and Kalman Filtering is active) that gives the actual residual of model
versus actual data over the course of the simulation. 1step.err can be loaded into Vensim with
Dat2VDF (from the main menu Datasets>Import Datasets>Dat2VDF ) to review these residuals.
†Optimization Control… specifies the file containing the optimization control instructions. This
would normally be a Vensim Optimization Control (.voc) file. Click on Ed… to the right to modify
the file. Chapter 10 contains more information on setting up and using optimization control files. You
may not name this file optimize.out as this file is created for storing the results of an optimization.
†Kalman Filtering, if on, causes Vensim to adjust the model states during the simulation, based on
the available data, using an extended nonlinear Kalman filter. The use of the Kalman filter requires
some additional input files and is discussed further in Chapter 10.

Step† allows you to specify the number of steps ahead to report forecast errors during simulations
using Kalman filtering. This only has an impact when both Report and Filtering are on. The files
1step.err, 2step.err and so on will be created. 2step.err, contains the results of running the model
without Kalman corrections to the second available set of data points. If this is left blank, the value 1
will be used.
Save List… specifies a list of model variables to save. By default all model variables are saved and
this is important in supporting Causal Tracing. However, if you are working with very large models
for which storing all values is not practical, the save list can speed things up tremendously. The Ed…
button to the right allows you to modify the list of names to be stored. The section "Maintaining Save
Lists" in Chapter 10 provides more details on save lists.

Use Minimal Memory‡ , if checked, will cause Vensim to minimize the use of memory during a
simulation. This is designed for very large (more than 1 million variable) models with a modest (less

206
than 100) number of times being saved. Using this option will result in larger files (there is no data
compression) and slower response when graphs are created but will speed simulation.

Closing the Dialog

To close the dialog click on one of the buttons along the bottom. Set enters Simulation Setup mode
(the same as clicking the Set up a simulation button on the toolbar). Simulate starts a normal
simulation. SyntheSim enters SyntheSim mode. Game starts a gaming Simulation. Sensitivity starts
a sensitivity simulation. Optimize starts an optimization. Cancel cancels the simulation command.

Simulating the Model

Whether from the Toolbar or Simulation Control dialog once you ask for a simulation a simulation will
be made and the dataset resulting from that simulation will be loaded into the Workbench. If a dataset
already exists with the name of the run you have chosen, you will be asked if you want to overwrite it.
If you respond no, you will be asked for a new run name. If errors occur before the simulation can
start, you will receive an error message and the simulation will be canceled.

Simulation Error Messages


When the simulation begins, an error window will be created to report all errors, warnings, and
messages. This window behaves exactly like tool output windows described in Chapter12.
Any errors encountered in a simulation will terminate the simulation and you will receive a message
explaining why. Warnings will not terminate a simulation. Warnings arise from Lookups that have
gone out of range and from variables that have gone beyond their specified low/high range. If there
are no errors, warnings, or informational messages, no error window will be created.

Information messages are displayed telling you what Changes files are being used.

Warnings occur because of range violations and Lookup overruns. The format for these is very
similar. The first time something goes above or below its normal range it is reported, then nothing is
reported until it returns to inside its normal range. For example, you might get messages like the
following.
WARNING: At 0 Below FIRST LOOKUP computing first var
WARNING: At 3 In FIRST LOOKUP computing first var
WARNING At 4 Above lonely var
WARNING At 7 In lonely var
WARNING At 8 Below lonely var
This indicates that the input to FIRST LOOKUP was smaller than the first value in the X-axis for the
Lookup at time 0, and remained below this minimum value until time 3, when it went above the
minimum value. After time 3 the input to FIRST LOOKUP remained between the first and last X-axis
values of the Lookup. The value for lonely var went above the maximum bound for this variable
at time 4, returned into normal range at time 7, and then went below the range at time 8.

207
Error messages are displayed if a file (such as a Changes file) cannot be found or if Vensim was unable
to interpret information. These errors will cause the simulation to be aborted. Fix the files or names
mentioned and simulate again.
If you have a model with Data variables and not all of those data variables are contained in the data
files Vensim will issues a warning message and attempt to proceed assigning a :NA: to the Data
variable. These warnings cannot be suppressed. If the data is used extensively in the model it is likely
to cause a floating point error. It is, however, sometimes convenient to be able to proceed even when
there is missing data and thus the simulation is not aborted.
If there was a division by zero or other overflow during a simulation (a variable's value got too large)
you will also receive an error message. This message will tell you what equation was being computed
when the overflow occurred. The simulation will be stopped and all results to that time stored. The
results at the time of the error will also be stored if possible. You can then review the run to discover
the cause of the error.

Active Initial Differences


Another type of simulation warning message is the reporting of differences between initial values and
the first active value computed. These difference occur only when you use the ACTIVE INITIAL
function. Suppose, for example, that you have the following equations:
Visibility = INTEG((indicated visibility-Visibility)/
TIME ADJUST VISIBILITY,indicated visibility) ~Page ~|
indicated visibility = enduser demand * PAGE FROM VOLUME ~Page ~|
enduser demand = ACTIVE INITIAL(BASE DEMAND *
PRODUCT VISIBILITY F(Visibility/REF VISIBILITY) *
PRODUCT PRICE F(Price/REF PRICE),
BASE DEMAND) ~Widget/Year~|
The last of these equations is being used to get around an initial simultaneous value error that would
otherwise result. Now suppose that Price is initialized at 1.5 and REF PRICE is just 1. The value
of enduser demand is required to initialize Visibility, and will be set at BASE DEMAND.
However, when enduser demand is computed at the initial time (given the values of all the levels),
it will be different because of the different price. When you do a simulation you will see the
messages:

For this example, this message is an indication of a formulation problem — Price should be
initialized more accurately. In general, there might be small differences that you will not want to
worry about. You can control whether or not an error message gets reported by setting the Active
Initial Relative and Absolute fields in the Global Options dialog Settings tab. Differences will be
reported only if they are larger in absolute value than the absolute number you enter, and larger relative
to the initial value by the relative number you enter. For example, a relative error threshold of .5
would have prevented these messages from being reported.
If you want to look more closely at initial computations, selecting the integration type Diff will cause
the initially computed values to be reported at Time 0 and the first active values to be reported at the
next SAVEPER.

208
Work-in-Progress (WIP) Graphs
When you create custom graphs, you can have one or more of them displayed during simulation. If
you do this, when you start the simulation you will see a custom graph, and the values will fill in as the
simulation progresses. You can move and resize the graphs during the simulation, although your
system might respond somewhat sluggishly.

If you are simulating with the Sketch Editor open and you have one or more Work-in-Progress graphs
in Output Objects on the current view Vensim will write to these graphs, but not open any additional
Work-in-Progress graphs.
If you ask for more than one graph to be displayed during a simulation, the graphs will open on top of
one another. You can move them around, and then use the Rec Coord button on the Graphs tab of the
Control Palen to have them come up where you positioned them the next time you simulate the model.

Interrupting Simulations
You can stop a simulation in progress by clicking on the Stop button.

You will be asked if you want to save the results so far. Respond Yes to save them, No to discard
them, and Cancel to continue simulating.
If you want to stop a simulation with work in progress graphs visible pressing the Esc key or using the
Ctrl+C key combination. This will prompt you to see if you want to stop the simulation.

Changing Constant and Lookup Values

There are two ways to changes Constants and Lookups for a new simulation. The first way is to
change the values interactively at the beginning when you set up the simulation either on the Sketch as
discussed above or using the Constant Changes dialog discussed below. The second is to create a file
containing the changes you would like make. The changes file is structured in a format similar to the
way Constant and Lookup equations are written.
For small models, interactive changes are likely to be the easiest. For large models with many
changes, you might want to use changes files. You can also create changes files interactively using the
Save Changes as .cin button in the Changes tab of the Simulation Control. The Model Settings dialog
also has a button to create a complete baseline changes file for all model parameters which can then be
modified.

Interactive Changes
There are three ways to change Constants and Lookups interactively:
1. Click on the Set up a Simulation button, then click on a Constant or Lookup appearing
highlighted in the sketch.

2. Click on the Set up a Simulation button, then click on the Constants button or the Lookup
button on the Simulation Toolbar.
3. Open the Simulation Control, click on the Changes tab, then click on the buttons Change

209
Constants… or Change Lookups…
If you have specified any changes files in the Simulation Control dialog these will be read before
interactive changes are made. This is true whether you are making interactive changes from the Sketch
or from the Simulation Control dialog.

Constant Changes
Clicking on a highlighted Constant in the sketch normally opens an editing box in which you can
change the value. If the Constant is subscripted, you will get a subscript selection dialog. If you click
on a Change Constants button (on the Simulation Toolbar or in the Simulation Control), you will open
the Constant Changes dialog:

All the constants are shown in a list. To change one, click on it. A comment describing what the
constant is will appear. Click on the modify button or press the Enter key to change the value. A new
edit box will appear. Type in a new value and press enter or click on the update button.

The constant you clicked on will now have this new value.

You can choose a constant to change by typing in the first few letters of its name to the left of the
Filter button. You can also reduce the list of constants by typing in a wildcard sequence (such as
*capital* to get any constant containing capital) and click on the Filter button.
To speed things up you can also do the following:
1. Use the up and down arrow keys to move through the list. When you get to the constant you want
to change press the Enter Key.
2. Type in a new value.
3. Press the Enter key. You will be put back in the list and can continue with step 1.

210
If you are using the keyboard for input in this manner you can also use the Page Up and Page Down
keys to move through the list. Once you have finished your changes click on the Close button. If you
reopen the Constant Changes dialog, you can pick up where you left off and continue to make changes.

Lookup Changes
You can change Lookups interactively by clicking on the graph in the Toolbar or Lookup button on the
Changes tab of the Simulation Control dialog. You will then see the Lookup Modification dialog:

Click on the Lookup you want to modify. A comment describing the Lookup will appear. Click on
the Modify button. You will see the Graph Lookup Editor:

Drag the points to where you want them, or change the values in the cells, then click OK. Details on
using the Graph Lookup Editor are given in Chapter 6.

After you have changed the Lookups, click on the Close button. You can return to the Lookup
Changes dialog after you have closed it by clicking on the Lookups button.

211
Constant Input Files (Not PLE or PLE Plus)
If you name a changes file in the Changes tab of the Simulation Control, Vensim searches for it when
the simulation begins, or when you start making interactive Constant or Lookup changes. By naming a
changes file and then making interactive Constant and Lookup changes, you can easily build on
previous scenarios.

Changes files can have any extension, but they default to .cin if no extension is specified. The format
for .cin (Constant INput) files is much the same as that of Constant and Lookup equations, except that
the tildes ~ and bars | are not needed. A constant file might look like this:
CONSTANT NAME 1= 123.4
CONSTANT NAME 2[sub]= 3,2,7
constant name 3= 120.0
CONSTANT NAME N= 332.2
LOOKUP NAME 1( 1,2,3,4,5,0,2,4,5,9)
LOOKUP NAME 2(-1000,0,1,2,3,4,5,1000, 0,0,2,5,7,8,9,9)
LOOKUP NAME 3((0,0),(1,1),(2,1))
The order of entries, spacing, and capitalization is arbitrary. Spaces and underbars _ are considered the
same, and multiple contiguous spaces and underbars are collapsed to a single space. Repeated changes
to a Constant or Lookup will overwrite the old values. The number of entries in a Lookup can change
from the number in the model. Subscript Ranges can be used in Constant equations just as in the
modeling language. You cannot change something that is not a Constant or a Lookup.
Variables that cannot be found or are misspelled cause errors.

For convenience, the format of the optimization control file (described in Chapter 10) is also supported
in the Changes file. Thus the lines:
0.0<= NORM FRAC BIRTH[CHINA] = .015 <= .1 FRAC
and
NORM FRAC BIRTH[CHINA] = .015
have the same effect.

To add comments to Changes files, add :C to the beginning of lines, as in


:C Low resource run
INITIAL RESOURCE=100E4
:C high resource run
:C INITIAL RESOURCE = 100E12
You can also add comments to the end of lines by entering the comment after a tilde ~, or to the middle
of lines by enclosing a comment in curly brackets {}, just as in a model. Comments are ignored. The
following examples are all valid ways of adding comments to lines.
INITIAL RESOURCE={100E4}100E12 ~Low/high choice
~INITIAL RESOURCE=100E30 ~ unbelievably big
{INITIAL RESOURCE= 100e2} {real tiny }
This first line sets INITIAL RESOURCE to 100E12. The second and third lines do not do anything
but could easily be commented back in. The choice of ~ or {} is purely aesthetic.

Getting Constant Changes from Spreadsheets


Vensim Provides an automated link to spreadsheets with the GET 122 CONSTANT and GET XLS
CONSTANTS functions. These functions and the way they can be used are described in Chapter 4.
They will automatically load in the current values from the named spreadsheet before any change files
are read or interactive changes are made.

212
If you have a large number of changes to make, or if you want to change Lookups, you might want to
set up changes in a spreadsheet and then save them to a tab or comma delimited file. It is somewhat
faster to process these than to connect to Excel or 123 to get the constants.
Suppose you have the model equations:
sex : female,male ~~|
county : madison,morane,melrose ~~|
initial population[county,sex]=0 ~Person~|
saturation lookup(0,0,0,0) ~Dmnl~|
and you have a Microsoft Excel spreadsheet containing:

The Constants are entered in a tabular format and the Lookup is entered with its X-axis on one row and
its Y-axis on another row. Note that the initial and closing parens ( ) are necessary to mark this as a
Lookup for Vensim. Saving this spreadsheet as a Tab Delimited file would give:
Population stats compiled by RQW,
Female,Male
"initial population[madison,sex]" 22000 27000
"initial population[morane,sex]" 14000 9000
"initial population[melrose,sex]" 35000 36000
saturation lookup( 0 1 2
1 1 0 )
You can then specify this file to be used as a changes file during simulation. Any row with an empty
first column is ignored. Thus the first two rows are simply comments are far a Vensim is concerned.
NOTE It is very important to make sure that the order of subscripts along columns is the same in the
model and the spreadsheet.
Saving a spreadsheet file as a .csv (comma delimited) file will also work.

NOTE If you want to use output from spreadsheets in this manner, the file must have extension .txt,
.tab or .csv. This is a signal not to expect the strict .cin format that Vensim normally requires.

Selecting an Integration Technique


Vensim provides you with a number of choices for integration that basically trade off speed and
accuracy. The best choice of an integration technique depends on what your purpose is. For most
models of messy problems, where there are large errors from aggregation, mismeasurement,
simplification, and lack of information, Euler integration suffices. For models of physical systems and
for simple conceptual models, especially those involving oscillation, Runge-Kutta integration is
probably preferred.

213
If you are conceptualizing your model as a difference equation model, then Euler and Diff are the only
integration techniques that are appropriate.

Euler Integration
Euler integration is the simplest and most obvious way to numerically integrate a set of differential
equations. Euler integration consists of the following steps:
1. Set Time to its initial value.
2. Initialize the levels.
3. Compute the rates of change of the Levels at the current value of Time.
4. Use the rates of change to compute the Levels at Time + TIME STEP according to the formula:
LEVELTime+TIME STEP = LEVELTime + TIME STEP * RATETime

5. Add TIME STEP to Time.


6. Repeat steps 3-5 until Time is equal to FINAL TIME.
See also Chapter 2, section "Computational Sequence" for more information.

Euler integration assumes that the rates computed at a given time are constant through the time interval
(TIME STEP). In general, this is not likely to be true, and that is why Euler integration is not very
accurate.
The error made in using Euler integration is proportional to the square of TIME STEP on an
integration step and proportional to TIME STEP over the whole simulation. To make the integration
more accurate, you can decrease TIME STEP. Although Euler integration is not a good technique for
getting accurate solutions to differential equations, for many business and social models where the
distinction between difference and differential equations is blurry, Euler integration is appropriate.

Difference Integration
Difference Integration is the same as Euler Integration except in the recording of the results. In Euler
Integration, the results are recorded at the end of step 3 above. With difference Integration the results
are recorded at the beginning of Step 3, before the new rates have been computed. Put another way,
Euler integration reports Levels and the values that result from those Levels, whereas difference
integration reports the Level and the values that resulted in those Levels.

TIME STEP
The best size of TIME STEP is determined by the following considerations:
TIME STEP should be equal to or smaller than SAVEPER.
TIME STEP should allow test inputs to be accessed regularly.
TIME STEP should allow data to be accessed with appropriate regularity.
TIME STEP should be smaller than 1/3 of the shortest time constant in the model (not applicable with
automatic step size adjustment in Runge-Kutta integration).
TIME STEP should be smaller than the shortest period for which a significant change in model
behavior is at all likely.
The last two of these are rules of thumb that prevents (usually, but not always) model behavior to be
significantly different than it would be with a smaller TIME STEP. Consider, for example the model:
S=STEP(1,1)~~|
SS=INTEG((S-SS)/DELAY TIME,S)~~|
DELAY TIME=.5~~|

214
If you integrate this model using Euler integration and TIME STEP=1.0 you will get sustained
oscillation of SS between 2 and 0. The correct behavior is, of course, smooth and quick adjustment to
1.0. An inappropriately long TIME STEP leads, in this case, to incorrect behavior. In general if you
see oscillation with a frequency that is near to twice TIME STEP you should test TIME STEP to see if
it has an appropriate value.
If you are using Runge-Kutta integration with automatic step size adjustment, the fourth and fifth
considerations do not apply. Vensim will automatically determine how small it needs to make TIME
STEP in order to achieve the desired accuracy or issue an error if it is unable to do so.

Runge-Kutta Integration
Runge-Kutta integration is a clever extension of Euler integration that allows substantially improved
accuracy, without imposing a severe computational burden. The idea is to step into the interval and
evaluate derivatives. This is similar to shortening TIME STEP in Euler integration, but provides more
accuracy with less increase in computation. Second order Runge-Kutta integration has an error that is
proportional to TIME STEP cubed for an integration step and proportional to TIME STEP squared for
the whole simulation. Fourth order Runge-Kutta integration has an error that is proportional to TIME
STEP to the fifth power for an integration step and proportional to TIME STEP to the fourth power for
the whole simulation.

When Vensim performs Runge-Kutta integration, it holds all exogenous and test inputs (STEP,PULSE
and RAMP) constant over the integration interval. This is done for computational efficiency, and
because the discontinuities that might result from changing these inputs invalidate the premise on
which the Runge-Kutta techniques are built. The pure delay functions (FIXED, MATERIAL and
INFORMATION) do not change within a Runge Kutta computation and the MESSAGE function
always returns zero.
Regardless of the integration technique you use, TIME STEP remains an important determinant of
when to compute exogenous values, and when to compare the model to data.

Fixed Step Size


The fixed step size methods are much like Euler integration. Using the rates of change of Levels as
computed at Time second order Runge-Kutta makes a half step (TIME STEP/2) , computes new rates
of change, and uses those rates of change to go from Time to Time + TIME STEP. Fourth order
Runge-Kutta integration does three intermediate evaluations of the rates of changes and then weights
these to give the final result. In just doing computation, second order Runge-Kutta should take twice
as long as Euler and fourth order Runge-Kutta four times as long for a given TIME STEP. The actual
differences in speed are not this great because of a number of additional things being done during a
simulation.

Automatically Adjusted Step Size


The automatic adjustment of step size uses a step halving approach. A second or fourth order Runge-
Kutta step is made, and then repeated two times at half the step size. The results are then compared.
If, for any Level, the difference between the two computations is greater than ABSOLUTE
TOLERANCE and the implied difference over TIME STEP is bigger than the value of the Level (from
the smaller step size) times RELATIVE TOLERANCE, the step is declared a failure. The initial step
size is divided by two and the process repeated. If, on the other hand, the process does not detect any
errors over an entire TIME STEP, the initial step size is doubled. The step size is never made bigger
than TIME STEP.
You can set ABSOLUTE TOLERANCE and RELATIVE TOLERANCE by writing equations for
them inside of your model as in
ABSOLUTE TOLERANCE=.001 ~Dmnl~Max acceptable error for RK4|
RELATIVE TOLERANCE=.001 ~Dmnl~Max acceptable relative error for RK4|

215
These should be constant equations since only the initial value will be used. If you do not write
equations for them, the default value of .001 will be used for both.
Because of the way adjustment is implemented, you can use a variable TIME STEP with this
integration technique and get good results. The internally computed step size is not reported or
accessible. Vensim limits the step size to be bigger than or equal to TIME STEP/256. If Vensim
cannot achieve the desired accuracy because of this limitation, a warning message is displayed at each
TIME STEP in which it fails to achieve the desired accuracy.
NOTE The automatically adjusted step size algorithms always yield a result at least as accurate as the
fixed step size algorithm with half the value of TIME STEP.
For more information on numerical integration techniques the book Numerical Recipes in C referenced
in Appendix B is very good reading.

Interactive Simulations (Gaming)

We discussed how to run a gaming simulation from the Toolbar above. You can also run gaming
simulations from the Simulation Control Dialog. The Toolbar technique works better so this approach
is really only useful when sketch information is missing or incomplete.
To run a simu lation interactively as a game, you need to define one or more variables as GAME
variables. This is done using the GAME function as described in Chapter 4. You can do this by
selecting the subtype Gaming under the type Auxiliary in the Equation Editor, as described in Chapter
6. For example, suppose you had a simple population model such as
Population=INTEG(births-deaths,100)~Rabbit~|
births=GAME(Population*.03)~Rabbit/Month~|
deaths=Population*.01~Rabbit/Month~|
If you just run this model it will show exponential growth in Population.
Open the Simulation Control dialog and click on Game. The Game Control dialog will appear.

This dialog functions much the same way the Constant Change dialog functions except the value
editing box remains visible below the list. Click on births, click on Modify and enter a new value for
births.

216
Click on the Update button and 6 will go up into the list of gaming parameters.

Continue until determines how long Vensim will run the model before coming back to you to ask for
input. Put in 50 and Press the Continue button. The simulation will progress until time 50 (you can
also cancel by pressing the Cancel button during the simulation).
Load Decisions… is used to read in a gaming input file with decisions stored by time. These files can
be created by hand or using the Model>Export Gaming menu item. The decisions will be read and the
game advanced to the recorded termination time. This is a good way to replicate the results of a
gaming session from a small file or for a slightly different model.
Backup can be used to back up the game to a prior time. If you click on this you will be asked the
time you want to back up to.

NOTE It is not possible to back up a game for a model that includes any of the pure delays (DELAY
FIXED, INFORMATION, MATERIAL, BATCH or CONVEYOR) or QUEUE functions.
At this point the Game Control dialog should show Time=50 at the top. You are still in the game.
You can enter a new value for births, or a new Continue until time. You can also use the tools. Select
Population into the Workbench and click on the Graph tool:

Graph for Population


800

400

0
0 5 10 15 20 25 30 35 40 45 50 55 60 65 70 75 80 85 90 95 100
Time
Population - GAME Rabbit
Population - SIMULATE Rabbit

Even though you entered a higher initial value for births, the base simulation population is quickly
catching up. A click on the Causes Strip graph will quickly tell you why. Having determined this you
can now go back and finish the game.

Partial Model Simulation (Not PLE or PLE Plus)


If you want to simulate just part of a model, use the Model>Partial Simulation command. To do this:
1. Open the view containing the structure you want to simulate. Partial Simulation will not work
when the Text Editor is open.
2. Highlight those variables in the sketch you want to simulate. You can do this by dragging over
them, or Shift-clicking on them. It is not possible to include variables from other views.

217
3. Select Model>Partial Simulation… and continue as you would for a normal simulation.
During Partial Simulation, Vensim will hold all variables that you did not highlight at their initial
values. Any dynamics that occur during the simulation will be the result of feedback between the
elements you have highlighted. This makes partial simulation a very effective way to test hypotheses
about the importance of different feedback loops, without having to make any changes to model
structure.
Partial simulation still requires a complete model. If you have one or more incomplete equations you
can use partial simulation to simulate an incomplete model as described below. Simulating an
incomplete model might require the definition of placeholders.
If you want to simply cut one feedback loop instead of highlighting feedback loops you can do this by
taking a complete model and deleting an arrow involved in the feedback loop. The variable that the
arrow went in to will be marked as unfinished and you can simulate the incomplete model as described
in the next section.
Note that it is not possible to perform partial model simulations from the Toolbar.

Simulating Incomplete Models


Simulating a model requires that equations be written for each variable. Often, when developing a
model, it is helpful to begin simulation experiments before a model has been completed. Ve nsim
provides a capability to do this using the Model>Partial Simulation… command. This command
simulates variables for which equations have been written while ignoring other variables. Since some
variables which have equations are likely to use other variables that do not have equations, you can
specify a placeholder value for variables that do not yet have equations.
For example, suppose that you are developing a model of market growth with technological
obsolescence as in:

Installed
product sales Product
revenue FRACTION REV SALES
PRICE
WAGE RATE
value of innovation
sales force
indicated sales force

TIME TO ADJUST SALES FORCE


availability of alternatives
sales force effectiveness
Here the inner positive feedback loop is fairly well developed, while the outer one is still pretty
abstract and needs more detail to be added. We might, nonetheless, want to simulate the positive loop
before continuing with the rest of the model. Suppose that we have the equations:
FRACTION REV SALES = 0.15
~ Dmnl ~|
indicated sales force = revenue * FRACTION REV SALES / WAGE RATE
~ Person ~|
PRICE = 100
~ $/Widget ~|
product sales = sales force * sales force effectiveness
~ Widget/Year ~|
revenue = product sales * PRICE
~ $/Month ~|

218
sales force = INTEG((indicated sales force - sales force ) /
TIME TO ADJUST SALES FORCE,10)
~ Person ~|
TIME TO ADJUST SALES FORCE = 12
~ Month ~|
WAGE RATE = 3000
~ $/(Month*Person) ~|

Placeholder Values
At this point, an attempt to simulate the model would result in a message that the model is incomplete.
However if you select the command Model>Partial Simulation… you will get the message:

and the Placeholder Tab of the Control Panels will contain:

In order to simulate the feedback loop it is necessary to have a value for sales force
effectiveness. This dialog works the same way as the dialog used to change model constants.
Click on sales force effectiveness then click on Modify, type in 100 and click on Update.

Now execute the Model>Partial Simulation… command again. This time the Simulation Control
dialog should appear. Click on the Simulate button to simulate the model. If you look at product
sales, you can look at the behavior of the partial model. For the parameters we have chosen, this is
actually a steadily declining value for sales. Our expected engine of growth is not generating growth,
and now we can fruitfully investigate why.

There is an important lesson in this simple example. Models containing a number of feedback loops
can generate a very wide variety of behavior. Theories and dynamic hypotheses that are based on the
interaction of different feedback loops are not always exactly right. By performing partial simulations
early on, you might uncover some pretty fundamental issues. This can reduce the time and effort spent
on issues that turn out to be unimportant or irrelevant.

Ignoring Variables
When you are creating a model, you might find that you don't want to specify how a variable will be
used in an equation. For example, suppose that you have specified with causal links (arrows) that

219
work flow is caused by Workforce, NORMAL PRODUCTIVITY, effect fatigue work
flow and temporary workforce. However, you have written the equation:
work flow = Workforce * NORMAL PRODUCTIVITY *
effect fatigue work flow
but you have not used temporary workforce, and you haven't decided if they will get their own
productivity, or have a fatigue effect. If you attempt to use the above equation Vensim will ask you if
you want to update the input list (to remove temporary workforce) — but you do not want to.
In the Equation Editor click on the button :IGNORE: in the More Tab.

The following equation will replace the equation you have entered:
work flow = Workforce * NORMAL PRODUCTIVITY *
effect fatigue work flow
:IGNORE: temporary workforce
The :IGNORE: keyword is telling Vensim that the equation is only partially complete, and that it is
still not using all the inputs it will eventually use. When you click on OK no changes will be made to
your diagram and a partial simulation will use the equation before the :IGNORE:.
NOTE You cannot simulate models containing :IGNORE: equations except by using the Partial
Simulation feature.
The :IGNORE: button will determine which inputs you have not used and add them after the
:IGNORE: keyword. The button can also be used to clean up a list of variables to be ignored as you
add in more variables to the equation.

220
9 Preparing, Using and Exporting Data

Vensim is designed to easily incorporate any data that may be available. This chapter:
? Discusses the format for data used in Vensim.
? Shows how data can be imported from spreadsheets.
? Describes how data can be used in models.
? Provides hints on how to manage and manipulate data.
The use of data as described here is not supported in Vensim PLE.
The term data, as used in this chapter and throughout most of this manual, refers to quantitative,
usually measured, values associated with particular times. Knowledge and analysis going into model
development, equation writing, and parameter selection are not part of this narrow definition of data.

Overview
There are two ways to use data in Vensim. First, data can be used for comparison with simulation
results. This can be done manually by comparing graphs, or automatically during optimization as
described in Chapter 10. Second, data can be used as a time-varying input into a simulation model. In
both cases, the methods you use to format the data for Vensim's use are the same. To format data for
Vensim's use it must be imported using the Model>Import Dataset command. When you import a
dataset, it is automatically loaded for use in creating graphs and tables.
The following are the most common ways to use data:
The simplest way to compare model results with data is to use the same names for model variables and
data series. If you then import the data and simulate the model, any time you bring up a graph or
table of a model variable that is also contained in the data, you will see values for both.
To use data to drive the model, name the data series with the same variable names as the exogenous
(data) variables in your model. Either write an equation for the data variable using the GET 123
DATA function or the GET XLS DATA function or, import the data into Vensim and in enter the
name of your imported data file in the Data Sources field of the Advanced Tab of the Simulation
Control dialog.
To use data and computations on data to compare to model results, it is generally easiest to prepare a
small model formulated with Data variables. The computation can be done as Data equations, or
as regular Vensim equations. The variable names should match the variable names in the model
against which comparisons will ultimately be made. Use the output from simulating this simple
model to compare to the actual model. Be sure to include the names of all data series of interest in
the simple model. This ensures that the output of the simple model contains everything of interest,
providing you with one complete dataset for comparison purposes.
To use data for computation of a payoff function, follow the steps outlined in 1 or 3 above and in the
Advanced Tab of the Simulation Control dialog, enter the name of the dataset to be compared to
the model in the Data Sources field. You will need to define a payoff function as described in
Chapter 10.
NOTE Data here only refers to time-varying data. If you want to enter Constant or Lookup changes,
see the section "Getting Constant Changes from Spreadsheets" in Chapter 8.

221
Importing Data
Vensim has a number of options for importing data. Data can be directly accessed from an active
spreadsheet application and it can be imported from simple text files in .dat format and also from tab
delimited and spreadsheet formats. Which format you choose to work with depends largely on the
sources from which you will be collecting data. Independent of the data source, the following are
worth remembering:
? For comparison, use the same name for data series and variables in the model.
? For Data variables, use the name of the Data variable in the data file.
? Data need not be equally spaced, or present at all time points.
? There is no limit to the number of data series used or the number of data points in a data series.

Active Links to Spreadsheets


You can make an active link to data contained in a spreadsheet using the GET 123 DATA or GET
XLS DATA function. For example suppose you have a spreadsheet file:

and want to use the data in row 2. Then you can write an equation
sales data := GET XLS DATA('test6.xls','sheet1','1','A2') ~~|
After simulating the model setting Print Every on the table tool to 10 we would get:

The sales data variable could then be used anywhere in the model to drive behavior. For
subscripted models you can define a vector of data series in this manner using a single equation. See
Chapter 4 for an example.

.dat Format DATA


In the .dat format for data, each individual data time-series begins with the variable name associated
with it. Following the variable name, the data is listed in two columns. The first column contains the
time for the data value; the second column contains the data value itself.
Comments may follow either the data names or the number pairs. You can add spaces freely to make
data more legible.

You can arrange variable names arbitrarily, and even repeat them, in which case Vensim will combine
the data into a single series.
You can name the .dat format file anything you wish. The normal extension is .dat, although you may
override this.
The general format for .dat data entry is as follows:

222
VARIABLE NAME 1
Time Point 1 Data Value 1
Time Point 2 Data Value 2
...
Time Point N Data Value N
VARIABLE NAME 2[subscript1] <TIME BASE NAME>
Time Point 1 Data Value 1 Optional Comment
Time Point 2 Data Value 2 Optional Comment
Time Point 3 Data Value 3 Optional Comment
. . .
Time Point N Data Value N Optional Comment
VARIABLE NAME 3[subscript3] / Optional Comment
Time Point 1 Data Value 1 Optional Comment
Time Point 2 Data Value 2 Optional Comment
. . .
Time Point N Data Value N Optional Comment
Note the use of subscripts associated with VARIABLE NAME 2 above. Subscripts have the same
format as they do in a model and are available in Vensim Professional and DSS. Vensim does not
support the use of a Subscript Range in data series you enter; you should include a separate data series
for each Subscript Constant for which there is data. Data need not be available for all members of a
Subscript Range.
You can include a comment on the line in which the variable is named as long as the comment is
separated from the variable name by a slash /. On the lines containing the data, the comment need not
have an explicit separator.

Although not required, you may prefer to separate the data to be used as exogenous inputs from the
data to be compared with simulated variables. The exogenous data is required to run the model, while
the comparison data is normally used in the validation and testing of the model. Vensim supports the
use of two or more files containing data.
The optional Time Base name specified after the variable name identifies the model Time Base to be
used to interpret the data. If a data file begins with a Time Base name enclosed in angle brackets < >,
Vensim assumes that all data will use that Time Base unless you explicitly override this by specifying
a different Time Base for a data series.
You will notice that there is liberal room for comments in this data format. If you want to keep a
history of where data comes from and who changes it is possible to do this using comments.

Example
<decimal year>
emigration[USA,USSR] / People leaving USA for USSR
1900 51000
1905 20000 new emigration laws enacted
1910 21000
1915 22000
GNP[USA] <MONTH> / Note that this is on a monthly
1 200E12 time base
61 220E12
population[USA]
1900 2.8e6
1904 3.5e6

223
Importing .dat format Data into Vensim
If you open a .dat format file in the Text Editor, there will be a command Dat2VDF appearing in the
File menu. Selecting this command will convert the data to a .vdf file and load it into Vensim for use
with Analysis tools. You can also load .dat format data in using menu Model>Import Dataset. There
are no options involved in loading .dat format data. You will be informed of any errors and told which
data series were imported.

Tab Delimited and Spreadsheet Data


Vensim also supports the entry of data from Tab delimited files, Lotus 123 format worksheets, and
Microsoft Excel format worksheets. These formats can readily be created by spreadsheet programs.
The general format for a Tab delimited file is just a series of numbers separated by Tabs (ASCII 08).
Lotus 123 format worksheets (.wks, .wk1, .wk2 and .wk3) are created automatically by Lotus 123 and
can normally be created from other spreadsheet programs using the Save As command. Excel format
worksheets (.xls) are automatically created by Excel. Note that Vensim's importation mechanisms
support only the simple two dimensional table format for spreadsheet data.
In working with these different sources of data, all data is treated in the same way and we will refer to
data from any of these sources as being in a table or tabular format. In working with tables, Time can
either run across the rows or down the columns. Because spreadsheets often have commentary that
will not be used, and may contain data in non-numeric format there are a number of options that can be
used when importing files.
A tab delimited file (upset.tab) might look like this (the first character after a Tab is shown bold):
Upset electronics production notes:
-----------------------------------
1984 1985 1986
Starts 23300 12235 19943
Note that there was a strike in 1985
Workforce 130 143 129
Turnover High Low Normal
This file contains numbers representing time, starts and workforce, some commentary and spacing and
some qualitative measurements of turnover. In order to convert this to .vdf format you will need to:
1. Use rows 3-7 (row 1 is a title and row 2 contains only dashes) and columns 1-4 .
2. Look for time going across.
3. Get time from row 3.
4. Skip row 5.
5. Get the variable names from column 1.
6. Convert Low, Normal, and High, (in row 7) to numbers (0,1 and 2).
The Model>Import Dataset command allows you to do this. But before you invoke that command, it is
necessary to set up a translation file that can be used on row 7 to convert the qualitative entries into
numbers. Call this file upset.trn and use the Text editor to enter the following
Low=0
Normal=1
High=2
The left hand side is the name as it appears in the original file. The right hand side is the name as it
should be translated — this will normally be a number.
Assuming that the original tab delimited file is called upset.tab when you invoke the Import Dataset
function and select the file upset.tab you will see:

224
In order to properly translate the file we need to make the changes listed above. To do this:
Change the from Row# from 1 to 3 to reduce the range used.
Time Across is the default and does not need to be changes.
Fill in the Row: field for Time with 3. The radio button should automatically highlight.
Enter 5 in List of rows to exclude.
Var : the location of variable names has column 1 as the default just leave this.

Type "ROW#7=upset.trn" in the box to the left of the "Add Ed" button and click on that button. You
should see:

225
Click on the OK button.

You should get the message translated without error, and 3 values should be written for each of
starts, workforce and turnover.

Table2vdf Options
Working through the Table to VDF dialog box the options are:

Range displays that portion of the table you want to use. You can click on the All checkbox or type in
the values you want. Anything outside this range will simply be ignored. Regardless of the range you
choose, the row and column numbers used elsewhere always refer to those of the original table.
Time Axis Name lets you specify the name to be used for the time axis. This is normally Time, but
could be an alternative time axis name such as Decimal Year.
? Across - specifies that time runs across the table.
? Specifies that time runs down the table. If you click this all of the Col# labels below will become
Row# labels and vice versa.
Time Axis Recognized When:
? Variable is time axis: looks for the name entered in the Time Axis Name: box and then considers
that row or column as time. Note that with this option enabled, multiple time axes may be entered,
and variables below the entered time axis will be assigned that time axis. In addition, any variable
names enclosed in angle brackets < > will be treated as alternative time axes even if the name is
different from that of the main time axis.
? Row# - lets you specify the row (or column) in which to find the time values. This was necessary
in our example because the time axis was not named.
? Formula - lets you specify time as a formula. The formula is applied only to the columns/rows
that are actually used. In our example the formula 1984 + 1*col would have given the same
results (note that col in this formula is relative to the first column with numbers and is not
increased on excluded columns or columns with name information).

226
Var:
? Col# Specifies the Column/Row in which to find the variable names.
? File - specifies the file in which names are assigned to each row or column. This file must have
the format
4=Starts
5=Workforce
6=Turnover
and must include names for all the rows or columns of interest. The default extension on files
for naming variables in .var, but you may choose another.
Subs: If the Subscripts for a variable are in a place different from the variable name, you can tell
Vensim where to look for subscripts. Enter the column or row number for each subscript. This works
just like finding the variable name except that the subscript names are appended to the variable name
with the appropriate punctuation.
Strip "", if checked, will look for quotation marks surrounding names and automatically strip them
off. This is useful for spreadsheet programs that dump out names with quotation marks around them.
All types of quotes, including single quotes, double quotes and balanced quotes will be stripped.

Value for Empty Cells: Sets a value for any cells that are empty (contain only spaces). Normally
empty cells are just ignored but sometimes it is useful to assign them a value (often 0.0).
List of Rows to Exclude: Allows you to create a list of rows that are not to be processed. Rows
outside of the specified range are automatically excluded. This list should be number separated by
commas as in: 1,3,7,9. If you want to exclude many contiguous rows you can use a minus sign -
between the numbers as in 1,3,4-8,12 which is the same as 1,3,4,5,6,7,8,12.
List of Columns to Exclude: This is the same as the list of rows to exclude except that it applies to
columns. Again note that the column numbers are those of the original table.
Translation Control: Allows you to specify the translation of strings to numbers (or other strings).
To use this enter ROW#n=filename or COL#n=filename in the box the left of Add Ed, then click on
Add Ed.
? Mov Sel — is a simple mechanism for reordering the list. Click on the line you want to move,
then click on the Move Sel button then click on the line you want to place the line you are moving
above. The line will be moved. Because the translation process always works from the original
table, the order of translation is not important. This is simply a mechanism for improving
readability on the translation list.
? Ed Sel — allows you to modify an existing entry. Click on the line you want to edit, then click on
Ed Sel and the line will be moved to the editing box. When you are done editor click on the Add
Ed button.
? Add Ed — moves the contents of the editing box into the list. Before the contents are moved they
are checked to make sure they have the right syntax. The filename is not checked for existence or
format until you click on the Translate Button or the OK button.
Load Format Information: is a shortcut for typing in all the formatting entries you can make. This
allows you to open a previously-created format file and use this file, instead of typing in all the format
information every time you process a particular data file.
Save Format Information: allows you to save to a format file the information that you have entered
into the Table to Vdf conversion dialog. If you are only making a couple of changes, this is not so
important. But if you have entered a large amount of formatting information, a format file can be very
helpful. If you click OK and you have not saved a format file, you will be prompted to do so.
Contents View: The information under contents view is designed to allow you to review the table with
which you are working. You can see a particular row using Choose, and scroll through the rows using

227
Nxt and Prv. Similarly for columns. When you press the Translate button, the content of the rows and
columns after they have been translated is displayed.
OK Attempts to convert the data to .vdf format. If you have entered a bad number you will be given
the message "Cannot read screen" and positioned in the offending box, otherwise an error window
showing the results of the conversion will appear.
Translate: Uses the translation control entries to convert any rows or columns and displays the results
for the translated rows and column under Contents View.
Cancel lets you leave the dialog without performing any data conversion.

Time Slop
When data are entered, there can be many different values at many different times. Since the time at
which a datum is available is treated as a real number, essentially the same time may appear as
different numbers (for example 1991.000 and 1991.001). To try to overcome this problem, the
conversion process for data uses a concept called "time slop". Put simply, time slop is the amount of
difference in times that are likely to be due to numerical problems rather than true differences in time.
For example, if the time slop is .5 and we have
s1
1.2 44
2.3 54
s2
0.8 36
2.0 22
the values for s1 and s2 are treated as if they occurred at the same times (1.2 and 2.3). This is because
.8 is within .5 of 1.2 and 2.0 is within .5 of 2.3. The first two time points (1.2 and 2.3) are treated as
new time points, but .8 and 2.0 are never used because they are considered the same as 1.2 and 2.3,
which already exist.
You can set a value for time slop in the Global Options dialog, Settings tab (see Chapter 16). If you
set this value to 0.0 (the default), Vensim will use its own algorithm to compute time slop when
importing datasets. For most data this algorithm will work quite well. However, if you have a lot of
data (with some monthly, some weekly, and some yearly), you will get better results if you set your
own value for time slop. Time slop is generally less of an issue when using tabular format data.

Managing Data
Precisely how you manage data depends on the data available and your purpose. However, there are
two techniques that have proven very useful.
The first technique is the simplest. Put all data equations for exogenous drivers in one group in a
model and use only raw data for comparison. This works fine unless you need to manipulate the raw
data before comparing it to model results.
The second technique is to build a separate data model. This is useful if the model must manipulate a
lot of raw data. In this way, you can keep the names of the data series the same as the names of the
model variables. This is not possible inside of a single model. (We made this design choice to avoid
the confusion arising from a single model having a data series and a variable with the same name.
While Vensim might be able to keep track of this, trying to distinguish what was actually on the right
side of an equation from what was intended to be on the right side would be confusing for users.)
Such a "data" model contains only := equations. Vensim simulates the model using the raw data as
input. The resulting data set (.vdf) file contains both the raw and the manipulated data. The "real"
model uses this output data set for simulations and never directly refers to the raw data.

228
Using Data to Drive a Model
As described in Chapters 2 and 3, Vensim allows you to use Data variables, sometimes also called
Exogenous variables. These variables are not computed during simulation, but are loaded in for use
during simulation. You can specify a variable is to be used as a Data variable by marking a variable as
of type Data in the Equation Editor, or writing an equation with no = sign, or an equation with a :=
sign. Variables for which no equations have been written will also be treated as Data variables.
If the only data variables you have in your model are defined use GET 123 DATA and GET XLS
DATA functions then you will not need to specify a data file to use since this data will be read directly
from the spreadsheet applications.
If you have Data Variables that are not defined with the GET ... DATA functions, it is necessary to
specify the dataset(s) that contain values for these variables. There are two ways to do this:

Specifying Data Sources in the Toolbar


To specify a data source from the Toolbar click on the Set button and then click on the : button to the
right of the first editing box. A file selection dialog will open. Select the name of the data file you
want to use (for example upset).

You do not need to include .vdf since Vensim will add this. If you have data in more than one data
file list the files separated by commas. If a data variable appears in more than one driving dataset only
the values from the last dataset containing the variable will be used.

Specifying Data Sources in the Simulation Control Dialog


Data Sources are specified in the Advanced Tab of the Simulation Control dialog.

In the Data Sources field, you specify one or more .vdf files that contain values for the Data variables
in the model. If a data series is contained in more than one of the data files you specify, the data series
from the last file will be used. Multiple file names are separated by commas. Only .vdf files are valid
data files for Vensim to read during simulation.
The datasets used as input for simulation can come from other simulations, or from importing data as
described above. Using datasets that are the output of a model simulation makes it simple to break off
a portion of a model and work with only that portion. Importing data from other data sources makes it
simple to use arbitrary driving inputs.
If you are using the optimizer for model calibration, the calibrating datasets will also be placed in the
Data Sources field. Because Vensim enforces a strict naming convention around data, there is no
conflict when driving datasets (exogenous inputs) are being used at the same time as calibration
datasets.

229
Lookups and Data
For a variety of historical reasons, a common way to put data in models is through the use of Lookup
tables which use Time as the input. While it is possible to do this in Vensim, it is not a recommended
practice. The entry of data into Lookups can easily lead to the introduction of errors. Because it is so
easy to create exogenous data using any text editor, you should do this and import it as a dataset
instead of using Lookup tables as drivers. If you are using data to drive a model, the different
interpolation modes offered for Data variables can prove very helpful. If you are comparing model
behavior with data, Vensim has built in logic to handle missing data points. The Strip Graph and
Graph tools also work best when a data series has the same name as a model variable, something that is
not possible when the data is entered through a Lookup.

Loading Data as a Model

We have discussed importing data for use with a model. It is also possible to import data without
having a model to use it with, so that you can examine the data inside of Vensim. To do this, first go
through the importation process for the data as described above. Then select the File>Open Model
command and for file types select Datasets (Runs). Select the dataset you have imported and click on
Open.
When you load data in this manner Vensim creates an empty model containing the names in the data
file, with empty equations for each name. Vensim also loads the dataset for analysis. You can use the
Variable Selection control to select data series into the workbench and create graphs or tables.

You can also use the Sketch tool to create hypothetical causal relationships and do causal tracing on
the data. For example, suppose that your data contains value for profit, revenue and cost. You

can use the Model Variable tool and add each of these to the sketch, then join them up to form:

revenue
profit
cost

If you now select profit into the workbench and ask for a Causes Strip graph you will see a graph of
the data for profit, with graphs of the data for cost and revenue below.

If you load a dataset containing subscripted variables in this manner, you will likely see subscript
range names such as RANGE0 and RANGE1. These are automatically created by Vensim during the
data importation process. Though the Subscript Range names may be obscure, the Element names will
be those from the original file.

Exporting Datasets
Just as it is often useful to move data into Vensim, it can also be useful to export data out of Vensim.
The special format that Vensim uses to archive data and simulation results is powerful and convenient
for use within Vensim, but not accessible to other applications. To make results created in Vensim
accessible for use elsewhere, you can export data from the Table tool, or use the Export Dataset
functions. These functions allow you to extract some or all of the information contained in a .vdf file.
When you invoke the command Model>Export Dataset, you will first be asked for the name of a
dataset to convert. You can select any dataset, it does not matter if it comes from the current model, or
was itself the result of importing data. Once you have selected a dataset you will see the Dataset
Export Options dialog:

230
This dialog allows you to select the format to export the data in and contains a number of options:

Export to lets you specify the file you want to export the data to. If you leave this blank, the data will
be exported to a filename with the same name as the dataset being exported and an extension
appropriate for the type of file you are exporting to.
Unicode UTF-8 (Vensim Standard) lets you specify the text encoding for the output file. Not all
programs will read UTF-8 text. Click on this button to select an alternate encoding. ANSI Standard
may work better with Excel. If you do not have any characters in the model variables beyond A-Z, a-z,
numbers and punctuation the results will be the same for any encoding.
Export as lets you set the format for the exported data. You can export to a .dat format file, a tab
delimited file, a Lotus 123 format spreadsheet file, an Excel format spreadsheet or a data list format.
The .dat format file is discussed under importing. Tab delimited is just a tabular view of output. The
data list format is actually a tab delimited file with each line in the form:
Variable Time Value
or if Put subscripts in own cols is checked
Variable Sub1 Sub2 Time Value

Where the first line contains the subscript range names used and later lines the subscript constants.
Note that the order of subscripts will follow the subscript range names from the first row and is not
dependent on the order of subscripts in the model variables. This is intended to make it easier to get the
data into a database.
If Add cols is checked then the entry in the editing box is included as
Variable Sub1 Sub2 Extra1 Time Value

This redundant format is useful if you are loading values into a database or want to create pivot tables.
Use an exclamation point ! to add the current run name (most useful in batch mode). Note that if you
want to add more than one extra column separate the values with a \t as in modeloutput\tExperiment1
Save List allows you to name a file containing the list of variables you would like saved. If this is left
empty, all the variables in the model will be saved. If a name in the list is not found, an error will be
reported and processing will continue with the other names. You can create and modify the save list
by clicking on the Ed… button to the right. See Chapter 10 for more information on save lists.

231
Time Running lets you set whether time will run across or down. Because some spread sheet
programs have limitations on the number of columns it may sometimes be useful to have time running
down. This option has no effect on .dat format files or datalist format files.
Put Subscripts lets you set whether you want to see subscripts with the variable name, or in their
own columns (rows if time is running down). Putting subscripts in separate cells can make it easier to
read and analyze a spreadsheet. The default is to put subscripts as part of the variable name enclosed
in square brackets []. When subscripts are put into separate cells the values for the variables will be
shifted over to the left (or down) for all variables. Variables that do not have subscripts will be
followed by one or more blank cells.
Time from lets you specify the first time to be exported and to the last time to be exported. If these
are left blank the full time range will be exported. If you specify with interval values will only be
exported on that interval. If you leave this blank all values in the range will be exported. If you leave
all of these fields blank all the value will be exported.
Append data to file determines whether the data is added to the end of a file. If you select this option
and the output file already exists the data will be appended to the end of the file instead of overwriting
the file. This can be a useful option if you want to record the results of a number of experiments in one
place.
Don't Show Time allows you to suppress the Time axis. This is most useful when you are appending
data and don't want to keep repeating the values for Time. Not applicable to .dat or datalist format
files.
Write numbers in European format allows you to output numbers using the , as the decimal
separator.

Export Dataset Example


Suppose you have a model run with values for Profits by region, sales by region and
total revenue along with 200 other variables. The values run from time 0 to 100 by .25. You
would like to look at values for only the variables you are interested at times 10, 11 and 12
First create a save list (prof.lst) containing the variable names that you want to have saved. Each name
should appear on its own line as in:
Profits
sales[east]
sales[west]
total revenue
If you list a variable that is subscripted without subscripts than all elements of that variable will be
extracted. For example Profits above will result in Profits[east] and Profits[west]
being extracted.
Now export the file using the settings

232
This will result in the output
Time 10 11 12
profits[east] 20.2 10.1 14.3
profits[west[ 10.1 14.4 3.3
sales[east] 120.3 111.1 100.1
sales[west] 87.22 77.3 86.2
total revenue 1.04E5 1.23E5 9.99E4

Exporting Sensitivity Results


If you ask to export a dataset that was created during a sensitivity simulation you will be asked:

If you answer No Vensim will continue to export only the run results using the dialog described above.
If you answer Yes you will get a different set of options.

233
Export to determines what file the data will be written to. You can only export sensitivity results to
tab delimited files.
Encoding determines the text encoding of the output file. See the discussion for exporting above.

Simulation index/time running determines the direction of the simulation index or time, depending
on the setting of Modify variable names by below. If this is down (the default) each row will
represent either an experiment or, if you have checked Simulation number under Modify variable
names, a time.
Write numbers in European format allows you to output numbers using the , as the decimal
separator.
Export only final time, if checked, suppresses the reporting of values by time. If this is checked, the
items below it are ignored since it is not necessary to modify any names.
Modify variable names by is used to determine how sensitivity results are mapped to a two
dimensional array. By default sensitivity results are modified by time (T1 Profit, T2 Profit
and so on). See the example below for more detail.
Modify names using determines how the modified name appear. If you have the variable
profit[south] then this would become T1 profit[south] or profit[south,t1]. See
the example below for more discussion.

Example
Suppose that you performed sensitivity analysis for a total of three simulations on a model that runs
from time 0 to 1 varying target margin. The results might look like this
Time 0 Time 1
Simulation 1
target margin .2
Profit[south] 10 20
total profit 24 18
Simulation 2
target margin .1
Profit[south] 20 18
total profit 26 28
Simulation 3
target margin .3

234
Profit[south] 30 10
total profit 44 8
By selecting to see the results at the final time and choosing Across for Simulation index/Time
running you would get
Simulation 1 2 3
target margin .2 .1 .3
Profit[south] 20 18 10
total profit 18 28 8
and it would be possible to transpose this by choosing Down for Simulation index/Time running.

If you ask to see all the results, again running the simulation index down, modifying variables by time
and choosing the prefix option you would get:
Simulation 1 2 3
target margin .2 .1 .3
T1 Profit[south] 10 20 30
T2 Profit[south] 20 18 10
T1 total profit 24 26 44
T2 total profit 18 28 8
the same thing choosing the final subscript option would yield:
Simulation 1 2 3
target margin .2 .1 .3
Profit[south,T1] 10 20 30
Profit[south,T2] 20 18 10
total profit[T1] 24 26 44
total profit[T2] 18 28 8
If you choose to see all the results modifying the variables by the simulation index and choosing the
prefix option you would get:
Time 0 1
S1 target margin .2
S2 target margin .1
S3 target margin .3
S1 profit[south] 10 20
S2 profit[south] 20 18
S3 profit[south] 30 10
S1 total profit 24 18
S2 total profit 26 28
S3 total profit 44 8
Finally choosing the same options except asking to see the simulation numbers as a final subscripts
gives:
Time 0 1
target margin[S1] .2
target margin[S2] .1
target margin[S3] .3
profit[south,S1] 10 20
profit[south,S2] 20 18
profit[south,S3] 30 10
total profit[S1] 24 18
total profit[S2] 26 28
total profit[S3] 44 8

235
All of the formats can be transposed and all are just different representations of the same data. Which
one is most convenient depends on what you plan to do with the results. If you want to work further
with them in Vensim, the last format may prove to be the most useful.

236
10 Advanced Simulation Techniques

This chapter describes how to:


? Setup and use Save Lists
? Run Sensitivity Simulations.
? Define the payoff function.
? Specify search parameters for Optimization.
? Set Optimization options.
? Interpret and use the output of Optimization.
? Use the Kalman Filtering function in Vensim.
Note that some of the material in this chapter is advanced in nature, and its discussion presumes
familiarity with probability and statistics.
The material in this Chapter is not applicable to Vensim PLE and the optimization and Kalman
Filtering discussion is applicable only to Vensim Professional.

Overview
To do a sensitivity simulation you must specify a set of constants to change and a Save List which is a
set of variables to save values for. To do an optimization you must specify a set of parameters to
search over and create a Payoff Definition that determines how good an individual simulation is.
The Save List and Payoff Definition are also useful elsewhere. In addition to sensitivity simulations a
Save Lists can be used when exporting data and when performing simulation or gaming with very
large models. A Payoff Definition can be used with a regular simulation to give a summary number
for the simulation and optionally report summary statistics.
Because of this dual purpose in this chapter we first discuss Save Lists, then Sensitivity Simulation
even though when you perform a Sensitivity Simulation from the Toolbar you will first define the
Sensitivity Control parameters and then define the save list. Similarly, we will first discuss Payoff
Definitions, then optimization even though when you can setup Payoff Definition files by starting the
Optimization wizard from the Toolbar.

Save Lists

Save Lists are used in sensitivity simulations, to control the export of datasets, to determine what is
stored in normal simulations, and to control the writing of gaming changes in Venapps. Save Lists let
you manage what data are stored. When you make a normal simulation, behavior for all model
variables are saved. In a sensitivity simulation where one hundred simulations is common, this would
make the resulting run file about 100 times as large which, except for very tiny models, is impractical.
For normal simulations of very large models, save lists can dramatically decrease memory and storage
requirements and make the simulation run many times faster. However, save lists can also prevent
Causal Tracing from working properly so they should be used with care.
A save list is simply a list of variables you want to save. You can either enter this list using a text
editor, or use the Save List control dialog.
You can open the Save List control dialog from a number of different dialogs. In all of these dialogs
you can click on the Ed or Edit button to the right of the save list file name. If there is no file name

237
present, you will be prompted for a name. Select or type in the name of the file you want to use. If the
file exists, its contents will be loaded into the dialog, otherwise the dialog will open empty:

Filename specifies the name of the file containing the savelist. You can change the name to save your
modifications to a new file. If you do this and the file you name already exists you will be asked if you
want to overwrite it.
Choose New File... allows you select a different savelist to work with. When you click on this a File
Selection dialog will open. Select the file you want to work with.
Clear Settings will empty the save list. This allows you to start over.

List of Variables to Be Saved contains the names of the variables to be saved. Click on an item in the
list and click on the Delete Selected button to remove it from the list. Click on the Modify Selected
button to change it.
Delete Selected deletes the selected item from the list.
Modify Selected removes the selected item from the list and places it in the editing box.
Add Editing takes the contents of the editing box and adds it to the list.

Use the editing box to type in and add the variables you want to save. The Select button will bring up
the Variable Selection dialog. If you are using subscripted variables, you can use the variable name
with no subscripts to save all elements, or just save specific elements.

You can save Auxiliaries, Constants, Initials, Levels and Time Bases. For normal simulations, all
Constants and Initial values are saved so you do not need to specify them here. For sensitivity studies,
all of the Constants being changed are saved automatically and do not need to be included in this list.
In either case, however, including them will not do any harm.

You can use the wildcard *LEVEL to force all the Levels in a model to be saved. This is most useful
in regular simulations since it permits the backing up of models in Gaming mode and also the
resumption of models at a time other than the final time.

Subscripts
If a variable in a savelist is subscripted you can simply use the variable name with no Subscripts to
save all the elements of the variable. If you want to save specific elements, dimensions or subranges

238
just specify those. For example, stock[item,store] would save all items at all stores as would
stock, while stock[milk,store] would only save the stock of milk at ever store and not the
other items.

File Format
The file format for a save list is exactly the same as the format in the List of Variables to be Saved in
the dialog. Each variable name is entered on a separate line.

Simulating with a Save List

Save lists are not required for normal simulations. The Simulation Control dialog has a separate entry
for save lists to be used during simulation. If you use a save list in a normal simulation, only those
variables you specify will be saved. This can make model analysis quite difficult, therefore the use of
save lists for normal simulations is intended only for very large models where the results are likely to
require substantially more than 1 megabyte of disk storage. To use a save list in a regular simulation,
add it in under the Advanced Tab of the Simulation Control dialog.
For variables that are not in the save list, only the terminal value for the variable will be stored. If you
ask for a graph of such a variable it will be displayed as constant at the terminal value. If you are using
custom graphs, it is very important to make sure that all the variables that will be graphed are included
in the save list. For work in progress graphs this is especially true, because they will look quite funny
if they are rescaled during a simulation and the values being graphed are not available.

Sensitivity Simulations (Monte-Carlo)


Vensim has the capability to do repeated simulations in which model parameters are changed for each
simulation. This can be very helpful in understanding the behavioral boundaries of a model and testing
the robustness of model-based policies. An example of sensitivity testing is given in Chapter 11 of the
Tutorial. To do a sensitivity simulation, you must enter a list of parameters that will be changed and
specify a Save List as discussed above. The Sensitivity Graph tool, Bar Graph tool and Stats tool can
then be used to view results. These tools are discussed in Chapter 13. The results can also be
Exported for further analysis as discussed in Chapter 9.
You can start a Sensitivity simulation from the Toolbar or from the Simulation Control dialog. To start
from the Toolbar click on the Sensitivity Icon . This will start the Sensitivity Simulation Setup
wizard which will first allow you to set up the parameters to change, then specify the savelist. Once
the wizard is open click on Next to go to the next step in the process or Prev to go to the previous step.
There is also a Finish button that can be used anytime if you have previously gone through the process
and set up the savelist to be used.
To Start a sensitivity simulation from the Simulation Control dialog you must first specify the name of
the sensitivity control file and sensitivity save list in the Sensitivity Tab of the Simulation Control
dialog. For both of these files there is also an Edit... button that allows you to make changes to them.

The actual appearance of the dialog for setting control parameters and specifying the savelist will
depend on whether you are starting sensitivity simulations from the Toolbar, where they will be
wrapped in the wizard, or the Simulation Control Dialog where they will be standalone dialogs. The
Savelist Control dialog discussed above is shown as a standalone dialog. Here we show the Sensitivity
Control dialog wrapped in the Sensitivity Simulation Setup wizard.

239
Filename is the name of the Sensitivity Control file. If no sensitivity control filename has previously
been specified Vensim will use the model name or, when using the Simulation Control dialog, you will
be queried for a name. You can type in a different name if you like. If you do this and that file already
exists you will be asked if you want to overwrite it. You do not need to include an extension, Vensim
will automatically add one.
Choose New File... allows you to choose a different Sensitivity Control file to work with. When you
click on this a File Selection dialog will open. Select the file you want to work with and its contents
will replace those in the dialog.

Clear Settings will remove all the parameters and reset the number of simulations, initial noise seed
and type of sensitivity simulation to their default values.
Number of simulations lets you set the number of simulations that will be performed. Though this
number is not restricted, the time it takes to complete the simulation and display the Sensitivity graphs,
along with the storage requirements, make it sensible to try to keep this number less than 1,000. If you
leave this blank, 200 simulations (the default) will be made. This number will not be used if you are
doing univariate sensitivity testing using the VECTOR distribution. If you are doing Latin Hypercube
searching, this number will normally be in the 10-100 range.
Noise Seed lets you specify the seed to be used in computing the random numbers for the sensitivity
analysis. If you repeat the same analysis twice you will get the same results. If you wish to do another
trial with the same noise characteristics, but different values for the parameters being chosen, then you
can change Noise Seed. Enter an integer between 0 and 231 (about 2E9).
? Multivariate (change all together), if selected, causes all constants to be changed together. If
you are using random control to change constants, this would normally be selected.
? Univariate (change one at a time), if selected, causes first one Constant to be changed and then
another, with the first Constant set back to its normal simulation value (the model value or
changed value entered for it). This is a useful option for doing a series of VECTOR searches
across parameters.
? Latin Hypercube (change together exhausting axes ranges) , if selected will cause a Latin

240
Hypercube search to occur. A Latin Hypercube search is simply a mechanism to ensure that the
full range of each parameter being varied is explored in the number of simulations specified. This
is desirable for big models where each simulation takes a long time.
? Latin Grid (weighted grid search), if selected, will conduct a grid search using the specified
probability distributions to divide the parameter space. The number of simulations specified is the
number of divisions, and will be raised to the power determined by the number of search
parameters to determine the actual number of simulations required. This is similar to specifying a
multivariate search with VECTOR distributions for the parameters but will sample the
distributions more coarsely on the tails.
? File (use a file to specify parameters), if selected, will use a file to determine what inputs to
change, and ignore any constants specified in this dialog. This file must be a tab delimited text file
(UTF8 for international characters). The first row should contain a list of model constants (tab
delimited), with the values on each successive row. If a value is missing from this file the
previously used value is repeated.
NOTE If you enter only 1 parameter in the sensitivity parameter list, then Univariate and Multivariate
searches are the same.
Currently active parameters is a list of model Constants and the way you want to control them.
Each line contains a constant and the controlling information in the form:
model const=RANDOM UNIFORM(.4,.8)
and so on. To remove an item, click on it then click on Delete Selected. To modify an item, click on it
then click on Modify Selected, or double click on it. To add an item, enter the information about the
item in the editing box and click on Add Editing.
Delete Selected deletes the currently selected item in the list.

Modify Selected removes the currently selected item from the list and puts it in the fields below for
modification. If you are currently modifying something you will be asked if you want to abandon what
you are modifying. Answer yes if you want to discard it. Answer no if you want to keep it, then click
on Add Editing, then click on Modify Selected.
Add Editing adds the information you are working on into the list. If you have not finished the
specification you will receive a message telling you what is missing.
Parameter lets you specify the model Constant that you want to change. Note that you can only
change model Constants. Click on the Sel button to open the variable selection dialog to select a
Constant.
NOTE If you are using a model with subscripts the full set of subscripts (with Subscript Constants
not Ranges) must be specified here.
Distribution lets you pick the distribution you want to use for the sensitivity on the model Constant.
See "Distributions" below for a discussion of the different choices. The box to the right contains a
drop-down list of the available choices.

Model Value: Will display the base model value for the parameter currently in the editing box. This
can be helpful for determining the appropriate range to vary a parameter.
Minimum Value lets you set the minimum value that the model Constant can take on. This can be a
number, or the name of a model Constant. (The reason to use a model constant here is largely for
conducting sensitivity testing from within a Vensim Application. In this way you can allow the
application user to modify the sensitivity ranges through the use of model constants.)
Maximum Value lets you set the maximum value that the model Constant can take on. This can be a
number, or the name of a model constant.

241
The four remaining boxes are, potentially, used to let you specify additional information about the
distribution of a model Constant. They can be numbers or model Constants. Each will be grayed if it
is not used with your current selection of distribution.

Distributions
Vensim lets you choose from between a number of distributions in performing sensitivity analysis.
The VECTOR distribution simply runs through a series of increasing values. The others all involve
drawings from random distributions. The distributions you choose should be based on the nature of
the models you are working with and the parameters you are changing.
All of the random distributions are truncated by the minimum and maximum values you specify. You
can make these numbers as broad as you want, but for most models there are limits on Constant values
beyond which model results begin to become less meaningful.

NOTE The random RANDOM… distributions are identical to the Vensim functions documented in
Chapter 4 except that they do not take the final seed argument. The RANDOM LOOKUP distribution
also has a different argument order. The VECTOR distribution can only be used in sensitivity
simulations – it is not part of the modeling language.

RANDOM BETA(min,max,A,B,shift,stretch)
Draws a number from a beta distribution where the value for alpha is A and the value for beta is B.
The resulting number is multiplied by stretch and then shift is added.

RANDOM BINOMIAL(min,max,P,N,shift,stretch)
Draws a number from a binomial distribution where the underlying probability is P and there are N
draws. The RANDOM BINOMIAL distribution will always draw an integer value. The resulting
number is multiplied by stretch and then shift is added.

RANDOM EXPONENTIAL(min,max,shift,stretch)
Draws a number from an exponential distribution that starts at 0 and has mean 1. Before the value is
returned it is multiplied by stretch, and then shift is added to it. Note that if min is bigger than shift
only the middle of the distribution will be used.

RANDOM GAMMA(min,max,order,shift,stretch)
Draws a number from a Gamma distribution (where the underlying Poisson distribution has mean 1) of
the specified order. The value for order does not need to be an integer. The draw from the
distribution is multiplied by stretch, and then shift is added.

RANDOM LOOKUP(min,max,lookup,shift,stretch)
Draws a number from the arbitrary distribution defined by the Lookup function lookup. lookup does
not need to have an area of one as it will be normalized. The output range for the random numbers
being generated is defined by the input range of the Lookup.
NOTE The name of the Lookup to be used is the third argument to this function while it is the first
argument to the simulation function RANDOM LOOKUP.

RANDOM NEGATIVE BINOMIAL(min,max,draw prob,number success,shift,stretch)


Draws a number from a negative binomial distribution. This is the number of tries required to achieve
number success successful outcomes where each outcome has probability prob. This is an integer
before it is shifted and stretched. The resulting number is multiplied by stretch and then shift is
added.

242
RANDOM NORMAL(min,max,mean,standard dev)
Draws a number from a normal distribution with the specified mean and standard deviation. In this
case the shift and stretch parameters have a simple interpretation and so have been renamed.

RANDOM POISSON(min,max,mean,shift,stretch)
Draws a number from a Poisson distribution with the specified mean. The resulting number is
multiplied by stretch and then shift is added.

RANDOM TRIANGULAR(min,max,start,peak,stop)
Draws from a triangular distribution starting at start with the specified peak and stopping at stop. By
mixing the min, max, start, peak and stop values you can easily achieve tent like distributions.

RANDOM UNIFORM(min,max)
Draws from a uniform random distribution.

RANDOM WEIBULL(min,max,shape,shift,stretch)
Draws from a Weibull distribution starting at 0 with mean 1 and having the given shape. Before the
value is returned, it is multiplied by stretch and shift is added. The Weibull distribution with shape 1
is the same as the exponential distribution.

VECTOR(min,max,increment)
Generates a sequence of numbers from min to max by increment. This sequence is not random, but
uniformly increasing. VECTOR is most useful in univariate sensitivity testing, or performing an
exhaustive grid search. Combining one VECTOR with other RANDOM distributions is not likely to be
very useful. VECTOR is not a available in the simulation languge.

File Format
You can set up and run sensitivity simulations using the Sensitivity Control dialog as described above.
You can also enter the control parameters directly into a file. The format for this file is:
#simulations,U|M|L,seed
constant=distribution(min,max,...)
Where #simulations is a number specifying how many simulations to perform. If this number is
not included, 200 simulations will be performed. Follow this number by a comma and a U to perform
a univariate sensitivity test, M to perform a multivariate sensitivity test and a L to perform a Latin
Hypercube sensitivity test. The random noise seed follows this.
For example:
250,M,1234
PRICE OF STEEL=RANDOM TRIANGULAR(.5,1.5,.5,1,1.5)
BUILDING TIME=RANDOM UNIFORM(11,15)
This would make 250 simulation randomly changing both PRICE OF STEEL and BUILDING
TIME.

Noise in Active Variables


The sensitivity simulation capabilities uses variation in model constants to change output. In some
cases it is desirable to have different noise streams in active model variables. To do this use the
RANDOM… functions available in Vensim and do sensitivity search on the Constant NOISE SEED.
This will give different noise streams on each simulation. You should use either a VECTOR
distribution on NOISE SEED or RANDOM UNIFORM(0,250000). (You can actually use any range

243
you wish here but increasing the range will not improve the randomness character because of floating
point to integer conversion issues.)
If you are using RANDOM… functions with separate noise streams , you can choose to change only
some of those noise streams by changing the seed argument to them. For example is you have:
my price = RANDOM UNIFORM(20,30,MYSEED) ~~|
their price = RANDOM UNIFORM(20,30,0) ~~|
then doing a search over MYSEED will show the results of different values for my price with a
consistent (though still random) set of values for their price.

Combinatorial Sensitivity
In some cases rather than using randomly selected values you may want to methodically search out all
possible parameter combinations in an N dimensional grid. For example you might want to see what
happens when x takes on the values 1, 2, 3, 4 and 5 and y takes on the values 3,5 and 7. There are 15
combinations of values that can be checked.
If you specify a Multivariate search with only Vector distributions Vensim will perform this
methodical search. It will ignore the number of simulation specified and instead do enough
simulations to look at every combination of parameters that is possible fro m the different Vectors
specified. Clearly, for even a modest number of parameters this can entail a large number of
simulations indeed.

This combinatorial simulation works only when every distribution is Vector. If even one distribution
is randomized then the vectors are simply sampled sequentially.

Payoff Definitions†
A payoff is a single number that summarizes a simulation. You need to define a payoff before you can
run an optimization or do Kalman filtering. You can also define a payoff for normal simulations. At
the end of the simulation the value of the payoff will be reported and added to the error history
window.
The payoff for a model can be defined in terms of a comparison of model variables with actual data, or
as a combination of model variables. These two types of payoffs are known as calibration payoffs and
policy payoffs. The payoff is defined inside of a Vensim Payoff Definition (.vpd) file. This file is
referenced as second step the Optimization wizard takes or is named in the Payoff Definition field on
the Advanced tab in the Simulation Control dialog (see Chapter 8).
If you are using the Optimization wizard the Payoff Definition dialog will appear in the second step.
From the Simulation Control dialog click on the Ed... button next to the Payoff Definition field.

244
Filename is the name of the Payoff Definition file. If no filename has previously been specified
Vensim will use the model name or, when using the Simulation Control dialog query you for a name.
You can type in a different name if you like. If you do this and that file already exists you will be
asked if you want to overwrite it. You do not need to include an extension, Vensim will automatically
add one.
Choose New File... allows you to choose a different Payoff Definition file to work with. When you
click on this a File Selection dialog will open. Select the file you want to work with and its contents
will replace those in the dialog.
Clear Settings will remove all the parameters and reset the Type to Calibration.

Type: Calibration, if checked, will attempt to match model variables to data for those variables. A
calibration payoff requires that a data file be specified. If Policy is checked, the payoff will be
computed based solely on model variables so a data file is not necessary to compute the payoff, though
one may be necessary to simulate the model.
Payoff Elements lists the different components of the payoff. For calibration payoffs, this is a list of
the model variables that should match data. The list takes the form:
model variable|data variable/weight
Variable is the name of a model variable (model variable) that you want to compare to
available data.
Compare to is the name of a variable (data variable ) in a data file, or a computed Data variable
in the model (defined using a := equation).
Weight is the amount of weight you want to give to the error between the variable and what you are
comparing it to. See the discussion of payoff computation below for a more complete description of
what weight does.
If you follow the recommended convention of using the same name for data and model variables you
can use the simpler form:
model variable/weight

245
For Policy payoffs this is a list of variables contributing to the payoff. The list takes the form:
model variable/weight
which is identical to the simple payoff form for policy optimization except that weight has a different
interpretation. This is discussed in more detail in "Payoff Computation" below.
NOTE The weight must be separated from the variable name (and any data name) by a slash /.
Comments in braces {} placed anywhere on a line are ignored. If the specified weight is not
numerical, it must be a model variable (usually a Constant, but Auxiliary, Level, Data, and Initial are
also valid types here). If no weight is specified, an error will occur.
Delete Selected deletes the selected Payoff Element.
Modify Selected brings the selected Payoff Element into the editing boxes below.
Add Editing adds the contents of the editing boxes into the list.

Variable is the model variable to include in the payoff. You can type in a variable name here or click
on the Sel button to select a model variable.
NOTE If you are using a model with subscripts, the full set of subscripts (with Subscript Constants
not Ranges) must be specified here.
Compare to is the name of the data series with which to compare to the model variable. If you use the
same name for the data series and model variable (recommended) you should leave this blank. For a
Policy payoff definition this is always blank.
Weight is the weight to be given to this part of the payoff. This can be a number or a constant in the
model. It should be positive for calibration payoffs, and can be negative or positive for Policy payoffs.
See Payoff Computation below for more details.

File Format
Payoff definitions are simple text files and you can also modify them in any text editor. The first line
of the payoff file specifies the payoff type. Use *Policy for policy and *Calibration for calibration
(only the first letter is significant). This is followed by the payoff elements, one per line, exactly as
they appear in the dialog. If you begin a line with :COMMENT that line will be treated as a comment.

Payoff Computation
The way in which the payoff is computed depends on the type of payoff. For calibration payoffs, it
also depends on whether or not Kalman Filtering is active. Note that, except in the case of Kalman
Filtering, if you have only one variable in your payoff definition, the actual value of the weight simply
scales the payoff and will not change optimization results. In the case of Kalman filtering this is not
true since the weight is one indication of the quality of the data relative to the model. For each type of
computation the payoff is initialized at the beginning of the simulation and changed each TIME STEP.

Policy Payoffs
At each TIME STEP the values of all the variables are multiplied by the weights they have been given,
then they are multiplied by TIME STEP and added to the payoff. (This is true independent of the
integration technique you have chosen. The payoff is effectively always integrated using Euler
integration.) The optimizer is designed to maximize the payoff, so variables for which more is better
should be given positive weights and things for which less is better should be given negative weights.
The weights should be set so that all elements are scaled to be of the same order of magnitude. Having
done this you can adjust weights up and down to emphasize different aspects of the payoff.
The payoff value realized is just the weighted combination of the different payoff elements integrated
over the simulation. If you are interested in looking at the terminal values of a variable then in the
model use the equation

246
payoff elm = IF THEN ELSE(Time > FINAL TIME-TIME STEP/2,model var,0)
to get the value at the end of the simulation. Note that if you are combin ing terminal values with other
values, you will need to adjust the weights to compensate for the fact that values are integrated over
the course of the simulation.

Calibration Payoffs without Kalman Filtering


At each TIME STEP the data for variables to be compared is checked to see if a value is available. If
it is available, the difference between the data and the model variable is multiplied by the weight
specified and this product is then squared. This number, which is always positive, is then subtracted
from the payoff so that the payoff is always negative. Maximizing the payoff means getting it to be as
close to zero as possible.
The weight on a variable should be set to be proportional to the reciprocal of the standard deviation of
the prediction error for that variable. If this is done, the expected value of the payoff will be equal to
(the negative of) the number of data points. In this manner the 95% confidence interval can be
determined by finding a change of 4 in the payoff.
The data with wh ich the model variable is being compared can come from any .vdf file, whether from
Import Datasets or from a previous simulation. In addition, the data can be computed within the model
using a := equation. If you do this, you will need to use the payoff element format with two distinct
names.

Calibration Payoffs with Kalman Filtering


At each TIME STEP the Kalman Equations are used to update the covariance matrix for the prediction
errors. This inner product of the errors on the available data weighted by this matrix is computed and
this value, which is positive, is subtracted from the payoff so that the payoff is always negative.
Appendix B has a list of references on this process.
With Kalman filtering active, the weights for variables are the variances of the measurement error
associated with the given data stream. This is completely different from the meaning of the weight
when Kalman filtering is not active, so you will need to use two different payoff control files if you
want to compute a payoff both with and without Kalman filtering. You must provide a positive weight
for each data series that is measured. If you believe the measurement is perfect, supply a small number
(for example .01). The mathematics for using the Kalman filter with zero measurement error are not
implemented in Vensim.
NOTE The weight has the opposite qualitative interpretation (to normal Payoff files) when Kalman
filtering is active. A large weight results in less importance given to the data.
The payoff that is reported for Kalman Filtering is a log-likelihood.

Payoff Definition Examples

Example: Calibration Payoff


*Calibration
population / pop weight
births | births_raw / 0.22
Using this payoff, the difference between the population generated by the model and the population
found in the data files will be used. The sum of squared errors will be computed, and weighted by
pop weight, where pop weight is a Constant in the model. births in the model will be
compared to births raw in the data, and added into the payoff using a weight of 0.22. In each
case, the weight is squared, since it is used to compute the raw residual, which is then squared.

Example: Policy Payoff


The payoff can also be calculated on system performance. In this case, payoff.vpd would take the form

247
*POLICY
population / -0.3
income /0.2
This would take the value of population weighted by -0.3 (more population is a bad thing) and income
would be weighted by 0.2 (more income is a good thing). The payoff is the integration of these
weighted values (that is, no square is taken in this case). If *POLICY is missing from the first line, it
is assumed that a data comparison is being made, which will cause an error if policy optimization is
being done.
Note that the numbers used for weights in payoff functions are not dimensionless, but convert what
they act on to a dimensionless number. Thus, scaling is a real issue in the computation of the payoff.

Optimization†
You can use optimization to look for model errors, adjust model parameters based on data, test
parametric sensitivity, and choose the best policy levers. Optimization can be used with or without the
filtering capability (itself a form of optimization), which is described later in this chapter. To optimize
is, quite simply, to achieve the best. Optimization requires that you define a payoff function that
summarizes how good a simulation with a single number (as described above).
Your definition of the payoff function will determine whether optimization is used to calibrate a model
to data or choose a best policy. In addition to defining the payoff function you will need to choose the
Constants in the model that you wish to optimize over. Once you have chosen these Constants, the
optimizer will try to find the values for those parameters that make the payoff as big as possible. If
you have a calibration payoff, that means making the model fit the data as closely as possible. If you
have a policy payoff, that means maximizing the weighted sum of performance measures.
At the end of an optimization, the results are written to a file called runname.out (where runname is the
name you have specified for the simulation). Depending on what options you have chosen, other files
might also be created. The file runname.out contains the values of the Constants you specified that
optimize the payoff you specified.
NOTE Optimization can be interrupted by clicking on the Stop Button or pressing the Esc key and
will shut down cleanly for later resumption.

Specifying Optimization Control


You can set up the Optimization Control file from the Toolbar or from the Simulation Control dialog.

To start from the toolbar click on the optimization button to open the Optimization wizard.
Complete the payoff definition as described above and then click on the Next button to set up the
Optimization Control file. From the Simulation Control dialog click on the Ed... button to the right
of the Optimization Control field. The Optimization Control dialog will appear a somewhat
different depending on where you start it form, but the contents will be the same. It is shown started
from the wizard here.

248
Filename is the name of the Optimization Control file. If no filename has previously been specified
Vensim will use the model name or, when using the Simulation Control dialog query you for a name.
You can type in a different name if you like. If you do this and that file already exists you will be
asked if you want to overwrite it. You do not need to include an extension, Vensim will automatically
add one.
Choose New File... allows you to choose a different Payoff Definition file to work with. When you
click on this a File Selection dialog will open. Select the file you want to work with and its contents
will replace those in the dialog.
Clear Settings will remove all the parameters and reset the control parameters to their defaults.

Optimization Settings: The uses and meanings of the control parameters are discussed below. They
are all set in this dialog by either typing in a value of selecting an alternative from the dropdown list.

Currently Active Parameters lists the parameters to be searched over. The general parameter search
definition takes the form
minval <= model constant = initial val <= maxval | toltype=tolerance
where minval is a number or model Constant that the search parameter can never be smalle r than,
model constant is the name of the parameter being searched over , initial val is a number
specifying the starting value for the search, maxval is a number or model Constant that the search
parameter can never be bigger than, toltype is FRAC or ABS (see FRACTIONAL_TOLERANCE
and ABSOLUTE_TOLERANCE below) and tolerance is a number. All of these except for the
name of the parameter to be searched over are optional.
Delete Selected deletes the selected parameter.
Modify Selected brings the selected parameter into the editing boxes below.
Add Editing adds the contents of the editing boxes into the list.

The different fields in the currently active parameter are repeated in the editing fields below. Use the
Select button to bring a model Constant into the editing window to specify it as a search parameter.

249
When you have a model constant in the editing box the base model value for that constant will be
displayed below the editing box. This is helpful in defining a meaningful search range.
NOTE If you are using a model with subscripts, you can use subscript ranges when specifying the
constants to be searched over. The resulting .out file will, however, list each of the subscript elements
separately.
If you are directly editing the optimization control file, the search specifications have the same form as
displayed in the Currently Active Parameter list.

Examples
NORM_QUALITY
specifies NORM QUALITY as a search parameter. It will use the value in the model equation (or in a
.cin file) as its initial value, and allow searches over all values of the parameter.
FRAC ERR DISC[DESIGN]=.05
specifies FRAC ERR DISC[DESIGN] as a search parameter and uses .05 as the initial search
condition.
0 <= FRAC ERR DISC[ASSEMBLY] = .1 <= .5

specifies FRAC ERR DISC[ASSEMBLY] as a search parameter, uses .1 as the initial search
condition, and prevents Vensim from using values less than 0 or more than .5.
PERSONNEL = 10500 <= 100000 | ABS
would terminate based on the default absolute tolerance (as discussed in "Optimization Options"
below).
PERSONNEL = 10500 <= 100000 |ABS = 3
0 <= FLOOR SPACE FRAC = 10
which assigns an absolute tolerance of 3 to PERSONNEL and a fractional tolerance of 10 to FLOOR
SPACE.

Starting the Optimization


To start an optimization from the Simulation Control dialog click on the Optimize button. From the
Optimization wizard click on the next button. This will allow you to change other settings associated
with optimization.

250
Data Sources is a list of data files to be used for data variables and calibration payoff computation.
These are required for calibration optimizations unless you have defined Data variables in the model
using GET ... DATA and specified these for comparison in the payoff definition.
Payoff Report, if checked, saves the components of the optimization criteria that have been specified
to the file runname.rep. This report includes the relative and absolute contributions to the log
likelihood payoff function for each of its components. It also generates a file called 1step.err (and
2step.err ... if the Step option has been set and Kalman Filtering is active) that gives the actual residual
of model versus actual data over the course of the simulation. 1step.err can be loaded into Vensim
with Dat2VDF (from the main menu Datasets>Import Datasets>Dat2VDF ) to review these residuals.
The payoff report file also includes a list of all Data, Constants and Lookups that come from outside
sources along with the source file. In the case of ODBC sources the control (.vdi) file is listed.
†Kalman Filtering, if checked, causes Vensim to adjust the model states during the simulation, based
on the available data, using an extended nonlinear Kalman filter. See further discussion of this below.

Step† allows you to specify the number of steps ahead to report forecast errors during simulations
using Kalman filtering. This only has an impact when both Report and Filtering are on. The files
1step.err, 2step.err and so on will be created. 2step.err, contains the results of running the model
without Kalman corrections to the second available set of data points. If this is left blank, the value 1
will be used.
Click on Finish to begin optimization.

Optimization Options
If you do not want to use the defaults you can set options in the Optimization Control dialog or directly
in the Optimization Control file. In the file these options must precede the search specification
parameters and take the form :KEYWORD=value.

As always, capitalization and spacing are ignored by Vensim. Options must precede the parameter
declarations, but otherwise order is not meaningful. All options can be shortened to four characters.

251
In addition, you can include comments inside of braces {}. If repeated or conflicting options are
specified, only the last are used.
Comments can be placed in optimization control files using the :COMMENT keyword or {} This lets
you put in remarks wh ich are ignored by the system. The remark will be repeated in runname.out.
If you use the Optimization Control Dialog all of the keywords will be entered automatically. The
keywords have (approximately) the same names as the fields in this dialog. They are reported in the
order they appear in the dialog.
NOTE comments are not supported by the Optimization Control dialog and will be lost if you edit a
file containing comments with this dialog.

Optimizer

:OPTIMIZER = POWELL {POWELL | OFF}


The default option is POWELL, which denotes a modified Powell search. When set to OFF, no
optimization is done. This is useful when the MULTIPLE_START option is activated. For example,
:MULTIPLE_START=GRID and :OPTIMIZER=OFF performs a grid search of increasing definition
starting from the specified values. This can be used to test the global validity of an optimum or the
sensitivity of the model to the search parameters outside normal operating ranges.

Sensitivity

:SENSITIVITY=OFF { OFF | PAYOFF_VALUE{=4.0} |


PAYOFF_PERCENT{=10.0} |
PARAMETER_PERCENT{=10.0} |
ALL_CONSTANTS{=10.0}}
This option allows you to find out how sensitive the payoff is to changes in parameter values. The
default setting is off, which does not invoke the sensitivity calculations. Otherwise, there are four
modes of use: PAYOFF_VALUE, PAYOFF_PERCENT, PARAMETER_PERCENT, and
ALL_CONSTANTS.

The sensitivity analysis done here is not part of the sensitivity analysis discussed earlier in this chapter
though they are closely related conceptually. The terminology, unfortunately, overlaps somewhat and
where clarity is required we will refer to optimizer sensitivity analysis.
PAYOFF_VALUE and PAYOFF_PERCENT make sense only at an optimum. When invoked, they run
through the parameter list, and determine how much each individual parameter would have to be
changed to decrease the payoff by the desired value or percent. Positive and negative value changes
are calculated separately, since they are not normally symmetric.
PAYOFF_VALUE is useful when the payoff is a true log likelihood or properly weighted sum of
squares. In this case, different changes in the absolute value of the payoff can be used to derive
confidence bounds on parameters. For example, for a sum of properly weight squares using the default
PAYOFF_VALUE of 4 (the default) results in 95% confidence intervals being reported for each
parameter. If you are using Kalman Filtering, which computes the actual log like lihood, you should
use a PAYOFF_VALUE of 2. (The properly weight sum of squares is 2 times the log likelihood. It
can be shown the log likelihood tends to a Chi Squared distribution with one degree of freedom and
this can be used to determine confidence bounds for a single parameter.)
PAYOFF_PERCENT is useful when the payoff cannot be interpreted as a log likelihood, as, for
example, in the case of policy. The resulting intervals serve to identify which policy levers need to be
keenly controlled, and which can be largely ignored.
PARAMETER_PERCENT looks at a percentage change in parameters and reports the percentage
change in payoff. This is faster to execute than PAYOFF_PERCENT and gives similar information if
the payoff surface is well behaved. Also, it can be executed even if the system is not at an optimum,

252
and still give meaningful results. The numbers reported show the change in the magnitude of the
payoff as a result of increasing and decreasing each search parameter by the specified percent. If the
model has been optimized, both of these numbers will be negative.
ALL_CONSTANTS is similar to PARAMETER_PERCENT but considers all model Constants, not just
search parameters. This is a comprehensive diagnostic tool that has little to do with optimization as
such. Again, it shows the change in the payoff as a result of the given percentage increases and
decreases in all Constants. Since most Constants are not search parameters, there is no reason to
expect these changes to be negative. At completion, a file named sortsens.tab is created, which lists
the information in sensitivity.tab in order of importance.

The optimizer sensitivity analysis can be invoked in conjunction with an optimization or


MULTIPLE_START, in which case the sensitivity will be determined relative to the point with
maximum payoff. If the OPTIMIZER and MULTIPLE_START control parameters are turned off, the
sensitivity will be performed relative to the input evaluation point.
Optimizer sensitivity analysis will not be performed if you have clicked on Cancel and no optimization
has been completed. If an optimization has been completed and a break requested, then the sensitivity
analysis will be performed about the maximum. If the sensitivity analysis is wanted after a break, but
not performed because of a break, set the options OPTIMIZER=OFF and MULTIPLE_START=OFF
in runname.out, copy it to a new file and use it as the optimization control file. The sensitivity will be
done about the best point the optimizer has reached.
The output from the sensitivity analysis will be placed in a file called sensitivity.tab. For
SENSITIVITY set to PAYOFF_VALUE or PAYOFF_PERCENT, the file will look like:
:COM The base payoff is 123.22
:SENSITIVITY = PAYOFF_PERCENT = 10
:COMMENT * Means a boundary was reached.
.21 <= FRAC_REQ_REW = .332 <= 1.0 *
26.5 <= NORM_QUALITY = 27 <= 27.21
10* <= WORK_SPEED_BASE = 16 <= 29
The first line reports the payoff value at the starting point. The second line just reiterates the
sensitivity settings. The third line is a comment reporting that * means that a boundary has been hit.
(That is, the difference in payoff can be less than specified at this point but the constraints in the
optimization control file forbid moving this parameter any further). The remaining values give the
parameter names with their starting values, surrounded by their values at the sensitivity limits.
This file is in a form to be used with the optimizer and the vector graphing option. During the
calculations of the sensitivity bounds, no intermediate calculations will be posted to the screen nor will
any output go to trace, startpoint, or endpoint files. The fractional tolerance for sensitivity calculations
is set at 1.0e-7 to ensure high accuracy of these results.
For SENSITIVITY set to PARAMETER_PERCENT and ALL_CONSTANTS, sensitivity.tab will look
like:
:COM The base payoff is 3.000000
:SENSITIVITY = PARAMETER_PERCENT = 10.000000
:COM Parameters are changed by +- 10% if 0 by += 0.1
PARAMETER -0.1 0.1
FRAC_REQ_REW = .332 -0.607316 -1.889160
NORM_QUALITY = 27 -0.0375092 -0.060395
WORK_SPEED_BASE = 16 -1.238576 -1.569352
Again, the first two lines are the payoff at the starting point and the type of sensitivity analysis
performed. The next two comments tell the definition of elasticity as reported and what happens in
special cases. The sensitivity results are given in table form, where the parameter name and its base

253
value are given on the left and the changes in payoff that result from changes in the parameter are
given on the right.
If SENSITIVITY is set to ALL_CONSTANTS, then another file named sortsens.tab is created. This
file is basically the same as sensitivity.tab, but the constants are sorted by decreasing impact so that it
is easier to weed out unimportant constants. If the optimization is interrupted with a Cancel command,
the sorted file will not be created, but sensitivity.tab will.

Multiple Start

:MULTIPLE_START=OFF {OFF | RANDOM | GRID | VECTOR}


This option restarts optimization multiple times from different starting points or, if
:OPTIMIZER=OFF, simulates the model for different values of the search parameters.

If MULTIPLE_START is set to RANDOM the optimizer will never stop unless you click on the Cancel
button to interrupt it. GRID will stop, but probably not after a reasonable time since the potential
number of simulations with GRID is 1024 to the power of the total number of search parameters.
When the optimizer receives the Cancel command, it shuts down cleanly, writing out the best values
found to the file runname.out. The files startpoint.tab, startpoint.dat, endpoint.tab, endpoint.dat, and
vector.dat (if VECTOR is specified) might also be created. These files and the conditions under which
they are created are discussed in the section "Optimization Output."
If MULTIPLE_START is OFF, then a single optimization is performed.

If MULTIPLE_START is RANDOM, starting points for new optimizations are picked randomly and
uniformly over the range of each parameter. A different random series for selecting these starting
points can be generated by changing the value of :SEED. The first point used for optimization is
always the initial setting of the search parameters.
If MULTIPLE_START is GRID, starting points are computed over successively finer grids over the
range of each parameter. This first grid computes the endpoints of the ranges, the next grid also
computes the midpoints, and each successive grid divides the previous grid by 2. This continues for up
to 1024 divisions (which could take years!) unless it is interrupted.
If MULTIPLE_START is VECTOR, starting points are computed over uniformly partitioned values of
each parameter. Unlike GRID, VECTOR changes only one parameter at a time. VECTOR searches the
first parameter from its minimum to maximum values, then the second, and so on. The partition is the
maximum - minimum value over the setting of VECTOR_POINTS.

The ranges for parameters are specified as constraints on the parameters being optimized. If
constraints are missing, the maximum and minimum available floating point numbers (roughly 1E34)
are used as for GRID and VECTOR. These are not typically good choices unless you are just testing
extreme conditions. A grid search on an unconstrained pattern would start at -1E34, then do 1E34,
then do about 0.0, then do -1E16 and so on. The number of points it hits that are sensible is likely to
be small in this circumstance.
For RANDOM, the following rules are used to compute search starting points:
? Upper and lower constraints present:
min <= parameter <= max
A number, X, will be chosen in the range [0,1) (including 0 but
not including 1.0) . The starting value for the parameter will
be:
parameter = min + X(max - min)

? Only the lower constraint present:


min <= parameter

254
A number, X, will be chosen in the range [0,1) (including 0 but
not including 1.0). The starting value for the parameter will
be:
parameter = min + 1/(1 - X)

? Only the upper constraint present:


parameter <= max
A number, X, will be chosen in the range [0,1) (including 0 but
not including 1.0). The starting value for the parameter will
be:
parameter = max - 1/(1 - X)

? Neither constraint present:


parameter
A number, X, will be chosen in the range (-1,1) exclusive. The
starting value for the parameter will be:
parameter = 1/(1 - X) - 1/(1 + X)
Two files, startpoint.dat and startpoint.tab, will be created containing the starting values for the
parameters and the payoffs at these starting values. If the OPTIMIZER=POWELL option is set, two
additional files endpoint.dat and endpoint.tab will be created, showing the parameter values and
payoffs that result from these starting conditions. These files contain the same information in different
formats. The .dat files can be loaded into the environment using Dat2vdf for further review.
If MULTIPLE_START=VECTOR is used and OPTIMIZER=OFF, an additional file named vector.dat
will be created listing the payoff as a function of each parameter value. Again, this can be loaded into
the environment using Dat2vdf, although the graphs look odd if more than one search parameter is
specified because of the incommensurate time axes. This vector.dat information is very useful for
viewing separate cuts of the likelihood surface.

Random Number Generation Method

:RANDOM_NUMBER=LINEAR (LINEAR|SUBTRACTIVE)
This option applies only if :MULTIPLE_START=RANDOM is used. There are two random number
generators which can be used with MULTIPLE_START: LINEAR and SUBTRACTIVE. The
default generator is LINEAR.

NOTE Both of these techniques are based on routines given in Numerical Recipes in C, by Press,
Flannery, Teukolsky, and Vetterling. If you are not certain that MULTIPLE_START is sampling the
entire space, then switch to the other random number generator and try again.

If RANDOM_GENERATOR is LINEAR, three linear-congruent generators are used. The first one
generates the most significant portion, the second generates the least significant portion, and the third
randomly picks one from a list of previously generated numbers.
If RANDOM_GENERATOR is SUBTRACTIVE, the subtractive method of Knuth is used.

Random Number Seed

:SEED =1
This option is only applicable if MULTIPLE_START=RANDOM. This is a positive integer needed to
initialize the random number generator for the optimizer. The default value is 1. Any other value will
produce a different random sequence. (Simulation and optimization use the same algorithm for
generating random numbers, but represent separate invocations. For each simulation, the random
number generator is reset and regenerates the same values.)

255
Number Restart (#Restart)
:RESTART_MAX=0

This option is applicable when MULTIPLE_START is set to RANDOM or GRID It determines the
maximum number of times the optimizer will restart. By default RANDOM and GRID will continue
until they are interrupted. Specify a positive number to have them restart only that number of times.

Output Level

:OUTPUT_LEVEL=1 {0 | 1 | 2 | 3 | 4 | 5 | 6}
This determines the amount of information the optimizer displays as it is running. This information
will go to the screen and to the error file for the simulation. It takes a value between 1 and 6. Higher
numbers give more information, with each higher level including all the information from the lower
levels. The specific information follows:
0 Suppresses output. This is useful if MULTIPLE_START is turned on.
1 The starting point and final point of the optimization are given along with their payoffs.

2 Displays any point with its payoff which is an improvement over the best payoff calculated so far.
The percent improvement is also displayed.
3 Displays the best point and payoff of every optimization, particularly useful with MWYS.
4 Displays best point and payoff of each iteration through the entire set of search vectors.
5 Displays the best point and payoff after each individual vector optimization.
6 Displays every point and payoff.
An asterisk (*) is printed in front of the parameters which have changed for the most recent simulation.

Trace

:TRACE=NO {NO{0} |YES{2} |3|4|5|6}


NO is a synonym for 0 and YES is a synonym for 2. This is valid only if MULTIPLE_START=OFF.
This allows you to trace the optimization results. If trace is set to anything other than NO, then two
files, trace.tab and trace.dat, will be created. The file trace.tab is a tab-limited file that lists parameter
values and payoffs at different iterations. The file trace.dat lists the same information in a format that
can be loaded into Vensim using Dat2vdf. The time axis for this file is simp ly an index that increases
by one on each simulation. As optimization progresses, both of these files are filled in. Termination of
the optimization session leaves them intact.
The value to which trace is set (2-6) determines how much information is included in the created files.
See the :OUTPUT option for a description of these different output levels.

If any point had a payoff which caused an overflow or some other numerical error, then the special
value NA is entered in trace.dat. These points will be ignored when loaded into Vensim.

Maximum Iterations

:MAX_ITERATIONS=1000
This is the maximum number of times the optimizer will search through the list of parameters to avoid
entering an infinite loop. This is a control parameter for POWELL optimization.

256
Pass Limit

:PASS_LIMIT=2
This is the number of times the optimizer will run through an entire Powell search. At the beginning of
each search the vector set is reinitialized to ensure that none of the directions have collapsed to zero. A
value of 2 is usually good enough to deal with this and is therefore the default value. This is a control
parameter for POWELL optimization.

Fractional Tolerance

:FRACTIONAL_TOLERANCE= 0.0003
This represents the fractional tolerance for a parameter value and is used to determine when to
terminate an optimization. The search is refined until the value for each parameter is within the
fractional tolerance times the search range (maximum value minus minimum value)of the parameter. If
no search range is selected the fractional tolerance multiplies the larger of 1.0 and the absolute value of
the parameter when the search starts. This option sets the fractional tolerance for all parameters. You
can set individual parameters separately to override this option, using the FRAC=# notation discussed
in "Specifying Search Parameters" earlier in this chapter.
If you specify a fractional or absolute tolerance for an individual parameter this overrides the global
fractional tolerance setting. At the beginning of the optimization absolute tolerances are computed for
all search parameters and these are used to determine both the initial step size (granularity) of the
search and the termination conditions. . All tolerances are adjusted by the tolerance multiplier for the
initial phase of the optimization. When searching in a direction that involved multiple parameters, the
tolerance is determined as the geometric mean of the tolerances in the different directions.
Optimizations work best when the tolerances for the parameters being searched over are balanced.
Essentially this means that changing any parameter by its tolerance will have approximately the same
impact on the payoff. If this is not the case you may get early convergence, or Vensim may perform an
excessive number of simulations to converge which takes longer. If you are conducting searches over a
large number of parameters it is worth it to take the time to try do this balancing.

Tolerance Multiplier

:TOLERANCE_MULTIPLIER = 21.0
The termination criteria for the search are adjusted for the early and coarse searches over the parameter
space, so that these searches will terminate quickly and a more refined search can start from a good
starting value. The tolerance multiplier allows you to adjust the balance between accuracy and
completion time in early searches. On each iteration, the tolerances are multiplied by 1 + ((n -
iter)/ n) * tolerance_multiplier, where n is the total number of search parameters and
iter is the number of iterations through the search directions. When iter gets bigger than n, or if no
improvement is found on an iteration, the tolerance multiplier is no longer used. This is a control
parameter for POWELL optimization.

Absolute Tolerance

:ABSOLUTE_TOLERANCE =1.0
This sets the default value for an absolute tolerance. The absolute tolerance is used in determining
when to terminate a search, but it is not applied to a parameter unless the ABS modifier is given for the
parameter (as discussed in the previous section) and no value is specified. All absolute tolerances are
multiplied by the :SCALE_ABSOLUTE and adjusted by the tolerance multiplier during optimization.

257
Scale Absolute

:SCALE_ABSOLUTE =1.0
Because of differing units of measurement, different parameters are likely to require different absolute
tolerances. Once these different absolute tolerances have been set, they can be scaled up or down
using the :SCALE_ABSOLUTE value. For example, if PARM_1 has an absolute tolerance of .3 and
PARM_2 has an absolute tolerance of .4, then setting :SCALE_ABSOLUTE=2 is the same as giving
PARM_1 an absolute tolerance of .6 and PARM_2 an absolute tolerance of .8.

SCALE ABSOLUTE does not apply to fractional tolerances. Generally, if you are specifying
tolerances for individual parameters you will get the best performance by specifying absolute
tolerances and scaling them all for early exploration (or if using multiple start).

Vector Points

:VECTOR_POINTS=25
This option only applies if the MULTIPLE_START=VECTOR option is set. This sets the number of
points to search along the vector.

Examples of Optimization Control Files

Example 1
NORM_QUALITY
In this example Vensim will try to find the value of norm quality that maximizes the payoff function.
The first and last points of the search will be reported, and a value for NORM_QUALITY will appear in
runname.out.

Example 2
:SENSITIVITY=PAYOFF_VALUE
4 <= WORK_SPEED_BASE <= 10
5 <= NORM_QUALITY <= 1
In this example, Vensim will search for the best values of WORK_SPEED_BASE between 4 and 10,
and NORM_QUALITY between .5 and 1. Once these values have been found, 95% confidence bounds
will be computed for these two values and reported in sensitivity.tab.

Example 3
:MULTIPLE_START=GRID
:OPTIMIZE=OFF
4 <= WORK_SPEED_BASE <= 10
5 <= NORM_QUALITY <= 1
In this example, a grid search will be performed over the two parameters WORK_SPEED_BASE and
NORM_QUALITY. The payoffs at all points will be reported in the files startpoint.dat and
startpoint.tab. No optimizations will be performed from these startpoints. If any payoff found is an
improvement over the normal values for WORK_SPEED_BASE and NORM_QUALITY, it will be
recorded and the best values reported in runname.out

Optimization Output
As optimization progresses, some information will go to the screen and to the error file. How much
information will depend on the value you have set for :OUTPUT_LEVEL.

After every optimization, a file named runname.out is created, where runname is the name of the
simulation run you are making. (If runname.out exists, then it is copied to runname.2out before a new

258
runname.out is created.) This file contains the best payoff so far, the reason the optimizer stopped, and
the values of the search parameters needed to achieve that payoff. This file also contains the controls,
parameters, and comments you specified in the input optimization control file. The system is set up so
that you can simply copy this file over to replace the input file and continue along. A separate file is
created so that you can review it and discard it if you think it does not contain useful information.
In addition to runname.out, a file named runname.log is created which contains the history of message
reported during optimization. Normally this file has the same content that appears in the message
window during optimization. If, however, the number of messages if very large they go to the file but
do not appear in the message window.
If optimization terminated normally or you answered yes in response to the question of whether or not
you wanted a simulation, a .vdf file is also created at the current optimum. This file can be loaded into
the Workbench and reviewed.

Additional Files
The following gives a brief description of all files that might be created by the optimizer and when
they are created.
? runname.out contains the parameters that give the maximum payoff. This file is always created
when the optimizer is invoked, and either OPTIMIZE or MULTIPLE_START is active.
? sensitivity.tab contains information about the sensitivity of the payoff to different parameters.
This file is created if the :SENSITIVITY option is used.
? startpoint.tab contains the initial optimization points and the corresponding payoffs in tab-
delimited format. This file is created if the MULTIPLE_START option is specified.
? startpoint.dat contains the initial optimization points and the corresponding payoffs in a format
suitable for Dat2vdf. This file is created if the MULTIPLE_START option is specified.
? trace.dat contains values of the parameters and payoff over the course of an optimization in a
format suitable for Dat2vdf. This file is created if the :TRACE option is used.
? trace.tab contains values of the parameters and payoff over the course of an optimization in tab-
delimited format. This file is created if the :TRACE option is used.
? sortsens.tab contains information about the sensitivity of the payoff to different parameters sorted
by importance. This file is created if the :SENSITIVITY=ALL_CONSTANTS option is used.
? endpoint.dat contains the final optimization points and the corresponding payoffs in a format
suitable for Dat2vdf. This file is created if the MULTIPLE_START option is specified and
OPTIMIZER=POWELL.
? endpoint.tab contains the final optimization points and the corresponding payoffs in tab-delimited
format. This file is created if the MULTIPLE_START option is specified and
OPTIMIZER=POWELL.
? vector.dat contains a list of parameters versus payoffs in a form suitable for use by Dat2vdf.
This file is created if MULTIPLE_START=VECTOR and OPTIMIZE=OFF.

Using Output Files


The optimizer can create a number of .dat files. You can load these files using Dat2vdf. To graph the
results, however, you will need to load a different model, since Vensim can not graph constants.
If you specify the variables you want plotted in a Custom Graph Definition file and load this using the
Graph Control in the Control Panel, then you can plot the different parameters and payoffs. You can
also do various xy plots that might be useful.

259
Another alternative is to select Model>Import Dataset… and import the output files, then load the
resulting .vdf file as a model. To do this specify the full name, including the .vdf (for example,
startpoint.vdf) in the load command.
The .tab files that are created can be viewed as text files, and also can be loaded into most spreadsheet
programs for further manipulation. For the most part, these files are set up so that they make sense
when interpreted as a spreadsheet.

Interrupting and Resuming Optimizations


You can stop an optimization by clicking on the Stop Button at any time. When this happens, the
optimizer will try to shut down cleanly, creating a runname.out file with the best parameter values
found. It will also ask you if you want to make a simulation using these values.
You can start optimizing again from the old values by renaming runname.out as another file (such as
runname.voc) and using that file as the optimization control file. You can also edit the renamed file
and make any adjustments or additions you might want. Files with runname.out cannot be used as the
input file. This is to prevent conflicts that might occur if Vensim were to try to read and write different
information to the same file.

Kalman Filtering†
In a dynamic system with unobserved variables it is desirable, but impossible to know, the state of all
variables at all times. However, if values for some of the variables areknown, you can make a good
estimate of the values of other variables. Kalman filtering combines data measurements and model
output to make indirect measurements of the model variables.
Kalman Filtering is turned on by checking the box in the Advanced tab of the Simulation Control. To
use filtering, both a payoff file and a filter control file (kalman.prm) are required. The payoff file
needs to be set up with the measurement noise variances entered, as discussed earlier in this chapter.

Driving Noise and Initial State Covariance


The filter control file (which must be named kalman.prm) specifies the covariance matrix for the
driving noise and the initial covariance of the state vector. The current implementation of the filter
assumes that the driving noise directly impacts the levels. The specification of the noise uses the
following format:
Lev_1/.34/1000
Lev_2/LEV_2_VAR/LEV_2_IVAR
Lev_1 | Lev_2/ LEV_1_2_COVAR
In the first line, the noise influencing Lev_1 has a variance of 0.34, and the initial variance of Lev_1
is 1000. In the second line, the noise influencing Lev_2 has a variance given by the model variable
LEV_2_VAR, and the initial variance of Lev_1 is given by LEV_2_IVAR. In the third line,
Lev_1 and Lev_2 have a covariance given by the model variable LEV_1_2_COVAR and no initial
covariance is specified, so it will be assumed to be 0. Model variables are typically constants and are
valid search parameters.

The initial value of the state covariance is a measure of how uncertain the initial states computed by
the model are. If you leave this blank Vensim will use 1E6 on the diagonal, and 0 off. Generally it is
better to enter this explicitly, since with a high variance, the first thing the filter will do is move the
model dramatically toward the data. If you have some confidence the initial states are within 20% or
30%, you should use this (for example take (.3*initial value)2).

Example
To best illustrate what the Kalman filter does and how it can be used, an example is useful. This
example is based on the workforce inventory model wfkal.mdl in the directory \models\sample\kalman.

260
net hire noise workforce meas noise

workforce
meas workforce
net hire
time adjust workforce
inventory meas noise
des workforce productivity noise meas inventory
norm productivity
des production
inventory
productivity
production

exp sales des inventory

inv correction
TIME AVG SALES
inventory coverage

time correct inventory

sales

The two measurements on the system are meas workforce and meas inventory. Both of
these are direct measurements containing errors (meas noise) from for the corresponding model
levels. Sales is an exogenous driver, with values specified in the data file sales.dat.

Graph for sales


200

80
0 10 20 30 40 50 60 70 80 90 100
Time
sales - SALES

Noise that drives model behavior enters the system through net hire noise and
productivity noise.

The goal is to determine the time profiles of workforce, inventory and the other model
variables given the available measurements. One approach to this problem would be to assume that
workforce and inventory are equal to their measured values. Another would be to simulate the model
with productivity noise and net hire noise both set to 0. The first of these approaches
uses only the data, the second only the model. Kalman filtering provides a mechanism to intelligently
combine the data and model in making indirect measurements of the model variables.

Creating the "Data"


To illustrate the purpose and value of Kalman filtering we will use the model to generate "data." This
technique allows us to easily review the unobservable variables (the time profiles of workforce,
inventory and other variables) and see how they simulate relative to what actually happens. To
create this data:

Import the data file sales.dat and enter this dataset (sales.vdf) into the Data Sources field in the
Advanced tab of the Simulation Control.

261
Select the Changes tab of the Simulation Control, click the Load Changes from… button and open
the file wfkal_n.cin containing:
productivity_noise = .20
workforce meas noise = .025
inventory meas_noise = 0.1
net hire noise = 4
Enter the run name data and simulate the model. We will use this run (data.vdf) as though it were data
collected from the real world.

Setting up the Filter


The Kalman filter requires the specification of the driving noise variance and the measurement error
variance. The function RANDOM UNIFORM(-.5,.5,0) returns a random variable with a mean of 0
and a variance of .08333. We multiply this times the random input magnitude assumed in making the
constant changes squared. Specifically:
meas inventory variance = 55 { .0833 * (.1*300)2 }
meas workforce variance = .5 { .0833 *( 0.025*100)2 }
inventory drive variance = 33 {0833*(.2*1*100)2 }
workforce drive variance = 1.3 {.0833*(4)2 }
Note that both the net hire error and the productivity error integrate directly into the levels and that
TIME STEP is 1 in this model.

The above values are set in the model to help define the Kalman filter. The first two values are used in
the payoff file (wfkal.vpd) as:
*Calibration
MEAS_WORKFORCE/MEAS_WORKFORCE_VARIANCE
MEAS_INVENTORY/MEAS_INVENTORY_VARIANCE
The second two values are used to define the driving noise covariance in the Kalman filter file
kalman.prm as:
inventory/inventory drive_variance/.1
workforce/workforce drive variance/.1
Here we have set the initial state covariance to a small number for each state variable. The Kalman
filter file (kalman.prm) must be created in the Text Editor (or you can use the existing file for this
example).

Simulating
We will make two simulations. The first called simple.vdf will simulate the model with no filtering.
The second called filter.vdf will simulate the model with Kalman filtering active.
Remove the changes file wfkal_n.cin from the Load Changes from… field in the Changes Tab (or
you will be simulating what you have already simulated).
Enter the run name simple and click the Simulate button to simulate the model.

For the Kalman filtering run, enter the run name filter. Enter the real world data (data.vdf) into the
Data Sources… field (along with sales.vdf). Enter the payoff file wfkal.vpd in the Payoff
Definition… field. Turn on Kalman filtering by checking the Kalman Filtering box. When you
click on this the file kalman.prm will automatically be used. You do not need to name this file in the
Simulation Control dialog. The Simulation Control should appear as below:

262
Click the Simulate button to simulate the model with Kalman filtering.

You can now compare the two alternative ways of measuring inventory and workforce (simple
simulation and simulation with Kalman filtering). The custom graph named COMPARE will do this.

Actual Inventory versus potential measurement


494.27

415.97

337.68

259.38

181.09
0 10 20 30 40 50 60 70 80 90 100
Time (month)

Actual Inventory (data.vdf) widget


Measured Inventory (data.vdf) widget
Simple Simulation (simple.vdf) widget
Kalman Filtering (filter.vdf) widget

Though each method is in the ball park, simple simulation is not tracking very well. Blowing up the
last 20 mo nths shows:

263
Actual Inventory versus potential measurement
434.52

388.19

341.86

295.52

249.19
80 82 84 86 88 90 92 94 96 98 100
Time (month)
Actual Inventory (data.vdf) widget
Measured Inventory (data.vdf) widget
Simple Simulation (simple.vdf) widget
Kalman Filtering (filter.vdf) widget

The use of filtering provides better estimates of the amount of inventory by combining the information
in the model (that predicts what a value will be) with the information in the measurements (data
collected from the system). This is true for measured variables, and it is also true for unmeasured
variables. For example, suppose that we had measurements for Workforce but not for Inventory.
It is still possible to make estimates of the value of Inventory using this data. If you create the file
wfkal2.vpd containing:
*Calibration
MEAS_WORKFORCE/MEAS_WORKFORCE_VARIANCE
And simulate the model naming the run filter2. You will get the estimate of inventory (using the
Graph Compare2) as:

Actual Inventory versus estimate based on workforce measurement


455.73

330.99

206.25
0 10 20 30 40 50 60 70 80 90 100
Time (month)
Actual Inventory (data.vdf) widget
Simple simulation (simple.vdf) widget
Filter Estimate (filter2.vdf) widget

This is somewhat less accurate than what was obtained with measurements on Inventory. But it is
remarkable that having measurements only on Workforce allows a reasonably good estimate of the
values of Inventory in a noisy system.

The addition of the Kalman filter provides an ability to recover reasonable estimates of the underlying
dynamics (the time profiles of workforce and inventory). This is potentially valuable for any model,
and is critical for a model that contains unobserved dynamics of a transient nature.

264
Combining Filtering and Optimization
The Kalman filter provides a valuable way to make indirect measurement of the behavior of model
variables. We can combine filtering with optimization to get indirect measurements of the structural
parameters in the model.
Suppose that we only have measurements on Workforce, and we want to estimate the underlying
parameters time correct inventory and time adjust workforce. To do this we set up
an optimization file (wfkal.voc)
:SENSITIVITY=payoff_value=2
1 <= time_correct_inventory=20 <= 50
1 <= time_adjust_workforce=20 <= 50
The :SENSITIVITY line tells Vensim to find a 95% confidence bound on the estimates. With this file
in place, and again using wfkal2.vpd with Kalman filtering turned on, start an optimization.
An error screen will appear and, after a time, report the results:
Initial point of search
TIME CORRECT INVENTORY = 20
TIME ADJUST WORKFORCE = 20
Simulations = 1
Pass = 0
Payoff = -129.708
---------------------------------
Maximum payoff found at:
TIME CORRECT INVENTORY = 3.88819
*TIME ADJUST WORKFORCE = 12.4016
Simulations = 159
Pass = 3
Payoff = -94.5603
---------------------------------
The :SENSITIVITY command puts output to a file called sensitiv.tab. This file contains:
:COM The base payoff is -99.3714
:COM A * Means a bound was reached, i.e. payoff not at criterion.
:SENSITIVITY = PAYOFF_VALUE = 2.000000
2.98486 <= TIME CORRECT INVENTORY = 3.82884 <=
5.04371
10.0239 <= TIME ADJUST WORKFORCE = 12.5768 <= 16.2581
TIME CORRECT INVENTORY was estimated to be 3.8 and, with 95% confidence lies between 3 and
5. TIME ADJUST WORKFORCE was estimated to be 12.6 and, with 95% confidence lies between 10
and 16. Since we are doing true maximum likelihood, the confidence bounds are not necessarily
symmetric.

Optimization Without Filtering


These results are reasonable, and need to be contrasted to the case in which no filtering is in use. To
do this use wfkal_w.vpd for the payoff and rerun the optimizer with filtering turned off. The weights
in the payoff file have a very different interpretation when using filtering. wfkal_w.prm gives a weight
of .12 to MEASURED WORKFORCE - this is 1/standard deviation and is appropriate for a payoff
without filtering. The results, much more quic kly this time are:
Maximum payoff found at:.
TIME CORRECT INVENTORY = 2.78701
*TIME ADJUST WORKFORCE = 18.5704

265
Since we are now using sum of squares we can get a 95% confidence bound by setting
PAYOFF_VALUE = 4. When we do this we get confidence bounds that put TIME CORRECT
INVENTORY between 2.7 and 2.9 and TIME ADJUST WORKFORCE between 18 and 19.
The actual parameters are, of course, well outside of these confidence bounds. The bottom line is that
care needs to be taken when doing simple simulation on systems for which there is extremely limited
measurement.

Optimizing Everything
For the above calculation we had a great deal of knowledge about the variance of the noise entering the
model. If you don't know the variances, it might be possible to estimate them. We can, for example
search over some or all of the noise terms in addition to the adjustments times. The file wfkal2.voc
does this for everything starting at a value of 20. Note that MEAS INVENTORY VARIANCE is not
included since the payoff definition does not use the measured inventory.
When we optimize, we get the results:
Maximum payoff found at:.
INVENTORY DRIVE VARIANCE = 12.1912 (33)
WORKFORCE DRIVE VARIANCE = 1.18771 (1.3)
MEAS WORKFORCE VARIANCE = 0.667975 (.5)
TIME CORRECT INVENTORY = 3.66288 (4)
*TIME ADJUST WORKFORCE = 13.0956 (12)
It takes over 500 simulations, but the numbers are reasonably good — the correct values are shown to
the right. The variance measures as not that accurate, but the measurements of the parameters are quite
reasonable. The actual values are also all well within the 95% confidence bounds.
Using filtering combined with optimization it is possible to accurately estimate structural parameters in
a model with limited knowledge of the stochastic characteristics of the model. This is the magic of
Schweppe Statistics. See Appendix B for more references.

Time Required for Simulations


One final note. Kalman filtering dramatically increases the time it takes to simulate a model . For
large models, the execution of the Kalman filter also requires a large amount of memory. Basically
memory requirements go up as the square of the number of Levels and computational requirements go
up as the cube of the number of Levels. If you have a large model and need to run Kalman filtering
you might want to see if you can create a smaller model that will do the filtering and use the resulting
state estimates to drive the larger model.

266
11 SyntheSim

SyntheSim synthesizes structure and behavior through simulation. It superimposes time graphs on top
of the model diagrams and instantly updates those graphs as you make changes.

Seeing Behavior
Part of understanding how models behave is, of course, seeing the behavior. With SyntheSim behavior
is displayed directly on the Sketch views of the model. This allows you to understand how behavior
patterns come together through their causal connections to cause the behavior of other variables.
When you start SyntheSim this behavior is automatically displayed, but you can also display the
behavior of existing runs without starting SyntheSim.
To display behavior select the menu item View>Behavior or just use the B key. Your sketch will
appear as:

The loaded runs will be displayed. You can change the runs from the Control Panel and the sketch
appearance will be updated.

Time Axis
If you are only displaying behavior the graphs will be displayed for whatever duration is set in the
Time Axis tab of the Control Panel (this is in contrast to full SyntheSim mode where the total duration
of the current simulation is always displayed). If you change the time axis, from the control panel or
from a Strip Graph tool or Graph tool output, the small graphs will update accordingly.

Enlarging SyntheSim Graphs


If you want to see a larger version of a SyntheSim graph just hover over the graph with the mouse for a
few seconds. That is, position the mouse over the graph and let it stay there without moving. When
you do this a ToolTip graph will appear:

267
ToolTip graphs are the same as the smaller graphs except that the axis values are labeled and the
variable name appears across the top. The graphs are kept identical so it is easy to relate them to what
you see on the sketch view.
If you want to get a larger graph of a variable just click on it and then click on the Graph tool. This
will display a regular graph. Though the scales will be different it will have the same content as the
graphs displayed on the diagram. Similarly, you can use the Table tool to see the actual numbers.

Subscripts and SyntheSim Graphs†


A subscripted variable appearing on a sketch represents more than one set of values. Vensim uses the
Subscript Control to determine which set of values to plot by choosing the first selected subscript
combination. For example, suppose that sales is subscripted by product and store with the
following subscript selections active:

Then a graph would be shown for sales[product3,store1].

You cannot tell from the sketch which subscripts are displayed, but if you bring up the ToolTip graph
this will be labeled.

268
Thus is you wanted to see store2, you would need to select it in the Subscript Control for store.
As you make changes in the Subscript Control the graphs will be redrawn, so it is relatively easy to
pass through the different subscripts in the model.

Starting SyntheSim

To start SyntheSim simply click on the SyntheSim button in the Toolbar. The starting simulation
will be the same as the simulation that would have been made by clicking on the Run button.
If you want to make changes to constants and lookups, referenced data or the integration technique to
be used in SyntheSim you can first click on the Setup a Simulation button , make the desired
changes and the click on the SyntheSim button.
In Vensim Standard, Professional and DSS you can also start SyntheSim by clicking on the SyntheSim
button in the Simulation Control dialog. You can use this to have SyntheSim start from a resumed
dataset or make other advanced adjustments.
NOTE The first time you start SyntheSim you may be asked if you want to overwrite an existing run.
If you stop SyntheSim and start it again with the same run name this question will not be repeated.
Each time you make changes in SyntheSim mode the existing run is overwritten.
When you start SyntheSim, a slider will appear below each constant or, if the
constant uses a shape, above the constant name. The Lookups will also be highlighted appearing with
a blue background.

Stopping SyntheSim

To stop SyntheSim simply click on the Stop button . SyntheSim will also be stopped if you open
another model or close Vensim.
When SyntheSim is stopped the last simulation made will be run again and saved as a normal
simulation. You can use any of the analysis tools on this run.

SyntheSim Toolbar
The SyntheSim toolbar appears when you start SyntheSim:

In PLE and PLE Plus to toolbar appears as:

The SyntheSim toolbar allows you to control the behavior of SyntheSim.

269
Changes Controls (Not PLE or PLE Plus)

Save Constant/Lookup Settings to a file allows you to write the current settings for all constants
as a .cin file. This file can be used in regular simulation or loaded using the Read button described
below.

Read Constant/Lookup Settings from a file allows you to use a .cin file to load changes. This
can be a file created with the Save button, or any valid changes file.

Change Model Constants opens the Constant changes dialog as discussed in Chapter 8. Each
time you make a change the model will be simulated and the results displayed.

Change Lookups opens the Lookup changes dialog. As you make changes the model will be
simulated to reflect those changes.

Run Control

Stop simulating stops SyntheSim mode. See notes on Stopping SyntheSim above.

Save this run to saves the current simulation to a different name and then loads it in at then end
of the loaded run list, leaving the current Runname active. This is a useful way to make an archive of
the run and its current settings. Its function is very similar to the Save Constant button, but it stores
all results.

The Runname editing box and the associated Select button work the same way the do for initially
choosing the simulation name. See the notes in Keeping Results from SyntheSim below for more
discussion.

Reset Buttons

Reset Current Slider to base model val resets the value associated with the current slider to be
equal to the constant value specified in the model. You can use the Home key on the keyboard as a
shortcut for this. The current slider is the one appearing highlighted as rather than
.

Reset all Constants/Lookups to base model vals resets the values of every Constant and Lookup
in the model to be the value originally specified.
NOTE The reset buttons do not use changes or resume files when they do resetting. Because of this,
if you started with a .cin file when you reset everything the behavior will not match where you started.
If you are using .cin file you should use the Read button instead of the reset all button.

If you are using the GET XLS CONSTANTS function and have made changes to the source
spreadsheet you should check your model before entering SyntheSim mode. Otherwise the Reset
buttons may set value to older numbers from the spreadsheet.

Control Buttons
The remaining buttons are the same as in the normal toolbar. In SyntheSim you can do the same things
that you can in regular analysis mode. This includes loading and unloading runs, selecting variables,
editing and displaying graphs and tables and setting scaling preferences.
You can also change the Time Axis to display, but this will only affect created graphs. The thumbnail
SyntheSim graphs displayed on the Sketch view are always for the full duration of the simulated run.

270
Keeping Results from SyntheSim
The simulations made in SyntheSim mode are continually saved to your computer. This means that
you can make full use of all the analysis tools to look at the runs you have made without having to
leave SyntheSim mode. It als o means that there is not a separate stored run for each experiment that
you do. There are three approaches to managing the runs that you make.

Saving Interesting Runs


Use a Runname such as experiment for the SyntheSim run. As you move sliders and adjust lookups
you will come to something interesting. At this point use the Save this run to button and store
the results with a meaningful name. Do not change the Runname – it continues to represent
experiments with the results stored from time to time.
This method has the advantage of letting you archive things whenever you find something interesting.
The runs can be kept for later analysis and comparison.

Branching Experiments
Start with a Runname such as result01. When you are happy with that change the name to result02
and continue to experiment. When you find something interesting change the name to result03 and so
on. Once you change the name the old run will be stored as it was, moving down in the list of loaded
runs.
This method has the advantage of being very simple and fast, though the Runnames that are saved are
not very meaningful.

Saving Cin Files (Not PLE or PLE Plus)


Similar to saving interesting runs it is possible to just save the changes associated with a run. This is
done using the Save Constant/Lookup… button . The changes file that is created can be used to
load changes for later simulations.
This method does not create additional runs, but only changes files. The changes files are nice because
they can be applied to the model even after changes are made to it.

Changing Constants
The most common thing you will do in SyntheSim mode will probably be to change model constants
by moving around sliders and observing behavior.
Moving Sliders
To move a slider simply position the mouse over the button slider’s , press the left mouse
button down and move the mouse to the left (to decrease the value) or the right (to increase the value).
As you move the mouse the value of the constant will change, the model will be simulated and the
results displayed. This process is repeated continuously in gradations that depend on the size of your
model and the speed of your computer. The value of the constant you are changing is displayed in the
button of the slider. When you let go of the slider a final simulation is made at the value of the
constant displayed and these results are stored so that you can use the analysis tools to review them.
It is possible to have more than one slider representing the same constant (as would be the case with
Shadow variables). If this happens these additional sliders will be updated when you let go of the
mouse button to match the slider you are working with.

271
Using the Keyboard
You can move sliders using the keyboard. This is useful if you want to make more discrete changes in
constant values or if you find the mouse difficult to use for this purpose.
At any time there will be one slider that is active. This slider can be identified by the colored rails
which will contrast with the clear rails on the other sliders. The
keyboard operates on the active slider.

You can change the active slider by clicking on it, or by using the Tab key or Shift+Tab key
combination. When you use the Tab key the order in which activation changes depends on the order in
which the sketch was built and may not be visually obvious.
The right arrow key ? will increase the value of the constant controlled by the active slider. The left
arrow key ? will decrease the value of that constant.

Setting Slider Bounds


When sliders are created they use the Range values specified in the equation for the constant to set the
slider bounds. If you did not fill in the Range values then Vensim will make up a range based on the
value of the constant.
To change the bounds on a slider, or directly set the value of the variable, use the left mouse button to
click on the slider’s rail (not the button). It does not matter if the slider is active when you do
this. This will open the Slider control options dialog:

You can use this dialog to set the value of the constant by typing it in, and also to control the
minimum, maximum and increment for the slider.
You can set a value that is not in the range if that is appropriate. If you change Min, Max or
Increment that change will hold until you move to another view or change the selected subscripts.
You can make the changes permanent by checking Make slider changes permanent. If you do this
the model will be changed and you will be asked if you want to save the model when you exit Vensim.
Opening the Slider control options dialog will also make the slider active.

Subscript Issues†
If a model constant is subscripted then a slider is created for the first selected value based on the
Subscript Control settings just as for display graphs. You can determine which subscripts are selected
by hovering over the Constant (not the slider) till the ToolTip comes up:

When you click on the slider rails the Slider control options dialog appears as:

272
You can make the slider apply to another element of the constant by selecting from the set subscript
list. If you change a slider in this manner it will be different from other sliders so caution is warranted.
Any changes to the selected subscripts will reset a change made here.
You can use the Ed… button to make changes to all subscript elements. This opens the same dialog as
is used to change constants from the Toolbar, but only for this variable instead of all Constants.
Note that the Min Max and Increment values are not subscript specific but apply for all subscripts. If
you change these permanently the change will hold for all subscript elements. If you change them
temporarily the change will be lost when the Subscript Control is used to change subscript selection.

Changing Constants from the Toolbar (Not PLE or PLE Plus)


In addition to changing constants through the sliders you can also change constants using the Change
Constants button on the toolbar. This will bring up the constant change dialog:

To change a value click on it, then click on the Modify button or press enter. An editing box appears
for you to type a value into:

273
Type in the new value and click on Update or press the enter key. The value will be updated and the
model will be simulated with the results displayed.
Click on the Close button when you have finished making changes.
Changing constants in the manner can be helpful when working with highly subscripted models.

Changing Lookups
When you enter SyntheSim mode all the Lookups will appear highlighted.

To change a Lookup just click on it. The Lookup Editor will open:

The use of the Lookup Editor is discussed in Chapter 6. The main difference here is that the OK and
Cancel buttons are replaced with Close and Reset buttons. This is because every change you make
will immediately be reflected in the current simulation.
You can move, add and remove points just as you can when building the lookup. As you move the
point, the model will continuously be simulated to reflect the changes you make.

If you clear all points, nothing will happen until you have added in two points. This is because at least
two points are required for a lookup and there is nothing meaningful that can be done with an empty
Lookup. You will not be able to close the dialog without at least two points.
The Reset button will reset the Lookup to have the value it has in the base model. It is the analog of
the Reset Current Slider button for Lookups.
Changing from the Toolbar (Not PLE or PLE Plus)

274
You can also change Lookups from the Toolbar by click on the Change Lookups button . This
will bring up a list of lookups:

Click on one and click on Modify to change it. The Lookup editor will open and operate just as
described above.
Subscripted Lookups

If you click on a subscripted lookup instead of opening the Lookup editor you will bet a list of the
lookup elements to choose from. Select one of these and click on Modify to change it. Then click on
the Close button when you are finished.

Changing Behavior

In order to understand a model thoroughly it is helpful to subject it to various test inputs and also to
selectively break feedback links and see how behavior changes. SyntheSim makes it very easy to do
this without putting in switches and additional model structure.
By Right-Clicking (or Ctrl Clicking) on any variable that is not a Lookup (Auxiliary with Lookup is
OK) you will open the Input Options dialog:

You can use this dialog to change the behavior of that one variable to something different from what it
otherwise would be.

If Override normal behavior is checked, this variable will behave differently from what it otherwise
would. The behavior is exogenous or constant as specified by the selected type (this is described
below). When the behavior of one or more variables has been overridden the Toolbar changes to:

275
Clicking on Stop Override in the toolbar will set the model back to having no overridden behavior on
variables. Note that the Reset All button is not available since things that are not normally
Constants may now be Constant and things that normally are Constants may no longer be Constants.
Variables with overridden behavior are distinguished by color. Normally appearing green with a
purple background:

Input Modes

There are several input modes available. For each of them there are control parameters that can be set.

Constant (with slider)

sets the variable to behave likes a constant which you will be able to control with a slider. You can set
the minimum and maximum range for the slider. Once you have done this a slider will appear and you
can change the range on the slider just as you would any other. This option is not available for
constants, since these are sliders normally.

Step Change sets the


variable to start at the From value and then change to the to value when Time reaches the value
specified for at time.

Ramp sets ramp


behavior starting at the from value, holding constant till the starting at time value then ramping up or
down to the to value at the time specified by finishing at after which it will again be constant.
Exponential Growth

sets exponential
growth from the initial value Starting from, remaining constant until changing after time and then
growing exponentially at growth rate (%/unit time) for the rest of the simulation. Note that the
number 2 means 2%/year (or .02/year) if the model has time in years (independent of the value of
TIME STEP).

276
Exponential Decay

sets an exponential
decay (decreasing at an ever decreasing rate toward 0). The variable will start at Starting from and
remain constant till changing after time then it will decay at decay rate for the rest of the
simulation. Note that the decay is in percent per unit time so that if the model is in months 5 means
5%/month (independent of the value of TIME STEP).

Sine Wave creates


a sine wave that goes from the value Between to the value and (note that the second value can be
larger or smaller than the first) and has the period specified by with period. The wave will start in the
middle of the two values, and maintain that value till mean value till time then go up to the second
value, turn and go down to the first and so on.

Pulse creates a pulse


of input that stays at Base Value until the time specified in at time when it takes on the values
specified in pulsing to and holds that value for the time specified in for duration. After that it returns
to Base value. If duration is 0 the pulse will last a single TIME STEP.

Pulse Train creates


a train of pulses starting at Base value and then going up to pulsing to at the time specified in
repeating every for the time specified in for duration. The value then returns to Base value till time
is twice repeating every then the pulse repeats.

Square Wave
creates a square wave that goes from the value Between to the value and (note that the second value
can be larger or smaller than the first) and has the period specified by with period. If the mean value
till time is after the model’s initial time the variable will take on the mean of the two values. After
mean value till time the wave will move to the first value, then go to the second value after ½ of the
period has passed. After another ½ the period passes it will return to the first value and continue in this
manner for the rest of the simulation.

Freezing Levels
In addition to changing the shape of inputs it is possible to freeze levels at their initial value. To do
this check the Freeze Levels at initial values checkbox.
This option is most useful for studying the local response of a set of equations to their inputs.
Typically, one of the inputs would be specified as a ramp over a useful range and the sensitivities to
different constant tested.
Consider the equation
effect price demand = (price/average price)^(-elasticity)
If we make changes to elasticity and run the whole model price and average price will both
move and it will be difficult to see the effect of price on for different prices. However by overriding

277
the behavior of price to be a ramp, and freezing the levels we have isolated the structure so that we can
study its local behavior. Normally you will be able to use Strip Graphs to study these relationships.

Model Errors
In order to enter SyntheSim mode you must have a model that passes error checking. If it does not
pass you will need to fix the errors.
When SyntheSim starts it makes a simulation just as if you had click on the Run button. If that
simulation causes a floating point error Vensim will not enter SyntheSim mode. You will need to
correct the condition that causes the floating point error. There is a discussion of how to do this in
Chapter 7 of the User's Guide.

Once you enter SyntheSim mode and start making changes it is quite possible that some of the
parameter combinations you choose will result in a floating point error. There are two indications that
this has happened. First the graphs are likely to be blank, or to stop abruptly halfway across.

278
Second, the status bar will display an error message like the one above.

When you encounter a floating point error you can trace its causes in the manner discussed in Chapter
7 of the User's Guide. When a floating point error exists in the final simulation made the variable
causing the error will automatically be selected into the Workbench. Note that if you have an output
control using a workbench tool on the page this selection will be lost.

Completely blank graphs usually indicate that the floating point error occurred at the beginning of the
simulation and you will need the Table tool to trace its causes. Partial graphs, such as those shown
above, indicate that the error was caused part way through a simulation and you can use graphs to trace
causes.

In many cases, the source of floating point errors will be obvious from the slider or Lookup you
changed that causes the error to occur.

Input Output Controls with SyntheSim

You can set put input sliders and output graphs and tables into any sketch view for use with
SyntheSim. As you move the sliders, or type in a diffe rent number, the model will be simulated. If the
number you type in is out of the range specified for the slider the closest number in the range will be
used. For example is the range is from 100 to 200 and you type in 1 then 100 will be used. If you add
2 to give 12 100 will still be used. If you add 3 to give 123 then 123 will be used.
When you move a slider Graphs, Strip Graphs and simple Bar Graphs placed as input output controls
will update, though they will not rescale. When you let go of the slider all output objects (including
tables) will be updated and rescaled. If you are typing in numbers, or using the keyboard to move the
automatic sliders, all output objects will be updated on each change. Note that sliders created as Input
Output objects do not support movement with the arrow keys since these are used to edit the value for
the constant.

Bigger Models
SyntheSim works well with surprisingly large models, but some models simply take too long to
simulate to be used effectively in SyntheSim mode.
How long a model takes to simulate is a function of the model size, the length of the simulation, the
value of TIME STEP and SAVEPER and the speed of your computer. In general if a model can be

279
simulated in less than ½ of a second it should work reasonably well in SyntheSim mode. As a rule of
thumb take the number of variables in a model as reported in Model>Settings, multiply by the number
of time steps and divide by the clock speed of your computer in megahertz. If this number is less than
300 then SyntheSim will probably work quite well.
If your model is to large too smoothly respond to slider movements, you can change settings so that it
will only be simulated when the mouse button is lifted, and not while the slider is being moved. To do
this check the Suppress SyntheSim during slider moves checkbox on the Sketch Appearance tab of
the Model Setting dialog (Model>Settings).
If your model takes more than a few seconds to simulate you may find that it is better just to perform
normal simulations and not enter SyntheSim mode. Even in this case you can get some of the benefits
of SyntheSim by displaying the behavior of the runs you make on the Sketch views as described in the
first section of this Chapter.

280
12 Control Panel and Subscript Control

In working with models, Vensim keeps track of a variety of settings to help in the
analysis and understanding of models. The Control Panel and Subscript Control
allow you to manage the majority of these settings. Each of these windows can be
brought forward by clicking on the buttons on the Main Toolbar, or by selecting
from the Windows menu. The Subscript Control is only available in Vensim
Professional and DSS. This chapter:
? Introduces the Control Panel
? Explains each tab on the Control Panel
? Describes how Vensim uses Control Panel settings
? Introduces Subscript Control
? Explains the simple and advanced Subscript Control mechanisms
? Describes how Vensim uses Subscript Control Settings

Control Panel

The Control Panel allows you to control the output the Analysis Tools will create.
To open the Control Panel, click on the button on the Main Toolbar or select the
Menu item Windows>Control Panel. If you have already opened the Control Panel
and it is behind other windows, you can click on the Control Panel button (above) or
hold down Ctrl+Shift and press the Tab key one or two times.

The Control Panel has a number of different tabs to manage different aspects of
Vensim. Click on a tab to get to its contents. Regardless of which tab you select,
there are two functions that remain.
Keep on top, if checked, will cause the Control Panel to stay on top of all other
windows. When you use the Analysis Tools to create output this output will appear

281
behind the Control Panel. Similarly, if you click on a sketch, you will still see the
Control Panel even the though the sketch is active.
Close closes the Control Panel. You will not lose any settings you have made, and
when you reopen the Control Panel it will be in the same location and the same
size. You can choose whether you want to close the Control Panel or simply let it
be pushed out of sight behind other windows. In either case clicking on the Control
Panel button or the Window>Control Panel command will make it visible.
The Control Panel is sizable. You can drag any edge or corner to resize the window.
This is true on all platforms. Note that the appearance of the edges of the Control
Panel will be different on Windows 95, Windows 3.1 and the Macintosh.

Variable

Most of the Analysis Tools in Vensim operate on the Workbench Variable. The
Variable tab of the Control Panel is used to select the Workbench Variable. The
Workbench Variable can also be selected by double clicking on the variable name
in any Output or Build window.
The list at the top contains all variables that match your selection criterion. By
default this is a list of all regular variables in a model, but you can also search for
partial name matches, and by type of variable. To select a variable into the
workbench:
? Click on any name in the list, or
? Type part or all of the name of a variable in the Name or Pattern field until the
variable appears in the list, then press the Enter key.
? Type in a complete name and then click on the Exact button to select the name
you have typed. This is useful if there are many names that start the same.
Name or Pattern lets you enter the beginning of names, or wildcard strings using *
to match any number of letters and ? to match one letter. For example *labor*
finds all variables that include the string labor; *labor finds all variable names
ending in labor; and labor* finds all variable names beginning with labor. When
you type a name with a wildcard and press Enter or click on select, only names that
match the pattern you entered are displayed, and all types of variables are searched.
NOTE As you begin to type into the Name or Pattern field, the first name in the
list that matches what you are typing is automatically selected. Clicking Select or
pressing Enter will cause the highlighted name to be selected in to the workbench.

282
Once you enter a * or ? in the name you are typing the currently selected item in the
list will no longer change.

Subscripts † allows you to specify the complete set of subscripts for the Variable
you are choosing and is active only for subscripted variables. Normally, if you
select a subscripted variable name such as Cum Cost without specifying any
subscripts, the title bar will change to:

The Subscript Control, described later in this chapter, can then be used to control
tool output. If, however, you are interested in looking only at TASK2, click on the
down arrow to the right of Subscripts

and click on [TASK2]. The variable Cum Cost[TASK2] will go into the
workbench and this variable will be used by the Analysis Tools independent of the
settings in the Subscript Control.
If you simply type in the name of a Subscript Element and that Element is valid for
the Workbench Variable, then the Workbench Variable will be changed to use that
element. For example, typing or selecting TASK3 when the Workbench Variable is
Cost[task] would change the Workbench Variable to Cost[TASK3].
Typing in the name of a Subscript Range does not have this effect (see the
discussion below).
Type allows you to select variables by type. When you click the down arrow at the
right, you see a list of the possible variable types. When you select a variable type,
only variables of the selected type appear in the list.
In addition to the normal variable types, Type allows you to select the Subscript
Ranges and Groups. Selecting by Type is the only way to fill the list with all
Subscript Ranges or Groups. When you use wildcard searches, Subscript Ranges
and Groups will not be displayed.
? If you select a Group (either by choosing Type group and selecting a group from
the list or by directly typing in the name of a group) the list is filled with all
variables belonging to that Group. The Workbench variable will not be changed.
? If you select a Subscript Range (from the list or by typing it) the list will display
all variables that use the selected Subscript Range. The Workbench variable will
not be changed.
Exact attempts to select exactly what you have typed in the Name or Pattern field.
This can be helpful if, for example, you just want to be sure that the model does not
have a variable called work. As you type work, work accomplished might
be selected in the list even though this is not what you want. Since the list can be

283
filtered, or displaying a specific variable type, the Exact button is the best way of
determining whether or not a variable exists.
Select sends all information in the Name or Pattern field to the Workbench.
Double-clicking a name in the list is equivalent to highlighting a name and clicking
Select. Pressing the Enter key has the same effect as clicking the Select button. If
you have typed part of a name and a match has been found in the list, clicking on
Select or pressing Enter will place that match into the Workbench.
When you select a variable into the Workbench the titlebar will change. If you
attempt to select something into the Workbench that is not a variable name nothing
will happen.
NOTE Selecting a variable into the Workbench replaces the previous Workbench
Variable. Thus, you can only select one variable into the Workbench at a time.
Time Axis

The Dataset Analysis Tools (see Chapter 14) in Vensim display data over time. The
Time Axis tab of the Control Panel lets you control the range and labeling of the
time axis as it used by these tools.
Time Base displays the currently selected Time Base. Clicking on the down arrow
to the right of Time gives you a selection of other valid time bases in the model.
The time base is used to label the Horizontal Axis of graphs and the first row of
tables. Variables defined using the TIME BASE function are available for selection
here. By default, Time is the only Time Base.

Changing the Time Range


Graphs and tables use the time range to determine how much of a simulation run to
display. Changing the time range allows you to focus on specific events or periods
for detailed analysis. There are three components to the time range: Start time, End
time, and Special time. The Graph, Strip Graph, and Gantt Chart tools use Start
time and End time. The Table, Bar Graph, and Document tools report values at
Special time.
To decrease the value of Start, Special, or End time, click the decrease arrow
indicator <-. To increase a value, click the increase arrow indicator ->. The current
value (corresponding to Start, Special or End time) is displayed below these
indicators and will be changed accordingly. You can also directly type in a value
for any of these times. As you type the graphic time bounds display will be updated.

284
If you type in an invalid value it will be ignored (thus if time ranges from 1900 to
2100 and you type 200 nothing will happen, but when you type the final 0 the
controls will adjust).
These bounds can also be changed with the mouse. To change Start time click the
mouse over the left edge of the time bar and drag it. The bar will move with the
mouse. To change the End time,click the right edge of the bar and drag. As you
change the Start or End time, the number displayed below the corresponding
indicators will change. If you drag Start time above End time, or vice versa, Vensim
will switch to changing the other one.
You can also change Special time by dragging the small box underneath the
highlighted rectangle above the time values. As you drag, Special time changes.
In addition to using the Time Axis Control window, you can modify Start time and
End time from the graphical output windows (from the Graph, Strip Graph and
Gantt Chart tools) by Shift-clicking inside of the graphs. See "Selecting a Time
Range" in Chapter 13 for more details.
Reset to Full Range resets the time range to the full range over all runs (the union
of all time ranges), and sets Special time to End time.
Display Time Base Name , if checked, causes the name of the Time Base to be
displayed at the bottom of graphs and as the label for the first row of tables.
Display Time Base Units, if checked, causes the units of Measure for the Time
Base to be displayed at the bottom of graphs and as the label for the first row of
tables. If Display Time Base Name is also checked the units will follow the name
of the Time Base in Parenthesis as in Time (Month).

Scaling

Graphs in Vensim are, in general, automatically scaled and those scales are then
divided up into a number of divisions. The Scaling tab of the Control Panel gives
you some control over how that happens. You can also use this to control the
appearance of the thumbnail graphs in SyntheSim mode.

Horizontal Divisions
Determines the number of divisions that a graph will have with vertical lines being
used to separate these divisions (there will alwaysbe one less line than there are

285
divisions). You can type a number or click on the down arrow to the right and select
from the displayed choices. Note that changing the number of divisions does not
change graphs youhave already created, but will only affect new graphs.
Horizontal divisions applies to the Strip, Sensitivity and Bar graphs. For the Graph
tool the default is to ignore this and set the number of horizontal divisions based on
the values along the time axis. You can change this for the Graph tool (See Chapter
14), or by setting the number of horizontal divisions to -1 in the Custom Graphs.
? Add line at 0, if checked adds a horizontal line to graphs at the y- value of 1.0.
This only happens on graphs that have scales running from a negative to a
positive number.
? Add line at 1, if checked, adds a horizontal line to graphs at the y- value of 1.0.
Vertical Divisions
Determines the number of divisions to be made in the vertical axis of graphs using
horizontal lines. This will change all graphical output except for Custom Graphs
that have explicitly had the number of Vertical Divisions set. Again changing the
number of divisions does not change graphs you have already created, but will only
affect new graphs.
? Add line at special time , if checked, adds a vertical line at the location of special
time.
Vertical Scaling (Ra w or Rounded) determines the appearance of the vertical scales
on plots from the Strip and Graph tools.
? Raw. If scaling is set to Raw, the top value on the scale is the maximum value of
the variable(s), the bottom the minimum.
? Rounded. If scaling is set to Rounded, the numbers are rounded for easier
reading.
SyntheSim Settings
? Include 0, if checked, causes the thumbnail graphs always to include 0 regardless
of the range of the variable.
? Colorize , if checked, causes the thumbnail graphs to flash red to indicate
increasing scale size and blue to indicate decreasing scale size.
? No change on drag, if checked, causes the thumbnail graphs to retain their scale
while sliders are dragged. When you release the mouse button the graphs will
rescale.
? Freeze , if checked, causes the thumbnail graphs to always retain their initial
scale. To rescale them you need to change to another view and change back or
load and unload a dataset from the Control Panel.
? Buffer Mult specifies how much extra room to build in when the scales are
expanding to accommodate future growth. The setting of two seems to work
well. Setting this to a smaller number will case graphs to be rescaled more
frequently, a larger number less frequently.

286
Datasets

The Dataset Analysis Tools in Vensim use the loaded datasets to create graphs and
tables. The Datasets tab of the Control Panel lets you manage which datasets are
loaded.
Available displays a list of datasets that are available for use but are not current ly in
use. This list is made up of all the dataset (.vdf) files that are in the same directory
as the model with which you are working. To load an available dataset, double click
on it, or click on it and then click on the >> button.
Available - Info... gets information about an available dataset, including the model
from which the run was made, the options used for the run, and any comment you
might have entered (in the Standard tab of the Simulation Control dialog). Click on
a run name then click on the Available - Info button.

Loaded displays a list of loaded datasets. To change the order of datasets, click the
dataset in the loaded list (on the left) that you want to appear first. It moves to first
place and becomes the only highlighted dataset.
Loaded - Info allows you to get information about a loaded run. Click on the run
name and click on the Loaded - Info button.
The order of datasets in the loaded list determines their order in graphs and tables.
For example, if you have configured the Document tool to report the values of
variables, it reports them from the first dataset in the list. The Table tool uses the
first dataset to choose an appropriate time axis. The Run Comparison tool (which
requires that the datasets are simulation output) uses the first two loaded datasets.
To reorder datasets click on the one you want to appear first. Then Control-click on
the one you want to appear second, then third and so on. Control-clicking a
highlighted dataset removes the highlight and moves that dataset below any
highlighted dataset.

287
Double clicking on a dataset in the Loaded list or clicking on a dataset and then
clicking on the << button will remove it from the Loaded list and place it in the
Available list. (If the loaded dataset was from a different directory it will just be
removed from the Loaded list and will not appear in the available list.)
>> (Load) loads the available dataset that is highlighted. The name will be moved
to the Loaded list. Loading a dataset does not remove it from disk. If nothing is
highlighted in the Available list the Load button does nothing.
Note that double-clicking on a name in the Filename list has the same effect as
clicking on the name and then clicking on the >> button.
<< (Unload) unloads all highlighted runs from the Loaded list. The Unload button
does not remove any files from disk. If you unload a dataset it will no longer be
shown in graphs.
Note that double-clicking on a name in the Loaded list has the same effect as
clicking on the name and then clicking the >> button.
Delete deletes the highlighted dataset in the Available list from disk. You will be
asked to confirm that you want to delete the dataset. The delete button is helpful in
cleaning up files.
Load From... allows you to load a dataset from a different directory. If you do
this, the name of the dataset as it appears in the Loaded list and Analysis Tool
output will include its full path. The Load From... button retains a memory of the
last directory yo u loaded from to make it easier to load multiple datasets from
another directory.
Graphs

or in Vensim PLE

288
Vensim has an ability to product custom graphs, tables and reports and these are
discussed in more detail in Chapter 15. The Graphs tab of the control Panel allows
you to modify and display this customized output.

Graphset Control (Not PLE or PLE Plus)


Rec Coord (Record Coordinates) records the screen positions of all open custom
graphs. This information will be stored with the custom graphs so that the next time
you display a custom graph it will be displayed at this position. This is especially
useful for work in progress graphs which will display automatically during a
simulation.
Redo Open causes all open custom graphs to be redone. If you have made a new
simulation or changed the loaded datasets the changes will appear in the graphs.
The graphs will be displayed in the their current positions at their current sizes.
Graphs that have been modified will not be displayed. This is useful if you are
redoing simulations and want to look at the same information.
To the right of the Rec Coord and Redo Open buttons is the list of currently
defined graphs. You can display a graph by double clicking on it in this list, or
clicking on it and then clicking on Display. You can also select more than one
graph in the list by dragging over the items on this list or holding down the Shift key
and using the arrow or PgUp PgDn keys to move through the list.

Graph Editing
Modify... modifies the highlighted graph. The Custom Graph Editor (described in
Chapter 15) will open on that graph. If the highlighted item is a report or table, you
will be informed that you cannot edit it using the Custom Graph Editor. If the
highlighted graph contains elements that are not modifiable from the Custom Graph
Editor, you will be informed that you will lose this information if you continue.
Copy makes a copy of the highlighted graph and opens the Custom Graph Editor for
modification of the copy. The copied graph is automatically given a new name
which you can change.
New creates a new and empty custom graph and opens the Custom Graph Editor on
the new graph. The new graph is automatically given a new name which you can
change. See Chapter 15 for more details.
Display activates the highlighted graph. Selecting a graph name and clicking
Display shows the named graph. Double-clicking on a graph name has the same
effect. If more than one graph in the list is highlighted, all the highlighted graphs
will be displayed.
Delete deletes the highlighted graph. You will be prompted to see if you really want
to delete the graph.

Custom Graphset (Not PLE or PLE Plus)


By default Vensim works with a set of graphs attached to the model. When you add
and change graphs, the changes are kept with the model. Under some

289
circumstances, however, it is desirable to have more flexibility on graph definitions
and separate these definitions from the model. Vensim allows you to do this using
the Custom Graphset options.
The name of the Graphset you are working with is shown in the combo box below
Custom Graphset. *Default is used to indicate the default Graphset that is attached
to the model with which you are working. Clicking on the down arrow to the right
will bring up a list of currently loaded Graphsets. Click on the Graphset in the list
you want to use. You can add to this list using the Open… button and remove items
from this list using the Close button.
Open… will open a list of available Graphsets. Select a Graphset and it will be
loaded and activated for use with the current model.
NewGS will start a new and empty Graphset.
Save As… will bring up the File Selection dialog and allow you to select a name to
save the Graphset. By default Graphsets will be saved in a plain text .vgd file. You
can also save Graphsets in a binary .vgf format. This format is intended primarily
for publication of Venapps but can also be used with regular Vensim.
Save will save the current Graphset. Any changes you have made with the Custom
Graph editor will be stored. Save is grayed for the default Graphset because this
will be saved with the model.
Into Model takes the Graphset you are working with and makes it the default model
Graphset. This will effectively erase the existing model Graphset. You will be
asked if you want to continue if you select Into Model. This button is grayed for
the default model Graphset since this Graphset is already in the model.
Close deactivates and unloads the current Graphset. The default model Graphset
will replace this Graphset for the current model. If the Graphset being closed is
active in any other models, these will also have their own default Graphsets
activated.
NOTE If you use a custom Graphset and want to prepare a model for use with the
Vensim Model Reader be sure to use the Into Model function before saving the
model as a binary format model.

Placeholders (Not PLE or PLE Plus)

290
The Placeholders tab of the Control Panel allows you to set placeholder values that
can be used in simulating models that are only partially complete. In simulating
such models, variables that do not yet have equations, but are used in equations, will
need placeholder values.
This tab displays a list of variables that do not yet have equations. Click on a
variable to highlight it. You can then use the Modify button, type in a new value
and click on the Update button. Alternatively you can click on a name, press the
Enter key, type in a value and press the Enter key again.
You can find a variable in the list by typing in the beginning of its name. As you do
so the list will scroll and highlight the first name matching what you have entered.
Filter is active if you have typed a start * or question mark ? into the editing
window. Click on Filter to show the subset of unfinished variables matching the
wildcard string you enter. See the Variable tab above for information on wildcard
strings.
Modify/Update lets you add in or modify a placeholder value for a variable. When
you click on the Modify button, the value associated with the variable highlighted in
the list will appear in a small editing box next to the variable name. Type in a
number and click on Update to put the new value in the list.
Reset forces the list of placeholder values to be refreshed. If you have asked for a
Partial simulation, the list will only contain variables that are used but have not had
a placeholder value specified. Clicking on Reset will fill the list with all model
variables that do not have equations. It will also reset the list shortened by applying
a filter.
Revert will revert to the value already displayed in the list. This button is grayed
except when you are modifying values. You can also use the Esc key to Revert.
See Chapter 8 for details on using Placeholders to simulate partial models.

Subscript Control†

The Subscript Control is used to let you manage which elements of a subscripted
variable are displayed by the Analysis tools.
? If the Workbench Variable you select contains a Subscript Range, the Subscript
Control determines which values are displayed for the variable (normally all those
selected).
? If the Workbench Variable contains a Subscript Range that is a Subrange, Vensim
uses the intersection of that Subrange with the selected subscripts.
? If the Workbench Variable contains explicit Subscript Elements (such as
sales[Hobby Kiln]), Vensim does not refer to the Subscript Control.

To open the Subscript Control click on the button on the Main Toolbar or select
the menu item Windows>Subscript Control. If you have already opened the
Subscript Control and it is behind other windows, clicking the Subscript Control

291
button above brings it forward. You can also hold down Ctrl+Shift and press the
Tab key one or two times to bring it forward, along with the Control Panel.

The Subscript Control has a Keep on Top option and a Close button just like the
Control Panel described above. It is also resizable.
Edit... lets you edit the equation for the current subscript tab. When you click on
this the Equation Editor will open. When a model has no subscripts the Subscript
Control will contain only a single tab labeled -- as shown above. In this case Edit...
works the same as New....
New... first queries you for the name of the subscript you want to add and then
opens the Equation Editor (see Chapter 6). The variable type is automatically set to
Subscript so you just need to type in the values. After you click on OK in the
Equation Editor the new subscript will appear in the Subscript Control.
The tabs on the Subscript Control contain the names of all the Subscript Ranges in
the model you are working with. For more complicated models, you can end up
with multiple rows of tabs. Each tab contains the name of a Subscript Range, the
number of selected Subscript Elements, and the total number of Subscript Elements
for that range. Click on the tab to manage that Subscript Range.
There are two Subscript controls called, for lack of better terminology, the Simple
Subscript Control and the Elaborate Subscript Control. You can switch between the
two as you choose. The Simple Subscript Control is designed for Subscript Ranges
with a small number of elements and it comes up by default for Subscript Ranges 12
or fewer elements. The Elaborate Subscript Control was designed to manage longer
lists of Subscripts and comes up by default for Subscript Ranges more than 12
elements.

Simple Subscript Control

The Simple Subscript Control contains a list of the Subscript Elements for the
applicable Subscript Range. Selected Subscript Elements are highlighted. Clicking
a name alternately selects and deselects a Subscript Element.

292
All selects everything.
None removes all selections.
Full opens the Elaborate Subscript Control for the same subscript range.

Elaborate Subscript Control

Subranges highlights Subscript Subranges of the available Subscript Elements.


Clicking on a name (such as A Distributors) in the Subrange list causes the
Subscript Elements for that Subrange to be highlighted in the Available list. Any
Subscript Elements previously highlighted in the Available list will be
unhighlighted. Subranges always includes All, which highlights everything in the
Subscript Elements list, and None which removes all highlighting.
Available Elements shows all the elements of the Subscript Range. Clicking on a
Subscript Element in the Available Elements list highlights it and unhighlights
everything else. Control-clicking on a Subscript Element in the Available list
toggles the highlight on that Subscript Element, leaving all other highlights
unchanged. The >> button moves whatever is highlighted in the Available list to the
Selected list. Double-clicking on a Subscript Element is the same as clicking and
then clicking the >> button.
Selected Elements shows which elements of the Subscript Range are currently
selected. You can highlight items in the Selected list by clicking or Control-clicking
on them. The << button moves highlighted items out of the Selected list. Double-
clicking is the same as clicking and then clicking on the << button.
Clear Selected clears all selected Subscript Elements. Note that if you have no
Subscript Elements selected, some tools might report an error message when you try
to invoke them.

Other Control Windows†

If you are working with Venapps, the Datasets tab of both the Control Panel and the
Subscript Control can be used as pop- up windows. Their function is analogous to
the Variable Selection Dialog, except that they have a Close button instead of an
OK/Cancel button. When these are used, the settings are changed as desired and
then the dialogs are closed.

293
294
13 Toolsets, Tools, and Causal Tracing

Vensim has four toolbars. The Main Toolbar appearing at the top is simply a shortcut
to menu items and functio ns. The Status Bar, appearing at the bottom provides
shortcuts (specific to the window open) to commonly performed tasks, and
information on the status of current activities. The Sketch Tools, normally appearing
along the top of the Build Window just underneath the Main Toolbar, are only
available in the Sketch Editor and are used to build and edit models. The Analysis
Tools, normally appearing on the left, are used to analyze the structure and behavior
of Vensim models.
Of these four toolbars, two, the Sketch and Analysis tools, are customizable in terms
of the tools they contain, their appearance, and the actions those tools perform. This
chapter:
? Gives an overview of how the Sketch and Analysis Tools work.
? Shows how to customize individual Tools.
? Describes how to modify, save and load Toolsets .
? Discusses the locking of Analysis Tools.
? Shows you how to activate tools and work with tool output windows.
? Describes how to select variables and zoom in on time ranges.
? Introduces Causal Tracing.

Sketch and Analysis Tools

Suppose that you are involved in a woodworking project. There are two ways you
could go about this project. First you could work on a single workbench bringing the
tools to the project as you need them. Second you could take your project from tool
to tool. In practice you are almost certain to do some combination of the two, and
what combination you choose is largely dictated by physical constraints. It is not
practical to carry a lathe to a dowel, nor would it make sense to drag a boat to a drill.
Vensim's Sketch Tools are like hand tools that you bring to your project. You pick
one up by clicking on it, then take it to the spot on the sketch where you want to
perform work. Vensim's Analysis Tools are like machinery that you take your project
to. You pick up a piece of your project by selecting a variable into the workbench,
then you click on the tool to perform the analysis.
This analogy is not perfect, but it is helpful in thinking about the function of the two
sets of tools. In a typical woodworking shop you will have both a drill and a drill
press. Both of these tools perform the same basic function, and yet you bring one to
your work and you bring your work to the other. The Equatio n Editor can be used
from both the Sketch Tools (acting as a drill) and the Analysis Tools (acting as a drill
press).

295
Sketch Tools

The Sketch Tools normally appear along the top of the Sketch Editor, although you
can configure them to appear at the left (See Chapter 17). When you click on a tool,
it will depress — this is the equivalent of selecting a tool to work with. Once
selected, a Sketch tool will remain active until another tool is selected. The mouse
pointer will change shape to indicate which tool you have picked.
When you are working with the Sketch Editor, the keyboard can also be used to select
the tools. The number 1 (along the top of the keyboard) will select the first tool, the
number 2 the second and so on. The number 0 is like 10 and then Q for 11, W for 12
and so on. The right and left arrow keys can also be used to select the previous and
next tools. Pressing the Esc key will select the Lock tool unless you are in the middle
of another task in which case the Esc key is used to cancel out of that task.

The up and down arrows on the right can be used to move to different rows of the
Sketch Toolset. See the section "Modifying Toolsets" below for details on this. The
default Sketch Toolset has only a single row.
The Analysis Tools

The Analysis Tools normally appear on the left of the main Vensim Window,
although you can also configure them to appear along the top. When you click on an
Analysis Tool, it will operate. This is the equivalent of turning a machine on after
you have placed the material on or in the machine.
There are no keyboard equivalents for the analysis tools.
The left and right arrows at the bottom can be used to move to different columns
of the Analysis Toolset. See the section "Modifying Toolsets" below for details on
this. There are two default Analysis Toolsets that come with Vensim. The built in
default is shown here and is called default1.vts. A Toolset with a more complete set

296
of tools is available called default2.vts. Both of these toolsets have only a single
column.
Some of the Analysis Tools can be locked so that they are automatically operated
each time a new variable is selected into the Workbench. A locked tool will show as
a depressed button. See the section "Locking Analysis Tools" below.

Customizing Tools (Not PLE or PLE Plus)

To customize the actions of a tool, click on the tool while simultaneously pressing the
Control key, or click with the right mouse button. A dialog box appears describing
the available options. Here is a generic dialog box for tool options.

The contents of these dialog boxes will vary depending on the tool, but all tools have
at least the following options:
Tool Icon Label sets the name that will appear with the tool icon when the mouse is
positioned over the top of the tool. You can name a tool to whatever you want,
although a unique, short and accurate description is most useful. The name you
choose does not influence a tool's function, except possibly the label used for the
output of an Analysis Tool.
Background sets the background color of the icon as it appears on the screen. Click
the button to the right to choose a color from the Color Selection dialog. The default
color, denoted by the button will cause the background to match that of
standard Windows buttons. Other colors will simply appear as a colored button.
Foreground set the foreground color of the icon as it appears in the Workbench.
Click the button to the right to choose a color from the Color Selection dialog. Again
the button will select the default color which will match that of standard
Windows buttons.
NOTE For continuity of appearance, Vensim uses the default colors on all the
default toolsets. For tools with multiple functions, the icons will change to reflect
these different functions and this is usually sufficient to distinguish the tools. For
example, the Causes Strip graph has a different icon to the Uses Strip graph, even
though they are both Strip graphs. Tools can also be grouped by leaving spaces in the
toolbar to clarify which functional class the tool belongs to.
Setting tool options is done in the same way for both the Analysis and Sketch tools.
The available options for Sketch Tools are discussed in Chapter 5. The options on the
Analysis Tools are discussed in Chapters 13. The Text Editor can also be called from
the Analysis Toolbar and the options for doing this are discussed in Chapter 7.

297
Note that the Background, Foreground, and Tool Icon Label options affect just the
appearance of tools, not their functionality. Some tools, such as Units Check and
Loops, have only these options. Most tools, however, have additional options, which
are discussed in the chapters dealing with specific tools.

Opening and Saving Toolsets (Not PLE or PLE Plus)

Toolsets are saved as files and you can open them, save them, and create new ones
just as with any file. Vensim will only allow you to open one Sketch Toolset and one
Analysis Toolsets at a time. Opening or starting a new toolset closes the old one.
When you exit Vensim, it remembers the toolsets you were working with and next
time Vensim starts with these toolsets loaded. If Vensim cannot find the toolset you
were last using, it will open the default toolset.
Toolset files are stored as text files to allow transfer across platforms. Analysis
toolsets are stored with extension .vts and Sketch Toolsets are stored with Extension
.sts. By default, all Toolset files are stored in the same directory Vensim is installed
in. You can store toolsets wherever you like, but using the Vensim directory is most
convenient because that is the directory that will be referenced when you ask to open
a Toolset.
Generally, you should modify Toolset files only from within Vensim, using the
techniques described in this chapter. However, if you want to edit a Toolset file,
perhaps to reorder the tools, you can do so with any text editor. The format of the
files is straightforward, although you must be careful not to remove fields, since this
can cause unpredictable results.
Toolsets Menu (Not PLE or PLE Plus)

To manage toolsets, use the Tools menu item. Under this there are submenus for the
Analysis Toolset and the Sketch Toolset. These submenus look the same.
New starts a new Toolset. You will be prompted to see if you want to load the built-
in Toolset. Answering Yes will load the default Sketch or Analysis Toolset shown
above.
Open… will query you for the name of the Toolset to load. By default, Toolsets are
expected to be in the same directory Vensim is installed in.
Save will save the current Toolset. If the Toolset does not have a name, you will be
prompted for one.

298
Save As… will the save the current Toolset to a different file.
Modify… will open the Toolset Editor, as described below.
Next Column/Row is the same the right/down arrow at the end of the Analysis or
Sketch Toolbar. Note the Sketch Tools use Row and the Analysis tools Column
regardless of position.
Previous Column/Row is the same as the left/up arrow.
When you make a change to a tool as described in the previous section, or if you
modify a Toolset as described below, the Toolset will be marked as modified. If you
do not save a modified toolset, when you exit Vensim you will receive a message
such as:

If you answer Yes, Vensim will save the Toolset with its existing name (overwriting
the old Toolset), or if it is not named, query you for a name to save under.

The Toolset Editor (Not PLE or PLE Plus)

The Toolset Editor is a dialog that lets you modify the Toolset you are working with.
You can add, remove, reposition and reconfigure tools using the Toolset Editor. To
invoke the Toolset Editor select the Tools>Sketch Toolset>Modify Toolset or the
Tools>Analysis Toolset>Modify command. The contents will depend on whether
you are modifying the Sketch Toolset or Analysis Toolset, but the function of the
Toolset Editor is the same.

299
Tool Classes shows a list of the available tools to work with. Each tool belongs to a
class. You can drag these tools into the active Toolset by positioning the mouse over
the tool, pressing the left mouse button and moving the mouse to the position you
want to place the tool. If you position the mouse on top of a tool in the active Toolset
the new tool will be inserted before that tool. If this makes a column too long, a new
column will be inserted. There may be a scroll bar is not all of the Tool Classes can
be displayed in the dialog at once. Scroll up or down to see additional classes.
Active Toolset shows you the tools in the currently active Toolset. Multiple columns
of tools are shown together. You can drag the tools from one location to another by
positioning the mouse over the tool, pressing the left mouse button and moving the
mouse. If you drop the tool on top of a tool it will be inserted above the tool. If you
drag a tool away from the active Toolset, it will be removed. You can copy a tool by
Shift-pressing then dragging and dropping.
Each tool in the Active Toolset is a member of a tool class. When you have dragged
a new tool from Tool Classes, you can modify it and in so doing, create different
members of the class. You can review or modify tool options by Control-clicking or
clicking with the right mouse button on a tool. For example, the Variable sketch tool
class can be configured with no shape (the default) or a Box shape (or other shapes),
in which case the icon changes from a Var to a Var-in-a-box.
Tools/Col sets the number of tools to be displayed in a column. For the Analysis
Toolset, if there is not enough room to fit all the tools, then each tool will be squished
until they all fit. For the Sketch toolset, the tools will simply run off the edge of the
page. Tools for both types of Toolsets will be squished in the dialog box however. If
you are working with a large screen you can choose a fairly large number here and
this may cause the dialog box to resize itself so that it does not have to squish the
tools too much. If you click on the Tools/Col button, you can enter a new number of

300
tools per column (between 4 and 64). If you decrease the number or tools per column
some tools might run onto the next column.
Flow Tools flows the tools together getting rid of extra spacing and short columns.

Adding Tools
To add a new tool, position the mouse over the tool in the Tool Classes list that you
want. Press the left mouse button and drag the tool onto the position in the Active
Toolset that you want the tool to occupy and let go of the mouse button. To be a little
more precise drag so that the tip of the arrowhead is in the center of the tool or space
that you want the new tool to be above.
The tool will appear in the position you have placed it. It will have a default
configuration. Control-click or click with the right mouse button to modify the tool
options. When you do change the options for a tool, the icon for the tool might be
modified. For example the Tree Diagram tool has three icons: , and . The
first shows that the causes of a variable will be displayed, the second that the uses of a
variable will be displayed, and the third that both causes and uses will be displayed.
You can also modify tool options directly from the Workbench.
Moving Tools
To move a tool, simply drag it to a new location. (In this manual, "drag" means to
press and hold the left mouse button as you move the mouse.) Release the mouse
button to drop and place the tool in its new location. The other tools will be moved
down to make room.
Deleting Tools
To delete a tool just drag it from the active Toolset and drop it in an empty spot on
the Toolset Editor. The tool will be removed from the Toolset when you click OK.

Locking Analysis Tools (Not PLE or PLE Plus)

You can lock many of the Analysis Tools so that they are activated each time a new
variable is selected into the Workbench. To lock a tool, open the options dialog for
the tool and check the box labeled Activate on variable selection.

301
After you click on OK the tool will appear in the toolbar as though it has been pressed
down. This indicates that it will be invoked automatically whenever a new
Workbench Variable is selected.
You can lock as many tools as you like, though more than one or two are rarely of
use. Output from locked tools adds to or replaces the previous output of the tool,
though for a Strip Graph additional windows will sometimes be created.
You can move the output of a locked tool and the new position and size will be
maintained. For the Strip Graph tool Vensim will attempt to maintain individual
graphs that are the same size, and adjust the size of the output window accordingly.
Only those tools showing in the current toolbar will be activated when a variable is
selected. Setting up two columns, one with locked tools and one without, can be a
useful strategy.
Quick Locking

You can also lock a tool by holding down the Shift Key and clicking on the tool. If
the tool is not locked it will be locked. If the tool is locked, it will be unlocked. This
is a convenient way to toggle one or two tools between being locked and unlocked.
You can tell whether a tool is locked or unlocked by whether it is pressed down or
not.

Activating Analysis Tools

To activate an Analysis tool, simply click it. The tool is highlighted briefly and a
window opens that displays the output of the tool. (If it takes a few seconds to
activate the tool, the cursor will change shape while the tool is activated.) For some
tools, depending on the options set, a dialog box might appear before the tool output
is shown. For example the Graph tool can be configured to bring up the Custom
Graph Editor when it is invoked. If the tool you select is unable to complete the
requested action, an error message will be given.
Precisely how a tool functions depends on the option settings for the tool as well as
the settings in the Control Panel and Subscript Control (Chapter 11) . The most

302
important factors influencing the behavior of the tools are the Workbench model, the
Workbench variable, the loaded datasets, and the selected time range.
Model

The Workbench model is the centerpiece around which tool operation is controlled.
Determination of causality and structural relationships is all done in the context of the
Workbench model. If you have several models open (in several Build windows), the
Workbench model is the model that is currently active.
Variables

Most tools operate on variables. The basic variable a tool operates on is the current
Workbench Variable. If this variable is subscripted, a single name can have multiple
values.
Vensim looks at all subscripts as they appear in the Workbench Title Bar. Subscript
Constants are used directly. When Vensim encounters a Sub script Range, the tool
queries the Subscript Selection dialog for that Subscript Range. (This Subscript
Selection dialog might or might not be visible.) Vensim uses all matches between the
desired Subscript Range (which can be a Subrange) and the selected Subscript
Constants.
Because Vensim treats subscripts in this way, a single name in the Workbench can
cause the tool to refer to multiple values. Alternatively, if there are no Subscript
Constants selected, the tool might not refer to any values. In this case, you will
receive a message stating that since nothing is selected, nothing is being done.
Not every tool uses detailed subscript information. The Tree Diagram and Outline
tools, for example, operate only on the variable name itself. For this reason you
might, for example, have no trouble creating a tree diagram but be unable to create a
strip graph.
Datasets

In addition to finding variables, tools that attempt to display simulation results or data
must also be able to locate datasets. The tool searches the Dataset Control dialog to
determine which datasets are currently loaded. If no datasets are loaded, some tools
will not operate. Clicking on these tools will display an error message.
Time Ranges

The Strip, Graph, Gantt, Stats, and Table tools all use Start time, End time, and
selected Time Base as specified in the Time Axis Control dialog. The Table and
Document tools also use Special time to determine what output to provide. You can
configure the bar graph to operate on Start, End, or Special time.
NOTE When you use the Equation Editor tool on the Analysis Toolset it simply
opens the Equation Editor and not a tool output window. Similarly the Text Editor
tool simply starts the Text Editor.

303
Working with Tool Output

An activated Analysis tool creates a new window, known as a tool output window or
tool instance. Custom graphs, tables and reports also create tool output windows, as
does units checking and model checking in the Text Editor. You can resize and move
a tool output window. Tool output windows are not dynamically linked to any data
source, but are simply snapshots of the things in place when the tool output was
created. For this reason, the contents of the tool output windows never change. If
you make a change and want to see the new results, you must invoke the tool again.
The only exceptions are the Output Objects placed on Sketches which are updated
after simulation and work- in-progress graphs which are updated as a game or
simulation progresses. You can also click on the Redo Open button in the Graphs tab
of the Control panel to regenerate open custom graphs (See Chapter 11).

Menus
All tool output windows have a simple icon-based menu in the title bar of the window
that is similar to the function of the main Vensim menu. This icon-based menu
features buttons that you click to perform menu itemssuch as Save. Tool output
windows are designed to be created and closed quickly.
The buttons are as follows:
Close removes the window and deletes the windows contents. A single click is all
that is required to close it. You can also close an active output window using the
File>Close command, or by holding down the Ctrl key and pressing the W key, or by
clicking on the Close button at the right.
Lock/ Unlock locks the window and deactivates the Close buttons. Locked
windows are not closed when you use the Output>Close All or File>Close
commands. To unlock a locked window, click the Unlock icon. You can also lock
and unlock active tools using the File>Lock/Unlock command when a Tool output
window is active.
Print sends the contents of the window to the printer: see "Printing" in Chapter 15.
You can also print the active output window using the File>Print command.
Export exports the contents of the window to the clipboard: see "Exporting."
below. You can also use the Edit>Copy command on the active output window.

Save saves the information in the tool window to disk: see "Saving" below. You
can also use the File>Save As command on the active output window.

304
The button at the right is used to maximize the output window. You can also
maximize the window by double clicking on the title bar. When you maximize it the
button at the right will change to to indicate that it will restore the window size.
You can also double click on the title bar, which remains visible, to restore the size.
The button at the far right can be used to delete the output window. This works the
same as most windows under Windows.
Moving Among Output Windows
You can open as many output windows as you like. You can circulate through the
output windows by:
1. Holding down the Ctrl key and pressing the Tab key. This will only work if a tool output window
is currently active.

2. Clicking on the button on the Main Toolbar, each click moves to the next output window.
3. Selecting Windows>Output Window List from the main menu to bring up a list of output
windows. Click on the one you want to see and click on OK.
4. If you have not maximized the tool output windows, you can also move among them using the
mouse if the windows are visible. Simply click on the window you want to see.

Sizing
The tool output windows are created to be large enough to display the information
they contain, subject to the size of your screen. For simple text windows and tabular
output, you can use the scroll bars to see more information in the windows, and
resizing will change the fraction of the contents currently visible. For graphics
windows, resizing will rescale the contents, changing the relative proportions of the
contents and, in some cases, the size of fonts.
You can resize a tool output window just like any other window. Just drag any edge
or corner of the window. The tool output windows also have a maximize button that
will make them fill the entire Workbench as described above.

Exporting
Graphical output from the Strip Graph, Sensitivity Graph, Bar Graph, Tree Diagram
and Gantt Chart tool is exported as graphics. All other tools export the contents of
the window as plain text.
Vensim exports directly to the clipboard. Text is exported without any special
markings, although text from tables is exported in Tab delimited format. Graphics
are exported in Windows Metafile format or PICT format on the Macintosh. Most
Windows and Macintosh applications let you paste exported text from the Clipboard,
and many also use the Metafile or PICT graphics format exported by Vensim.
Export Options (Not PLE or PLE Plus)

The Graphics tab of the Global Options dialog (Chapter 17) allows you to specify
how you want exported graphics to go to the clipboard. You can force graphics to be
sent in color or black and white, and also control the appearance of graph lines.

305
The Settings tab of the Global Options dialog also has a check box to have graphics
exported printer-ready. This will cause the device resolution of the printer to be used
in setting up the export. Depending on your computer and printer, exporting printer-
ready can improve the ultimate appearance of your documents.
Export Size (Not PLE or PLE Plus)

The Settings tab of the Global Options dialog (Chapter 17) also allows you to choose
how Vensim sizes exported graphics. The options are Screen, Full and Query. If the
size option is set to Full, Vensim allows the tools to determine their own desired size
(which can be quite large). If the size option is set to Screen, Vensim makes the
exported graphics the same size as the graphics on the screen. In this case, adjusting
the size on the screen determines the size of the output. If the size option is set to
Query, you will be asked how big to make the exported output, as in:

? Screen Size shows the size of the graphic as it currently appears on the screen. Clicking on this
will set Width and Height to correspond to the displayed size.
? Full Size shows the size desired by the tool to create the graphic. Clicking on this will set Width
and Height to correspond to the desired size.
? Width determines the width of the exported graphic. It is measured in inches or centimeters
depending on the option you set in the Global Options dialog.
? Height determines the height of the exported graphic.
Because each tool responds to different size constraints, sizing a graph before
exporting it can yield substantially different results than resizing after exporting.
Consider, for example, output of the Graph tool that needs to be kept small. Resizing
after exporting might yield:
Graph for total cost
8M

6M

4M

2M

0
0 3 6 9 12 15 18 21 24 27 30 33 36 39 42 45 48
Time

total cost - PROJ1 $/month

whereas resizing and then exporting would give:

306
Graph for total cost
8M

0
0 6 12 18 24 30 36 42 48
Time

total cost - PROJ1 $/month

Depending on what you are doing, you might wish to resize before exporting.
NOTE For accurate sizing of exported graphics, set the sizing option to Query in the
Global Options dialog, and enter the size you desire. Setting the sizing option to
Screen, and changing the size on the screen will also work, but is less accurate.
Saving
Saving works essentially the same as exporting except that instead of sending the
information to the Clipboard, the information is stored in a disk file. Text windows
have their output saved as text, graphics files save their output as placeable Metafiles
under windows, and PICT files on the Macintosh. A large number of applications can
read these file types. Saving tool output in this manner can be convenient when you
are documenting your work. When you click on this button you will be prompted for
the name of a file to store your results to.
Vensim supports some trans fers of graphic information (from tool output) to plain
text format. When you click on the Save button, you can choose an optional file type
of Graphics Transfer (.gtx). This is an ASCII file containing the graph information.
Selecting Variables into the Workbench
All variable names appearing in tool output windows are "live." That is, you can
select variables into the Workbench from the tool output without using the Variable
Selection dialog. To do so, click the name of the variable you want, or select a name
by dragging over it. In this case the highlighted text will be selected into the
Workbench when you let go of the mouse button.
†If a variable is subscripted, clicking before the left bracket selects the name of the
variable into the Workbench just as if you had selected it from the Variable Selection
dialog. Clicking inside the brackets selects the fully subscripted name. For example,
if the Subscript Range country takes on the values CANADA, MEXICO and USA then

places Population[country] into the Workbench, whereas:

places Population[USA] into the Workbench. In addition, if you highlight only


the subscripts, this will change only the subscripts of the selected variable. Thus if
births[country] is in the Workbench then

307
places births[USA] into the Workbench. However, if a variable such as FINAL
TIME is in the Workbench, then

does nothing, since USA is not a valid subscript value for FINAL TIME.

Selecting a Time Range


The Graph, Strip Graph, Sensitivity Graph and Gantt tools all display graphs over
time. As an alternative to using the Time Axis tab of the Control Panel to change
time ranges, you can set a new range for Start and End times for these graphs by
Shift-clicking within the graph and dragging the mouse.

Hold down the Shift key and click within the graph to establish one end of the range.
Then, without releasing the mouse, drag left or right to anchor the Start or End time.
Two vertical lines indicate the range you have selected. (The accompanying example
shows a Start time of 2 and an End time of about 3.) Release the mouse button when
you have established the range you want. Note that you won't see the new Start time
and End time used until you generate a new graph by clicking the Graph tool (or
another tool that uses Start and End time). If you want to increase the time range for
a graph, you can use the Time Axis Control in the Control Panel. Alternatively, if an
output window is open showing the full (or larger than current) time range, you can
Shift-click and drag across the time range desired (including the full range if you
want to reset the time axis).
If you release the mouse button to the left of the graph (but still inside the window),
Start time will be set at the lowest value on the graph. If you release to the right of
the graph, End time will be set to the highest value on the graph.
The currently selected Time Base does not influence the selection of a time range
from inside a graph. All computations on Start and End time are actually carried out
using Time, then converted to the currently selected Time Base as necessary.

308
Selecting a Vertical Range
Analogous to selecting a time range, it is possible to zoom in on the vertical scale of a
graph. Unlike setting the time range, however, this type of zoom will not be retained
after its first use. To zoom in on the vertical scale, hold down the Control key and
drag over the range you want to zoom in on. The next time you request a Graph or
Strip Graph tool this range will be used to display output. This will not have an
influence on later graphs because the vertical range is reset (to automatic scaling)
after one Graph or Strip graph tool use. You can also set the Y-axis bounds using
custom graphs.

Causal Tracing

Causal Tracing is the ability to quickly find the causes of model behavior. Vensim's
analysis tools make this fast and easy to do. The following steps outline the process
in its most commonly practiced form:
1. Start with some behavior that needs to be investigated. Select this variable into the Workbench.
2. Use the Causes Strip graph to show the behavior of the variable and its causes.
3. Inspect the graphs to see which cause is most likely responsible. If it is ambiguous, lock the graph
and choose a candidate.
4. Select the variable that is most likely responsible for the behavior into the workbench by double
clicking on it.
5. Return to step two and repeat until you have gone in a circle, found a causal strip that is surprising
or gotten down to just Constants and Loookups. In the first case you have found a feedback loop,
in the second you will need to study the equation to understand the relationships involved and in
the last case you will have traced the behavior of interest to a set of parameters.

In practice, there is a lot more variety in Causal Tracing. The Tree diagram tools can
be used to jump over large sections of a model more quickly than the Causes Strip
graph. In many cases, you will want to use the Document tool to study the equation
of a variable to make sure the equation is correct. All of the different tools and their
configurations are discussed in Chapter 14.

Causal Tracing Example


Start with something that is interesting.

Graph for workforce


200

80
0 10 20 30 40 50 60 70 80 90 100
Time (month)
workforce - Step person

309
Here we see that workforce is oscillating and moving toward equilibrium and we
want to understand why. For each of the windows that follows the highlight indicates
the variable that is about to be selected into the Workbench.

? ?

? ?

? ?

310
We have gone full circle and found a feedback loop. In this model the workforce is
hired in response to inventory shortfall, and after they are hired, they build inventory.
The problem is that workers are being hired as long as there is any inventory shortfall,
which means that when inventory comes into balance, the workforce (and therefore
production) are at their peak and exceed sales. There is more discussion of this in the
chapter on Oscillations in the Modeling Guide.

311
14 Analysis Tools

NOTE Not all analysis tools are available in all configurations. Vensim PLE and PLE Plus both have
fixed toolsets and do not support modifications to the behavior of tools.
The Analysis Tools allow you to explore the structure and behavior of a model. The Analysis Tools
are normally located on the left of Vensim's main window. This chapter describes each of the Analysis
Tools:
? The Tree Diagram tool displays a graphical representation of the causes or uses of variables.
? The Outline tool shows the same information as the Tree Diagram tool, but in a text -only format.
? The Document tool displays the equation for a variable, its units of measure, and selected values.
? The Loops tool shows a list of all feedback loops that pass through the Workbench Variable.
? The Strip Graph tool helps you trace causality by displaying the behavior of a variable and the
behavior of the causes or uses of that variable.
? The Sensitivity Graph tool shows the results of sensitivity simulations, and also allows you to
trace causality.
? The Graph tool gives you the big picture of a variable, or a number of variables in the Custom
Graph tool, and helps you prepare presentation-quality output.
? The Table tool displays numerical values for the Workbench Variable and optionally for its
causes or uses.
? The Stats tool provides summary statistics about the Workbench Variable and optionally for its
causes or uses.
? The Bar Graph tool displays a bar graph of a variable at a specific time to help you compare
summary measures across runs or subscripts.
? The Gantt Chart tool measures the Start Date and End Date of various tasks using a Gantt chart
format.
? The Runs Compare tool allows you to compare initial differences between two simulation runs.
? The Units Check tool is an alternative way to start units checking on a model.
? The Equation Editor tool is an alternative way to start the Equation Editor.
? The Reality Check tool runs Reality Check on the Constraint selected in the Workbench.

Structural Analysis Tools


The Structural Analysis Tools provide information about the structure of a model. These tools can be
used without reference to datasets, although the Document tool has the option of displaying behavioral
information. Because of this, you can use the Structural Analysis Tools before simulating a model.
To use these Analysis Tools, first select the variable you are interest in into the Workbench (using the
Variable Selection Control in the Control Panel, or by double clicking on the variable name in a tool
output window). Note that the Tree, Outline and Loops tools work only on the variable name and
ignore all subscripts. The Document tool, depending on how it is configured, will make use of the
information in the Subscript Control.

312
Tree Diagram

The Tree Diagram tool creates a graphical representation of the structure of a model
associated with the selected Workbench Variable. The Tree Diagram tool provides you with an easy-
to-read, graphical representation of the causes and uses of variables. The Tree Diagram displays
structural relationships (and not simulation results) and can therefore display information about a
complex structure in a relatively small space.
The Tree Diagram tool is especially useful for general orientation and as a memory jogger.
Tree Diagram Options

Show Link (Causes or Uses or Both) determines whether the Tree Diagram tool will show the causes,
the uses, or both the causes and uses of a variable. If you choose Causes, the tree diagram grows from
right to left. If you choose Uses, the diagram grows from left to right. If you choose Both the causes
grow to the left and the uses grow to the right. The icon for the Tree Diagram tool reflects your
choice.
Causes (Normal, Initial) determines which equations are traced when determining causes. Levels,
and variables with equations using INITIAL, REINITIAL or ACTIVE INITIAL, are computed
one way when they are initialized, and another way as the simulation progresses. For example,
suppose the equation for Water is
Water = INTEG(inflow,init water) ~~|
? Normal shows the path of causality during the normal simulation. Thus, if Normal were checked,
the Tree Tool would show inflow as a cause of Water.
? Initial shows the path of causality as the model is initialized. Thus, if Initial were Checked, the
Tree Tool would show init water as a cause of Water.
Show Types (Level, Auxiliary, Data, Initial, Constant, Lookup, Test Input, Constraint) determines
what variable type will be shown on the Tree Diagram. This option allows you to filter for specific
variable types. For example, selecting only Level will show the true dynamic structure. The
Workbench Variable, regardless of its type, will always be shown. If you don't select all types, the
causes of types that are not selected will still be searched and the connections marked with a line as
discussed in output.
Fonts (Huge, Reg, Med, Small, Tiny) lets you set the fonts for display output. These should be
increasing in size from Tiny to Huge. The tree tool will attempt to output in the regular font, if this

313
fails because of size it will successively try Med, Small and Tiny. If, even using Tiny, it cannot fit the
tree it will give up and report that it cannot display output. Huge is used when you resize a tree output
window to larger than original size.
Attributes (Color, Width, Polarity) will attempt to retain the attributes for the link that exist in the
sketches defining the link. If any of these are checked all of the views, in the order they are listed in
the view selection menu as described in Chapter 5, will be searched. If these Views contain the
defined link the Color, Width and Polarity will be retrieved from that link. For larger models this can
slow things down significantly.
Tree Depth [default 2] lets you choose the depth to which you want to see the causes or uses. For
example, with Causes selected, a depth of 1 indicates that you want to see just causes, a depth of 2
indicates that you want to see causes and the causes of causes. You can type in a depth, or select a
depth by clicking on the down arrow to the right. The largest selectable depth is 999, which generally
displays the structure of the entire model.
The second value to the right of the drop-down box is used only if you have elected to show both
causes and uses. In this case causes are displayed to the depth displayed in the drop-down box, and
uses to the depth typed in to the box to the right.
Tree Diagram Output

Each time you invoke the Tree Diagram tool a new window is created. This window displays the
causes or uses of a variable as a tree branching from the right for causes or from the left for uses. A
variable name in parentheses ( ) means that the variable appears elsewhere in the same diagram
(indicating a feedback loop) and its further causes or uses are not shown. If you have set Capitalize by
Type in the Global Options dialog, variable types are denoted using different case mixtures, as
described in Chapter 2.
This is the output of the Tree Diagram tool for the model world.mdl when crowding is the
Workbench variable.

If a branch passes through variable types that are not selected to a variable type that is selected, the
branch is collapsed, showing the selected types as directlyconnected, but with a cross in the line. For
example, unchecking all variable types except Levels and increasing the depth on the previous diagram
to 5 gives:

Note the parentheses ( )around the second occurrence of Population in this diagram.

If the Tree Diagram tool is too large to be displayed clearly on the screen, you will be asked if you
want to see it anyway. Depending on your relative printer/screen size, it might still be possible to print

314
such a Tree Diagram. Note that when printing a Tree Diagram, Vensim will always put the whole
diagram on a single page.
NOTE The Tree Diagram tool ignores subscripts. It operates on the Workbench Variable and selects
causes and uses from the union of all possible causes and uses, for all subscript values.

Outline

The Outline tool shows the same information as the Tree Diagram tool in a text -only outline
format.
Outline Options

The Outline tool has a subset of the options of the Tree Diagram tool. There is only one font button. If
outlines become overly large scroll bars are added to the output.
Outline Output

The Outline tool shows exactly the same information as the Tree Diagram tool. The result, however, is
displayed in outline format, in which causes or uses are indented as subheadings under a variable.

Document

The Document tool allows you to review the equation, definition, units of measure, and selected
values for a variable. This information is often required to understand why a variable functions as it
does, given the inputs. The Document tool also allows you to document portions of a model, variables
of particular type, or even an entire model.
Document Options

In addition to the standard options, the Document tool allows you to select what information you want
to see for a variable, and in what format.

315
Display allows you to select what information you want to see displayed. You can select any
combination of the options you wish.
? Equations, if on, shows the equation(s) for the variable. If the variable is subscripted, then the
equation(s) appropriate to the currently selected subscripts are shown.
? Text, if on, shows the comment field for the variable.
? Range, if on, prints the low and high range values for the variable.
? Groups , if on, lists the group(s) that the variable is a member of.
? Options, if on, shows any optional flags that can be defined for the variable.
? Units, if on, shows the units for the variable.
? Units-Check, if on, checks the equation(s) for the variable for units consistency. (The Units
Check command checks all equations in the model. This option checks only the particular
equation you are reviewing. This can be handy when correcting units problems and chasing down
propagation errors.)
? Values, if on, shows the value of the variable at Special time in the first loaded dataset. (If there is
no value for the variable in the first dataset two dashes -- are displayed.)
? Cause-Lkup-Cnst, if on, shows the values of Lookups and Constants that are inputs to the
equation. Values are taken from the first loaded dataset and dashes -- are displayed when no
values are available.
? Cause-Active, if on, shows the values of non-constants that are inputs to the equation. Values are
taken from the first loaded dataset at Special time.
? Cause-Def, if on, shows the definitions for the variables appearing in the equation.
? Use, if on, shows the where the variable is used.
? Use - Def, if on, shows the definitions of the variables in which the current variable is used.
Formatting (Original or Terse or Verbose) determines how equations are displayed.
? Original displays equations with the same spacing and punctuation you used to created them.
? Terse outputs equations in a compact, essentially line-wrapped format. When this option is
selected the Document tool tries to minimize the space needed for the equation.
? Verbose outputs equations in a stylized and readable, albeit bulky, format.

316
? Shorten comment, if on, removes all excess spaces and carriage returns in the comment.
Line Length (default 75) determines the number of characters used in an editor line. This can be set to
any number between 25 and 512. Use large numbers if you want to paste the output to a word
processor for additional formatting.
Output Font... lets you set the Font to be used for output.

Multiple Equation Options allows you to document multiple equations within the model. This is
useful for printed documentation to be provided as a supplement to reports and similar works. By
default Multiple Equation Options are turned off. You can also select to document:
? All Vars shows all variables in the model.
? One Group documents all variables in a group. If you select this option you will be queried for
the group to document. This makes it straightforward to document part of a model. You can, in
this way, document different Views of a model by using the Edit>Act on Selected>Group
command in the Sketch Editor, then documenting by Group.
? All of Type documents all the variables in the model of a particular type. The type that will be
documented can be selected from the combo box at the right.
If you are documenting multiple equations you can also choose the following options:
? Number Equations, if on, creates an equation number for each variable in the model. The
equation numbers increase by 1 for each variable in the model in the order they are documented.
? Send Output to File, if on, outputs the documented equations to a file. For large models this is
faster than outputting it to an output window. Also, output to a window can be truncated if there is
too much of it.
? Ordering determines how the variables will be put out when they are documented. As Entered
will retain the original document order — this option is most useful if the model was built using
the Text Editor. Alphabetic will order the equations alphabetically. Alphabetic by Group will
order the Groups alphabetically and within each Group order the variables belonging to that Group
alphabetically.
? Document Output
Vensim creates a window the first time you invoke the Document tool. Successive invocations add
information to this window. You can scroll the window to review information from previous
invocations. If you have more than one Document tool in the Analysis Toolset, each tool displays
output to a different window.
NOTE If you change the Output Font for the Document tool and you already have output from the
tool open you will need to close the output before the font change will take effect.

The Document tool finds the equations for subscripted Workbench Variables by referring to the
subscript selection lists. Only the relevant equations are displayed.
Vensim formats equations in the document window according to your setting of the Formatting option.
A row of asterisks ************* separates equations to make them easier to read.
If no datasets are loaded, the value options are ignored and no message is given. When values are
reported for dynamic variables, they are always taken from the first dataset and reported at Special

317
time, which you can change from the Time Axis tab of the Control Panel. If you have a dataset loaded,
but no values for a variable are found, two dashes -- are displayed.

Loops

The Loops tool displays a list of all feedback loops passing through the Workbench Variable. The
list is ordered from the shortest loop (the one involving the least number of variables) to the longest
loop. This provides useful summary information on model interactions. Only loops of length less than
32 variables are searched for. The Loops tool has no options.
Loops Output

Each time you invoke the Loops tool, Vensim creates a text window listing the loops found and their
length.

The Loops tool will not list loops involving more than 32 intermediate variables.

For large models, there can be a surprisingly large number of loops. Under these circumstances the
Loops tool can take a long time to complete operations. If more than 50 loops are found you will be
asked if you want to see more than the first 50.

Dataset Analysis Tools


The Dataset Analysis tools help you analyze variables, data, and simulations, in a variety of ways. All
of the Dataset Analysis tools operate on subscripted variables. If theWorkbench variable, as it is
displayed in the Workbench, contains Subscript Ranges, then the appropriate Subscript Control tabs
will be referenced by Vensim and one or more elements of the subscripted variable will be displayed.
If you trace causes on a subscripted variable the causes of the subscript instance or instances you have
selected will be shown. Because there can be multiple equations for a variable the causes shown may
include different variables depending on which instances of a variable are having their causes traced.
Uses, on the other hand, work the same way as for the structural Analysis tools. Each variable that
uses any instance of the Workbench variable is displayed.

Strip Graph Tool

The Strip Graph tool is likely to be your most frequently used tool. It displays small, simple
graphs in a strip to help you trace causality quickly by showing the causes or uses of a variable. The
strip graph plots asingle variable on each graph of the strip and shows behavior for each loaded dataset.

318
Strip Graph Options
You can tailor the appearance of graphs and control the amount of output with the Strip Graph Options
dialog. Right-click or Control-click the Strip Graph tool to display the Strip Graph Options dialog.

Show Link (Causes or Uses or None) determines which variables, in addition to the Workbench
Variable, will be displayed.
? Causes shows the Workbench Variable and those variables that cause it.
? Uses shows the Workbench Variable and those variables that use it.
? None just shows the Workbench Variable.
Causes (Initial, Normal) determines which equations are traced when determining causes. Levels,
and variables with equations using INITIAL, REINITIAL, or ACTIVE INITIAL are computed
one way when they are initialized and another way as the simulation progresses. For example, suppose
the equation for Water is
Water = INTEG(inflow,INIT WATER) ~~|
? Normal shows the path of causality during the normal simulation. Thus, if Normal were checked,
the Strip Graph tool would show inflow as a cause of Water.
? Initial shows the path of causality as the model is initialized. Thus, if Initial were checked, the
Strip Graph tool would show INIT WATER as a cause of Water.
Show Types (Level, Auxiliary, Data, Initial, Constant, Lookup) determine which types of variables
are displayed by the Strip Graph. Graphs are shown for Level, Auxiliary, and Data variables.
Numerical values are shown for Initial and Constant variables. Mixed variables will normally appear
in a graph, but will be straight lines for Constant or Initial components. Because the x-axis of a
Lookup is not a Time Base, a separate Strip Graph is created for Lookups (see below):

319
Definition, if checked adds the definition of a variable to the right of the name. This is useful when
working with models that have short variable names.
Line Type (Linear Interp, Dots Only) displays graph plots as dots or lines (see below). Linear
Interpolation is usually preferable for viewing simulation results, while Dots Only is useful for
reviewing data.

Transform (Off or Fourier or Autocorrelation) determines what kind of plots the Strip Graph tool
generates. The Fourier graph and Autocorrelation graph are useful for reviewing periodic data and
residuals.
? Off causes the Strip Graph tool to create plots of variables over time.
? Fourier causes the Strip Graph tool to create a frequency domain plot with the x-axis labeled
"Frequency." Frequency is measured in the units of the currently selected Time Base; power is
measured in the square of the units for the variable.
? 0 mean, if checked, subtracts the mean from the data series before computing the Fourier
transform. This will remove the value that appears at frequency 0 representing the mean value and
can make it easier to identify a later peak.
? Autocorrelation causes the Strip Graph tool to show an autocorrelation plot for each variable. An
autocorrelation plot shows the correlation of a variable with the variable's value at a previous time.
The x-axis on this plot represents the number of lags, where a lag is one SAVEPER. The X axis
starts at 0 where, by definition, the autocorrelation is 1.0.
? Max # lets you specify the maximum number of lags to be used. By default this is 40. Larger
values can be useful in looking at long term oscillatory phenomena. Shorter values might be
appropriate when looking at residuals.
NOTE Both the Fourier and Autocorrelation options change the units for the x and y axes of plots.
Be careful when you interpret results.
Max Graphs Per Window is the maximum number of graphs that will appear in a single window. If
too many graphs are placed in a single window, each graph is shrunk, making them difficult to read.
But if only a few graphs are placed in a window, many windows might be required to display all the
graphs on the screen. The current value of the maximum number of graphs per window is shown.
Type in a new value or click on the down arrow to the right to select from a list of values that can be
used.

320
Max Windows is the maximum number of windows that will be created each time you invoke the
Strip Graph tool. If you need more windows than specified by this number, you will be asked if you
want to see them all. This is to prevent too many windows from being created, as might happen if you
use a SUM function, which creates tens or even hundreds of windows. The current value of the
maximum number of windows is displayed. Type in a new value or click on the down arrow to the
right to select from a list of values that can be used.
Output Strip Width is the width of the Strip Graph window. This is measured in inches or
centimeters according to your selection in Tools>Options.
Output Strip Height is the height of the individual graphs (excluding labels) within the Strip Graph
output window. If the graph would be too big to fit on the screen, Vensim will adjust this height.
Fonts (Normal, Small and S quished), lets you set the fonts that will be used for output. The normal
font is used if there is sufficient room, if not the small font is used. If using the small font does not
leave enough room, the squished font is used.
Strip Graph Output

Clicking on the Strip Graph icon generates one or more windows that show plots of the Workbench
Variable and — depending on the settings — its causes or uses. If a Workbench Variable is
subscripted, and more than one subscript is selected, Vensim reports multiple values for this variable.
If more plots than will fit in a single window are required, multiple windows will be created, subject to
the settings of the Max Graphs Per Window and Max Window options.
NOTE Strip Graph is the only tool that creates more than one window for a single invocation. Since
each window is a separate tool output window, you can delete them selectively, leaving just the ones
you need.

A strip graph has an active X-axis that you can use to set the global Start time and End time by shift
dragging over a range as described in Chapter 12.
NOTE You cannot adjust the Start time or End time using plots of Lookups, autocorrelation plots, or
Fourier plots, because these types of plots do not have a Time Base for the X-axis.

321
Sensitivity Graph

The Sensitivity Graph tool is designed to allow you to review the results of sensitivity
simulations. This tool also maintains much of the flexibility and power of the Strip Graph tool to aid
in model analysis. When sensitivity results have been stored for a variable, the Sensitivity Graph will
show confidence bounds or multiple traces. When results are not available, it will display a graph just
as the Strip Graph tool would. You can display multiple simulations (though only one sensitivity
simulation) and overlay data and simulation experiments on sensitivity results.
Sensitivity Graph Options

You can set the Sensitivity Graph to show confidence bounds or individual traces, and set the colors
and values for the confidence bounds. You can also set a number of options that are the same as for
the Strip Graph and the discussion of those will not be repeated here.

Show Sensitivities as:


? Individual Traces, if checked, will cause a thin line to be displayed for every sensitivity
simulation performed. You can set the color of all of the individual traces with the Color button to
the right. Because of memory limitations, some configurations of Vensim might restrict the actual
number of traces displayed (generally to about 100). The use of individual traces is probably
appropriate when you are making only a handful of simulations.
? Confidence Bounds , if checked, causes the simulations results to be displayed as confidence
bounds. These are computed at each point in time by ordering and sampling all the simulation
runs. Thus, for example, for a confidence bound at 50, 1/4 of the runs will have a value bigger
than the top of the confidence bound and 1/4 will have a value lower than the bottom. You can
enter up to 8 confidence bound regions (in any order) and the color that should be used to display
them. Simply type in a number and click to select a color.
Plot Mean Value, if checked, causes the mean value at each point in time to be displayed. In general
the mean value will not be the same as the median value (middle of the confidence region) or the base
simulation run. You can set the color with which the mean value is displayed by clicking on the color
button to the right.
Suppress first run plot, if checked, will suppress the plot from the first run. This is often desirable if
you are choosing to plot the mean value.

322
Sensitivity Graph Output

To use the Sensitivity Graph tool, the first loaded run must be a sensitivity run. Computation can take
several seconds or even minutes if there are a large (>500) number of simulations contained in the
sensitivity run.

The graph on the left shows individual traces, that on the right shows confidence bounds. If you ask
for the Sensitivity Graph of a Constant that has been changed in creating the runs you will get:

The flat confidence bands result because this is a constant.

If you ask for a Sensitivity Graph of a variable that has not been saved you will get the same output
you would get for a Strip Graph.

Graph

The Graph tool displays single or multiple variables on a single graph. It is useful for getting the big
picture of a number of variables, and for printing presentation-quality copies of your graphs.

323
When invoked from the Workbench, the Graph tool allows only one variable per graph, although there
can be multiple datasets and subscript values.
Displaying multiple variables on a graph requires a Custom Graph, using the Define custom graph on
invocation option (see below) or using the Graph tab of the Control Panel. Chapter 15 describes how
to set up Custom Graphs. You cannot do causal tracing with the Graph tool.
Graph Options

You can customize a graph's style and printed output by changing the options on the Graph tool.
Right-click or Control-click on the Graph tool to get the Graph Options dialog.

Line Type (Linear Interp or Dots Only) display plots as lines or dots.
? Linear Interpolation connects all the data points with lines. This is normally the easiest type of
graph to understand quickly.
? Dots Only displays each data point as a separate dot. This is useful for reviewing data.
Graph Size (Small or Medium or Large or Full Screen or Custom) determines the initial size of the
window created by the Graph tool. You can resize the Graph after it is displayed.
? Small, Medium, Large, and Full Screen create successively larger windows.
? Custom allows you to enter the initial size of the window created. Type in a width and height (in
inches or centimeters according to the setting you have chosen in the Global Options dialog).
Graph Type (Normal, Cumulative, Stack) determines how data will be represented.
? Normal displays the values of the variables over time.
? Cumulative integrates the values of the variables. For positive variables, Cumulative yields an
upward-sloping graph over time. The cumulation for a variable begins at the first time that values
for the variable are available, regardless of the global Start time. This ensures that if you shorten
the time range, the values will be the same as those in a graph of the full time range. Cumulative
graphs allow you to view accumulations without adding additional model variables.
Stack displays the values of the first variable normally, the second as the sum of the first and second
variables, the third as the sum of the first three, and so on. All variables are stacked, including
different subscript elements in a run and the same variable for different runs. For positive variables,
this means that each successive variable is higher than its predecessors and that the final variable is the
sum of all variables. An error occurs if the variables are from datasets with different sampling points
(for example, different values of SAVEPER). Stack graphs are a convenient way of breaking down

324
the components of a variable. It make the most sense to use stack graphs with one variable from
multiple runs, or multiple subscripts from one run but rarely both.
X-Labeling (Between Lines, On Lines) determines the position of labels for the X-axis.
? Between Lines places the labels between the grid lines that marks values on the X-axis. This is
useful if the graphed data represent activity during a period.
? On Lines places the labels on the grid lines marking the X-axis. This is useful if the graphed data
represent activity at a particular time.
X-Divisions (By Value, As Global) determines the number of X-axis divisions in the graph.
? By Value sets the number of X-axis divisions to line up with round numbers.
? As Global sets the number of X-axis divisions equal to whatever is set in the Time Axis Control
dialog.
Title Font lets you set the font that will be used in displaying the title of the Vensim model. Clicking
on this and the other font buttons brings up the font selection dialog.
Label Font lets you select the font that will be used in the X and Y axis labels for the graph.
Stamp Fonts lets you select the fonts that will be used in printing the stamp on printed output.

Legend Fonts (Normal, Small and Tiny) let you set the fonts that will be used in the legend of the
graph. The small font is used when the normal font is too big, and the tiny font is used when the small
font is too big.
No legend, if checked, suppresses the legend on the graph. This will make the graph bigger and can be
useful when graphing a large number of variables or datasets.
Drop from legend if no data is available, if checked, will drop any variable from the legend for
which no points are being plotted. The color selection of the remaining items will be unchanged. This
option is useful if you have a large number of datasets available, but each of them contains only a
subset of the model variables.
Identifying Mark is text displayed at the lower left of a printed graph in a small font. This option is
blank by default. If you type text here, it will be displayed on the printed graph only, not on the
screen. You can use this option to make notes, indicate the source of a graph, and so on.
Stamp is placed over the lower part of the printed graph in the Overlay Font. You can use this option
to mark printed graphs as confidential, preliminary, draft, or whatever is useful. The text you type here
will not appear on the screen.

Graph Title is the title displayed on top of the graph. This option is blank by default, and if you leave
it blank, the title will be the icon name followed by the name of the Workbench Variable (for example,
"Graph for Natural Resources").
Define Custom Graph on Invocation, if checked, will cause the Custom Graph Editor to be opened
you click on the tool. The graph definition will be filled in with the information that would have been
used to create the graph. This is a convenient way to create graphs with a small amount of
customization.
NOTE The Graph Tool always uses round numbers for the minimum and maximum X values unless
the range on the X-axis is less than 10.
Graph Output

When you click on the Graph tool, Vensim opens a new window containing a graph. If you try to
graph more than 16 values (say four Subscripts for five runs), only the first 16 are shown. (This
limitation does not apply to Custom Graphs.) Keep in mind that graphs with more than five or six
lines are hard to read.

325
The time axis for the graph follows the global Start time and End time, but is rounded to even
numbers. If the X Divisions As Global option is selected, the number of horizontal divisions is
determined by the setting in the Scale tab of the Control Panel. If X Divisions By Value is selected,
the number of horizontal graph divisions is based on the minimum and maximum values for the time
axis, and does not derive from the Control Panel settings.
For each variable, the units are reported. When invoked from the Workbench, the Graph tool always
creates a graph with a single vertical scale.

Table

The Table tool generates a read-only table that you can scroll to review values. The resulting table
displays numerical values for variables and — depending on the Table Options settings — their causes
or uses. The Table tool's most common use is for detailed analysis of a narrow time range, but it is
also good for displaying a lot of values on the screen and also for displaying arrays of data at a given
time.
The Table tool uses Start time, Special time, and End time from the Time Axis tab of the Control Panel
to determine how to produce output.
Table Options

Right clicking or Control-clicking on the Table tool icon opens the Table Options dialog. You can
specify how the tool should function and customize the appearance of the Table tool icon.

326
Show Link (Cause, Use, None) determines what variables the Table tool displays in addition to the
Workbench Variable. See the Strip Graph Options section above for more detail.
Causes (Initial, Normal) determines which equations are traced when determining causes. See the
Strip Graph Options section above for more detail.
Show Types (Level, Auxiliary, Data, Initial, Constant, Lookup) determines which types of
variables are displayed by the Table tool. Level, Auxiliary, and Data variables display values at
different times. Initial and Constantvariables display only a single value that does not scroll with time.
Lookup variables list the X-axis and Y-axis below one another.
Number Format (Pretty, Scientific) determines the format for displaying numbers.
? Pretty makes numbers easier to read. For example, numbers from 1,000,000 to 999,000,000 are
displayed as 1M to 999M; numbers from 1,000,000,000 to 999,000,000,000 are displayed as 1B to
999B; numbers from 1E12 to 999E12 are displayed as 1Tr to 999Tr.
? Scientific puts all numbers in the form 1.0E13, which generally shows more significant digits.
Equilibrium Testing, if on, causes the Table tool to show all Levels that are changing between
INITIAL TIME and the first Time saved after that. You can set tolerances to indicate how much of a
change you want reported. If the change is bigger than Rel * the variable value at INITIAL TIME and
bigger than Abs, it will be reported. If Rel and Abs are left blank, any change will be reported.
Equilibrium testing is a useful way find out which levels are changing and pushing the model out of
equilibrium. If you are doing Equilibrium testing, it is a good idea to set SAVEPER equal to TIME
STEP.
Output Font lets you set the font that will be used in the table output. This option only has an effect
when a new window is created for the table.
Print Every determines how often to table the numbers. Normally all the numbers are tabled and
leaving Print Every at 0 will cause this to happen. If, however, you want to see the numbers less
frequently you can set Print Every to a larger number. For example setting print every to 10 will show
output at times 0, 10, 20 and so on. This option is only used when the Table tool creates a new
window. Thereafter the times shown are set in that window.
Time Running Down, if checked, causes time to be displayed along the leftmost column of the table
instead of across the top row.

327
Column Width determines the width assigned to different columns. The widths are measured in the
number of zeros 0 in the selected font. This option is only effective when a new window is created.
? First sets the width of the first column. This column is not scrolled with the rest of the window,
and normally contains variable names.
? Rest sets the width of the remaining columns, which normally contain numbers.

2d Subscripting † , if checked, causes Vensim to display values at a specific time with subscripts
instead of time running across. Vensim will use the variable to be displayed along with the settings in
the Subscript Control do determine which elements to display. It will display the last varying subscript
across, and the second last varying subscript down. If more than two subscripts are varying this will be
repeated. This is a very effective way of looking at all elements of a 2 dimensional array.
Transform determines if you see the model result over time or a transformation into another domain.
? Off is the normal setting and simply displays the value of variables over time.
? Fourier, if checked, computes a Fourier transformation of the variables on the current time range
and displays that with frequency and power information. Although times will still appear in the
first row, they are not related to the output in this mode.
? Autocorrelation, if checked, computes and dis plays the autocorrelations for the workbench
variable from 0 lag time up to the number specified in Max Times.
? Max Times determines how many SAVEPERs to compute the autocorrelation for.
NOTE many of the options are used only when the Table output is first created. If you want all your
options to take effect you might need to delete the Table tool's output window and invoke the Table
tool again.
Table Output

The first time you click on the Table tool, a new window is created. Successive invocations add
information to the bottom of this window without removing the old information. You can use the
scroll bars to review earlier output. If you have multiple Table tools in the toolset, multiple output
windows are created (one for each tool).

The Table tool creates a read-only display of numbers in row-and-column format (similar to a
spreadsheet). The left-most column is a set of labels that do not move when the table is scrolled
horizontally. You can scroll and resize the output window as you like. If only one value is found for a
variable, the value for that variable is always displayed in the first column, regardless of the horizontal
scroll position of the window. If no values are found, two dashes (--) appear in the first column. If
some values are available and others are not, two dashes mark the missing values.
The Table tool reports whatever is in the dataset .vdf file without assuming whether or not it will find
dynamic data. This works differently from the Strip Graph tool, which first determine the type of a
variable from the model and then look for its values. For example, if you have two datasets loaded
representing runs from two separate models, and RESOURCES REMAINING is a Constant in the
current model and a Level in the old model, the Strip Graph tool will report the first dataset as having
no values. But the Table tool will report the complete set of values from the first dataset.

328
Stats†

The Stats tool provides summary statistics on the Workbench Variable and its causes or uses
(depending on option settings). This tool provides a quick statistical overview of the values for a
variable (that you could review in detail with the Table tool).
Stats Options

Most of the options for the Stats tool are the same as those for the Table tool except that Print Every is
not used and Time Running Down is replaced by Stats Running Down. In addition there are some
options specific to the Stats tool.
R square against 1st, if checked, will compare the values in each dataset against the first and report an
R-square for this comparison. R-square is defined to be (1 - sum of square error / the variance of the
variable in the first run). The resulting number ranges between -infinity and 1. The R-square of a run
with itself is always one. To get the R-square of a simulation with data, load a dataset with the data as
the first loaded dataset and the simulation as the second.
Percentiles allow you to get more detailed information about the distribution of the results. If you
include 25 as a percentile, the Stats tool will report the number that is bigger than the value the variable
took on 25% of the time. The 0th percentile is the minimum, the 50th percentile is the median and the
100th percentile is the maximum. You can enter any positive number to see the percentiles reported
for this.

NOTE If you change the options to add or remove either R-square or percentiles, you will need to
delete the output of the Stats tool and invoke it again to see your changes.
Over, determines what to do the statistics over.
? Time, if checked, causes statistics for a given variable over the course of the simulation to be
reported. This is the default.
? Sensitivity, if checked, causes the Stats tool to work across sensitivity runs at a given time. You
can set the time to look at as Start, Special, End or Select. If you choose Select you must also fill
in a value. This option will only work on runs that are sensitivity simu lations containing the
variable to be displayed. Any other datasets will simply report missing.
? Subs , if checked, will cause statistics to be reported across the subscripts for a given variable at
the chosen time. The subscripts that will be reported are those selected in the Subscript Control.
For example by selecting all elements of all subscripts in the Subscript Control you can use this to

329
get the average value of a variable over all its subscripts at Special Time.
? Stats Output
Like the Table tool, an invocation of the Stats tool displays information in a read-only row-and-column
format window, adding to the window if it is already open. Instead of displaying values, however, the
Stats tool displays the following summary statistics for each variable.

Count displays the number of points considered.

Min displays the smallest value among all the points considered. If the count is 1, this is the only
information displayed. (If the count is 1 then Min, Max, and Mean are the same, and the standard
deviation is not defined.)
Max displays the largest value among all the points considered.
Mean displays the arithmetic average over all the points considered.

Median displays the number which the variable is bigger than one half the time and smaller than on
half the time.
StDev displays the standard deviation over all the points considered. (Note that the standard deviation
is computed using N, not N-1.)
(Norm) displays the normalized standard deviation (the standard deviation divided by the mean).
This is computed only if the mean is non-zero.

75% displays the number which the variable is smaller than 75% of the time. You can choose to see
up to 8 percentiles in this manner.
R-square dis plays the R-square against the first dataset.

#points shows how many points were compared in computing the R-square. This is shown only when
R-square is shown. If two datasets have non commensurate time axes, this might be smaller than the
number of points for either of the datasets.
The Stats tool uses Start time and End time to determine which points to review, unless you are
viewing sensitivity results.

Bar Graph

The Bar Graph tool creates a bar graph of one variable at a specific time. This is useful for
comparing summary measures across runs or subscripts. The Bar Graph tool can also be used for
showing histograms of variables over all times, and histograms of the results from sensitivity
simulations. Custom Bar Graphs can display more than one variable.
Bar Graph Options
The Bar Graph tool has options to change orientation and the times at which the bars are computed.

330
At Time (Start or End or Special or Selector As time-graph) determines what time the bars will be
displayed for. Since the Bar Graph tool displays a single value of a variable, and simulation and data
contain multiple values of variables, it is necessary to select a time at which to display the value.
? Start shows the v alues for variables at Start time as set in the Control Panel.
? End shows the values for variables at End time as set in the Control Panel.
? Special shows the values for variables at Special time as set in the Control Panel.
? Select allows you to select a value for the time at which the Bar Graph tool shows values. Enter
the time at which you want the bars to be displayed. This value will be interpreted in the context
of the currently selected Time Base.
? As time -graph shows the values from all times. This generates a time-graph in the style of the
bar graph and is useful when the number of time points being reviewed is small. This option is
not valid if you are creating a histogram for a sensitivity simulation.
As Histogram Across
Off, if checked, simply presents values at a time or across time according to the At Time settings.

Time, if checked, causes a histogram of the data across time to be prepared. Histograms across time
are only prepared on a single variable even if the subscript selection would indicate more than one
variable to be displayed.
Subs , if checked, causes a histogram across subscripts at a given time to be displayed. This is not
compatible with the As time-graph selection. If more than one subscript range has multiple selections
the range will be over all possible combination of subscript values just as for the non-histogram bar
graph.
Sensitivity, if checked, causes a histogram across sensitivity runs at the specified time. Sensitivity
histograms can be used to compare the results of different sensitivity simulations.

Cumulative, if checked, causes a cumulative histogram to be displayed. A cumulative histogram


starts at 0 and increases monotonically to the total number of data points. It is the same as the area
under the regular histogram to the left of the current point.
? Hide Outliers, if checked and either Y-min or Y-max is filled in, will cause any values below the
specified minimum or above the specified maximum to be ignored. If hide outliers is not checked,
and an exceptional value is found, a < Minimum or >Maximum category will be added.
? Y-min is the minimum value used in computing the histogram. This number will determine the
horizontal scale on a vertical bar graph and the vertical scale on a horizontal bar graph.
? Y-max is the maximum value used in computing the histogram. This again determines the
horizontal scales on a vertical bar graph.
? #Bars determines how many bars will be displayed on the histogram. If you have specified a Y-

331
min or Y-max and not checked Hide Outliers, additional bars are added for the outliers.
? PDF Scaling, if checked, scales the histogram as a Probability Density Function so that the area
underneath the histogram is one. This can be very useful for comparing sensitivity simulations
where the number of sensitivity simulations made is different between the two simulation runs.
? Min, determines the minimum value that will be displayed on the vertical axis for vertical bar
graphs and the horizontal axis for horizontal bar graphs.
? Max, determines the maximum value that will be displayed on the vertical axis for vertical bar
graphs.
Orientation (Vertical or Horizontal) determines whether the bars are displayed vertically or
horizontally. Depending on the length of subscript names, this can influence the size of a bar graph
that can fit on the screen. The Bar Graph tool icon reflects your choice.
Fonts (Normal and Small), let you set the fonts that will be used for output. The normal font is used
if there is sufficient room, if not the small font is used.
Bar Graph Output

The Bar Graph tool creates a bar graph in a new window. The labels for the bars (below) are the
different subscript combinations. Multiple runs are displayed side by side so that they can be
compared easily. All bars have a common axis.

Histogram Output

When you have the histogram option specified you will see a histogram of values over the currently
selected time range.

332
Current
truncated normal noise - time histogram
200

150

100

50

0
0-1 3-4 6-7 9-10 12-13 15-16 18-19
1-2 4-5 7-8 10-11 13-14 16-17 19-20
2-3 5-6 8-9 11-12 14-15 17-18

Note that the Y axis in the histogram is data counts, while the X axis corresponds to the values of the
variable. The same graph displayed with PDF Scaling would appear as:
Current
truncated normal noise - time histogram
0.2

0.15

0.1

0.05

0
0-1 3-4 6-7 9-10 12-13 15-16 18-19
1-2 4-5 7-8 10-11 13-14 16-17 19-20
2-3 5-6 8-9 11-12 14-15 17-18

Bar Graphs as Graphs

If the number of variables that would appear on a Bar Graph is too big to fit on a single screen, the bar
graph will be displayed using the Graph tool. If, for example, you had a project with 100 phases and
you asked to see the cost of each phase, this might happen. If it does, the graph will be a dots-only
graph (no lines connecting the dots). The X-axis for the graph in this example would be the different
phase names.

333
If the X-axis for a graph is a single Subscript Range (as it is in this example), you can reselect
Subscripts by Shift-clicking on the graph. For example, if you found something of interest between
PHASE19 and PHASE37, you could Shift-click on the graph and select that region. If you then
invoked the Bar Graph tool again, you would see a blow-up of that region. Eventually this blow-up
will be a regular Bar Graph which shows you exactly what is going on for each individual phase.

Gantt Chart†

The Gantt Chart tool — designed to work primarily with project models — produces Gantt
charts automatically from data and simulation results. A Gantt chart measures the Start Date and End
Date of various tasks along a horizontal axis.
You can use the Gantt chart with any variable in a model, but the most common use is with project
models and a variable with a name like:
task is active[task] = IF THEN ELSE(
task is started[task] :AND:
:NOT: task is finished[task],1,0) ~~|
To see a Gantt Chart, use the Subscript Selection dialog to select all elements of task, select the
variables task is active[task] into the Workbench, and activate the Gantt Chart tool.
Gantt Chart Options
The Gantt Chart tool has options for sorting tasks and showing lapses in task activity.

334
Display Sequence (Sort by Start Date or Sort by End Date or Default Order (no sorting)) specifies
how the bars should be ordered.
? Sort by Start Date specifies that the task that began the earliest is displayed first, the second
earliest second, and so on. The earliest Start Date for a task is the earliest Start Date for that task
over all datasets. The resulting bars look like an inverted staircase on the left, but might be
different on the right. (The appearance of sorted Gantt charts when there are multiple runs is not
always what you would expect. One run (say out of 4) with outlying task start times can totally
change the order.)
? Sort by End Date specifies that the task that ended first is shown first, the task that ended next is
shown second, and so on. The End Dates for comparison are the latest dates over all runs. The
resulting bars look like a staircase on the right, but might have a different appearance on the left.
? Default Order (no sorting) specifies that the bars are reported in the same order as the tasks are
defined (on the right side of a Subscript Range equation). This order is often the same as Sort by
Start Date, depending on model-building conventions and interruptions in the project being
modeled.
Threshold determines when the Gantt Chart should display a bar. Gantt Charts display a variable as
on or off. The threshold allows you to redefine on and off to have a meaning appropriate to your
needs. By default, the threshold is zero, which works fine with a variable such as task is active
which is zero when the task is not active and one when it is. But if you want to see graphically when a
variable is above a certain value (such as when Population exceeds 200 million), you can set the
threshold to this value.
In Gaps (var < threshold) (Span the Gaps (solid) , Show the Gaps (broken)) determines how task
interruptions are displayed. A task interruption occurs when a variable that has been, and will again
be, above the threshold goes below the threshold (var < threshold). For project models, premature
victory is often declared and tasks that were thought to be completed are restarted. When this happens,
showing the task as always active can be misleading.
? Span the Gaps (solid) shows a solid bar from the first to the last time the variable was above the
threshold.
? Show the Gaps (broken) shows a series of bars for all periods during which the variable was
above its threshold.
Font allows you to set the output font for the Gantt Chart.
Gantt Chart Output

335
Each invocation of the Gantt Chart tool creates a separate output window. The X-axis in the Gantt
chart is a time axis. You can select the Start Date and End Date by Shift -dragging on the axis.
Separate runs are shown with differently colored bars.

Runs Compare

The Runs Compare tool compares the values of variables between the first and second loaded
datasets. The Runs Compare tool will only work if both datasets are the output of simulation runs. If
the values of variables are different, or if variables in one run are missing from the other run, this is
reported.
The Runs Compare tool is most useful when the runs are from the same, or very similar models. The
order in which the runs are loaded can influence the order in which differences are reported, but will
not change the content.
Runs Compare Options

The Run Compare tool lets you select which type of variables you would like to compare, and the
threshold of difference that is required before any differences are reported.

Show Differences for Type allows you to select the different types of variables to show differences
for. Note that Gaming is actually a subset of Auxiliary. It is included as a separate category for
comparison of Gaming simulations.

336
Thresholds before differences are displayed lets you specify these thresholds. The difference must
exceed the value for Relative times the original value and also exceed the value for Absolute before
the difference is reported. By default both of these are set to zero so that any difference is displayed.
Run Compare Output

If another runs comparison window is open when the Runs Compare tool is invoked, the old
comparison is deleted. The Runs Compare tool either creates a text window describing the differences,
or reports that no differences were found.

NOTE The Runs Compare tool first tests the first loaded run against the second and reports
differences by type in alphabetical order. After doing this, it checks to see if the second loaded run has
any variables of the selected type that are not in the first run, or are of a different type in the first run.
Thus after getting a number of messages about differences between the first and second run, you might
also get some messages about the second and first run that are out of alphabetical order.

Miscellaneous Tools
The Miscellaneous tools are essentially shortcuts. The are not available in Vensim PLE or PLE Plus.

Units Check

The Units Check tool simply provides a short cut for performing units checking on a model.
Clicking on it is the same as the command Model>Units Check. See Chapter 3 for details. There are
no options for the Units check tool.

Equation Editor

The Equation Editor tool is used to start the Equation Editor on the current Workbench Variable.
This will only work if you are using the Sketch Editor to work on the model. This is a convenient
shortcut for getting to the equation for a variable. See Chapter 6 for discussion of the Equation Editor.

Text Editor†

The Text Editor tool is used to start the Text Editor. When you activate the tool, you will be queried
for a file to edit. You can set the default file type that will be shown. See Chapter 7 for discussion of
the Text Editor and the available options.

337
Venapp Editor‡

The Venapp Editor is actually a special configuration of the Text Edit tool that opens the
Sketch Editor in a special mode. When you click on this tool you will be asked for the name of a
Venapp. See Chapter 3 of the Vensim DSS Reference Supplement for details on Editing Venapps.

Reality Check

The Reality Check tool simulates the model in order to test the Reality Check that is currently
selected into the Workbench. If you do not have a Reality Check selected into the workbench, you will
receive an error message.
The run name used will be that shown in the top toolbar — you will not be asked if you want to
overwrite this run even if it exists. This analysis tool is equivalent to choosing one Reality Check in
the Reality Check Control dialog (see Chapter 9 of the Modeling Guide) and pressing the button
Highlighted to run that check.

338
15 Custom Graphs, Tables and Reports

Vensim Analysis tools provide fast, flexible ways to find information about a model and its
simulations. Custom output allows you more control over the appearance of graphs. The Graph tab of
the Control Panel allows you to manage Custom Graphs as described in Chapter 11. For most
purposes you will probably want to work just with the graphs attached to the model and this can be
done using the Custom Graph Editor described in this chapter. You can also customize the output of
the Table tool and Bar Graph tool and create custom reports, though this can only be done with
separate graph description files.
This chapter:
? Describes how to use the Custom Graph Editor.
? Describes the Custom Table Editor.
? Discusses xy graphs.
? Describes the structure of .vgd files.
? Explains how to customize the Graph tool.
? Explains how to customize the Bar Graph tool.
? Explains how to customize the Table tool
? Explains how to write custom reports

Overview
Customized Graphs allow you to display more than one variable, with more than one scale, on a single
graph. Customized Tables allows you to select the variables that will appear on a table. Customized
Bar Graphs allow you to display values for multiple variables on a single bar graph. Reports allow you
to compile a number of output values for display inside of text. You also have more control over
labeling when using Customized tools.
There are two ways to create customized output. The first, and simplest, is to use the Custom Graph
Editor or Customer Table Editor.. These are interactive dialogs that makes it very easy to set up a
custom graph or table. These editors are fast and easy to use, but only works for custom graphs and
tables. In addition, there are some Custom Graph options that cannot be accessed from it.
The other way to create customized output formats is to write a description of the output you want in a
Vensim Graph Description (.vgd) file. A .vgd file is a text file containing keywords and values that
describe what is to be displayed in a graph or table and specify how to label it. The Custom Graph
Editor stores the graphs you create in .vgd format described in this chapter. By default this information
is contained in the model file but is can also be saved as a .vgd file (see Chapter 11). You can move
back and forth between editing the text file form and using the Custom Graph Editor. However, care
must be taken not to modify a graph definition file directly and use the Custom Graph Editor at the
same time.

The Custom Graph Editor

The Custom Graph Editor is a dialog that allows you to enter and modify Custom Graph descriptions.
It is invoked from the Graph tab of the Control Panel as discussed in Chapter 12, or from a graph tool
configured to define a custom graph on Invocation (See Chapter 14).

339
The top line states the name given to this graph as it appears in the Graph tab of the Control Panel.
The default naming scheme is to use the beginning of the title of the graph or, if that is blank,
GRAPH_0, GRAPH_1 and so on, but you can type in another name. If you do type in a name the
name will be checked to be sure it is not the same as an existing graph name. If it is you will be given
a message and asked to pick a new name. Graphs are invoked by name, and the name must be unique.
Hide allows you to hide elements of the graph to reduce clutter and increase the amount of the graph
devoted to displaying out.
? Title, if checked suppresses the title that appears above the graph proper.
? X Label, if checked, suppresses the label on the X-axis .
? Legend, if checked, suppresses the legend. If there are a large number of runs or variables to be
graphed the legend can get very large and make the area available for the actual graph
unreasonably small.
Title is the title that will appear above the graph if it is not suppressed. Type in any title you want, or
leave this blank (a blank title is not automatically suppressed).
X-Axis specifies the variable to be used on the X-axis . If this is left blank the currently selected Time
Base (usually Time) will be used. To get X-Y plots enter a variable that is not a time base. You can
use the Sel button to the right to get the Variable Selection dialog and choose from a list.
X-Label sets the label that will be used on the X-axis . Normally this is just the name of the X-Axis
variable. You can, however, type in anything you want.
X-min specifies the minimum value the X-axis takes on. If left empty, Vensim uses the value
specified in the Time Axis control, possibly rounded down. Values of a variable you enter here will be
used as entered without rounding.
X-max specifies the maximum value on the X-axis . If left empty Vensim uses the value specified in
the Time Axis control, possibly rounded up. This value will be used as entered without rounding.
X-divisions lets you set the number of divisions made along the X-axis (there will be one less vertical
line than there are X-divisions). If this is left blank a number of X-divisions that allows the selection

340
of round numbers as the X labels will be chosen. If this is set to -1 the number of divisions specified in
the Scaling tab of the Control Panel will be used.
Lbl-Intervals, if checked, causes the X-axis labels to be placed on the intervals between vertical lines
instead of on the lines. This is useful for annual data, where the interval represents events during a
year.
Y-divisions lets you set the number of divisions along the vertical axis. If this is left blank the value of
Y-divisions in the Scaling control will be used.
Stamp specifies the stamp that will be printed in the lower right corner of the graph when it is printed.
This does not influence the appearance of the graph on the screen.

Comment specifies the comment that will be printed below the graph when it is printed. This does not
influence the appearance of the graph on the screen.
Norm, Cum, Stack determines the type of graph that will be displayed. Cumulative graphs (Cum)
show the integration of the output values instead of the output values themselves. Stack graph show
the first variable, then the first plus the second and so on. Note that only variables with the same scale
are stacked, so you will need to click on the same scale checkbox between the variables you want
stacked.
NOTE If you have selected a Stack graph the bottom of the dialog changes to

fill in Stack first with the number of variables you would like stacked. Additional variables will be
graphed normally. If this is left blank all variables will be stacked.
Dots, if checked, causes the graph to be displayed using a series of Dots instead of connected line
segments.
Fill, if checked, will cause the area between stack graph lines to be filled in solidly instead of being left
blank. This makes it clearer which elements of a stack graph are contributing. This option is only
available for Stack graphs.
Width specifies the width in inches or centimeters (as set in the Options Settings dialog) the graph will
appear when first displayed. You can, of course, always resize the graph.
Height specifies the height the graph will appear when first displayed.

Variable Entry
The next six lines let you enter the variable you want to have displayed.

Scale, if checked, indicates that the variables above and below it will be put on the same scale. To put
more than two variables on a scale click the box between the first and the second then the box between
the second and the third and so on. The Units, Y-min and Y-max (if any) specified for any member of
the group will be used. If more than one members has them specified the last will be used.
Variable is the name of the variable to be displayed. The variable need not appear in the current
model, but it will not be displayed unless it is contained in the dataset to be used.

341
Dataset specifies the source for the graphed data. If left blank Vensim will use the first loaded dataset.
You can specify a file name (such as base.vdf) with a directory if desired or use *n to refer to the n'th
loaded dataset. Leaving dataset blank and using *1 are equivalent.
Label specifies the label to be attached to the variable. If left blank the variable name, followed by the
run name (as in population - current) is used.

Line Width specifies the width of the line with which to show the graph. Normally all graph lines are
of equal width, but different color, although this is controllable as an option. If you specify the options
to show use thick lines for the Graph tool, (see Chapter 16) they will also be used for custom graphs
unless Line Width is given a non-zero value. You can specify a negative number to get a patterned
line (-1 DOT, -2 DASH, -3 DASHDOT, -4 DASHDOTDOT).
Units specifies the label to be used on the Y axis for the units of measure of the variable being plotted.
If left blank the workbench model will be searched for the named variable and the units of measure
specified there used.
Y-min specifies the minimum value that will be used on the Y-axis. If left blank Vensim will pick a
reasonable value. For work in progress graphs Y-min will default to 0.
Y-max specifies the maximum value that will be used on the Y-axis. If left blank Vensim will pick a
reasonable value. For work in progress graphs Y-max will default to 100.

Graph Control

As WIP Graph, if checked, causes the graph you are defining to be displayed automatically each time
a simulation is begun. Such graphs are called work in progress graphs (WIP), and the display the
output point by pointas the simulation progresses. You can define any number of graphs to be
displayed during simulation though more than a few is rarely useful. If there is no Y axis scale
specified WIP graphs will use a Y scale from 0 to 100 is assumed.
Maxpoints specifies the maximum number of points that will be used in the simulation. If left blank
the default value of 100 is used. If you are making a simulation with many saved values you will need
to increase this.
Copy to lets you copy the graph definition you are currently working on to a new name. This leaves
the graph definition you started with intact, but also saves the changes you have made. You can
accomplish the same thing using the Copy button in the Custom Graph control dialog.
Test Output allows you to see the output of the graph you are working on. The graph will come up in
place for review. You can print or export this graph, but pressing any key will cause it to disappear.
Soft Bounds , if checked, will cause the graph to adjust Y scales if the variables to be plotted exceed
them. This only has an effect when you have specified Y-min or Y-max. If, when building the graph
the specified scales are insufficient the scales will be adjusted. If this is used with a work in progress
graph the graph will be rescaled and completely redrawn.
As Table... will open the Custom Table Editor. The names and datasets for variables, if any, will be
included in the initial Custom Table definition. No other information will be used.

Displaying a Named Graph


You activate customized output from the Graph tab of the Control Panel. Click on the Control Panel
button in the Main Toolbar or select the Windows>Control Panel menu item. This control displays a
list of the named graphs. Select one, click on the Display button and the selected graph will appear on
the screen. Errors occurring while creating output, if any, can be reviewed in the Vensim Error Log
window, which can be made visible using the Windows>Error History command.

342
The Control Panel is discussed further in Chapter 12.

XY Graphs

You can use the Graph tool to create XY plots by specifying something other than a time base as the x-
axis. The rules for this are exactly the same as those for the normal graph, but you will not necessarily
get a sensibly connected line. Typically, an XY plot uses the Dots option to create a scatter plot.

Example

Workforce Versus Inventory (xy)


400

200
100 102 104 106 108 110 112 114 116 118 120
workforce

inventory : step widget

Can be created using the definition:

343
For this particular problem using Dots Only was not completely necessary. In, fact it is fun to look at
this graph with completed lines:

Workforce Versus Inventory (xy)


400

200
100 105.8 111.5 117.3 123
workforce
inventory : step widget
inventory : step2 widget

Multiple XY plots can be superimposed on one another. You can draw multiple variables relative to a
given variable in a dataset, or the value of each x,y pair can be drawn from a different dataset as shown
above.

Getting Values for Variables

It is possible to get model values to be used in the titles and labels of the Custom Graphs, Custom
Tables and Custom Reports. For example in the above XY plot we might have replaced the old title
"Workforce Versus Inventory (xy)" with
Workforce/Inventory with Inventory Correction @
\Time Correct Inventory&*1/ and \Time Correct Inventory&*2/
resulting in the plot:

344
Workforce/Inventory with Inventory Correction @ 4 and 2
400

200
100 105.8 111.5 117.3 123
workforce
inventory : step widget
inventory : step2 widget

The ability to display variable values in graphs is most powerful in Venapps because you can display
String variables replacing them with names that a Venapp user may have typed in.
To display a variable value surround the name of the variable a backslash \ followed by a forward slash
/ what is between the slashes will be interpreted as a variable. Included in the \/ can be specifiers for
the dataset, Time at which the value will be chosen, formatting for the variable and even substitute
strings for the variable. You control what is displayed by using a special character to separate the
specifiers. The & in the above example precedes the run name (the wildcards *1 and *2). A variable
name can be followed by the following specifiers:

& runname
Names the dataset to find the variable in. You can name a run explicitly, or use *1, *2 ... to name the
first loaded run, second loaded run and so on. If this is left blank the first loaded dataset will be used.

# time base
Specifies the time base used to find the value for the variable. If this is not specified the currently
selected Time Base (normally Time) will be used.

@ time
Specifies the time at which the number will be reported. This time should be measured in the Time
Base chosen. If no time is specified the value at the currently set Special Time as shown in the Time
Axis control will be used.

%format
Specifies the format in which the string will be written. The format specification follows standard C
language practice. Numbers are always reported using floating point. Typical options might be
%.0f - show 0 decimal places (no decimal .)
%.4f - show 4 decimal places
%8.3g - use eight spaces showing 3 significant digits
If no format is specified Vensim's standard pretty number format will be used.

?value=label
The value relabeling option lest you put out special numbers as special strings. For example if you
have a variable that is on or off you might use
\financial restraint switch?0=Low?1=High/
You do not need to use any of the controls. Just the variable name displays the variable in the first
loaded run at special time and displayed as a Vensim formatted number or, in the case of String
Variables, as a string without the surrounding single quotes. For example using the labeling:

345
Would result in the legend markings:

Where
pname[p1] :IS: 'Super Sudser' ~~|
pname[p2] :IS: 'Brass Polish' ~~|
Note that the name displayed is that from the simulation run, not from the model.
NOTE If Vensim cannot find the variable you have named it will put out two dashes --.

Displaying the Dataset Name


In addition to putting variable names in \/ you can also get the name of the dataset to be displayed. To
do this just use \DATASET/ instead of a variable name. For example \DATASET&*1/ would show
the name of the first loaded dataset. If you have a variable in your model called DATASET this will
not work.

The Custom Table Editor


The Custom Table Editor allows you to create tables of values. You open it by Clicking on the As
Table... button in the Custom Graph Editor.

The Table Name , Output width, height and Title fields have the same meaning as with the Custom
Graph Editor.
Table Content is a list of what is to be included in the table. You can include as many variables as
you want in a table and you can also intersperse these with comment lines for spacing or heading

346
purposes. The content will show up in the list as a series of strings separated by vertical bars |. This is
just a convenient way of splitting up the Variable, Dataset, Label and Format information described
below. To change the order in which variables or comments are displayed just drag them to a new
position.
To Modify an entry in the list click on it and then click on Modify. To delete an entry from the list
click on it and then click on Remove . Double clicking on an entry is the same as clicking on it and
then clicking on Modify. When you modify a list element it will move from the list to either the
Variable or Comment line as described below.

Variable Entry

To display a variable you enter the variable name, this can be done by typing in the name or by
clicking on the Variable button and selecting a variable.
Dataset is the name of the dataset from which to draw the variable, use *1, *2 and so on for access to
loaded dataset or leave this blank to get data from the first loaded dataset.
Label is the label that will be used in the first column (row if time is running down). If this is left
blank the name of the variable will be used for the label.

Format allows you to determine how the number will appear. Format will be used as a prefix and can
contain C language formatting string beginning with a %. Some most common formats would be $ to
add a $, %g for scientific notation, and %.0f to show only a whole number (rounded from the
underlying number). You can also use %.6g to get 6 digits in scientific notation (the number following
the . is the number of significant digits) or %5.2f to get numbers that look like 123.45. Note if you
want to see a % sign you need to double it as in %.0f%% to show percentages in whole numbers.
Add adds the content (which must include a variable name) into the list. Once it is in the list you can
move it by dragging it to a different position.

Comment Entry

A comment is simply some text that can be used to label a series of rows or columns. You can enter a
space as a comment to get spacing in the table. Just type in the comment and then click on Add to put
it in the list. Once it is in the list you can move it by dragging it to a different position.

Time Range
From determines the first time to be displayed (the global Start Time is used if this is blank).
to determines the last time to be displayed (the global End Time is used if this is blank).

by determines the frequency with which numbers are displayed (SAVEPER from the first run is used if
this is blank)
(+) determines the additional terminal time value to be displayed (the global Special Time is used if
this is blank). The (+) time will only be displayed if it is different from the to time.
If you leave the time range fields blank the table will display values based on the settings on the Time
Axis tab of the control panel.
Running Down, if checked, will have time run down and the variables run across. If it is not checked
time will run across the top.

347
Don't Display, if checked, will suppress the first Row/Column showing Time. If you check this the
first variable that is displayed will replace time. This makes it simple to use another time base to
display the data.
Cell Width determines the width of columns in characters. You can specify a different value for the
first column and the remaining columns.
Scientific Notation, if checked, will cause values to be displayed using scientific notation instead of
Vensim's pretty number format. Note that if you specify the format for an individual variable this
setting is not used for that variable.
Font specifies the font to be used when displaying output. Click on this button and select a font from
the Font Selection Dialog.

Custom Graph Definition Files†


The Custom Graph and Table Editors will allow you to create and modify Custom Graphs. In order to
work with Reports and Bar Graphs, however, you will need to work directly with Vensim Graph
Definition (.vgd) files. After you have created a .vgd file you can still use the Custom Graph Editor to
modify and add Custom Graphs. If you try to edit a Custom Graph that uses functions not supported in
the Custom Graph editor you will receive a message about incompatibilities; if you proceed some of
the previous definition will be lost. You cannot modify Custom Reports, Tables or Bar Graphs.
If you open a .vgd file in the Text Editor the File menu item will contain the command Load Custom.
This will load the graph definition file and bring the Control Panel forward with the Graph Tab active.
This a quick way to develop and test custom tool output. Chapter 7 discusses the Text Editor in more
detail.

File Format
Although the .vgd file commands for each tool can contain different information, there are common
elements and rules governing the use of keywords, labels, references to runs, and variables in all .vgd
files. A sample .vgd file might contain:
:GRAPH Test Graph one
:VAR V1|Volume
:DATASET *2
:GRAPH Test Graph 2
:Var myvar[ott]
:DATASET exper1
Two graphs are defined. The following concepts help structure these graph definitions.

Keywords (such as ":GRAPH") are used to describe output. All keywords must begin with a colon :.
The keyword can begin anywhere on a line, but must be the first element on the line. The keyword
must be separated from the rest of the line by a space or an equal sign =.
Labels (such as " Volume") are strings that will appear in the output exactly as entered in the .vgd
file. Labels appear after a vertical bar | and continue to the first comma , or until the end of the line .
Quotes, more vertical bars, and everything else except commas , are included directly inthe label
without alteration. Labels cannot include new lines or commas.
Nesting is shown with indentation but interpreted solely by context. Graph and table descriptions are
often hierarchical. In the documentation, this hierarchy is indicated with indentation, but Vensim itself
does not pay attention to indentation. Vensim keeps track of hierarchy bykeywords and acts
accordingly. For example, the beginning of a graph or table description, as occurs with the second
":GRAPH" above, always ends the current graph or table description.

348
Datasets (such as " exper1") can be accessed whether or not they are loaded. When you refer to a
dataset in a description, Vensimsearchesthe disk to find the dataset. If the dataset is not already loaded
in Vensim, it will be loaded while the output is produced and then unloaded. If the dataset does not
exist, an error message is displayed.
Wildcard datasets (such as "*1") can be used to refer to one of the currently loaded datasets. Instead
of explicitly naming a dataset, you may use an asterisk * and a number from 1 to 9 to denote the
corresponding dataset in the Dataset Control dialog. For example, "baserun" would use values from
the file baserun.vdf, whereas *2 would use the second loaded dataset. If you omit references to a
dataset, Vensim uses the first loaded dataset.

Wildcard variables (such as " myvar[ott]") can be used to access different instances of subscripted
variables. A subscripted variablecan represent more than a single value. If you enter a variable name
with no subscripts and that variable is subscripted, Vensim searches the associated Subscript Selection
dialog and uses the first entry determined from these. If you explicitly include Subscript Ranges in the
variable name, Vensim will refer to the subscript selection list and use all entries determined from
these. For example, if ott is a Subscript Range having elements ONE,TWO,THREE, with TWO and
THREE selected, then myvar is the same as myvar[TWO], and myvar[ott] yields
myvar[TWO] and myvar[THREE].
Long lines can be continued with a backslash \ followed immediately by a new line.
NOTE .vgd files are not case sensitive.

Common Keywords
Every type of custom output can use the following keywords.

:TITLE title specifies the title to appear at the top of the window. If title is left blank the name of the
graph, table or report will be used.
:LOCATION x,y specifies the location to place the output on the screen This is measured in pixels
and is automatically generated by the Record Coord button in the Graph tab of the Control panel,
though it can be entered directly.
:SIZE width,height specifies the initial size of the output window in pixels. This value is generated
automatically by the Record Coord button in the Graph tab of the Control panel and can also be
entered directly. If a separate specification is made for :WIDTH and :HEIGHT :SIZE will override
this.
:NO-LEGEND n suppresses the legend in a graph (Graph or Bar-Graph). If n is 0 then the legends
are shown normally. If n is 1 then the legend is suppressed, 2 the title is suppressed and 4 the x-axis
labels suppressed. You can also add the numbers to suppress more than 1 thing so that 7 would
suppress all three items.

Custom Graphs

The Graph tool displays a number of variables from a number of runs in a single graph. You can
customize the Graph tool to specify which variables to use from which run and to assign titles. In
addition, you can control the appearance and format of the printed output.
To begin a graph description, use the :GRAPH keyword. Although all keywords are optional, you
must include at least one :VAR in the graph description.

349
Graph Tool Keywords
The Graph tool has a three-level hierarchy: graph labeling and control, scale grouping, and descriptors
for the individual variables to be included in the graph. For each hierarchical level the order, after the
keyword beginning the hierarchy (:GRAPH, :SCALE and :VAR respectively), is unimportant and
keywords are shown alphabetically below.
Scales can be specified with the :SCALE keyword or by separating the names of variables with
commas , using the :VAR keyword. Both of these work the same way. The :SCALE keyword is
more flexible but also more cumbersome. Use the one most convenient for you.

NOTE A complete Custom Graph definition requires one :GRAPH and one :VAR line.

Graph Labeling and Control


:GRAPH name begins the description of a graph. The name appears in the Custom Output Selection
dialog as an identifier for the graph.
:CUMULATIVE plots the cumulative (integrated) value of the graph variable.

:DOTS does not interpolate between points when drawing the graph lines. This option is handy for
creating scatter plot of noisy data where connecting the dots would make the graph hard to read. It is
also useful for looking at Data variable to see exactly where they fall.
:GRAPH-STYLE n determines the type of graph. Use 0 for a quick graph, 1 for a normal graph, 2 for
a 3d line graph, 3 for a ribbon graph and 4 for an area graph.
:HEIGHT value specifies the height of the graph (including all labels). The value for height is in
inches or centimeters depending on what you have set in the Global Options dialog.
:LABEL-LINES specifies x-axis labels centered on vertical grid lines. This is the default.

:LABEL-INTERVALS specifies x-axis labels centered between the vertical grid lines. A plot on a
scale presented in calendar years usually looks best if it is graphed with the labels placed between
vertical lines; other plots make sense only if the grid lines are marked.

:LANDSCAPE specifies horizontal printed orientation. This does not affect the appearance of the
graph on the screen. This option will only take effect if orientation is set to Best Choice in the Print
Options dialog.
:MAX-POINTS n specifies the maximum number of points to be used in a work in progress graph.
This value default to 100 and should be set larger if you are making simulations in which (FINAL
TIME-INITIAL TIME)/SAVEPER is bigger than 100.

:NO-LEGEND n suppresses the legend at the bottom of the graph, the title of the graph and labels.
Use 1 to suppress the legend, 2 to suppress the title and 4 to suppress the x-axis labels. Adding these up
will suppress more than one thing (for example 3 suppressed the legend and title). This is useful if it is
obvious from the graph lines what they are, or if you want to add a legend in a different format after
exporting the graph.
:PORTRAIT specifies vertical printed orientation. This does not affect the appearance of the graph
on the screen. This option will only take effect if orientation is set to Best Choice in the Print Options
dialog.
:STACK N plots the graph variables as a stackup, that is, VAR_1, VAR_1 + VAR_2, VAR_1 +
VAR_2 + VAR_3, and so on. Only variables grouped under a single :SCALE will be stacked. If N
is specified and nonzero only the first N variables will be stacked – additional variables will be
graphed normally.
:STACK-FILL like stack except that the area between the graph lines is filled with the graph line
color. Generally useful with only a single :SCALE.

350
:STAMP text|ident defines a stamp that appears on a printed version of the graph such as
CONFIDENTIAL. text appears in a large font that overwrites the lower right part of the graph. A
vertical bar | separates the text from identifier. identifier appears in the lower left -hand corner of the
printed graph. Neither the stamp nor the identifier appear on the screen.
:TITLE text gives the title of the graph. This appears centered over the top of the graph. If no title is
specified, the graph name is used.
:WIDTH value specifies the width of the graph (including labels). The value for width is in inches
or centimeters depending on what you have set in the Global Options dialog.
:WIP marks the graph as a work in progress graphs. Work in progress graphs are displayed
automatically during a simulation. Work in progress graphs are not scaled automatically so it is
usually necessary to specify the minimum and maximum values for all the axis. You can have up to 10
work in progress graphs defined.
:X-AXIS name gives the name of the graph's independent variable. If :X-AXIS is not specified, the
Time Base currently selected in the Time Axis Control dialog is used. The y-axis names depend on
which variables are selected for graphing.
:X-DIV value or :XDIV ?value=label?value=label... specifies the number of horizontal graph
divisions. If :X-DIV is left set to 0 or not included, the number of divisions will be determined based
on the x-axis values in the graph. If you want the number of divisions as set in the Time Axis Control
dialog use :X-DIV -1. You can also use the :XDIV keyword to break up the x axis with qualitative
labels. Just follow :X-DIV with a series of values and labels and the x-axis will be broken up
according to the values and given to corresponding labels.
:X-LABEL text defines the label to be displayed on the x-axis. By default this is the name of the
graph's independent variable. The labeling on the y-axis is modified variable by variable using the
:VAR keyword.
:X-MAX value specifies the maximum value on the x-axis.
:X-MIN value specifies the minimum value on the x-axis.

:Y-DIV value specifies the number of vertical graph divisions. If you do not specify a value the
number set in the Scale Control dialog will be used.
:Y-LABEL ?value=label?value=label... specifies that the Y axis should be given special labels
according the values specified. The values should be increasing but need not be equally spaced. This
allows explicit entry of important value break points. All variables must share the same scale when
:Y-LABEL is used.
:Y-MAX value specifies the maximum value on the y-axis. This value is overridden whenever a
specific variable is given a value for :Y-MAX.

:Y-MIN value specifies the minimum value on the y-axis. This value is overridden whenever a
specific variable is given a value for :Y-MIN.

Scale Grouping
:SCALE groups variables to appear on a single vertical scale. If :SCALE is not specified, variables
appearing on separate lines will appear on separate scales. If conflicting :UNITS, :Y-MIN or :Y-
MAX values are specified for variables in a single scale, those from the last variable will be used.

Variables on the Graph


:VAR name1|label1,name2|label2, ... specifies one or more variables that will appear on the graph, on
the same scale. The labels are optional. If not specified, the variable's name will be combined with the
name or a dataset.

351
:CONFIDENCE %=color, %=color, ... specifies that the variable will be displayed as a percentile
graph if it is a saved variable from a sensitivity simulation. % is a number between 1 and 100 that
describes the percentile range. Color is a RGB color specification with the values separated by vertical
bars | as in 255|0|0 for pure red. You can specify as many ranges as you want or leave them blank to
get defaults. You can also include more than one confidence plot on a graph, though the results might
be confusing. If the dataset is not a sensitivity simulation or the variable was not saved nothing will be
displayed. This cannot be used with :SENS-LINES
:DATASET filename|label specifies the name of the dataset in which values for the variable will be
found. The label is optional and will be used only if there is no label for the variable. You can use
wildcards to specify datasets, as described in the "The Structure of .vgd Files" above. If no dataset is
named, the first loaded dataset will be used.
:LINE-COLOR r-g-b specifies the color for the graph line (or shapes). The color is specified as a
combination or red, green and blue components each of which must be between 0 and 255. If this is
blank the standard graph line colors (as set in the global options for Vensim) are used.
:LINE-STYLE style specifies the style for a line. The choices are DOT, DASH, DASHDOT and
DASHDOTDOT. Note that this can’t be mixed with a line width (styled lines must have width 1).
:LINE-WIDTH width specifies the width that the graph line will have. Normally graph lines have the
same width, but different colors. Can’t be mixed with line style.
:MEAN color specifies that the mean of the sensitivity simulation should be displayed as a line of the
specified color. This option will only have an effect if one of :SENS-LINES or :CONFIDENCE is
specified.
:SENS-LINES color specifies that the results from a sensitivity simulation should be displayed as line
traces. You can specify the color to show the traces with or leave it blank for black. This cannot be
used with :CONFIDENCE.
:SHAPE shape,size (for use with :DOTS only) lets you specify the shape that the dots will take
on. Acceptable shapes are SQUARE, SOLID-SQUARE, CIRCLE, SOLID-CIRCLE, CROSS, X,
DIAMOND, TRIANGLE, and UPTRIANGLE (upside down triangle). The size is in pixels and gets
properly translated on printing.
:RUN filename|label is a synonym for :DATASET.

:UNITS units defines the units label for the variable(s). If no units label is given, the Workbench
model will be searched to see if it can determine a units label. If not, nothing will be shown.
:Y-MIN value specifies the local minimum value for the y-axis.
:Y-MAX value specifies the local maximum value for the y-axis.

Example 1 - Multiple Variable Graph


:graph world base (#3)
:title Base run from the WORLD model.
:var Capital
:var Natural_Resources
:var quality_of_life
:var Population
:var Pollution
Results in the output:

352
Base run from the WORLD model.
10 B Capital units
1e+012 Resource units
2 Satisfaction units
6B People
40 B Pollution units

0 Capital units
0 Resource units
.4 Satisfaction units
0 People
0 Pollution units
1900 1930 1960 1990 2020 2050 2080
Time (Year)
Capital - base Capital units
Natural Resources - base Resource units
quality of life - base Satisfaction units
Population - base People
Pollution - base Pollution units

Example 2 - Dataset Control


:GRAPH SPEED
:TITLE Work Speed
:X-AXIS time
:X-LABEL Month
:X-MIN 0
:X-MAX 100
:Y-MIN 0
:Y-MAX 1.0
:VAR wrk_speed[ASSY]
:DATASET simulation.vdf
:UNITS dimensionless
:VAR experience_effect[ASSY],fatigue_eff[ASSY]
:DATASET simulation.vdf
:UNITS dimensionless

Example 3 Scaling Control


:GRAPH LABOR
:TITLE Assembly Headcount
:X-MIN 1980
:X-MAX 1990
:Y-MIN 0
:Y-MAX 1000
:SCALE
:VAR direct_labor[ASSY]|Direct Labor
:RUN simulation.vdf
:VAR direct_labor[ASSY]|. . . . . . . . .actual
:DATASET actual.vdf
:UNITS people
:Y-MAX 10000
:SCALE
:VAR indirect_labor[ASSY]

353
:RUN simulation.vdf
:UNITS people
:Y-MAX 500
Note that variable-specific limits override the global :Y-MAX values on this graph.

Example 4 - Sensitivity Graphs


:GRAPH Sens1
:var net cash flow
:confidence 50=255|244|128,75=0|255|0,95=0|0|255,100=128|128|128

Example 5 - Qualitative Display


:GRAPH Qualitative
:TITLE Natural Resources over Time
:X-DIV ?1900=Early?1997=Now?2100=A century later
:X-LABEL During the Industrial Age
:Y-LABEL ?0=None?4E11=Not Much?1E12=Lots
:VAR Natural Resources
:NO-LEGEND

Natural Resources over Time


Lots
Not Much
None
Early Now A century later
During the Industrial Age

Custom Bar Graph†

The Bar Graph tool shows the values for a number of variables from a number of runs at a specific
time.

Bar Graph Tool Keywords


There is very little real hierarchy in the Bar Graph. However, it is convenient to think of variable and
dataset selection as different levels in the hierarchy. Except for the initial keyword (:BAR-GRAPH),
any :AS-RUN keys and :BAR-VAR-TIME, the order of keywords is unimportant.

NOTE A complete Custom Bar Graph definition requires one :BAR-GRAPH and one :VAR line.

Graph Labeling and Control


:BAR-GRAPH name begins the description of a bar graph. The name appears in the Graphs tab of
the Control Panel as an identifier for the graph.
:BAR-B Y-TIME - display the first variable as a bar graph over time. Additional variables will be
ignored.

:BAR-TIME value specifies the time at which the bar values are to be taken. This time is interpreted
in the context of the currently selected Time Base. If :BAR-TIME is not specified, Special time is
used.
:FORCE - prevents the display of a Bar Graph as a modified Graph when the number of bars grows
large. This is useful if you are trying to display a lot of things on a Bar Graph.

354
:HEIGHT value specifies the width of the bar graph (including labels). The value for width is in
inches or centimeters depending on what you have set in the Global Options dialog.
:HORIZONTAL makes the bars horizontal (the default is vertical).

:NO-LEGEND n suppresses the legend at the bottom of the graph, the title of the graph and labels.
Use 1 to suppress the legend, 2 to suppress the title and 4 to suppress the division labels. Adding these
up will suppress more than one thing (for example 3 suppresses the legend and title).
:OSUBTITLE text - defines a text string that will be displayed above the Bar Graph rectangle on the
left. This keyword is ignored unless the :HORIZONTAL keyword has been used and at least one
:OVAR keyword have been used specified.

:SOFT-BOUNDS - allows the Bar Graph to reset the scaling if the bounds are exceeded. This is
typically most useful in conjunction with the :WIP keyword.
:SUBTITLE text - defines a text string that will be displayed above the Bar Graph rectangle. This
keyword will be ignored unless the :HORIZONTAL keyword is also used.
:TITLE text defines the title of the bar graph. If not specified, the name of the bar graph will be used
as its title.
:WIDTH value specifies the width of the bar graph (including labels). The value for width is in
inches or centimeters depending on what you have set in the Global Options dialog.
:WIP - forces the bar graph to display itself during the simulation. This can be an effective animation
technique for larger models but the Bar Graph may change to quickly to prove interesting in smaller
models.
:X-LABEL text specifies the x-axis label.
:Y-MAX value defines the maximum value on the y-axis.
:Y-MIN value defines the minimum value on the y-axis.

Variables on the Bar Graph


:VAR var1|label1,var2|label2, ... supplies a list of variables to be included. It makes no difference
whether you place multiple variables on a single line or one variable per line. The labels are optional.
:OVAR var1|label1,var2|label2, ... supplies a list of variables to be included for display on the left
which is opposite to the display of a :VAR. This allows you to make two sided bar graphs which are
especially useful for comparing two things that differ along one dimension. The most common use for
this would be to create population pyramids as shown in the example. This keyword will be ignored
unless the :HORIZONTAL keyword is also used.

:BAR-VAR-TIME - display the variable at a time. This allows you to display different variables at
different times (or the same variable at different times). This applies only to the :VAR that directly
precedes it.

Datasets on the Bar Graph


:DATASET filename|label specifies the name of the dataset in which values for the variable will be
found. The label is optional. You can used wildcards in specifying datasets as described in the "The
Structure of .vgd Files" above. If no dataset is named, all of the loaded datasets will be used.
:RUN name|label is a synonym for dataset.

Example
:bar-graph Cost_bar
:title A Simple bar graph of cumulative cost
:horizontal

355
:var cum cost[design]|Design
:var cum cost[produce]|Production
:var cum cost[test]|Testing
:run basequal.vdf|Base Quality
:run highqual.vdf|Improved Quality Control

Base Quality
Improved Quality Control
A Simple bar graph of cumulative cost

Design

Production

Testing

0 50 M 100 M 150 M 200 M

Grouping Variables as Runs


Normally, Bar Graphs display each variable in a group with the same variable from different runs as
shown above. In some cases, however, it is desirable to group different variables together by a
subscript or another attribute.
:AS-RUN label indicates that the variables that follow are to be treated as if they were from a single
run – with label representing the name of that run. For example
:BAR-GRAPH WORK_DONE
:TITLE Work Done
:HORIZONTAL
:AS-RUN Task Definition
:VAR TASK DEFINITION[TASK1]|Task1
:VAR TASK DEFINITION[TASK2]|Task2
:VAR TASK DEFINITION[TASK3]|Task3
:VAR TASK DEFINITION[TASK4]|Task4
:AS-RUN Work Completed
:VAR Work Completed Correctly[TASK1]
:VAR Work Completed Correctly[TASK2]
:VAR Work Completed Correctly[TASK3]
:VAR Work Completed Correctly[TASK4]
:DATASET Base
would result in

356
Task Definition
Work Completed
Work Done

Task1

Task2

Task3

Task4

0 150,000 300,000 450,000 600,000

Note that you can combine multiple datasets with :AS-RUN though it is not recommended. In this case
the datasets will be grouped most closely together.
If you use :AS-RUN make sure that the same number of variables appear under each :AS-RUN group
and that the orders are consistent. Only the first set of variable labels will be used.

Population Pyramids
Custom bar graphs can be used to create and animate population pyramids. Consider a model that has
population by age and sex with 5 year cohorts. The Bar-Graph definition
:BAR-GRAPH POPPYR
:TITLE Population Pyramids
:SUBTITLE Female
:OSUBTITLE Male
:WIP
:FORCE
:HORIZONTAL
:Y-MIN 0
:Y-MAX 300
:VAR Population Group[FEMALE,age group]
:OVAR Population Group[MALE,age group]
:SOFT-BOUNDS
Will give the result:
Current
Population Pyramids

Male Female
ag 65
ag 60
ag 55
ag 50
ag 45
ag 40
ag 35
ag 30
ag 25
ag 20
ag 15
ag 10
ag 5
ag under
300 225 150 75 0 0 75 150 225 300

357
And this pyramid will be animated during a simulation. The model poppyr.mdl and the graph
definition file poppyr.vgd can be used to experiment with this.

Custom Tables†

Custom Tables allow you to display the values of variables as numbers at different times. They work
the same as the Table tool, except you have more control over appearance.

Custom Table Keywords


Custom Tables have a number of global keywords and there are two that are variable specific.

Label and Scaling Keywords


:TABLE tablename begins the definition of a custom table. tablename will appear in the Graphs tab
of the Control Panel.

:CELLWIDTH n defined the width of the cells after the first. This width is specified in characters
and should be made big enough so that the table entries do not overrun one another. The default value
is 10.
:COMLINE comline specifies a comment to appear on a line. If the comment contains tabs each of
the tabs will be placed over a column. The comment before the first tab will not scroll and the parts
after the first tab will scroll just as time values do when the user scrolls the table. Note that you can
use variable specification ( for example \Population/) in :COMLINE to get values. To enter leading
spaces start comline with a vertical bar |. The bar will not be displayed in the output table.
:FIRST-CELLWIDTH n defines the width of the first cell in the table. This width is specified in
characters and should be made big enough so that the table entries do not overrun one another. The
default value is 20.
:FONT face|size|attrib|color specifies the font to be used in displaying and printing the table. The
font has the standard Vensim font (for example Arial|12||0-0-0).
:NOTIME suppresses the reporting of Time at the top of the table. The first :VAR or :COMLINE
will replace the top line of the table and not scroll out of view.

:PRETTYNUM causes numbers to formatted using Vensim's pretty number formatting conventions.
If this is not specified numbers will be printed using scientific notation.
:PRINT-EVERY number - controls the frequency with which results are displayed. This allows you
to customize the amount of information being displayed.
:SPECIAL-TIME number - sets the special time for reporting values. The values at SPECIAL-
TIME are reported last in the table. If SPECIA L-TIME and X-MAX are the same no values are
reported at SPECIAL-TIME.
:TIME-DOWN causes time to run down instead of across.

:TITLE text defines the title of the table. If not specified, the name of the table will be used as its
title.
:X-MAX number sets the last time for reporting values.
:X-MIN number sets the first time for reporting values.

Variables on the Table


:VAR var|label specifies the variable to be reported and the label to be used in its reporting. The
numbers for the variable will be displayed. You can use Subscript Ranges in the variable name just as
for the graph tool. Note that if you use a label for a subscripted variable the label will simply repeat.

358
:DATASET dataset specifies the dataset to get the variables values from. This applies only to the
current :VAR.
:FORMAT format determines the format with which the current variable will be displayed in the
table. This can be a prefix for each number such as $ or a standard C language formatting string such
as %6.0f to display numbers as whole number. For example you could use %.0f%% for display
percentages as whole numbers (note the final % is doubled following C formatting conventions). This
applies only to the current :VAR.

Example
:table table1
:title Population overview
:prettynum
:comline Population runs from \population@1900/ to \population@2100/
:font Arial|10||0-0-0
:var population|How many
:var births
:var deaths
This results in:

Custom Reports†
Custom reports allow you to type in text intermixed with simulation results as a means of giving useful
text -based information.

Custom Report Tool Keywords


The custom report definition has only a few keywords. Normally the bulk of reports is simply typed in
text, and it is placed in the output as it is typed in. Custom reports must start with the :REPORT
keyword and end with the :END-OF-REPORT keyword.

NOTE A complete Custom Report definition requires a :REPORT line and an :END-OF-REPORT
line.
:REPORT name begins the definition of a custom report.

:FONT fontname specifies the font to be used in the report. The font name follows the standard
Vensim convention. You can insert the name of a font using the Edit>Insert>Font command in the
Text Editor. You can only have one font per report. If you have more than one :FONT line only the
last one will be used.

:NEWPAGE will cause a page break to be inserted in the report when it is printed. There will be a
blank line in the output showing on the screen. Nothing following the :NEWPAGE keyword on a line
will appear or be used.
:TITLE specifies the title for the report.

359
:VAR varname #timebase@time&dataset%format?val=label?val=label...|Label specifies the
name of a variable to report a value for in the report. The options following the name follow the
conventions described in "Getting Variable Values" above. The label is the text that will appear in the
report before the numbers, the variable name is used if no label is included.
:END-OF-REPORT marks the end of the report.

Text for Reports


Once you have entered the :REPORT keyword you can type in as many lines of text as you want. As
long as the text does not begin a line with one of the above keywords it will simply be repeated in the
output. Thus the report:
:REPORT FINANCIALS
Sorry, this report is not completed
:END-OF-REPORT
Would output the window:

Variables in Reports
Reports are intended to be a simple way to provide formatted numbers that can be printed or reviewed
in a convenient fashion. To accomplish this, there is a simple mechanism for placing data in reports.
If you surround text in the report with backslash \ followed by a forward slash / what is between the
slashes will be interpreted as a variable. The the lines
The annual sales of \sales/ were composed of
material sales of \material sales/ and finished product
sales of \finished sales/
Would allow you to view sales and its two components in a report. You can accomplish the same
things using the :VAR keyword with
The annual sales of \ / were composed of
:VAR SALES
material sales of \ / and finished product
:VAR MATERIAL SALES
sales of \/
:VAR FINISHED SALES
Which is equivalent to
:VAR SALES
:VAR MATERIAL SALES
:VAR FINISHED SALES
The annual sales of \ / were composed of
material sales of \ / and finished product
sales of \/
and to
The annual sales of \ / were composed of
material sales of \ / and finished product
sales of \/

360
:VAR SALES
:VAR MATERIAL SALES
:VAR FINISHED SALES
The most valuable use of the :VAR keyword is for the case in which the variable, with the
specification of its run, time base, time to be chosen and so on is quite long. To maintain some amount
of alignment in the report using \ / with an appropriate number of spaces in between (the spaces are
ignored when the output is created) can be helpful.
Note that if you use \/ and :VAR you can put the :VAR lines anywhere, but the number of them must
match the number of \/s you have entered. Also note that the order of the :VAR lines is the order in
which they will be used.
Whether it appears explicitly in \variable@1992/ or in a :VAR line, the variable name can be followed
by the various controls described in "Getting Variable Values" above.

Example
:REPORT Status Report
Status of the ecosystem in year \Time%g/ (experiment \DATASET/)

Population (organisms) \Population/


Crowding \Crowding/
Birth Rate (organisms/year) \births/
Death Rate (organisms/year) \deaths/
:END-OF-REPORT
Results in:

361
16 Menus and Common Dialogs

The Vensim menu structure has been designed to be as simple as possible in order to make it easy for
you to accomplish what you need to. This chapter:
? Describes all of Vensim's menu items.
? Discusses printing from Vensim.
? Reviews a number of dialogs that are used in different places in Vensim.
Many of the functions of Vensim, especially around building and analyzing models, are not directly
accessed from the menu.

Menu Commands

The following sections describe the commands on each menu. Note that the Edit, Layout (also named
Insert) and View menus for the Sketch Editor and Text Editor are discussed in their respective
Chapters 5 and 7 respectively.

File Menu

or in PLE and PLE Plus

New Model
New Model starts a new and emp ty model that contains only the mandatory simulation control
parameters. The Model Settings dialog (see Chapter 3) will appear. Select the time bounds and make
any other changes you want then click OK and an empty sketch will appear. The model will be
unnamed until you perform a Save or Save as.
? If you have modified the Workbench model and you have not set the option to load multiple
models you will be queried to see if you want to save your changes to the current model.

362
? If you have set the new model option in the Settings tab of the Options dialog (see Chapter 17),
New Model creates a model with the contents you have specified.
? If you have asked for new models to open in the Text Editor in the Advanced tab of the Global
Options dialog the Text Editor will open instead of the Sketch Editor.
Open Model
Open Model opens a text format (.mdl) or Binary format (.vmf) Vensim Model that is on disk and
puts it into the Workbench. When you ask to open a model you will see the File Selection dialog
described later in this chapter.
In addition to the standard model formats, you can choose to open Datasets (.vdf), Venapp Application
Definitions (.vcd or .vcf), and Vensim Command Files (.cmd).
? .vdf (Vensim Data Format) is a dataset generated from a simulation or data conversion. When
you open this as a model, blank equations are created for all the variables contained in the dataset.
This is useful for reviewing the contents of a dataset and for doing free-form data analysis. This is
also an alternative way to begin the construction of a model.
? .vcd‡ (Vensim Application Definition) is a file containing the commands and descriptions
defining a Vensim Application or Venapp. If you open this as a model the application will be
started. For more details see the Vensim DSS Reference Supplement. You can also open .vcf
files. These are the same as .vcd files except they are in binary format.
? .cmd ‡ (Vensim Command file) is a file containing a series of Vensim commands. If you open this
the commands will be executed in batch mode. See the Vensim DSS Reference Supplement for
details.

Close
Closes the current window. If the Sketch or Text Editor is active the model it contains will be closed.
You will be queried to save any changes. If a tool output window is active it will be closed unless it is
locked. If the Control Panel or Subscript Control is active it will be closed. Ctrl + W is the same as
File>Close.

Save
Saves the current model or file. This menu item is grayed unless the Sketch Editor or Text Editor is
active. Ctrl+S is the same as Save.

Save As/Save Settings


If the Sketch Editor or Text Editor is Active this will allow you to save the current to a different model
name or format. You can save models as either a text format model, a binary format model or a
version 1.62 text format model. The last of these will make the model readable by someone using an
older version of Vensim.

If the active window is a tool output window, Save As will let you save the contents of the window to
disk. This is discussed in more detail in Chapter 12. Ctrl+S is the same as Save As when an output
window is active.
If the Control Panel or Subscript Control is active it saves the current workbench settings (model,
workbench variable, subscripts and so on). Ctrl + S is the same as Save As when a control is active.

Load.../Lock/Unlock
The name of this Menu item depends on context.

Lock/Unlock will be displayed if a tool output window is active. This command toggles the lock
status of the output window.
Load is grayed when a control is active.

363
Load is grayed when you are working with the Sketch Editor or Text Editor on a model in normal
mode. However, in off-line mode Load will load the active model into the Workbench for analysis.
In the Venapp Editor Run Venapp is displayed.

In the Text Editor: Load Custom is active when you are editing a graph description file. Run Venapp
is displayed if you are working on a Vensim Application Definition. Run Commands is displayed if
you are working with a command file. Dat2VDF is displayed if you are working on a data file. See
Chapter 7 and the Vensim DSS Reference Supplement for more details.

Edit File†
This command is used to open a file (not a model) in the Text Editor. You can also invoke the Text
Editor from the toolbar and get the same results.

Print
Prints the contents of the currently active window. See "Printing" later in this chapter. Print is grayed
if a control is active. Ctrl + P is the same as File>Print.

Print Settings
Let you set up the printer. See "Printing" later in this chapter for more detail.

Exit
Exit closes Vensim.

If you have changed the Workbench model, the loaded toolsets, any files in the Text Edit tool, or any
sketches, Vensim asks if you want to save the changes. When Vensim exits, it records the current
settings and the positions of controls so that when you start Vensim again you can pick up where you
left off.

C:\temp\...
Vensim keeps a list of the four most recent models you have worked on. Selecting one of the models
in this list will open that model directly.

View/Edit/Layout Menus
For the most part, the use of these menu items is specified in the chapters on the Sketch and Text
Editors. The View and Layout menu items are grayed when any other windows are active.
When are working with a tool output window the Edit menu contains one active item Copy. This
command allows you to copy the contents of the tool output to the clipboard. See Chapter 13 for more
details.

Model Menu
PLE Plus PLE

364
Settings
Settings allows you to open the Model Settings dialog as discussed in Chapter 3. You can use this to
set values for FINAL TIME, INITIAL TIME, TIME STEP and SAVEPER, define units for Time,
setup units equivalences and mark such attributes as whether initial causes will be shown in sketches.

Check Model
Checks the current model. See Chapter 3 for details on doing this. Ctrl + T is the same as
Model>Check Model.

Units Check
Performs units checking on the model. See Chapter 3 for details. Ctrl + U is the same as Model>Units
Check.

Reform and Clean


Cleans up the model and allows you to reformat equations. See Chapter 3 for details.

Compare To…
Compare the current model to another model. A file selection dialog will open allowing you to select a
model to compare to the current model. Changes in variables and equations will be reported.

Simulate
In Vensim Standard, Professional and DSS the Simulate… command opens the Simulation Control
dialog to start a simulation. From this dialog you can choose what type of simulation to run. See
Chapters 8 and 10 for more details.
In Vensim PLE and PLE Plus there is no Simulation Control dialog so the types of simulations are
directly invoked. Simulate runs a normal simulation, Start SyntheSim enters SyntheSim mode, Run
Game starts a game, Sensitivity start a Sensitivity Simulation and Reality Check opens the Reality
Check dialog.
Stop Simulation exits SyntheSim or Simulation Setup mode. It is the same as clicking on the Stop
button on the Toolbar.

365
Partial Simulation (Not PLE or PLE Plus)

Partial Simulation allows you to simulate only the part of a model you have selected, the part that is
visible or to simulate the finished portions of a model that is not yet complete. These commands can
only be used when the model you are working with is on-line and in the Sketch tool. If you highlight
some of the variables in a view and select "Selected Variables" only those variables will be simulated.
All other variables will be held at their initial values. If you are working with an incomplete model
this will simulate the parts you have finished, and may require that you specify placeholder values.
See Chapter 8 for more details. "Visible Varaibles" is like Selected Variables except that what is
visible is simulated. Changing the hide level currently shown can thus alter the simulation results in
order to demonstrate the impact of different feedback loops.

Import Dataset
Import Dataset allows you to convert data into a form that can be used by Vensim. This command
will open a File Selection dialog and query you for the name of a dataset. See Chapter 9 for more
details.

from .dat format (Not PLE)


from .dat format allows you to convert data in the simple .dat format described in Chapter 9. This
command assumes data is in this format regardless of the extension on the file. It is convenient for
loading .err files output during optimization.

Export Dataset
Export Dataset allows you to convert a .vdf file to a format you can use elsewhere. When you use this
command you will be prompted for the dataset to convert, and then a dialog will open providing you
with options on export format. See Chapter 9 for more details.

Export Gaming (Not PLE or PLE Plus)


Export Gaming allows you to extract the gaming decisions from a simulation run into a text (.gin)
file. The format for this file is
:Time=0
gamevar1=1
gamevar2=2
:Time=5
gamevar2=0
:Time=20
The values of all gaming variables are recorded at the first time. Thereafter a value is reported only if it
has changed. The final time for the game is recorded in the last line. This file can be read using the
Load Decisions button on the Gaming Input Changes dialog of the Venapp command
GAME>READGVARS to replicate the game results.

366
Tools Menu

Analysis Toolset
Opens up a submenu for the Analysis Toolset. See Chapter 13 for more detail.

Sketch Toolset
Opens up a submenu for the Sketch Toolset. See Chapters 5 and 13 for more detail.

Options
Opens up the Global Options dialog. This is a tabbed dialog that lets you set a variety of options to
customize Vensim. See Chapter 17 for discussion of the Global Options Dialog.

Language
Opens up a dialog that lets you select a different language for the Vensim User Interface. If no other
languages are available you will receive a message indicating this. Select the language you want to use
then close and reopen Vensim for the new language to be used.

Convert Charset
Allows you to convert character sets on arbitrary text files. You should not use this command on
binary files, or files created by applications other than a text editor. This function is largely to allow
updating of supporting files such as sensitivity control files after converting the corresponding model.

Vensim PLE and PLE Plus have an Options menu instead of a Tools menu and it does not have either
of the Toolset submenus.

Windows Menu

367
Control Panel
Pops the Control Panel forward. The Control Panel is used to manage variable selection and other
activities and is discussed in Chapter 12.

Subscript Control†
Pops the Subscript Control forward. The Subscript Control is discussed in more detail in Chapter 12.

Molecules
Brings forward the Molecules add-in to Vensim. Molecules are building blocks for models that are
available as a, currently free, add-in to Vensim and other system dynamics software. For more
information check Chapter 10 of the Modeling Guide.

Pop Output Forward


This command will bring all tool output windows to the foreground. If a tool output window is
currently active, it will cycle to another output window.

Output Window List


Brings up a list of all output windows. They are listed by their titles which may not be unique. Select
the one you want and click OK to see it.

Close All Output


Closes all the tool output windows. Windows that have been locked will not be closed.

Error History
This will open a log of errors. When Vensim is started it creates and keeps a running log of errors and
messages in the file vensim.err which is normally kept in the Vensim directory. The Error History
makes these errors go to the screen as well. When you open it the errors in the log file will be
displayed and new errors and messages appear. The error log can be very helpful when you are having
trouble opening a model or dataset file.

Selection History
The selection history is a window that keeps a record of which variables have been selected into the
workbench. When it is opened it will be empty. As you select variables into the workbench they are
also added to this list. The list can be helpful when you want to keep track of what you have looked at.
Closing and reopening it will empty it.

Pop Build Forward


Will pop the Text Editor and Sketch Editor windows open. If a build window is active the next build
window will be shown.

Keep Build Behind


If not checked, will keep build windows behind all other types of windows. This can be useful if you
prefer to manage your tool output windows by keeping a small number open. This will prevent them
from getting pushed out of sight behind the build windows. When this menu item is checked it will
allow build windows to come to the foreground.

Close All Build


This will close all build windows. All models open in the Sketch Editor, and all Models and other
Files open in the Text Editor will be closed. If the files are changed you will be asked if you want to
save them.

368
Model: Random.mdl
Will move to the build window named. There may be a number of such windows. If too many build
windows are open there will be a More... menu item. Click on this to see a list of open build windows.

Help Menu

Vensim Manuals
Opens on-line help for the Vensim Manuals . All Vensim documentation is available online. This
menu item is not available on the Macintosh. To open the help documentation on the Macintosh you
will need to use a web browser. The complete documentation is also available from
http://www.vensim.com/documentation/vensim.htm.

Readme Notes
Opens on-line help information about recent changes and additions made to the software since the
documentation was written.

About Vensim
About Vensim displays the configuration of Vensim you are using, the current version number, your
serial number and copyright information. Click OK to close the dialog.

Main Toolbar

The Main Toolbar provides shortcuts to some of the commonly used menu items. is the same as
File>New, is the same as File>Open, is the same as File>Save (File>Save as for the tool
output windows and File>Save Settings for the Controls), is the same as File>Print, is the
same as Edit>Cut (only active for build windows), is the same as Edit>Copy (not active for
controls), is the same as Edit>Paste (only active for build windows, is the same as
Model>Simulate, is the same as Windows>Pop Build Forward, is the same as Windows>Pop
Output Forward, is the same as Windows>Control Panel and is the same as
Windows>Subscript Control.
The remaining icons deal with simulation and are discussed in Chapter 8.

Printing

When you ask to print from Vensim you will print the currently active window. Only build and tool
output windows can be printed so if the Control Panel or Subscript Control is active nothing will
happen when you ask to print.
For text output from the Text Editor and the Document, Loops, Outline, Run Compare, Stats, Table,
and Units Check tools (as well as a number of other utility windows), the information will be printed

369
as simple text with a header containing page numbers and, optionally, the time and a comment. The
orientation will be Portrait unless you explicitly ask for Landscape in the Print Options dialog.
For graphical output from the Bar, Gantt, Graph, Strip Graph, Sensitivity Graph and Tree tools,
Vensim will size the output to be big enough to clearly display the information subject to the page size
(or a size you specify). When there is a mismatch between desired and available size, each tool has its
own algorithm for fitting into the desired space. Fonts and relative object sizing will often be changed.
Graphical output is always fit to a single page.
When printing from the Sketch Editor the information will be printed as it appear on the screen but
without the handles. Depending on your choices output may appear on multiple pages.
If you are having problems getting printed output with the right colors on a color printer check the
Graphics tab of the Global Options dialog as discussed in Chapter 17.

Print Options Dialog


If a tool output windows is active you may elect to have the windows print without a dialog appearing.
Normally, however, the Print Options Dialog will appear when you ask to print. You can also open the
Print Options dialog with the File>Print Options command, though some of the items will be grayed.

Selection determines what will be printed. The choices that can be made depend on whether you are
printing from the Sketch Editor, the Text Editor or a tool output window.
? The Sketch Editor gives you the choices Whole View, Selected and All Views.
? Whole View causes the current view to be printed. The size of the view in inches or centimeters
depending on your options settings is shown in parentheses.
? Selected prints only the area of the current view you have highlighted. This options is grayed if
you have not highlighted anything. The size of the currently highlighted area is shown in
parentheses.
? All Views causes all views for the current model to be printed. The total number of views is
shown in parentheses.
? The Text Editor gives you the choices Whole File and Selected.
? Whole File prints the entire file.
? Selected prints only the text you have highlighted. This is grayed if you have not highlighted text.
? Tool Output Windows give you the choices Current Tool Output, Selected Text and All Graphics
Output.
? Current Tool Output causes the current tool output to be printed.

370
? Selected Text causes only the text you have highlighted to be printed. This option is only
available for text output windows when you have highlighted a part of the output.
? All Graphics Output causes all the tool output windows containing graphical output to be
printed. The number of windows is shown in parentheses. Graphical output includes all types of
graphs and Tree Diagram output. This option is only available is you started printing from a
graphical output window.
Orientation (Best Choice or Portrait Always or Landscape Always) allows you to set the
orientation of printed paper.
? Best Choice causes Vensim to choose the orientation based on the type and size of the graph or
the shape of the View. Text output is always printed in Portrait orientation.
? Portrait Always causes printed output to appear in Portrait (normal) orientation.
? Landscape Always causes printed output to appear in Landscape (sideways) orientation.
Vensim cannot change the printer orientation for some older printers. If Vensim is unable to modify
the printer orientation, an error message will be sent to the error dialog (Windows>Show Error).
Note also that some printers (especially some older HP LaserJets) function correctly only in portrait
mode, and have only a single font available in landscape mode, though TrueType fonts may work.
You may need to experiment with font selections to get the best output available from your printer.
Print Info for Bottom Left determines what is printed on the bottom left corner of a graph or view.
You can choose to have a comment printed (for example, the type of experiment you are doing) as well
as the date and time. When you print non-graphical output (for example, from the Document tool,
Table tool, or Text Edit tool), your comment and the date and time information will appear as part of
the header.
? Comment. A comment appears on the bottom left corner of graphical output, or in the header for
text output.
? Time & Date, if checked, causes the time and date to be printed in the bottom left corner for
graphical output or the upper left corner for text output.
? At Corner of (Page or Graph) determines where the comment and time are printed on graphical
output. This option is grayed if you are printing a sketch or text.
? Page puts the information into the bottom left corner of the page. If you are pasting printed
output into a report, you may want to have the comment in the page corner so you can easily
cut it off.
? Graph puts the corner just below the graph itself. If you are pasting printed output in a notebook,
it is useful to have the comment in the graph corner.
Size determines how big the printed output will be. By default, Vensim will try to print text and
sketches at their normal size and make graphical output as big as necessary, up to the size of the page,
to show alldetail.
? Fit to Page will decrease the size of a view or all views so that they fit on the page. If the view
will fit without shrinking it will be centered. This option is only available when printing from the
Sketch Editor. Graphical output will always be fit to a page.
? Fill Page will cause the output to fill the page making it larger if it would not otherwise do this.
This option is not available when printing text.
? Zoom% specifies the percent zoom that should be used when printing. When printing a sketch
this is the same as zooming in and the zoom percent currently being used will show up here. For
graphical output it zooms relative to the target size of the output. For text it adjusts the size of
fonts. If it is left blank no zooming will occur.
? Custom Width, if checked, specifies the use of a custom width instead of having Vensim
determine the width of output. Type a value for the width of the printed graph or sketch (in inches
or centimeters, depending on your global setting) when Custom Width is checked. This option has

371
no effect on text output. Width is always relative to the portrait orientation of the printed page.
? Custom Height, if checked, specifies the use of a custom height instead of having Vensim
determine the height of output. Type a value for the height of the printed graph when Custom
Height is checked. Height is always relative to the portrait orientation of the printed page.
Open on Printing, if selected, causes the Print Options dialog to appear each time you ask to print tool
output. This allows you to tailor comments, layout, and size for each printed graph or table. the Print
Options dialog will always appear when printing from the Sketch, Text or Lookup Editor.
Selected Printer shows which printer Vensim will print to. If you have more than one printer installed
on your computer you may choose among them. If you select the "Default - " printer Vensim will use
the default printer you have installed, so that changing the default printer will change the printer
Vensim prints to.
NOTE that the printer you specify will be used in all printing from Vensim.

Setup allows you to set up the default configuration of the printer that appears in the Selected Printer
combo box. You can use this to change the number of copies printed, paper size, and other options
supported by your printer.
NOTE that changing options in this manner will change them globally. It is the same as changing
printer options from the Windows Control Panel.

Macintosh Notes
The Macintosh does not allow the selection of different printers from within an application. The
Selected Printer and Setup functionality are replaced by a Page Setup button.

Page Setup allows you to set device specific settings - such as scaling and the number of copies - for
printing. These settings will be global, though most Macintosh applications print through this dialog
anyway.
NOTE The orientation settings in the Page Setup dialog are not used. The orientation of output is set
from the Print Options dialog directly.

Printing In Color
When Vensim prints it queries the printer to determine if it is capable of printing in color. If it is
Vensim prints in color, if not Vensim renders graphical and text information in black and white. Some
software drivers for printers that are capable of printing in color indicate that they are black and white
printers.
If you have a color printer that is not printing in color go to the Graphics tab of the Global Options
dialog (Tools>Options) and select Color under the Color settings for Printer. This will also work if
you want to render output with gray scaling to a monochrome printer.
If you want to force output to be in black and white click on the Monochrome selection.

Utility Dialogs

There are a number of utility dialogs that are used under a variety of different circumstances. These
dialogs may request information, such as the name of a file or the answer to a yes or no question, or
may simply be informing that something has happened. Most utility dialogs have an OK and a cancel
button that work in the standard way.

File Selection Dialog


To access files, you use the File Selection dialog. This dialog is a standard system dialog and its exact
appearance will depend on what operating system you are using. Under Windows 95 the dialog will
appear as:

372
Under Windows XP the dialog will appear as:

You click on the file you want, or on a folder to move into a subdirectory and then click on Open to
open the file. Under Windows 2000, 98, 95, NT and 3.1 you can also type in information about file
names and directories. The list at the bottom allows you to select different types of files.

Variable Selection Dialog


The Control Panel has a Variable tab that allows you to select the Workbench variable as described in
Chapter 11. There are also times when you need to select a variable for other purposes. These include

373
adding a variable to a sketch, searching for a variable in a sketch, adding variables to graph definitions,
and other purposes. The Variable Selection dialog is used to manage this mo dal selection of variables.

The Variable Selection dialog functions in exactly the same way as the Variable tab of the Control
panel except that it has OK and Cancel buttons. Depending on where the Variable Selection Dialog is
called from, it might not include the Subscripts drop-down.

Written Response Dialog

When Vensim requires a text response from you, a small dialog opens for you to type your response.
Leaving the line blank returns an empty response. Clicking on the Cancel button has the same effect.
The default value (if any) is displayed when the dialog appears.

Color Selection Dialog


In any place in Vensim where you can use colors you will get to choose between 64 different colors.
To choose click on the colored button, and you will see the color selection dialog:

The dialog contains 64 colors. The first 48 are predefined. You can set the last 16 from the Colors &
Markings tab of the Options dialog. Click on the color you want. The first color button will often be a
standard looking button with a dash in it ( ). Click on this button is used to specify that the default
color should be used. If the first button is simply white there is no default color so just click on the
color you want to use.
The exact appearance of the Color Selection dialog will depend on your computer. Normally only
solid colors are used, so that many colors may look the same on computers with smaller numbers of
colors.

374
List Reorder Dialog
The List Reorder dialog provides a simple mechanism for reordering lists. This is used to reorder
custom graphs and to reorder Views.

To use this press the mouse button down on the name of the item you want to move. Then drag that
item to the new position you want it to occupy. As you drag the item will be removed from the list and
the Cursor will change shape. Release the mouse button with the crosshairs in the space between the
two items you want to move between. To make an item first move the cross-hair above right near the
top of the window, but keep it in the window. Use the analogous action to make an item last.

If you need to drag an item beyond the visible list, move the cursor above or below the list. The list
will scroll. Let it scroll until the position you want is visible then move the cursor to the new position
and let go of the mouse button.

Fonts Selection Dialog

The Fonts Selection dialog is used to choose fonts in Vensim. It is use to set fonts for tool output and
also a number of global fonts. The Sketch Editor makes extensive use of the Font Selection dialog
functionality in setting word attributes.
Face names the face for the font. There is a list of available font faces below this to choose from. The
fonts that are available will depend on your computer.
Bold, if checked, causes the font to appear bold.
Italic, if checked, causes the font to appear italic.

375
Underline, if checked, causes the font to appear underlined.
Strikethrough, if checked, causes the font to appear with an overstrike.

In setting fonts in the Sketch Editor you may also get the choice Vertical which will cause the font to
be displayed vertically starting from the bottom.
Size (Points) lets you set the size of the font. You can type in a size or click on the arrow to the right
to choose a size. Vensim does not support font sizes larger than 99 points.
Color lets you select the color for the font. Click on the button then click on the color you want.

Example displays the currently selected font and attributes. The name is also used to indicate if the
font is a screen font, a printer font or a True Type font. True Type fonts will usually give a good
match between the appearance of the font on the screen and the appearance when printed.

Query Boxes
Query boxes appear when Vensim needs a yes or no answer, possibly with the option of cancellation.

Yes performs the suggested action and closes the dialog.


No does not perform the suggested action and closes the dialog.

Cancel usually causes Vensim to stop performing the command sequence that generated the question.
For example, clicking the Cancel button in this dialog would stop the exit from Vensim.

Message Boxes

? Information boxes report various events in the program.


? Caution boxes contain warnings of conditions that might cause errors or generate misleading
output.
? Stop boxes report errors. You may, for example, have requested information that Vensim could
not provide, or simply typed an incorrect name.

376
No matter what the level of message box, you respond by clicking OK (even if conditions are not OK).

Fatal and Program Errors


Fatal and Program errors appear as stop message boxes labeled with Fatal Error for Vensim, or Vensim
Program Error.

If a Fatal Error occurs, Vensim shuts down (normally cleanly), which allows you to save any work in
process. Acknowledge the error and save what you can. Insufficient memory can cause a Fatal Error.
Program Errors result when Vensim's internal consistency checking detects a problem. This is either a
situation that is not expected and will not be handled properly, or a memory corruption of some sort.
The error message you will see is an internal check location and is intended to help us analyze the
source of the problem.
If a PROGRAM ERROR occurs, acknowledge the error and save as much of your work as possible
using the Save command from the Sketch tool, Text Edit tool and Workbench. Vensim will not shut
down, but may not behave properly. After a Program Error you may be able continue, or the system
may crash completely.
NOTE if you are getting program errors and saving models in binary format the Model>Reform/Clean
command may fix the problem.
Please let us know about Program Errors. We will attempt to determine the source of the problem and
provide you with an update or work-around to guard against future problems.

377
17 Options

Vensim has a variety of options that can be set and all are accessed using the Options dialog. This
Chapter:
? Describes the Global Options dialog and its tabs
? Contains references to other chapters relative to the options.
Vensim PLE and PLE Plus have only a small number of options. These are discussed in the first
section. The remainder of the Chapter applies only to Vensim Standard, Professional and DSS.

Options for PLE and PLE Plus


To change options in PLE and PLE Plus use the menu item Options>Options.

Show Line Markers on Graph Lines, if checked, causes lines to be displayed with numbers on top of
them. Graphs drawn in this manner are somewhat more cluttered than normal graphs but it can be
easier to distinguish graph lines.

Continually Refresh Sketches, if checked, causes the sketch to be redrawn continually as you work
with it. With some video drivers Vensim will leave marks on the screen. You can use the
View>Refresh command to remove these. Continual Refresh will do that automatically but will also
cause screen flicker.

Excel R1C1 Letters


When you use the GET XLS CONSTANTS or GET XLS DATA functions Vensim queries Excel for
this information. The appropriate format for this query is different for some international versions of
Excel.
If you are having trouble getting these functions to work open the spreadsheet xlstest.xls in
models\sample\extra and click on the button labeled Get Row and Column Labels (you will need to
enable macros). This button should open a dialog such as

378
? Row the first letter returned in the above response. Normally R.
? Col the last letter returned in the above response. Normally C.
Sketch View Positioning
Autocenter causes the sketch to be positioned in the middle of the page each time the model is
reopened.
Pagemarks causes the sketch to appear with pagemarks. This makes it easer to determine how things
will print and is helpful for larger sketches that are done with a single view.
No Pagemarks does not add pagemarks or reposition the sketch each time it is opened.

Color for Display, Print & Clipboard


Allows you to set the way Vensim Uses color. By default Vensim will test to see if the device can
support color (which will almost always be true except for some printers) and send color if it can. If
you specify monochrome Vensim will use line patterns to distinguish graph lines. You can stop this by
check Only Solid Lines which can be useful when line markers are showing.

Font for Dialog Boxes


Normal specifies the font for most dialogs.

Equation Editor specifies the font for the equation editor. Sometimes equations are easier to read if
you use a fixed pitch font such as Courier for the equation editor.
Compressed sets the font to be used when a dialog would be too big to fit on the screen. Normally
this only happens on computers with small screen resolutions.
To change the font click on the button and then select the font you would like from the Font Selection
dialog.
Changes you make in this dialog are stored across Vensim sessions.

379
The Global Options Dialog

The Global Options dialog is opened with the Tools>Options command. It is a tabbed dialog box and
contains a significant number of tabs which are discussed below. To look at a different tab click on it.
Because there are two rows of tabs clicking on a tab that is not in the front (bottom) row will move that
row of tabs for to the front. Clicking on OK will make all the changes you have made in any tabs
permanent. Clicking on Cancel or pressing the Esc key will discard any changes you have made in any
tab. All of the settings in the Options dialog are stored across Vensim sessions.

Fonts

The Fonts tabs are used to set up fonts that will be used in a number of places. Since most of the tools
allow you to directly specify tool output fonts , changes made in this dialog will not influence tool
output appearance, but only the default font when you add a new tool. Custom Graphs, on the other
hand, do not have a direct mechanism for specifying fonts and those mu st be specified here. All of the
fonts are specified using the Fonts Selection Dialog (see Chapter 16).

380
Fonts1

Printed Title is printed at the top of graphs, tables and views. The Graph Tool and Custom graph tool
do not use this font.
Print Comment/Date is printed at the bottom of graphs with the date and time if you have asked for
these to be printed in the print options dialog.

Text Editor Font † is the font used in the Text Editor for models. If you open the Text Editor using a
tool in the toolbar you will get the font specified in that tool. Once the text editor is open you can also
change the font, though this change will not be permanent.
General Text/Utility is the default font used in text output windows that are not created from a tool on
the toolbar. This includes the selection history window, error lists and custom report output.

Dialog Boxes is the font that is used in Vensim's dialog boxes. You can choose the font you like to
make the dialog boxes more readable, or smaller. The default is MS Sans Serif 9 point.
Equation Editor Dialog is the font use in the Equation Editor. This allows you to use a fixed pitch
font such as Courier in the Equation Editor without changing other dialogs. A fixed pitch font can be
handy for making equations line up vertically. This has the same defaults as the regular dialog box
font.
Dialog Boxes (Compressed) sets the font that Vensim uses when it cannot create a dialog box using
the normal dialog box font. If you ever get a message that Vensim is unable to open a dialog because
it is too big, you can try to find the smallest legible font possible with this button. If you are working
on a computer with at least a normal VGA screen you will probably never use the compressed dialog
font.

Venapp Font‡ is the font used in Vensim applications. You can override this font using the
SCREENFONT control and by specifying fonts for individual controls. See the Vensim DSS
Reference Supplement for details.
Initial Tool Face let you set the faces used when you initially load a tool using the Toolset Editor.
? Normal specifies the face that will be used by the Strip Graph, Sensitivity Graph, Bar Graph,
Gantt Chart, Tree Diagram and Graph tools. Tools that output text are initialized with Text Font
described above. Only the font name you select will be used (point size and attributes will be
ignored).
? Fixed Pitch specifies the initial font face used when a fixed pitch font is normally desirable.

381
Currently only the Text Editor uses this.
NOTE If you want to change all fonts in use by Vensim first change the fonts in this dialog. In order
to change the fonts used by tools you will need to change each individual tool. As an alternative,
however, you can ask for a new toolset and then load in the internally stored toolset and this will use
the fonts set in this dialog.

Fonts2

Graph Markings (1,2...) specified the fonts that will be used in displaying markings on line graphs.
This font is only used if Line Markers is selected on the Graphics tab.

Custom Graph Fonts


Let you specify the fonts that will be used in the custom graphs you create.
Title Font is the font used for the title of the graph.
Label Font is the font used to label the X and Y axes of the graph.
Stamp Font is the font that the graphs Stamp is printed with.

Legend Normal is the legend font that is used when there is no difficulty fitting the graph in the
desired size.
Legend Small is used for the legend when the graph is too big to fit in the desired window.

Legend Tiny is used for the legend when, even using the Legend Small font, the graph is too big to fit
in the desired window. If the graph is still too big things are squished together.

Colors & Markings


The Colors & Markings tab is used to set up the colors that will be used in graphical output. Here you
can set the colors of plot lines, as well as the graph background and foreground color and the line
marking characters. You can also use this dialog to create custom colors for use in the Color Selection
dialog.

382
Color Line 1-12 are the colors that are used to plot lines on graphs. Line 1 is used first, then 2 and so
on. If there are more than 12 lines in a graph the colors will repeat.
Marking Line 1-12 are the markings that will be used on graph lines. Markings are used only if Line
Markers is set in the Graphics tab.
Graph Border Color is used to draw the box around graphs, normally this is black.
Graph Gridline Color is used to draw gridlines in graphs, normally this is gray.

Graph Background Color is the color the graphs are drawn against. Making this an off-white color
can provide a useful contrast in graph appearance.
Window Background Color is the background color used outside the graph proper behind labels and
other test.
Show Colors in Tables, if checked will display different runs in different colors when you use the
Table and Stats tools. This is a very useful way to distinguish different runs and is checked by default.
The colors used are the same as those used for graphs.
Define Custom Color allows you add to the color choices in the Color Selection dialog discussed
under utility dialogs later in this chapter. There are 16 custom colors you can define to be available
with the Color Selection dialog. When you press this button you will see the standard Windows Color
customization dialog.

383
Click on the custom color you want to modify, click in the color and intensity screens, or type in
values for hue, saturation and luminosity (or red green and blue) and click on the "Add to Custom
Colors" button. Click OK to finish, Cancel to cancel.

Macintosh
On the Macintosh when you click on the Define Custom Color button you will be prompted for the
number of the color you want to change. Select a number between 1 and 16 and click OK. The
number corresponds to a position in the bottom two rows of the Color Selection dialog described
below. You will see the standard Macintosh color wheel dialog. Choose a color you want and click on
OK.

Graphics

The Graphics tab is used to control the appearance of graphical output going to the screen, printer and
clipboard. By default Vensim tests the screen and printer to determine how to manage output. While
this is normally fine for the screen, for both the printer and the clipboard you may wish to override
these defaults and specify more completely the desired output characteristics.
The options under Screen control the appearance of graphs on your computer. The options under
Printer control the appearance of graphs when you print them. The options under Clipboard control
the appearance of graphics when you export them or save them to disk. In each case you have the
same set of possible options and all can be set independently.
Note that the Export graphics and sketch information formatted for printer option in the Settings
tab will determine whether the printer or screen is used in testing the device capabilities of the
clipboard.

384
Color (Test or Color or Monochrome) determines whether or not to use different colors for different
plot lines.
? Test tests the device to see if it is capable of displaying color. For some notebook computers and
printers this test can result in misleading or incomplete results. For this reason you may want to
override the test and force Vensim to use color or monochrome even when this is inconsistent with
test results.
? Color causes graphs to be drawn with colored lines. On monochrome devices this may result in
gray scale attributes.
? Monochrome causes all graphs to be drawn with black lines.
Graph Lines (Solid for Color or Solid or Patterned) determines the line styles used with graph lines.
? Solid for Color uses solid lines when the lines can be displayed in color (possibly because you
have selected Always Color above). If the lines are monochrome they will be patterned (solid,
dotted, dashed, dash-dotted and dash-dot-dotted).
? Solid causes graph lines to be displayed as solid lines under all conditions.
? Patterned forces lines to be displayed with patterns under all conditions. If you click on this you
will notice that the Thick Line options described below are both grayed. This is because you
cannot display a thick line with a line pattern.
Strip Graph lets you set line attributes for the Strip graph.
? Thick Lines, if checked, causes the Strip Graph to display different runs with different line
thicknesses. The first run is displayed thin, the second thicker and so on. You may find this
helpful in distinguishing between runs. This option is only active if the lines are being displayed
as solid lines.
? Line Markers, if checked, causes lines to be displayed with numbers or other markers on top of
them. You can choose the marks in the Graphics tab. Graphs drawn in this manner are somewhat
more cluttered than normal graphs but it can be easier to distinguish graph lines.
Graph Tool allows you to set line attributes for the Graph Tool. The options are precisely the same as
those for the Strip Graph.

385
Units (for New Models)

The Units tab is used to set the units synonyms that will be used for new models These synonyms will
be attached to a new model when it is created. To add a synonym type in the synonyms separated by
commas and click on Add Editing. The modify a synonym in the list click on it and click on Modify
Selected. The delete a synonym from the list click on it and click on Delete Selected. There is more
discussion of units synonyms in Chapter 3.

Startup
The Startup tab controls the way Vensim Starts.

Startup using last model worked on, if checked, causes Vensim to start with the last model you
worked on loaded in the Workbench. If you are working on a number of models, you may wish to
uncheck this to save startup time.
Use Vensim in offline mode (not recommended) , if checked causes Vensim to separate the
workbench model from the model you have loaded in the Text Editor or Sketch Editor. If you select
this option you need to explicitly invoke the File>Load command to make a model active. Changes
you make to a model will not be reflected in the analysis tools. This option is useful for working with
very large models that might make Vensim sluggish but it can be quite confusing because model
changes seem to have no effect. This it is not a recommended setting.

386
Backup file path (no drive) allows you to set a path for the storage of old versions of a file when a
new version is written. If this is left blank the old version will be named with a 2 preceding the
extension. For example test.vmf would have test.2vmf as its old version name. The path is used by the
Text Editor and Sketch Editor to name the backup file.
NOTE Do not include a drive letter when you specify the path - backup will occur on the same logical
drive your model is on. If the path as entered does not exist on the current logical drive the default
naming convention is used.

Tab Width for Text Editor † allows you to specify the number of spaces a Tab represents in the Text
Editor. The Text Editor is designed to work best with fixed pitch fonts.

Compiled simulation path‡ tells Vensim where to find the files necessary to run a compiled
simulation. Compiled simulations are discussed in the Vensim DSS Reference Supplement.

External function library‡ names the Dynamic Link Library containing external functions for use
with Vensim. External functions are described in the Vensim DSS Reference Supplement.

Molecule Library Path, names the path where molecules are installed. Information on molecules is
available from http://www.vensim.com/molecules.html.
NOTE Some changes you make in the Startup Settings dialog will not take effect until you exit and
restart Vensim.

Sketch and Sketch Defaults

The Sketch and Sketch Defaults tabs are used to control the function of the sketch. All sizes are
measured in pixels. As you resize an object in the Sketch tool the current size is reported in the Status
bar, so you can quite easily find a size you like and record it in the initial value columns.

Sketch

Solid Arrowheads , if checked, makes arrowheads solid. If not checked, arrowheads appear only as
the outline of the arrowhead.
Single Polarity, if checked, causes polarities attached to arrows with more than one handle to be
shown only at the last handle before the word the arrow goes into.

387
Comments on Hover, if checked, causes the comment and units for a variable to appear in a small box
below the word when you let the mouse idle (remain motionless) over the word for more than a
second. This also enables the display of ToolTip graphs in SyntheSim mode.
? for ___ secs determines how long these comments will be displayed before automatically being
hidden. If you put 0 here the comments will only be hidden when you move the mouse, click or
press a key.
Start Words in Clear Box, if checked, will cause words placed on a sketch to appear in a clear box.
This allows them to be line wrapped. You can take away the clear box, or change it to another shape
afterward. This applies only to words added using an Existing Variable tool or the variable list and
words automatically brought into a sketch when Vensim detects an added cause.
Show Variable List, if checked, causes the list of model variables to appear at the right of the sketch.
This list can be used to add existing variables to the sketch.
Continual Refresh, if checked, causes the sketch to be redrawn continually as you work with it. With
some video drivers Vensim will leave marks on the screen. You can use the View>Refresh command
to remove these. Continual Refresh will do that automatically but will also cause screen flicker.
Equation Editor lets you set options for the Equation Editor. There are really only two of these so
they are included in the Sketch Tab.
? No Argument List, if checked, causes function names to be placed into the Equation Editor
without a description of their arguments. Instead the number of arguments will be indicated by the
number of commas.
? Accept Enter, if checked, allows you to use the Enter key when working in the Equation Editor to
break up lines. If this is not checked pressing Enter will activate the focus button which is
normally the same as clicking on OK. You can use Ctrl + Enter to break up lines in any case.
Polarity Distance from Arrow (default 14) is the distance from the arrow at which arrow polarity
indicators (+,-,s,o...) should be written.
Arrowhead length (default 14) is the length of an arrow head from its base to its tip perpendicular to
the base.
Arrowhead width (default 8) is the width of the base of the arrowhead.

Positioning (Autocenter or Pagemarks or No Pagemarks) determines how the sketch positioning


information is managed.
? Autocenter causes each view to be entered as it was left. If you scroll the view to a new position
that position is made the center of the sketch and the view will be opened at it.
? Pagemarks causes dashed lines showing the borders of pages to appear. These lines are based on
your currently selected printer (see "Printing" in Chapter 15). When you move to a view it will
always be started with the 0,0 position at the top left. Because the sketch canvas is extensible in
all directions there may be information above and to the right of this you can scroll to. When you
zoom in or out on a view the page marks will remain the same allowing you to determine how
much you can fit on a printed page.
? No Pagemarks is the same as Pagemarks in terms of positioning information but the page marks
themselves are not displayed.
Snap-to for Word Positioning allows you to set up a snap-to grid that will make it easier to align
words. By default you can move words to any pixel position. If you set a snap-to grid it will not be
shown, but when you move a word the word will only move by the increments you specify. The grid
is always at 100% so that if you zoom is has the same meaning. The grid is used to determine both how
words are positioned and how they are sized, but has no effect on arrow placement.
? Horizontal sets the horizontal increment. Yo u can choose whether to apply the snap-to relative to
the Left, Center or Right of a word. Choose Left to line things up on the Left and so on.

388
? Vertical sets the vertical increment. You can choose whether to apply the snap-to relative to the
Top, Center or Bottom of a word.
By Types Shapes allows you to customize the mapping between the type of a variable and the shape
that is used to display the variable. This mapping is used when you ask for a variable appearing on a
diagram to be shaped by type. This allows you to customize the appearance of diagrams and change
that appearance easily.
There are five types of variables you can set the shape for. To set a shape click on the downward
pointing arrow at the right of the shapes name and click on a new shape. The default shape mapping is
Box for Levels and Clear Box for everything else.

Sketch Defaults

Initial Sizes
Flow Thickness (default 4) is the initial thickness of the flow connectors associated with rates (the
separation between the double lines). This will be rounded to the next higher even number.
Valve Width (default 12) sets the initial width of valves.
Valve Height (default 16) sets the initial height of valves.
Circle Size (default 40) sets the initial diameter of circles
Box Width (default 80) sets the initial width of a box.
Box Height (default 40) sets the initial height of a box.

Color for New Shadow Variables (default gray) sets the initial color for shadow variables. You may
want to set this to black to ensure readability on portable computers.

Defaults for New Views


When you start a new view the view will be given default attributes. You can change these with the
View>Font and Colors... command. You can also configure the Sketch Tools to use colors different
from the defaults.
Sketch Background (default -) sets the background color that will be used for a view. If you choose
the default - color the view will appear as other editing windows.
Shape Color (default black) sets the color that shapes will appear in.

Fill Color (default -) sets the color that shapes will be filled with. Selecting the default - color means
that shapes will not be filled.

389
Arrow Color (default blue) sets the color that arrows will be drawn with.

Initial Arrow Color (default gray) sets the color that arrows indicating initial causes will be drawn
with.
Font determines the font with which new sketches are started. This is very helpful because you can set
it to something you want so that you do not have to select a new font each time you start a new view.

Toolbars
The Toolbars tab give you control over the Location of Vensim's various toolbars.

Analysis Tools Position (Top of Left or Hidden) determines the position of the Analysis Tools. The
location of these is relative to the main Vensim window. If you choose Top they will appear below
the Main Toolbar.
Sketch Tools Position (Top or Left or Hidden) determines the position of the Sketch Tools. The
location of these is relative to the Sketch Window. If the Analysis and Sketch Tools are both on top
the Sketch Tools will appear below.
Hide Main Toolbar, if checked, will hide the main toolbar.
Hide Bottom Statusbar, if checked, will hide the bottom Status bar.

Show Model Path in Ti tlebar , if checked, will display the full model path in window titles. If the
path is long it may have ellipses placed within it. If this is not checked only the model name will be
shown.

Settings and Advanced

The Settings and Advanced tabs let you control the behavior of Vensim in a variety of ways. The
Advanced tab is not available in Vensim Standard.

390
Settings

Autosave Time (Min)


Autosave Time (Min), lets you set the frequency with which models in the Sketch Editor are
automatically saved. As you do editing Vensim will save the current version of the file. Should
Vensim be abnormally terminated you can recover the autosave version.
If you open a model that has an autosave version in place Vensim will inform you of this and ask if
you want to open the autosave version. If you answer yes Vensim will query you for a name to save
this as. It is best practice to save to a new model name and not overwrite an existing model in case
there is something wrong with the autosave version of the model.
If you want to disable autosaving of models enter 0 as the autoave time.

Close Active Model on Open or New†, if checked, closes the Workbench model when you open a
different model or ask for a new model.

Excel R1C1 Letters


When you use the GET XLS CONSTANTS or GET XLS DATA functions Vensim queries Excel for
this information. The appropriate format for this query is different for some international versions of
Excel.

If you are having trouble getting these functions to work open the spreadsheet xlstest.xls in
models\sample\extra and click on the button labeled Get Row and Column Labels (you will need to
enable macros). This button should open a dialog such as

? Row the first letter returned in the above response. Normally R.


? Col the last letter returned in the above response. Normally C.
Export Graph Size (Screen or Full or Query) sets the size of the exported graphics output. Exported
graphics can always be scaled after they are exported, but the results will often be better if you scale

391
them first. This is because each tool has a different algorithm for responding to different available
sizes.
? Screen sizes the output at the size as it appears on the screen.
? Full sizes the output at the size the tool that generated the output requires for normal display of the
output.
? Query allows you to set a size for the output when it is exported. When you ask to export
graphics, a dialog box requests a size for the output.
Export graphics & sketch Information formatted for printer exports graphics formatted as they
would be for printing (that is, using the printer resolution and color characteristics). Depending
on your printer this may improve the appearance of the final printed output.
Warnings (Display or Suppress) displays or suppresses warnings. Most warnings occur during
simulation because of table and range overruns. If warnings are suppressed you don't see them.
Size Entry (Inches or Centimeters) changes the units in which you enter sizes. Sizes are used in
exporting and printing graphics and the values you enter will be interpreted based on this setting.
Macro Variables (Show or Hide) determines whether the intermediate variables that result from using
macros will be displayed. Macro variablenames can be recognized because they begin and end with #.
? Show causes intermediate macro variables to be dis played. Causal tracing using the Outline,
Stats, Strip Graph, Table and Tree tools will show these variables.
? Hide causes macros to be treated similarly to functions. Only the inputs to the macros are
displayed during causal tracing.
Dataset Conflicts (Query or Overwrite (no query)) determines whether or not you will be asked if you
want to overwrite a dataset when that dataset already exists. If you tend to make several simulations
with the same name, you may wish to check Overwrite.
Datasets Loaded in Position: (First, Last or #) lets you set the position a dataset is loaded in after a
simulation or importation occurs. Last loads it in as the last dataset, while First loads it in as the first
dataset. You can also ask to have it loaded in a specific position (2,3 ...) by typing in a number. If you
rerun a simulation and those simulation results are already loaded the new results will be loaded in the
same position the old ones were.
Variable Display Format (Show_underbar, Capitalize by Type) determines the appearance of
displayed variable names.
? Show_underbar, if marked, causes underbars rather than spaces to appear within variable names.
? Capitalize by Type, if marked, causes variable names to be capitalized using a set of built in
Vensim conventions. This option is retained for historical reasons.
Thresholds
Maximum X-Gap for Graphs. This option specifies the maximum X-gap in a graph that will be
displayed as a continuous line. For example, suppose that you have yearly data on car sales for 1960-
1965, 1970-1975, and 1980-1985. If you set the maximum X-gap at 2.0, your graphs will have three
separate lines. If you leave the maximum X-gap at its default value of 0, your graphs will have one
line with the 1965,1970 and 1975,1980 values joined by a line. The values of X-gap are interpreted in
terms of the currently selected time axis.
Time Slop for Dat2VDF determines when two time values are treated as equal when importing data.
If you set the time slop to zero (0.0), Vensim will use its own algorithm to determine when time points
are the same. However, if you use data heavily, we recommend that you set your own value. See
Chapter 9 for a more complete discussion of time slop. Time slop is most important in importing .dat
format data.

392
Active Initial Relative sets relative error that will trigger a warning that there are differences between
initial values and active values at the initial t ime. This is discussed further in "Simulation Error
Messages" in Chapter 8.

Advanced†

Text Edit History (On or Comment or Off) determines whether or not a separate history file is created
when you make changes to a file using the Text Editor. See Chapter 7 for more details on history files.
? On causes a history file to be created or appended, which logs whatever changes were made
whenever you save a file. This is useful as a record of your work.
? Comment allows you to enter a comment into the history file. Each time you save a file you are
asked to enter a comment. This is helpful for making notes in history files so that you can track
changes. No comment is added if you cancel the Written Response dialog.
? Off prevents the creation of any history file. This is not a recommended setting, since you can
delete history files easily at any time.

Compilation‡
Compilation is used to speed up simulation by writing out the model equations as a C language file that
can then be compiled and run as a Dynamic Link Library with Vensim. Details on compiled
simulations can be found in the Vensim DSS Reference Supplement. You can choose separate compile
options for Simulation (including Gaming), Optimization and Sensitivity. It is more likely you will
want to compile for optimizations and sensitivity runs. Reality Checks are always interpreted because
the equation structure is continually changed.
? Interpret causes the equations of the Workbench model to be interpreted, instead of compiled,
during a simulation. Interpreting simulates slower, but gets started very quickly and is preferable
if you are frequently changing the model. If you do not have a C compiler available this is the
only option you can choose.
? Compile causes Vensim to create, compile, link and execute a set of C equations representing the
model equations. If you have made no changes to the model since the last simulation, the
creation, compilation and linking of equations will be bypassed. Compiled simulations take
longer to set up, but simulate more quickly.
? Query is the same as Compile if you have not made any changes to your model since the last
simulation. If the model has changed you will be asked if you want to compile it: if you respond

393
yes the model will be compiled; if you respond no the model will be interpreted.
? Color/Graphics Options, brings up the Graphics Options dialog. This allows you to control the
appearance of graphs on the screen, at the printer and in the clipboard. This is especially useful in
managing the appearance of printed output when you are exporting graphics for use in other
applications.
Variable coun for function breaks in mdl.c allows you to customize the number of variables grouped
within the C functions created when compiling the model. This should be a value between 20 and 2000
and has a default of 100. When using optimizing compilers a smaller number can help to increase
compilation speed with minimal impact on run time. For nonoptimizing compilers a large value (eg
1000) can be helpful for decreasing both compilation and runtime.
Template Model is: lets you specify the name of the model Vensim should start with when you ask
for a new model. You should enter the full path name of the model you want to use. The model must
appear as a text file. This is convenient for setting up commonly used macros or other information you
want to be common across your models. If you choose this option you will not be queried to fill in
model settings.
Start New Model with Text Editor , if checked, opens new models in the Text Editor. By default new
models are opened in the Sketch Editor. If you choose to start a new model in the Text Editor you will
be asked for a name to save the model to.
Query Time Bounds for New Model, if checked, brings up the Model Settings dialog when you start
a new model. If not checked the model will be started with the default settings (Time from 0-100
Months by 1 month). If you have filled in the Template Model is value this setting has no effect.
Terse Format for View>As Text, if checked, will cause the formatting of equations when viewing as
text to be Terse – otherwise equations will appear as entered.
Suppress Simulation Information Window, if checked, will prevent the error window that pops up
indicating which changes files are being loaded and providing other information from appearing. If
there is an error (as opposed to a warning or informational message) this window will still appear.

394
Appendix A — Glossary of Terms

The following terms are used throughout the manual, and it is useful to have some understanding of
their exact meaning. File extensions, and the names of files that Vensim uses and creates are included
for completeness. Terms shown in bold have definitions in this glossary.
.bmp – BitMaP file. Used to store embedded bitmaps when a file is saved in .mdl format. The filenames are the
same as the model name with numbers added.
.dat – DATa input file. This is a simple text file.
.cin - Constant INput file used to change Constants and Lookups in simulation (text file).
.gin – Gaming Input file use to change gaming variables when running games (text file).
.cmd - CoMmanD file used to run a series of commands in batch mode (DSS only) (text file)
.frm – FoRM file used to tell Vensim how to import tab delimited and spreadsheet files.
.lst – LiST file containing a set of variables to be saved either for a sensitivity simulation or to decrease the output
size for large models.
.mdl - MoDeL format file used to transfer Vensim models from one platform to another.
.out – OUTput file from an optimization giving the best parameter results (Pro/DSS only text file).
.prm - PaRaMeter control file used to control optimizations. The .prm extension is obsolete - see .vpd, .voc and
.vsc.
.rep – REPort file created when the payoff report option is selected (Pro/DSS only text file).
.vcd - Vensim Custom Description file used to create a scripted Venapp (DSS only).
.vcf - A binary version of a .vcd file.
.vdf - Vensim Data Format file used to store simulation results and converted data. Binary file.
.vdi – Vensim Data Input file used to query an ODBC connection for Constants and Data (DSS Only text file).
.vdo – Vensim Data Output file used to output data to an ODBC connection (DSS Only text file).
.vgd - Vensim Graph Definition file used to set up custom graphics.
.vgf - A binary version of a .vgd file.
.voc – Vensim Optimization Control file. Used to specify how to optimize a model. This is a text file (Pro/DSS
only).
.vpd – Vensim Payoff Definition. Used to define the payoff for optimization (text file Pro/DSS only).
.vmf - Vensim Model Format file used to store models. This is a binary file.
.vpa – Vensim Packaged Application containing a model and Venapp definition file (DSS only binary file).
.vpm- Vensim Packaged model containing a model and support files (binary file).
.vsc – Vensim Sensitivity Control. Control file for doing sensitivity simulations (text file).
.wmf – Windows Meta File format – this is used to store embedded metafile images when a model s saved in .mdl
format. The filenames are the same as the model names with numbers added.
.sts - Vensim Sketch ToolSet file. A file containing a Sketch toolset.
.vts - Vensim Analysis ToolSet file. A file containing an Analysis toolset.
† - a section of the manual only applicable to Vensim Professional and Vensim DSS.

395
‡ - a section of the manual only applicable to Vensim DSS.
Analysis Toolset - The set of tools used to analyze model structure and behavior. By default these appear on a
toolbar along the left.
Arrow - An object connecting two variables on a sketch ( ).
Autocorrelation - The correlation of a variable with itself at a previous Time.
Auxiliary - A variable computed at each given Time based on the values of other variables at that time.
Behavior - What happens. Used in contrast to structure.
Boolean - An expression that results in a zero or one value. Vensim expects booleans to be used with the
IF_THEN_ELSE function, and treats any other type of expression by testing it against zero.
Build window - A window that is used to build models or edit files. The Sketch Editor or Text Editor.

Button - A control appearing in dialogs ( ). Also the part on the mouse that you can push up and down to
make an audible clicking noise.
Causal - A system, including a model, in which direct physical or logical causality can be attributed.
Checkbox - A control appearing in dialogs ( ). The check mark in the left corresponds to an
on/off switch with the check meaning on.
Click or Click On - Positioning the pointer over an object and then depressing and releasing the left mouse
button without any intervening mouse motion.
Command - A capability of Vensim, normally accessed through menus.
Comment - a word in a diagram that is not a variable.
Compiled Simulation - A simulation that is performed by writing a C program representing your model, then
compiling and running this C program.
Conserved Flow - a flow out of one Level and into another Level.
Constant - A variable that is set equal to a number.
Constraint - A variable that describes a condition that might exist and a required consequence.
Control - A window, button or list appearing in a dialog.
Control window - A window (technically a modeless dialogue) that is used to manage Vensim's settings.
Control-click - Same as to click, except that the keyboard's Ctrl key is held down throughout the operation.
Control-drag - Same as drag except that the Control key is held down during the operation.
Correlation - The relative connectedness of two variables. Correlations range in value from -1, indicating
opposites to 0 indicating unconnected to +1 indicating moving together.
Covariance - The connectedness of two variables. Can be positive or negative and its meaning depends on the
units of measure for both variables.
current.vdf - The default file for simulation output.
Custom Graphs - Graphs that are predefined in terms of what variables and datasets are shown.
Dat2vdf - The process of converting input text data to Vensim Data Format (.vdf).
Data - Measured or guessed at values for model variables, usually available over time. Also a variable that is
not computed, but has measured or guessed at values.
Dataset - A collection of variables and their values over Time. Datasets result from simulation, and from the
conversion of data using Dat2vdf.
default.vts - The default toolset file. If you ask to load the toolset in default.vts and it cannot be found or is not
readable, Vensim will use its own default toolset.

396
Dialog - A window that you interact with by typing and clicking.
Dimensionless - Units of measure indicating that a variable has no dimensions.
DLL - see Dynamic Link Library.
Dmnl - Synonym for dimensionless.
Double Click - Two clicks of the left mouse button in quick succession. More exactly depressing the left mouse
button, releasing it, pressing it down again and releasing it quickly, and without moving the mouse. As
much as possible, Vensim allows you to click slowly and move the mouse a little bit while still getting the
effect of a double click.
Drag - Moving the pointer with the left mouse button depressed. To drag depress the left mouse button and
move the mouse without releasing the mouse button. Dragging can be used to move objects, and to
highlight text: 1. To move an object position the pointer over the object and drag. As you drag an outline
or other indicator will show where the object is moving to. Position the outline where you want the object to
be and release the mouse button; 2. To highlight text position the pointer over the beginning of the text you
want to highlight, and drag. Let go of the mouse button when you have highlighted the text you want.
dynven.exe (dyn2ven on Mac) - A utility for converting DYNAMO models to the Vensim modeling language.
Dynamic Link Library - A program that is connected to Vensim while Vensim is running. External functions
and compiled simulations work using Dynamic Link Libraries.
End time - The latest time used to analyze datasets. End time determines where the x-axis on most graphs and
tables ends.
endpoint.dat - Contains the final optimization points and the corresponding payoffs in a format suitable for
Dat2vdf. This file is created during optimization.
endpoint.tab - Contains the final optimization points and the corresponding payoffs in tab-delimited format. This
file is created during optimization.
Entrain - A mode in the Text Edit tool in which the model is repositioned each time you select a new variable
into the Workbench.
Equation - An algebraic expression defining one variable in terms of other variables, or as an integration of
itself and other variables.
Error - A problem detected in a model that prevents simulation.
Exogenous - A variable that is not computed, but has values specified by data.
Filter - A device for uncovering unmeasured variables.
For Variable - A synonym for Subscript Range (archaic).
Fourier Transform - A method for viewing data, especially residuals, in terms of what periodic behavior they
might have.
Group - An element of a model used to organize variables for easy reference. Groups do not take on values, but
act like section headings.
Highlight - To make an object visually distinct
. Objects are highlighted to indicate that they will be used for a special purpose. You can highlight text by
dragging over it.
Initial - A variable that has a value computed at the beginning of the simulation and then remains the same for
the rest of the simulation.
Integration - The mathematical process underlying simulation. Integration is akin to, and often the same as,
accumulation.

397
Interpreted Simulation - A simulation that results from interpreting the equations for a model internally to
Vensim.
Junction (or Junction Node) a comment that can have arrows going into it or coming out of it.
kalman.prm - A control file specifying what is to be done on a simulation where Filtering is turned on.
Kalman Filtering - A technique for uncovering the values of unmeasured variables.
Level - A variable that changes only over Time.

List - A control appearing in a dialog ( ).


Load - The process of bringing something into the Workbench. Loading a model is only used in off-line mode.
Lookup or Lookup Table - A set of x and y values relating an output to an input. Lookups are used to specify
arbitrary nonlinear functional relationships.
mdl.bat - A batch file used to compile and simulate the model in compiled mode.
mdl.c - Contains the ordered equations representing the equations for your model rewritten in the C language.
mdl.obj Contains a compiled version of mdl.c.
mdl.tmp - A temporary snapshot of the Workbench model that will be used with the simulation. This file is
necessary if you have not saved the Workbench model before beginning simulation, or if the Workbench
model is in Text Edit format. This file may also be created by Vensim upon exiting to speed restarting.
Menu - A list of commands, organized hierarchically, appearing across the top of a window.
Modal Dialog - A dialog that stops you from what you were doing until you complete interaction with it.
Model - A collection of variables or concepts and their logical interconnections. To be simulated a model must
also include equations.
Modeless Dialog - A dialog that allows you to continue with other activities while it remains open.
Mouse - The device used to move the pointer around the screen. This might actually be a trackball or other
device.
NA (:NA: in models)- A special number indicating that values are Not Available.
Object - Something that is visually distinct from the things around it. Objects include words, arrows, letters,
tools, buttons and the vertical lines in graphs used to change time ranges. Objects are important because
they get clicked on, selected and dragged.
Optimization - The process of making things as good a possible. Usually used to mean maximizing a payoff
function for a given simulation model.
Output window - a window containing tool output.
optout.bak - Backup copy of output.prm.
optout.prm - Contains the parameters that give the maximum payoff. This file is always created when the
optimizer is invoked.
Parameter - A synonym for Constant. A variable that is specified as a number.
Payoff - The numerical ranking of a simulation, where more is better.
payoff.prm - The default payoff control file.
payoff.rep - The output file when a payoff report is requested during a simulation.
PC - Personal Computer - used generically to refer to all 80x86 based computers running Windows or Windows

398
NT.
Platform - A computer that Vensim runs on.

Pointer - The shape, (usually some sort of arrow such as ) that moves when you move the mouse.
Polarity - The sign of a causal connection. A plus sign means increasing cause increases the effect.
Powell Search - An optimization search technique.
Preemptive Dialog - A dialog that stops you from what you were doing until you complete interaction with it.
Pressing - Depressing the left mouse button and not releasing it. This is the first half of a click.
Radio Button - A control that allows you to choose between a number of alternatives

( ). Only one radio button in a group can be marked.


Range - See Subscript Range.
readme.txt - A file shipped with Vensim indicating any corrections or changes relative to this manual.
Reality Checks - Combinations of Constraints and Test Inputs that allow you to test the validity of a model
relative to your own understanding of the world.
Residuals - The difference between what a model predicts a variable will be and what the variable is measured
to be.
RGB - Red, Green, Blue.
Scroll - To reposition the contents of a window.

Scroll Bar - . Used to scroll windows. Horizontal scroll bars like


this one scroll left and right, vertical scroll bars scroll up and down.
Select - What you do to activate menu items. You can select a menu item such as Model>Quit by depressing the
left mouse button over "Model" in the menu-bar and dragging until "Quit" is highlighted and releasing the
mouse button. You can also select a menu item by clicking on "Model" in the menu bar, and then clicking
on "Quit" which, along with the other Model commands, will remain visible after your first click on
"Model."
sensitivity.tab - Contains information about the sensitivity of the payoff to different parameters. This file is
created during optimization.
Shift-click - Same as click, except that the keyboard's Shift key is held down throughout the operation.
Shift-drag - S ame as drag, except that the keyboard's Shift key is held down throughout the operation.
sim.dll - The dynamic link library used to run compiled simulations.
Simulatable - A model that can be simulated. Errors will prevent a model from being simulated.
Simulation - Computing values for model variables over Time by using the equations and structure specified
for the model.
Simulation Model - A model that has fully specified equations and can therefore be simulated.
Sketch - A partial visual representation of the structure of a model. Sketches appear in the Sketch tool.
Sketch Editor - The part of Vensim that allows you to build and change model diagrams and equations.
Sketch Toolset - a set of tools for building model in the Sketch Editor. By default these tools appear along the
top of the Sketch.
sortsens.tab - Contains information about the sensitivity of the payoff to different parameters sorted by
importance. Created during optimization.

399
Special time - The time that is used when output is required at a single point in time. The Document, Bar and
Table tools displays values at Special time.
Start time - The earliest time used to analyze datasets. Start time determines where the x-axis on most graphs
and tables begins.
startpoint.dat - Contains the initial optimization points and the corresponding payoffs in a format suitable for
Dat2vdf. Created during optimization.
startpoint.tab - Contains the initial optimization points and the corresponding payoffs in tab-delimited format.
Created during optimization.
Startup - The time when you start Vensim.
State - A variable that changes only over time, see also Level.
stel2ven.exe (stel2ven on Mac) - A utility for converting Stella and ithink models to the Vensim modeling
language.
Structure - The nature of the interactions in a model. The Sketch tool allows you to modify structure.
Simulation uses structure to generate behavi or.
Subrange or Subscript Subrange- A Subscript Range that is completely contained in another Subscript Range.
Subscript - A variable that is applied to another variable to make it stand for one or more distinct things. For
example, country could be applied to population as in Population[country] to indicate
that the model represents more than one country, and that each country has its own population.
Subscript Constant - A variable that represents one instance in a subscript range. Subscript constants are
applied to model variables to specify which, of a number of possible elements, they represent.
Subscript Range - A variable that represents a number of subscript constants. Using a subscript range in an
equation implies that the equation will be computed for each of the subscript constants.
Supplementary - A variable that is not expected to be used, but that is computed because it is useful to know its
value.
System - A collection of interacting components.
Table - A synonym for Lookup (archaic).
Test Input - A variable that describes an alternative definition for another variable to by used in performing
Reality Checks.
Time - The most basic variable underlying a simulation. If time appears in a font other than Courier it has its
normal meaning.
Time Base - A variable that is connected linearly to Time, and can therefore be used as an x-axis.
Tool - A logical device for building and analyzing models.
Toolbar - A collection of icon based buttons that activate a tool or command.
Toolbox - The window from which you choose tools to put on the Workbench. The Toolset>Add Tool
command opens this window.
Toolset - A collection of tools. Toolsets retain tool positioning and configuration information.
trace.dat - Contains values of the parameters and payoff over the course of an optimization in a format suitable
for Dat2vdf. This file is created during optimization.
trace.tab - Contains values of the parameters and payoff over the course of an optimization in tab-delimited
format. This file is created during optimization.
Units or Units of Measure - The manner in which a variable is, or could be, measured (e.g. Miles, Days,
Kilograms).

400
Variable - The basic component of a model.
vector.dat - Contains a list of parameters versus payoffs in a form suitable for use by Dat2vdf. Created during
optimization.
Venapp - A customized model based application built using the scripting language that is part of Vensim DSS.
Venapp can also refer to the Run-time version of Vensim.
vensim.err - The ERRor log file used by Vensim to record errors for the current session. vensim.err is kept in the
same directory as the Workbench model.
vensim.ini - A file used to determine how Vensim starts up.
Warning - A problem detected in a model that does not prevent simulation.
Wildcard - A substitute symbol for something not explicitly identified. Usually a ? or a *.
Window - Something visually distinct appearing on your screen. A window usually has a border around it, and
often has a title bar on top.
Windows - A software program available from Microsoft that Vensim runs under.
Word - A name for a variable or comment appearing in a sketch.
Workbench - The window that displays the model name and contains the active Vensim tools. This window is
always present when Vensim is running.

401
Appendix B — Bibliography

Vensim is a tool for increased productivity and quality in solving complicated


dynamic problems. In this bibliography we will describe background material
helpful for understanding the concepts and techniques behind Vensim.

Building Models

Building models requires that you abstract from real problems to represent them in a
simple mathematical form. For many engineering and technical problems there are
well established methods for doing this. These methods are specific to the problem,
and accessible through literature related to the problem. There is very little
literature on the general theory of technical modeling.
For less well defined problems, especially social problems, a large number of
attempts have been made to give a general coverage of the problem. Many of these
approaches go under the heading of "System Theory" or "General Systems Theory."
In our own view, the most productive approach to these problems has been in a field
called "System Dynamics."
System Dynamics
System Dynamics is a field that resulted from the pioneering efforts of Jay W.
Forrester to apply the engineering principles of feedback and control to social
systems. One of the earliest, and still one of the best references in this field is
Industrial Dynamics by Jay W. Forrester (The MIT Press, Cambridge, MA, 1961).
A simpler introduction to System Dynamics along with a number of exercises, by
the same author, is Principles of System (The MIT Press, Cambridge, MA, 1968).
All of the MIT Press books mentioned in this bibliography (except the one by Gelb)
are available from Pegasus Communications, One Moody Street, Waltham MA
02154-5339 Phone 781 398 9700
A very recent textbook giving a thorough presentation of system dynamics theory
and modeling is Business Dynamics: Systems Thinking and Modeling for a Complex
World by John D. Sterman (McGraw Hill, 2000). An older book that is also clearly
written is Introduction to System Dynamics Modeling with DYNAMO, by G.P.
Richardson and A.L. Pugh (The MIT Press, Cambridge, MA, 1981).
Another useful resource, containing a number of interesting real world examples is
System Enquiry, A System Dynamic Approach by Eric F. Wolstenholme (John Wiley
& Sons, New York 1990). This book also gives a brief introduction to what, in this
manual, is called policy optimization.

402
A very popular and readable book covering many conceptual issues in thinking
systemically about problems is The Fifth Discipline by Peter M. Senge (Doubleday,
New York, 1990).
An interesting and controversial work World Dynamics by Jay W. Forrester (The
MIT Press, Cambridge, MA, 1971; second edition, 1973) discusses growth in a
finite world. This model contained in this book was used in a number of the
examples in this manual, and is included in the models supplied with Vensim
(world.mdl in \models\sample\extra).

Model Analysis

Model analysis is an area with a large literature almost all of which is purely
mathematical. A problem with this literature is that much of it becomes impractical
when applied to any non trivial model. Many of the features in Vensim, such as
causal tracing, were developed in response to the gap between what could be done,
and what was practical.
There are two important types of mathematical, largely statistical, analysis that have
been incorporated in Vensim. These are Kalman Filtering, and Schweppe Statistics.
Filtering and Optimal Control
In the late 1950s there was a revolution in engineering as new techniques were
discovered to improve the control of dynamic systems. The mathematics for this,
now commonly referred to as Kalman Filtering are discussed in Optimal Filtering
Techniques by B.D.O. Anderson and J.B. Moore (Prentice Hall, Englewood Cliffs,
New Jersey, 1979). Another book giving a number of examples of how to use
filtering techniques is Applied Optimal Estimation edited by A. Gelb (The MIT
Press, Cambridge, MA, 1974).

Schweppe Statistics
In parallel to the development of the Kalman Filter, Fred Schweppe developed
robust mathematics for estimating model parameters, selecting among alternative
models, and testing model validity. These mathematics, as it turns out, envelop the
Kalman filter. The book Uncertain Dynamic Systems by F.C. Schweppe (Prentice
Hall, Englewood Cliffs, NJ, 1973) covers the entire field of engineering statistics,
including the new contributions of Schweppe. A more intuitive treatment of these
techniques is contained in "Statistical Tools for System Dynamics" by D.W.
Peterson in Elements of the System Dynamics Method edited by Jørgen Randers
(Chapter 11, pp. 224-241, The MIT Press, Cambridge MA, 1980).
Probability and Statistics
There is nothing the beats a solid foundation in probability and statistics. The two
volume set An Introduction to Probability Theory and its Applications by William
Feller (John Wiley & Sons, New York 1968) is highly recommended. The book
Theoretical Statistics by D.R. Cox and D.V. Hinkley (Chapman and Hall, 1974)
provide a solid theoretical background to statistics and maximum likelihood.

403
Technical Reference

The book Numerical Recipes in C by William H. Press et al has a wonderful


coverage of a wide range of numerical problems including integration techniques,
optimization, random number generation, root finding and Fourier transformation.
A number of the algorithms in Vensim are based on this book.

404
Appendix C — Converting Models

Vensim uses models written in the Vensim modeling language. This language shares certain
characteristics with other modeling languages. For your convenience, we have included translators
from some of these other languages. These translations are somewhat incomplete, but do automate out
most of the drudgery from the translation process.
After you have converted a model you will be left with a set of equations that you can load into
Vensim. If you are using Vensim Standard, you may need to edit the equations using another text
editor to correct any persisting errors. In Vensim Professional and DSS you can use the Text Editor to
correct errors.

Model Interchange Format

There is an ongoing, albeit very slow, effort to try to define an interchange format that will allow
models to be easily moved among the different software products used for system dynamics modeling.
All of the software products clearly have their own nuances and extensions and this is intended to be a
format that captures the bulk of basic system dynamics model structure.
The interchange format will make it easier to move models from one software product to another.

For the present, Vensim comes with two utilities to aid in the importation of models developed with
other simulation packages and those are described here.

Converting DYNAMO Models to Vensim


If you installed the sample models, you will have a utility named dyn2ven.exe that converts DYNAMO
format files to Vensim format. Since the placement of comments and units is more structured in
Vensim than in DYNAMO, there are a number of options for the conversion.
1. A single source file in which the equations are followed by comments (after a space or new line).
The comments end with the units of measure enclosed in parentheses. For example,
A deaths.k=pop.k*drn Total number deaths.(person/year)
2. Same as 1, except the units are at the beginning of the comment,
A deaths.k=pop.k*drn (person/year) Total number deaths.
3. A separate definition file contains the comments, with the equation file containing the units of
measurement,
A deaths.k=pop.k*drn (person/year)
and the definition file containing the definition,
deaths The total number of deaths.
4. Again a separate definition file, but where the units are included in the definition file with the
equation file containing only the equations,
A deaths.k=pop.k*drn
and in the definition file,
deaths The total number of deaths. (person/year)
NOTE In all cases units must be in parentheses.
To invoke dyn2ven at the DOS prompt (this is not a Windows application) type

405
dyn2ven -3 rabbit.dyn rabbit.def rabbit.vmf

where the number -3 corresponds to the format of your DYNAMO model. If no number is specified,
-1 is assumed. If the DYNAMO model contains no comments or units, the first option will still
translate correctly.
On the Macintosh double click on the Dyn2Ven icon and you will be prompted for a file name. When
you select the file you want to convert you will be queried for additional options. Type them in the
same format used for DOS but skipping the first named file.
The conversion process is generally not completely automatic. Some elements (especially
FINAL_TIME, SAVEPER, and INITIAL_TIME) are different. Defaults are put in, but, some
editing is usually required after conversion. To illustrate this, there are three files on the models disk
that you can compare: burnout.dyn, burnout.vm1, and burnout.vmf. The file burnout.vm1 is the
output of the conversion process. It was created using the command
dyn2ven -1 burnout.dyn burnout.vm1

The file burnout.vmf is a working Vensim model. The last few lines differ between these two models,
showing what additional editing was required.

Variable Names
There is a switch in dyn2ven that will allow you to translate comments into variable names. This can
be helpful if the comments are both descriptive and unique. If the comments are not unique this is not
useful at all. To translate comments to variable names follow the format number by a 0 and,
optionally, the number of letters per word, and the number of words to be retained (the default is 3
letters and 6 words). For example
dyn2ven -1046 b1.dyn b1.vmf
would use the first 4 letters of the first 6 words in the comment, while
dyn2ven -10ZZ b1.dyn b1.vmf
would use the entire comment.

Things to Look Out for


Because Vensim macro have a different convention for directly using model variables (that is you must
add the suffic $) look out for macros that use Time, TIME_STEP and possibly other variables as
arguments.
The file dynamo.mac contains macro definitions for functions in Dynamo that are not directly
supported in Vensim. Where possible the translation program will attempt to be sure the arguments
passed are sufficient to comp ute the macros.
Dynamo N equations for Time may not be correctly translated. Initializing time should be done using
an INITIAL_TIME = equation.

Converting Stella® or ithink® Models to Vensim

If you installed the sample models, you will have a utility named stel2ven.exe that converts Stella and
ithink format files to Vensim format.
Vensim does not support the same graphical representations used in Stella and you must therefore save
your Stella model as equations. These equations can then be transferred as a text file to the computer
using Vensim. You will need a file transfer or disk copying utility to do this. Once this is done the
utility stel2ven can be applied, giving the input name and desired output name as in
stel2ven software.stl software.vmf

406
On the Macintosh you can double click on Stel2Ven and then select the file you want to convert. Once
you have done this you will be prompted for more input. Type the name of the output file and any
options you want to use.
Vensim will add default run control parameters (INITIAL_TIME, TIME_STEP, FINAL_TIME,
and SAVEPER) to the converted model but you may need to modify these. You can use the Sketch
tool to reintroduce graphical information and modify structure graphically.
For Stella models the comments and units fields will be left blank. For ithink models saved with
comments, the comments will be read into the Vensim comment field. This process will fail if the
comment contains equation-like material (especially an = sign), so some additional hand correction
may be necessary.
The units field of the Vensim model will be left blank.
Note that ithink equations are not definitive representations of model structure. Because of this the
translation of these models may not be accurate. If you are using ovens, conveyers, uniflows, levels
forced positive or any other non equation structural elements you will need to review the translation
very carefully.
The translation program does provide two switches that attempt to modify level equations to conform
to some forms commonly used in ithink models.
-u forces all rates to be positive (uniflows).
-p keeps all Levels positive no matter what.

Use these switches with care. It is preferable to perform a direct translation and make adjustments as
necessary.
The file stella.mac contains macro definitions for functions used in Stella that are not directly
supported in Vensim.
NOTE Vensim checks for and reports problems such as divide by zero, logarithms of negative
numbers, and overflows. If these conditions exist in your model they will need to be corrected before
you can fully utilize the translated model.

407
Appendix D — File Formats

The equations in .mdl files are stored as plain text and follow the rules for equations
discussed in Chapter 2 of the Reference Manual. Sketch information is also
encoded in a plain text format as described below. The format of .vgd and .vcd, .cin
and other support files is as documented in the reference manuals.
The format of .vmf, .vdf, .vgf, and .vcf files is proprietary and not documented.

Sketch Information

When models are stored in .mdl format the sketch information is appended at the
end. This information is not intended for user modification, but a brief overview of
its structure is useful. Consider the following model:
Comment

Population
births deaths
average lifetime
birth rate
The sketch information for this appears as:
\\\---/// Sketch information - do not modify anything
except names
V300 Do not put anything below this section - it will be
ignored
*View 1
$192-192-192,0,Times New Roman|12||0-0-0|0-0-0|0-0-255|-
1--1--1|-1--1--1|96,96
10,1,Population,275,69,40,20,3,3,0,0,0,0,0,0
12,2,48,91,71,8,8,0,3,0,0,-1,0,0,0
1,3,5,1,4,0,0,22,0,0,0,-1--1--1,,1|(204,71)|
1,4,5,2,100,0,0,22,0,0,0,-1--1--1,,1|(130,71)|
11,5,48,167,71,6,8,34,3,0,0,1,0,0,0
10,6,births,167,90,19,11,40,3,0,0,-1,0,0,0
12,7,48,487,70,8,8,0,3,0,0,-1,0,0,0
1,8,10,7,4,0,0,22,0,0,0,-1--1--1,,1|(441,70)|
1,9,10,1,100,0,0,22,0,0,0,-1--1--1,,1|(353,70)|
11,10,48,397,70,6,8,34,3,0,0,1,0,0,0
10,11,deaths,397,89,22,11,40,3,0,0,-1,0,0,0
10,12,birth rate,99,118,29,11,8,3,0,0,0,0,0,0

408
10,13,average lifetime,508,104,49,11,8,3,0,0,0,0,0,0
1,14,12,6,0,0,0,0,0,64,0,-1--1--1,,1|(130,104)|
1,15,13,11,0,0,0,0,0,64,0,-1--1--1,,1|(445,95)|
12,16,0,269,22,37,9,8,4,0,0,-1,0,0,0
Comment
1,17,1,5,1,0,0,0,0,64,0,-1--1--1,,1|(203,31)|
1,18,1,10,1,0,0,0,0,64,0,-1--1--1,,1|(349,27)|
The first line beginning \\\ marks the beginning of sketch information. This line is
repeated for each view. Only the beginning \\\---/// is significant.
The second line beginning V300 is a version code. Vensim version 4 and Vensim
version 3 both use the same version code (300). Vensim tests this to be sure the
information will be in the expected format. Only the version code itself (V300) is
significant.
The third line beginning with a * names the view. You can use any name you want
subject to the length limitation of 30 characters.
The fourth line beginning $ defines the views default font and color settings. This is
in the format
$iniarrow,n2,face|size|attributes|color|shape|arrow|fill|
background
With
? iniarrow the color of initial arrows or 0.
? n2 a reserved number (16 bit integer) must be 0.
? face the name of the font face as in Times New Roman.
? size the size in points of the font.
? attributes one or more of BUSI for bold underline strike-through and italic.
? color the color of the font. This and all the colors that follow are in R-G-B
format where each of R, G, and B ranges from 0 to 255. The color -1--1--
1 is used to indicate a default color.
? shape the color of shapes.
? arrow the color of arrows.
? fill the fill color for shapes. -1--1--1 is used to indicate no fill.
? background the background color for the sketch. -1--1--1 is used to
indicate that a normal window background should be used.

Objects
The remaining lines till a new \\\---/// marker are all interpreted as objects. Each line
begins with 2 numbers. The first is the object type, the second the object id.
Normally id's begin with 1 and count up, though there may be gaps due to

409
movements and deletions. The interpretation of the information after these two
numbers depends on the first number.

1 - Arrows
The format for an arrow line is
1,id,from,to,shape,hid,pol,thick,hasf,dtype,res,color,fon
t,np|plist
for example
1,3,5,1,4,0,0,22,0,0,0,-1--1--1,,1|(204,71)|
from,to - These are the words the arrow connect (from and to in the direction of
causality). The words are numbers corresponding the id numbers used in the
definition of the words.
shape - determines the shape of the arrow (arc, polyline and so on).
hid - hidden - Indicates whether or not the arrow is hidden.
pol - polarity - this is the ASCII code of the polarity character to be displayed with
the arrow.
thickness - The thickness of the arrow connecting words. Larger than 20 is used for
double parallel lines.
hasf - hasfont - Indicates what if any changes should be applied to the arrow
relative to the sketch default font and color. This is a bitwise or with bit 1 for arrow
color, 2 for polarity color, 4 for polarity size, 5 for polarity attributes and 6 for
polarity face.
dtype - delay type - Used to indicate the delay marking for the arrow.
res - reserved - reserved should be 0.
color - this is the color of the arrow or -1--1--1. The color is only relevant if the
first bit of hasfont is set.
font - A full font or just a color for the polarity or blank. This is only used if
hasfont is bigger than one. Which parts o the font are relevant is determined by
hasfont.
nc - number of points - The number of intermediate points in the arrow. This is
always 1 for arc arrows, but may be more for polyline and perpline arrows.
pointlist - The coordinates of the points. Must be one for each point. In the format
(x,y)|(x2,y2)|...

10, 11, 12, 30, 31- Variables, Valves, Comments, Bitmaps, Metafiles
Variables, valves and comments all have pretty much the same information.
n,id,name,x,y,w,h,sh,bits,hid,hasf,tpos,bw,res1,res2,box,
fill,font

410
where n is 10, 11, 12, 30 or 31 for variables, valve, comments bitmaps and metafiles
respectively.
name - name is the name of the model variable the word represents as in
10,1,Population,275,69,40,20,3,3,0,0,0,0,0,0
In the case of a valve it is a number that will be ignored as in:
11,5,48,167,71,6,8,34,3,0,0,1,0,0,0
In the case of a comment it is just index of the icon for the comment as in
12,7,48,487,70,8,8,0,3,0,0,-1,0,0,0
where the 48th icon is the cloud. The comment index will be ignored if the
comment does not display an icon. Note that the text for comments will appear on
the line that follows the basic comment information if there is text as in:
12,16,0,269,22,37,9,8,4,0,0,-1,0,0,0
Comment
For bitmaps and icons the name is actually a name of a file containing the bitmap or
metafile.
x,y - is the position of the word. All coordinates refer the center of the word. x
increases to the right, and y downward. These are interpreted in pixels.
w,h - width,height - the width and height of the word. Each is actually half the
total value. Subtracting width from x is the left side, adding width to x is the right
side and so on.
sh - shape - the shape around the word. The first 5 bits refer to the shape. The sixth
bit (1<<5) is used to indicate that the word is attached to a valve (or the valve to
another word), the seventh bit is used to indicate that the shape is determined by
type and the 8th bit is reserved.
bits - This is a bitwise or'd value to indicate whether in arrows are allows (bit 1)
and whether arrows can start from the word (bit 2). The third bit is used to indicate
if there is a comment string that will follow on a second line.
hid - hidden - hidden is a flag to indicate whether of not the word is visible in the
normal view state.
hasf - hasfont - indicates whether or not the word has a special font - this is a
bitwise or'd flag. The first bit is set if there is a special box color, the second for a
word color, the third for a fill color, the forth for a font size, the fifth for font
attributes and the sixth for a font face.
tpos - textpos - textpos indicates the position of the word relative to the shape. 0 is
inside, 1 below, 2 left, 3 above, 4 right.
bw - boxwidth - boxwidth indicates the width of the box surrounding the word. 0 is
the default (1 pixel on the screen).
res1 - reserved

411
res2 - reserved
The following may be empty if hasfont is 0.
box - box color - indicates the color of the shape for the word - check hasfont.
fill - fill color - This indicates the fill color for the shape - check hasfont.
font - If the font has face, color or attributes set a font or color will appear here.
NOTE The end of a sketch definition is marked by the end of the file or a new view
starting \\\---///.
Input Output Objects are recorded as comments to allow backward compatibility to
Vensim version 3. The 4th bit in bits is set to indicate it is an Inp ut Output object.
The type of object is recorded in the tpos field and the contents appear in the
comment field in the form varname,action or just action for Custom Graph output
objects.

412
Appendix E — Allocation

Anytime there is a potential mismatch between the amount of something available and the amount that
is desired some sort of allocation needs to be done. Much of the time it is sufficient to just make sure
that the amount used never exceeds the amount available, as is commonly done with shipments from
an inventory. If there are multiple actors involved, however, this becomes more complicated as it is
necessary to decide as it is necessary to decide how much to take from, or give to, each agent.
The allocation functions in Vensim provide solutions to both the one-to-many and the many-to-many
allocation problems. While these solutions do not provide for every possible allocation mechanism,
they are the best that we know of for solving allocation formulations.
The material in this Appendix is relevant in general but the functions discussed are only available in
Vensim Professional and DSS.

Difficulty of Getting a Good Formulation


To illustrate the difficulties of coming up with a good general allocation formulation consider the case
in which there is a single market demand that a number of suppliers are trying to satisfy. This is a
many to one allocation problem.

A common approach to this problem is to assign to each supplier a fraction 'f' of the demand, according
to the simple formula:
f[i] = (a[i]/ sum(a[i!]))
where
f[i] = fraction of demand won by supplier i (in other words, supplier i's market share)

a[i] = attractiveness of supplier i's offering (if price were the only difference among the products, a[i]
might be 1/price[i])
sum(a[i!]) is the sum over all the attractiveness values.

This formula has many desirable properties, but it has a major shortcoming: it is possible for a tiny
supplier to capture the entire market. For example, suppose the demand is the total global demand for
cars. Suppose, further that there are only two competitors: GM, and JoeBob's. GM is a world-wide
giant; JoeBob's is two cousins hand building cars in their garage. If Joe and Bob manage to build a
better car than GM, then the above formula will immediately award a majority of the market to
JoeBob's.
We can overcome this problem in two ways. One would be to include measures of visibility in the
attractiveness number. In that case, JoeBob's product might be best, but its attractiveness would be
tiny, because of lack of word-of-mouth and advertising. This approach is tricky as we are really
overloading the meaning of attractiveness as a surrogate measure for capacity.
As this example suggests, the allocation problem can be quite tricky.

Requirements of a realistic allocation logic


To simplify discussion it is best to think of the allocation problem as trying to match up supply and
demand. Using this terminology, there are five properties that a good allocation formulation needs to
have:
1. Conservation of Matter: The amount received by the demanders (summed across all demanders)

413
must be equal to the amount provided by the suppliers (summed across all suppliers).
2. Nonnegative: All quantities allocated must be positive or zero.
3. Conservation of Intent: No supplier shall provide more than it desired to supply and no demander
shall receive more than it has chosen to demand. (Less, however, is possible).
4. No Loopholes: Under conditions of adequate supply, each demander should receive its stated
demand. Under conditions of adequate demand, each supplier should supply its stated supply.
5. Clear Differentiation: When there is insufficient supply, extremely low priority demanders should
receive little or nothing and extremely high priority suppliers should receive everything or almost
everything. Conversely, when there is excess supply extremely unattractive suppliers should
provide little or nothing and extremely attractive suppliers should provide the bulk of the demand.
6. Continuity: Small changes in priorities, supply and demand should cause small changes in the
resulting allocations. Smoothness, which requires that small changes cause only small changes in
the derivative of the allocations is also often desirable.
With some adjustment and manipulation, the allocation logic in the previous section can be made to pass 1
through 4 above, but getting it to pass 5 is very hard. To come up with a formulation that satisfies all
of these we need to move a little bit beyond simple algebra.

Market Clearing Allocation


One of the principles of economic theory is that price will adjust so that supply and demand match.
This way of thinking about allocation actually turns out to be very useful even for situations where
price adjustment is not used as a market clearing mechanism. To understand this, we start with a pure
supply and demand example and see how the approach can be used to solve the JoeBob versus GM
problem discussed earlier.
Suppose that there are two suppliers with the supply curves shown below:

100
quantity

S2

S1
0
0 10
Price
and that there are two demander with the demand curves shown below:

414
100
D2

quantity

D1

0
0 10
Price

We can find a market equilibrium by adding up the two supply curves to form a market supply curve,
adding up the two demand curves to form a market demand curve, and then finding the point where the
two curves intersect.

demand
100
quantity

supply

0
0 Price 10

Once we find that price, about 7, we just go back to the original supply and demand curves to
determine how much each supplier supplies, and how much each demander demands.
Consider again the original example of car sales. In this case we said that there is some market
demand and we want to determine how it is divided between the two suppliers. Thus we treat the
market demand as constant, determine the price where it intersects the supply curves.

100 d3
quantity

supply

d2

0 d1
0 Price 10

415
If the demand is small, such as at d1, only supplier s2 supplies anything. At demand d2 both suppliers
supply something. If the demand is d3, supply never meets demand so we can’t determine price. It is
clear, however, that both suppliers should supply all they can.
In the earlier section we were talking about priority, and now we are talking about price. While the
two seem related, they are not the same thing. In fact as the example was posed the decision about
what to buy was a decision by demanders based on preference not a decision by suppliers based on
price. However, all we need to do is flip the supply curve and change the label on the x axis to get that
interpretation:

100 d3
quantity

amount demanded
from suppliers by priority

d2

0 d1
0 priority 10

If demand is low (d1), the highest priority suppliers are used. When demand is higher (d2), more
suppliers are used. If the demand is very high (d3) then all suppliers are used to their capacities.
What we have created then, is a graphical way of solving the one-to-many or many-to-many allocation
problem. We can interpret this as either a market based balancing of supply and demand, or a
rationing scheme based on the preferences of the agent being rationed to. The underlying curves can
be made to respect the capacities of the agents, and the preferences of agents can me represented by
selecting different shapes and positions.
This approach is a generalization of the approach and algorithm developed by William T. Wood in the
1980s to solve the one-to-many allocation problem using prioritization curves such as the ones
illustrated above.

Prioritization, Demand and Supply Curves


The curves used to represent prioritizations need to be nonnegative, continuous (no jumps) and
monotone. More specifically, demand/prioritization curves need to slope down and supply curves
need to slope up. In addition, there are two restrictions on shape that, though they are not strictly
necessary for this approach to allocation to work, do make sense.
? There should some priority beyond which the quantity will no longer increase. This might be due
to hard constraints on capacity (for production) or satiation for demand.
? There should be some priority for which the quantity gets very small or actually becomes 0.
Generally this leads to curves that are roughly S shaped and characterized by their midpoint, and the
distance over which they are spread. The set of shapes Vensim makes available are shown in the
following graph:

416
Priority Response Shapes
1

0.75

0.5

0.25

0
0 1 2 3 4 5 6 7 8 9 10
Priority
Retangular
Triangular
Exponential
Normal

Each of these shapes is the integral of the named shape. The integral of the exponential is actually the
symmetric integral from 0 out. The rectangular and triangular distributions have a width of 3. The
shape parameter on the Normal curve is the standard deviation and is set to 1.5 in the above graph.
The shape parameter for the exponential just stretches exp(-priority) and is also set at 1.5.
These shapes provide a pretty good selection of smoothness and contained change. For most purposes
the normal curve has very good behavior. The tails force continuity and always keep all actors active,
just with tiny numbers. This is helpful if you are looking at sensitivities because changes in the
priority of any supplier or demander will not cause a movement from 0 to a significant positive
number as can happen with the rectangular case.
In addition to these shapes Vensim includes a truncated constant elasticity curve. The equation for
constant elasticity is
quantity = A * price?

Where the elasticity ? is positive for supply curves and negative for demand curves. For demand
curves as price goes toward 0, the quantity becomes infinite and this is why the constant elasticity
demand curves are truncated (satiation) at a minimum price and the supply curves are truncated
(capacity) at a maximum price. In most cases these truncations will not matter as the price will be
within the normal range of behavior.

Specifying the Curves


In order to specify the curves to be used for supply and demand we need to tell Vensim the type of
curve, the center, the width or truncation point and in the case of the constant elasticity curves, the
elasticity. Adding to this list the quantity, we could have up to 5 parameters for each curve. To
prevent the resulting explosion of arguments, Vensim uses a Subscript convention to specify the
shapes of the curves. Curves are specified by first a quantity argument, and second a priority argument
that characterizes the curve. The four different attributes of the curve (shape, center, width and
sometimes elasticity), are contained in the final subscript of the priority argument.

417
This is most clearly shown by example:
buyer : us,them
pprofile : ptype, ppriority, pwidth, pextra
demand[buyer] = 20,40
Units: Widget/Month
priority[us,pprofile] = 3,5,2,0
priority[them,pprofile] = 3,7,4,0
Units: Dmnl
We would then use demand and priority to specify the demand curve for us and them. Though
you can use any Subscript Range to represent the priority profile it is probably easiest to use the one
defined above. We have labeled the last element pextra. For the constant elasticity case it will be
the elasticity, but a more general name is used here because we may introduce additional shapes.
The pprofile Subscript must always be the last Subscript. In addition, the Subscript just before it
must be the same as the last Subscript for the quantity argument. During simulation, Vensim will
check to see that this is the case. If it is not a floating point exception will be generated referring you
to the offending equation. This checking is not done during the regular model check.
The type of curve is specified by ptype, and the meaning of the remaining elements depend on this
type. The types are:

ptype 0 – Fixed Quantity


The quantity specified is constant for all priorities (a horizontal line as in the examples above). The
remaining elements are ignored. This may be useful for very special cases but needs to be used with
care as it can easily defeat the purpose of the allocation logic.

ptype 1 – Rectangular
The curve will be shaped as the integral of a rectangle. The ppriority element specifies the
midpoint of the curve and the pwidth element determines the speed with which the curve goes from 0
to the specified quantity. pextra is ignored.

ptype 2 – Triangular
The curve will be shaped as the integral of a triangle. The ppriority element specifies the midpoint
of the curve and the pwidth element determines the speed with which the curve goes from 0 to the
specified quantity. pextra is ignored.

ptype 3 – Normal
The curve will be shaped as the integral of a normal distribution. The ppriority element specifies
the midpoint of the curve (the mean of the underlying distribution) and the pwidth element is the
standard deviation of the underlying distribution. pextra is ignored.

ptype 4 – Exponential
The curve will be shaped as the integral of an exponential distribution that is symmetric around its
mean (0.5*exp(-ABS(x-ppriority)/pwidth) on -? to ? ). The ppriority element specifies the
midpoint of the curve (the mean of the underlying distribution) and the pwidth element is a
multiplier on x in the underlying distribution. pextra is ignored.

ptype 5 – Constant Elasticity


The curve will be a constant elasticity curve. Letting qo be the quantity passed we would have, for a
demand curve:
q(x) = q0 * (x/ppriority)^(-pextra) if x > pwidth

418
q(x) = q0 * (pwidth/ppriority)^(-pextra)if x <= pwidth
Whereas for a supply curve we would have (see below for more discussion on supply/demand):
q(x) = q0 * (x/ppriority)^(pextra) if x < pwidth
q(x) = q0 * (pwidth/ppriority)^(pextra)if x >= pwidth
The important thing to note is that pextra is always a positive number. Passing anything less than or
equal to 0 results in a completely flat curve, that is the same as ptype 0.

Positive Values in Priority Profiles


All of the elements of the priority profile should be positive, though the ptype element can be 0. The
only potential exception to this is pprioroty, which can be negative (except for ptype 5) but even for
this negative values are unlikely to make sense.

Supply versus demand


Supply curves slope up, while demand curves slope down, but you pass Vensim the same type of
information for both supply and demand curves. Vensim determines which type of curve it is from the
function it is passed to. For many-to-many allocation problem, you pass the demand curve, then the
supply curve. For the one-to-many allocation problem the curve passed is always downward sloping,
though it may not always be interpreted strictly as a demand curve.

One-to-many Allocation
One-to-many allocation takes a fixed quantity, the amount available, and allocates it to a number of
requesters. It can be used to allocate a fixed demand among suppliers, and to allocate a fixed supply
among demanders. If you do not want either one of the demand or supply to be fixed you should look
at the section on many-to-many allocation, which allows both supply and demand to vary.
The Vensim function for one-to-many allocation is ALLOCATE AVAILABLE. This function is a
generalization of the older ALLOCATE BY PRIORITY (which is itself an alternative implementation
of the original functions MARKETP and ALLOC P). It takes as its argument the quantity available,
the amounts requested, and priority profiles of the requesters that will be used to do the allocation
should the amounts requested not be satisfied with what is available.
Though there are only 3 arguments to the ALLOCATE AVAIALBLE function, the priority profiles are
passed with an additional subscript as described in the previous section.
To illustrate the use of ALLOCATE AVAILABLE consider the case where a store needs to allocate its
available supply to different branches.
branch : Boston,Dayton,Fresno
pprofile : ptype, ppriority, pwidth, pextra
demand[Branch] = 500,300,750
Units: Widget/Month
priority[Boston,pprofile] = 1,5,2,0
priority[Dayton,pprofile] = 1,7,4,0
priority[Fresno,pprofile] = 1,3,4,0
Units: Dmnl
Shipments[branch] = ALLOCATE AVAILABLE(demand[branch],
priority[branch,ptype],supply available)
Units: Widget/Month
Notice that the priority argument is passed with the first subscript element ptype and not the
subscript range pprofile. The other elements of ppriority will be referenced internally by the
function, but because ppriority does not appear on the left, it can’t appear on the right.
If supply available ramps from 0 to 2000 then the resulting allocations appear as:

419
Shipments
800

600

400

200

0
0 10 20 30 40 50 60 70 80 90 100
Time (Month)
Shipments[Boston] : Current
Shipments[Dayton] : Current
Shipments[Fresno] : Current

If we change ptype to be 3, and cut the pwidth elements to ½ of their values for all of the branches,
we would get:

Shipments
800

600

400

200

0
0 10 20 30 40 50 60 70 80 90 100
Time (Month)
Shipments[Boston] : Current
Shipments[Dayton] : Current
Shipments[Fresno] : Current

By experimenting with the priorities, shapes and widths you should be able to get something that meets
your needs.

420
Multiple Subscripts
You can use ALLOCATE AVAILABLE with multiple subscripts, but the additional subscripts must
all come before those active in the allocation. For example, suppose that for the above example there
are 5 different items that need to be allocated. We would modify the above equations to:
branch : Boston,Dayton,Fresno
pprofile : ptype, ppriority, pwidth, pextra
item : (i1-i4)
demand[item,Branch] = 500,300,750;
50,30,40;
10,100,10;
20,1,40;
Units: Widget/Month
priority[Boston,pprofile] = 1,5,2,0
priority[Dayton,pprofile] = 1,7,4,0
priority[Fresno,pprofile] = 1,3,4,0
Units: Dmnl
Shipments[item,branch] = ALLOCATE AVAILABLE(
demand[item,branch],priority[branch,ptype],
supply available[item])
Units: Widget/Month
Note that the priority values do not depend on the item. If you wanted them to depend on item you
would need equations such as
priority[i1,Boston,pprofile] = 1,5,2,0
and so on.

In the above example the subscript order item,branch is not the natural subscript order. Normally
big things come first, then small things so branch,item would be a more common choice.
However, if you use the subscript order branch,item it won’t work. You can use this in other
model variables but not in the input to the ALLOCATE AVAILABLE function and not for the result.

ALLOCATE BY PRIORITY
The ALLOCATE BY PRIORITY function behaves the same way as the ALLOCATE AVAILABLE
function except that there is no choice on shape, priority is passed as a vector on the subscript being
allocated across and the width is passed as a single parameter common across all subscripts. While
this function will continue to be supported for backward compatibility, its use is not recommended.

Many-to-many Allocation
The many-to-many allocation problem takes the demand preferences of one or more consumers and the
supply preferences of one or more providers and matches these. We will discuss this as finding the
price at which the supply, summed across all providers, equals the demand, summed across all
consumers. If you are working with true supply and demand curves that price is the standard market
clearing price. If you are working with something else, such as matching of capacity and demand based
on service quality, you may need to put a different interpretation on the resulting solution.
To solve the many-to-many allocation problem we first find the price that clears the market with the
FIND MARKET PRICE function. Once this is done we compute the amount supplied by the different
providers using the SUPPLY AT PRICE function and the amount demanded by the different
consumers using the DEMAND AT PRICE function.
supplier : s1,s2

421
demander : d1,d2,d3
pprofile : ptype, ppriority, pwidth, pextra
demand satiation[demander] = 500,300
Units: Widget/Month
Supply capacity[supplier] = 200,300,450
Units: Widget/Month
demand curve[d1,pprofile] = 3,5,2,0
demand curve[d2,pprofile] = 3,7,4,0
Units: $/Widget
supply curve[s1,pprofile] = 3,1,2,0
supply curve[s2,pprofile] = 3,3,4,0
supply curve[s3,pprofile] = 3,5,4,0
Units: $/widget
market price = FIND MARKET PRICE(
demand satiation[d1],demand curve[d1,ptype],
supply capacity[s1],supply curve[s1,ptype])
Units: $/Widget
amount supplied[supplier] = SUPPLY AT PRICE(
supply capacity[supplier],
supply curve[supplier,ptype],
market price)
Units: Widget/Month
amount demanded[demander] = DEMAND AT PRICE(
demand satiation[demander],
demand curve[demander,ptype],
market price)
Units: Widget/Month
The FIND MARKET PRICE function takes everything in and determines the price at which supply
and demand will balance. Note that the variable market price is not subscripted, and that only
Subscript Constants (always the first element) appear on the right. The DEMAND AT PRICE and
SUPPLY AT PRICE functions, on the other hand, use the subscript range demander/supplier
but the subscript constant ptype – just as the ALLOCATE AVAILABLE function did.

Just as for the ALLOCATE AVAILABLE function it is possible to have more subscripts, but these
must come before the demander and supplier subscripts. For example we might have market
price[product] and then we would need demand satiation[product, demander],
demand curve[product, demander,ptype] and so on.

Normally the FIND MARKET PRICE function will be able to find an internal solution at which
demand and supply match. If, however, any of the supply or demand curves are of type 0, then this
may not be the case. If no balance is found the function will return a very low (excess supply) or very
high (excess demand) price. If you are using some fixed demands or supplies you should check for
this and use an ALLOCATE AVAILABLE function to deal with problems of misbalance.

One-to-many with FIND MARKET PRICE


In the above example there were 2 demanders and 3 suppliers. If you only have 1 demander or
supplier you can still use the FIND MARKET PRICE function. You will need to create a subscript for
the one agent such as
demander : d1
The rest works the same.

422
Matching Suppliers and Demanders
In the discussion so far it is important to note that there is only a single product or service represented.
Because of this it does not matter whether demander 1 gets things from supplier 1 or supplier 2. Thus
we can solve for how much each supplier provides and how much each demander gets, but not who
gets what from whom. While this is fine for "commodity" markets, in many cases the supply and
demand connections are important.
We are working on a MARKET MATCH function that will match suppliers and demanders based on
their preferences and capacities. This function will be available in a future Vensim Release.

423
Index

- in causal link 167

&
& runname 345

.
.cin 205
.vgd files 339
.vgd files keywords 348
.vgd files labels 348
.vgd files loaded runs 348
.vgd files nesting 348
.vgd files structure of 348
.vgd files wildcard variables 349
.voc 206
.vsc 205

:
:AND: 62
:END_OF_MACRO: 63
:IGNORE: 177
:IMPLIES: 64
:INTERPOLATE:† 64
:IS: 64
:LOOK_FORWARD: 64
:MACRO: 64
:NA: 25
:NA: 27
:NA: 64
:NOT: 64
:OR: 65
:RAW: 66
:TEST_INPUT: 67
:THE_CONDITION: 67

+
+ in causal link 167

A
A_FUNCTION_OF 71, 182
Absolute Tolerance 215
ABSOLUTE TOLERANCE38
Absolute tolerance scaling257
Absolute value 71
Activating Analysis Tools302
Active Initial Differences 208
Active Links to Spreadsheets222
Active Toolset 300
ACTIVE_INITIAL 71
Adding a Comment 178

424
Adding Tools 301
Additional Files 259
Advanced 206, 391
Advanced Subscript Manipulation.................................................................................................................................... 31
ALLOC_P 74
ALLOCATE AVAILABLE73
ALLOCATE BY PRIORITY73
Allocation 413
ALLOCATION BY PRIORITY..................................................................................................................................... 413
alman filtering 251
Analysis Tools 312
Analysis Toolset 367
ARCCOS 61, 74
ARCSIN 74
ARCTAN 74
Array maximum value of 131
Array minimum value of 131
Array product of 107
Array sum of 122
Arrays
Sorting 127, 130
Arrays entering 29
Arrow Options 152, 153
Arrows in .mdl file 409
Arrows options 166
Arrows reattaching 162
Arrows reshaping 162
As Text 140
As WIP Graph 342
Autocorrelation 320
Automatically Adjusted Step Size.......................................................................................................................... 215, 216
Autosave 391
Auxiliary variables 17, 19

B
B key 267
Background 145
Background for tools 297
Backup files DOS 199
Backup files in Text Editor198
Backup files naming conventions ................................................................................................................................... 199
Bar Graph Time 331
Bar graphs and graphs 333
Bar Graphs as Graphs 333
Bar tool customizing output339
Bars | 212
Based On option 204
Beginning of File 194
Behavior 267
Bibliography 402
Bigger Models 279
Bitmaps in sketch 165
Bottom Menu 10
Boxes around words reshaping ....................................................................................................................................... 163
Breaking a Feedback Loop218
Building Models 402

C
Calibration payoff 247
Causal Models 17
Causal Tracing 309

425
Causal tracing and macros392
Causal Tracing Example 309
Causal tracing in Text Editor198
Causes and subscripts 318
Causes in Document Tool 316
Causes, Initial 319
Causes, Normal 319
Centimeters 392
Change option 205
Changes 212
Changes files 205
Changes files adding comments...................................................................................................................................... 212
Changing Behavior 275
Changing Constant and Lookup Values.......................................................................................................................... 209
Changing Constants 271
Changing Constants from the Toolbar............................................................................................................................ 273
Changing from the Toolbar274
Changing Lookups 274
Changing the Appearance of a View .............................................................................................................................. 162
character encoding 60
Check Model 181, 182
Clipboard 305
Close 363
Closing the Dialog 207
Collapsed links in Tree Tool314
Color in Exported Graphs 384
Color Selection Dialog 374
Color word 145
Commands in Text Editor 194
Commands simulate 203
Comment Entry 347
Comments in Changes files212
Common Keywords 349
Compiled Simulation 393
Computer Platforms 13
Confidence bounds on estimated parameters.................................................................................................................. 252
Consistency views and equations.................................................................................................................................... 134
Constant Changes210, 211, 212
Constant Input Files 212
Constants 19, 20
Constants changing 209
Constants subscripted 29
Continuation Character in .vgd files ............................................................................................................................... 349
Control Panel 368
Control Panel and Subscript Control .............................................................................................................................. 281
Correcting Errors 182
Correcting Units Errors 59
Corrupted Models 60
COS 75
COSH 75
Crossed line in Tree Tool 314
CSV files as changes files 213
CUMULATEF 75
Cumulative graphs 324
Custom Bar Graph 354
Custom Graph Fonts 382
Custom Graphset 290
Custom Report Tool Keywords...................................................................................................................................... 359
Custom Reports 359
Customizing Tools 297

426
D
Dat2vdf on optimizer output259
Dat2vdf time slop 392
Data 221
Data and Lookups 230
Data exogenous 223
Data functions 176
Data input format 222
Data loading as a model 230
Data loading into Vensim 222
Data only functions 61
Data option in simulation 206
Data variables 19
Dataset Analysis Tools 318
Datasets Control in Venapps293
Datasets in .vgd files 348
Datasets loading 363
Datasets on Control Panel 287
Datasets on the Bar Graph356
Datasets reordering 287
Datasets Simulate command365
Defaults for New Views 389
Defined Variables 147
Defined Variables and Shadow Variables ...................................................................................................................... 146
Defining function 61
Delay 77
DELAY BATCH 75
DELAY CONVEYOR 76
DELAY N 78
DELAY PROFILE 79
DELAY_FIXED 76
DELAY_MATERIAL 77
DELAY3 80
DELAYP 81
Delete tool in a sketch 160
Deleting tool output 304
Delimiter matching 173
Delimiters braces {} 195
Delimiters brackets [] 195
Delimiters parentheses () 195
DEMAND AT PRICE 81
Demand Curves 419
DEPRECIATE BY SCHEDULE...................................................................................................................................... 81
DEPRECIATE STRAIGHTLINE.................................................................................................................................... 82
Depth of tree diagrams 314
Diff and Active Initial 208
Difference Integration 214
Differences Between the Macintosh and PC................................................................................................................... 13
Dimensionless Synonyms 48
Disjoint lines 392
Displaying the Dataset Name346
Dmnl 48
Do you want to correct syntax errors................................................................................................................................ 51
Document Options 315
Dots Only 320
Driving Noise and Initial State Covariance .................................................................................................................... 260
DSS Reference Supplement 9
Dynamic functions 61
DYNAMO model conversion405
dynamo.mac 406

427
E
Elaborate Subscript Control292, 293
ELMCOUNT 83
Empty tool in a sketch 149
encoding 60
End time changing 285
endpoint.dat 259
endpoint.tab 259
Enlarging SyntheSim Graphs267
Equation Editor 48, 170, 337
Equation Editor anatomy of170
Equation Editor starting 170
Equation Editor starting from a sketch ........................................................................................................................... 168
Equation empty 25
Equation Format and Conventions.................................................................................................................................... 23
Equation Missing 25
Equation Order 21
Equation Ordering 18
Equations
simultaneous 55
Equations active simultaneous .......................................................................................................................................... 56
Equations formatting 316
Equations Options 161
Equations punctuation in 51
Equations simultaneous initial condition .......................................................................................................................... 56
Equations subscripted 179
Equivalence 35
Error Checking Order 48
Error Checking Sequence 49
Error Line in Equation Editor180
Error messages 50
Error Report Window197, 198
Errors
semantic 183
Errors fatal 377
Errors program 377
Errors syntax 196
Errors used-not computed 52
Euler Integration 214
Example 234
Examples 250
Existing Variable Options157
EXP 83
Exponential distribution114, 115
Export Dataset Example 232
Export Options 305
Export Printer Ready384, 392
Exporting Datasets 230
Extrapolating lookups 70

F
far-eastern 386
Fatal and Program Errors377
Fatal Errors 377
Feedback loops breaking for simulation ......................................................................................................................... 218
File Format 243, 246, 348
File Formats 408
Files Constant Input 212
Files old versions 199
Files selecting 372

428
Filtering 260
Filtering and Optimal Control403
Filtering option 206, 251
FINAL_TIME 37
Find in Text Editor 190
FIND MARKET PRICE 83
FIND ZERO 84, 85
Fixing Models 60
Floating Point Overflows 208
Font 145
Font sketch defailt 143
Fonts 380
Fonts for tools 381
Fonts printer 392
Fonts Selection Dialog 375
Fonts2 382
For Constant 19
For Variable 19
FORECAST 86
Foreground for tools 297
Formatting of equations 316
Formulation 413
Fourier Transform 320
Freezing Levels 277
Function data only 61
FunctionKeyDescription 195
Functions and Keywords 61
Functions data 176
Functions defining 61
Functions dynamic 61, 176
Functions simple 61
Functions summary 62

G
GAME 86
Game Interval 203
GAME INTERVAL 38
Gaming size of .vdf file 203
GAMMA LN 87
Gannt Chart Options dialog335
Gantt Chart tool 334, 336
General Navigation 11
GET 123 CONSTANTS 87
GET 123 DATA 87, 88
GET 123 LOOKUPS 88
GET DATA AT TIME 89
GET DATA BETWEEN TIMES...................................................................................................................................... 89
GET DATA FIRST TIME 89
GET DATA LAST TIME 90
GET DATA MAX 90
GET DATA MEAN 90
GET DATA MIN 90
GET DATA STDV 91
GET DATA TOTAL POINTS.......................................................................................................................................... 91
GET VDF CONSTANTS 91
GET VDF DATA 92
GET VDF LOOKUPS 93
GET XLS CONSTANTS94, 95, 270, 378
GET XLS DATA 95, 96, 378
GET XLS LOOKUPS 96, 97
Ghost variables 134

429
Global Options Dialog314, 380
Global Options dialog and time slop............................................................................................................................... 228
Glossary of Terms 395
Got a model with no real variables ................................................................................................................................... 51
Graph Control 342
Graph Divisions time axis 285
Graph Labeling and Control354
Graph Options dialog 324
Graphics 165
Graphs adding comments 371
Graphs and bar graphs 333
Graphs Fourier 320
Graphs line types 324
Graphs maximum per window........................................................................................................................................ 320
Graphs named 342
Graphs x-axis divisions 325
Graphs x-axis labels 325
Graphs X-gap 392
Grid search in optimizer 254
Grid sensitivity 244
Group 19
Group creating 178
Group in Equation Editor 178
Groups 39, 40
GTX 307

H
Hierarchy in .vgd files 348
Historgrams 331
History files 199
History files DOS 199
Hover 387

I
Icons in sketch 165
IF_THEN_ELSE 97
Ignoring Variables 219
Imporing data into Lookups184
Inches 392
increment 23
INITIAL 19, 97, 98
Initial Causes 313
Initial Causes in sketches 46
Initial Sizes 389
INITIAL TIME 43
INITIAL_TIME 37
Input Modes 276
Input Output Controls with SyntheSim........................................................................................................................... 279
Input Output Object 155
INTEG 98
INTEGER 98
Integral and Differential Equations................................................................................................................................... 16
Integration Technique204, 213
Interacting With Models 196
INTERNAL RATE OF RETURN...................................................................................................................... 98, 99, 100
Interpreted simulation 393
Interrupting Simulations 209
Interval for gaming 203
Introduction 8
INVERT MATRIX 100

430
K
Kalman Filtering 206, 251
Keeping Results from SyntheSim ................................................................................................................................... 271
Keywords in .vgd files 348
keywords in graph descriptions....................................................................................................................................... 349
Keywords in Graph tool 349
Korean 387

L
Label and Scaling Keywords358
Labels
suppressing 349
Labels in .vgd files 348
Labels tool icon 297
Landscape mode 371
Legend suppressing 350
Level initial conditions 72
Level initialization 72
Levels 17, 20
Likelihood viewing 255
Line numbers in Text Editor192
Line types 320, 324
Linear Interp 320
Lines disjoint 392
Links showing 319
List Reorder Dialog 375
Locking Tools 301
Locking windows 304
LOG 100
logarithms 100
Lookup Changes 211
Lookup Editor from text editor....................................................................................................................................... 191
Lookup functions 68
Lookup in replicate 137
LOOKUP INVERT 102
LOOKUP SLOPE 102
Lookup Table 19
Lookup used directly 131
LOOKUP_AREA 101
LOOKUP_BACKWARD101
LOOKUP_FORWARD 102
Lookups 71
Lookups adding points 185
Lookups extrapolating 70
Lookups extrapolation 101
Lookups horizontal scaling185
Lookups importing data 184
Lookups in Equation Editor175
Lookups overruns 207
Lookups units 69
Lookups when Pasting 137
Lookups, changing 205, 212
Loops Tool 318

M
Macintosh 13, 14, 384
Macintosh Notes 372
Macro variables in causal tracing.................................................................................................................................... 392
Macros 40
macros built in 176

431
M acros definitions 41
Macros in Equation Editor41, 177, 186
Macros names 42
Magic Wand solid 159
Main menu commands 362
Main Toolbar 369
Making Changes with the Equation Editor..................................................................................................................... 171
Managing Data 228
Many -to-many allocation 421
Mark on printed graph 325
Market Clearing Algorithm414
MARKETP 103
Matching delimiters in Text Editor................................................................................................................................. 195
Matching Suppliers and Demanders ............................................................................................................................... 423
Mathematical Foundation 16
MAX 103
MAX TIMES 38
Menus and Common Dialogs 362
MESSAGE 104
Message Boxes 377
Metafiles 305
Metafiles in sketch 165
MIN 104
Min Max in Equation Edit tool ....................................................................................................................................... 178
Minimum in Stats tool 330
Mips While You Sleep (MWYS) .................................................................................................................................... 254
Miscellaneous Tools 337
Model Analysis 403
Model Capacities 12
Model Errors 278
Model Interchange Format 405
Model Settings 43
Model>Edit command 188
Modeling Guide 8
Models converting to other simulation languages .......................................................................................................... 405
Models errors in 43
Models loading 363
Models simulating 207, 237
Models startup 386
Mouse Movement Terminology ........................................................................................................................................ 14
Moving Among Output Windows................................................................................................................................... 305
Moving Points 186
Multiple Equations 29
M VSS 216, 239

N
NA 256
NA in range 178
Navigation 168
Nesting in .vgd files 348
NET PRESENT VALUE104, 105
Next View 145
Noise in Active Variables 243
NOISE SEED 38
NO-LEGEND 349
Normal Causes 313
Not Defined 19, 53, 54, 183
Notes on Sketch Behavior133
Notes on Text Edit Behavior188
NPV 106
NPVE 106

432
Numbers pretty format 327

O
Object Ordering 145
Objects 409, 412
One-to-many Allocation 419
Operators 24, 25
Optimization 248
Optimization Control 249
Optimization Output 258
Optimization random starting points............................................................................................................................... 254
Optimization resuming 259
Optimization turning on 251
Optimization Without Filtering..................................................................................................................................... 265
Optimization, interrrupting253
Optimizing Everything 266
Options 378
Options for PLE and PLE Plus ....................................................................................................................................... 378
optout.prm 248, 258, 259
Ordering of objects 145
Outline Options 315

P
Parameters changing 205
Parentheses 314
Parenthesis delimiters () matching.................................................................................................................................. 173
Parenthses () 314
Partial Model Simulation 217
Partial Simulation 366
Password 44, 45
Pausing Simulations 38
Payoff 244, 245, 246
Payoff calibration 244
Placeholder Values 219
Placeholders 291
Plural for units 48
Plural in units 58
Polarity of causal connection167
Policy Payoffs 246
poppyr.mdl 358
Population Pyramids 357
Portrait mode 371
Powell optimization 252
POWER 106, 107
ppriority 418
Pretty Number format 327
Print Options setting 372
Printing 370
Printing color 372
Printing comment position371
Printing comments 371
Printing graphics scaling 370
Printing orientation 371
Printing size 371
Printing time and date 371
Prioritization
Demand and Supply Curves ..................................................................................................................................416
Probability and Statistics 403
Problems with Variable Types.......................................................................................................................................... 51
profiles 419
Program Errors 377

433
Publishing a Model 12
PULSE 107, 108

Q
QUANTUM 108
Query Boxes 376
QUEUE AGE AVERAGE108
QUEUE AGE IN RANGE109
QUEUE AGE OLDEST 109
QUEUE ATTRIB AVERAGE........................................................................................................................................ 110
QUEUE ATTRIB IN RANGE........................................................................................................................................ 110
QUEUE ATTRIB MAX 110
QUEUE ATTRIB MIN 110
QUEUE ATTRIB QUANTITY...................................................................................................................................... 111
QUEUE FIFO 111, 112, 113

R
RAMP 113
Random in sensitivity simulation.................................................................................................................................... 242
Random numbers in sensitivity....................................................................................................................................... 242
Range in Equation Editor 178
Range violations 207
Ranges 40
Ranges modifying 178
rank
sorting 127
Rates 153, 154, 155
RC COMPARE 115, 116
RC COMPARE CHECK 115
RC DECAY 115
RC DECAY CHECK 115
RC GROW 115
RC GROW CHECK 115
RC RAMP 115, 116
RC RAMP CHECK 115
RC START TIME 38, 39
RC STEP 115, 116, 117
RC STEP CHECK 115
Readme Notes 9
Reality Check 338
Reference Manual 8
Reform and Clean menu command................................................................................................................................... 60
Reforming and Cleaning Models ...................................................................................................................................... 60
REINITIAL 117
Relative Tolerance 215
RELATIVE TOLERANCE38
Renaming subscripts 179
Replace String in Text Editor191
Replace Var in Text Editor191
Replacing Clouds 159
Requirements of a realistic allocation logic .................................................................................................................... 413
Rescaling Views 142
Resume option 205
Rounding on graph scales 285
Run Name option 204
Run Venapp 190
Runge Kutta and SAMPLE IF TRUE............................................................................................................................. 118
Running a Game 202
Runs Compare 336, 337

434
S
SAMPLE IF TRUE and RK integration ......................................................................................................................... 118
SAMPLE_IF_TRUE 117
Save As 189
SAVEPER 37, 44
Saving 307
Scaling 284
Schweppe Statistics 403
Search and Replace 193
Search parameters for optimization................................................................................................................................ 248
Sectors running separately 19
Selected subscripts 303
Selecting a Time Range 308
Selecting in Text Editor 193
Selecting Text 193
Selecting the Time Range 201
Selecting the Variable Type173
Sensitivity 205
Sensitivity Graph Options322
Sensitivity histograms 331
sensitivity.tab 253, 258, 259
Set 207
Setting Slider Bounds 272
Settings 365
Shadow variables defined 147
Shape 166
Shape around word 163
Shape Color 145
SHIFT IF TRUE 118
Simple functions 61
Simulating 262
Simulating from a sketch 168
Simulating from the Toolbar201
Simulating Incomplete Models ....................................................................................................................................... 218
Simulating with a Save List239
Simulation 201
Simulation Control Parameters ......................................................................................................................................... 37
SIMULATION PAUSE 38
Simulation Speed 38
Simulation Time with filtering........................................................................................................................................ 266
Simulations compiled 393
Simulations interpreted 393
Simultaneous Equations and subscripts............................................................................................................................ 55
Simultaneous Equations fixing......................................................................................................................................... 56
SIMULTANEOUS Function56, 57
SIN 118
SINH 119
SINTEG 119
Size of graphs 324
Sizing windows 305
Sketch 388
Sketch and Analysis Tools295
Sketch and database 169
Sketch and Sketch Defaults387
Sketch Comment 156
Sketch definition 135
Sketch free form 169
Sketch Information 408, 409
Sketch information in Text Editor .................................................................................................................................. 198
Sketch rescaling 142
Sketch tool starting 133

435
Sketch Tool window layout146
Sketch Tools 148, 296
Sketch Workbench Interactions ...................................................................................................................................... 168
Sketches and Equation Editor187
Sketches and Equations 135
SMOOTH 79, 120
SMOOTH N 119, 120
SMOOTH3 121
Soft Bounds 342
SORT 130
sorting 130
sortsens.tab 254, 259
Source of Units Check Errors58
Spacing in Changes file 212
Special Interpolation Modes71
Special time changing 285
Special Variable Names 38
Specifying Data Sources in the Simulation Control Dialog......................................................................................... 229
Specifying Units 177
Speed
Simulation 38
Splitting Arrows 159
Spreadsheets and constant changes ................................................................................................................................. 212
Spreadsheets getting data from ......................................................................................................................................... 27
Square root 121
Stack graphs 324
Stamp on printed graph 325
Start time changing 285
Starting SyntheSim 269
Starting the Optimization 250
startpoint.dat 258, 259
startpoint.tab 258, 259
Startup 386, 387
Startup model 386
Startup Settings dialog 47
Stats tool 329, 330
Status Bar 10
stella.mac 406
STEP 121, 122
Stopping SyntheSim 269
String Constants 19
Structural Analysis Tools 312
Subranges 32, 33
Subscript Constant 19
Subscript Constants175, 291, 303
Subscript equivalence 35
Subscript Errors 53
Subscript Functions 30
Subscript Issues 272
Subscript Range 20
Subscript Ranges 175, 303
Subscript Ranges and subranges ..................................................................................................................................... 291
subscripted constants 29
Subscripted Lookups 274
Subscripted variables in .vgd files .................................................................................................................................. 349
Subscripting Constants 29
Subscripts 28
Subscripts and sketches 28
Subscripts and SyntheSim Graphs.................................................................................................................................. 268
Subscripts family mismatches52
Subscripts in Equation Editor175, 186
Subscripts in Savelists 237

436
Subscripts mapping 33
Subscripts numeric ranges 31
Subscripts renaming 179
Subscripts selected 303
Subscripts selecting from graphs .................................................................................................................................... 334
Subscripts selecting to Workbench ................................................................................................................................. 307
Summary List of Functions61
Supplementary 23
Supplementary in Equation Editor.................................................................................................................................. 173
SUPPLY AT PRICE 122
Supply Curves 419
Symbol Conventions 14
Synonyms for units 48
Synonyms units 47
Syntax Errors 50, 196
Syntax Errors and the Text Editor..................................................................................................................................... 50
Syntax errors automatic reporting................................................................................................................................... 196
Syntax Errors in a .mdl File51
Syntax Errors in Equation Editor.................................................................................................................................... 182
SyntheSim 9, 267
SyntheSim Toolbar 269
System Dynamics 402

T
Tab Delimited Data 224
Tab Delimited Files as changes files............................................................................................................................... 213
TABBED ARRAY 123
Table 19
Table customizing output 358
Tables 183
TAN 123
Technical Reference 404
Text Edit tool 188
Text Editor 49, 337
Text Editor Entrain toggle option ................................................................................................................................... 195
Text Editor replacing strings 191, 195
Text Editor replacing variable names ............................................................................................................................. 191
Text Editor replacing variables ....................................................................................................................................... 196
Text Editor searching in 195
Text Editor Tool Options 188
Text Editor Using a mouse193
Text for Reports 360
The Analysis Tools 296
The Custom Table Editor 346
The Layout Menu 144
The Status Bar 192, 193
The View Menu 192
Thresholds 390
Tilde ~ 212
Tildes ~ 212
Time Axis 270
Time Axis Divisions 286
Time Base 19, 39
definition 123
Time base changing 284
Time Base in data entry 223
Time Base name 223
Time Range 347
Time range changing 284
Time shifting 27
Time Slop 228, 392

437
TIME STEP 44
TIME_BASE 123
TIME_SHIFT 124
TIME_STEP 37, 38
TIME_STEP choice 214
TIME_TRANSITION 124
Title
Supressing 349
Tool Activation and on-line model................................................................................................................................. 168
Tool instances 304
Toolbars 390
Tools
Strip Graph318, 319, 320, 321
Tools aligning 298
Tools background 297
Tools Bar Graph 330
Tools foreground 297
Tools Graph 323
Tools icon labels 297
Tools menus 304
Tools names 297
Tools sketch 133
Tools Table 326
Tools Tree Diagram 313
Toolset Editor 299
Toolsets 295
Toolsets deleting tools 301
Toolsets Menu 298
Toolsets moving tools 301
Toolsets saving 298
ToolTip graph 267
trace.dat 259
trace.tab 259
Tracing Lines 186
TREND 124
Types showing 319
Typographic Conventions14

U
Unchangeable Constants20, 30
Undo/Redo 136
Units 21, 22, 386
Units adding equivalences 58
Units and Lookup Functions59
Units and lookups 58
Units Check 337
Units Check error window 57
Units Checking 57
Units Checking in Document Tool ................................................................................................................................. 316
Units plural 58
Units removing extra 60
Units Synonyms 47, 48
Unnamed 362
USE FLAG 183
Used but Not Defined 54
Uses and subscripts 318
Using Lookups 69
Using Output Files 259
Using the Keyboard 272
Using the Text Editor 188
UTF-8 60

438
Utility Dialogs 372
Utility windows 370

V
Valves 148
Variable Entry 347
Variable names in parentheses ........................................................................................................................................ 314
Variable names replacing 196
Variable Options 150
Variable Selection 168, 281
Variable Selection Dialog307, 374
Variable Selection from sketch tool................................................................................................................................ 146
Variable types in Equation Editor................................................................................................................................... 187
Variable types missing 52
Variable types showing 327
Variables 19, 20
Variables adding to sketch145
Variables in Reports 360
Variables mixed 31
Variables multiple on a graph324
Variables Naming Rules 20
Variables selecting by type283
Variables selecting with wildcards ................................................................................................................................. 282
Variables starting values 98
Variables types 19
Vcd Files in editor 190
VECTOR ELM MAP 32, 125
VECTOR LOOKUP 127
VECTOR RANK 127
VECTOR REORDER 127
Vector Search graphs 255
Vector search in optimizer254
VECTOR SELECT128, 129, 130
VECTOR SORT ORDER130
vector.dat 259
Venapp Editor 338
Vensim DLL 12
Vensim Documentation 8
Vensim DSS 12
Vensim Manuals 369
Vensim Model Reader 12
Vensim Modeling Language 16
Vensim Overview 9
Vensim PLE 11, 12
Vensim PLE Plus 12
Vensim Professional 12
Vensim Software 11
vensim.err 368
Ventana Graph Description file ...................................................................................................................................... 339
View rescaling 142
View/Edit/Layout Menus 364
View>Behavior 267
View>New command 142
Views adding variables 161
Views consistency 134
Views defined 134
Views interactions 134
Views selecting 145
VMAX 131
VMIN 131

439
W
Warnings 392
Warnings in simulations 207
Wildcard datasets 349
Wildcard variables 349
wildcards 282
Windows Strip graph 321
Windows>Clear Screen command.................................................................................................................................. 304
WIP 209
WITH LOOKUP 131
Word Color 145
Word Position 144
Word-and-arrow models 135
Words joining 163
Words moving in view 162
Workbench Var adding to sketch.................................................................................................................................... 145
Work-in-Progress 209
Wrapping Text 163
Written Response Dialog 374

X
X_IF_MISSING 132
X-Axis 340, 341
X-axis labels 325
X-gap 392
XIDZ 132
XY Graphs 343

Y
Y Scale zooming in 309

Z
ZIDZ 132
Zoom 141

440

You might also like