table of contents - pudn.comread.pudn.com/downloads162/doc/739322/vensim... · specifying the group...
TRANSCRIPT
1
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 MAP 32 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
2
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
3
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
4
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
5
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
6
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
7
8
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.
9
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
10
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
MainToolbar
SketchToolset
AnalysisToolset
ToolOutput
StatusBar
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
11
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
12
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.
13
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.
14
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.
15
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.
16
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.
(1) ??T
tt dtrateslevels0 or
tt rateslevelsdtd
?
(2) ),,,( constdataauxlevelsgrates tttt ?
(3) ),,,( constdataauxlevelsfaux tttt ?
(4) ),,,( 0000 constdataauxlevelshlevels ?
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:
(3a) 0),,,( ?constdataauxlevelsf ttt
17
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:
pricesales
inidicatedprice
target revenue
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).
18
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.
price
sales
inidicatedprice
target revenue
AverageSales
time to average sales
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
19
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
20
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 _.
21
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).
22
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:
Equation
Units
Supplementary Flag
********************.Finance********************~|{. . . intervening equations . . .}
net income = taxable income - taxes~$/year [0,1E9]~The flow rate of income accruing….
~:SUP |
Group(by position)
Range
Comment
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:
23
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
24
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):
25
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 ~~|
26
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.
27
|
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.
28
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
29
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~|
30
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.
31
Example 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:
32
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
33
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
34
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
35
~ 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. |
36
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
37
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
38
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.
39
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.
40
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.
41
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:
42
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.
43
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.
44
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.
45
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.
46
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
47
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-clicking 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.
48
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.
49
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
50
"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:
51
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.
52
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] ~~|
53
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
54
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.
55
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 ~|
56
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
57
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:
58
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
59
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:
60
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.
61
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
62
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
63
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
64
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 (Chapter
2). :NOT: Logical NOT (Chapter 2). NPV(S,D,I,F) Net Present Value of S with discount rate D starting at
65
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 by 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
66
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
67
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 input 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.
68
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:
69
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:
70
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
71
|
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.
72
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
73
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
74
~ 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.
75
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) ?
76
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)
77
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 t ime 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
78
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
79
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.
80
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)
81
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.
82
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
83
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.
84
See also: ALLOCATE AVAILABLE, DEMAND AT PRICE, SUPPLY AT PRICE, Appendix E.
Examples
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.
85
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]
86
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
87
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
88
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.
89
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.
90
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.
91
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 number 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.
92
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
93
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.
94
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
95
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.
96
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.
97
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
1 X 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 start ing value.
98
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
99
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
100
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.
101
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))
102
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
103
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.
104
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
105
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.
106
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).
107
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 must 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.
108
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.
109
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
110
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.
111
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
112
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 ATTRIBute
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))
113
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.
114
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.
115
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
116
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.
117
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)}
118
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
119
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..
120
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
121
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 input10
7.5
5
2.5
00 10 20 30 40 50 60 70 80 90 100
Time
S - CURRENTSS - CURRENTSSI - 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:
122
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.
123
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.
124
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
125
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.
126
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
127
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.
128
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;
129
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
130
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.
131
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.
132
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.
133
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.
134
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.
135
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.
136
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
137
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.
138
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.
139
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.
140
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.
141
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.
142
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.
143
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).
144
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
145
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
146
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.
147
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:
fraction sales sailfraction sales phone
sales by sailsales by phonesales by mail fraction sales mail
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:
148
fraction sales sailfraction sales phonefraction sales mail
sales by sailsales by phone
sales by mail
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 risespeople becometired and make
mistakesqualityovertime
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.
149
? 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.
150
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.
151
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
152
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.
153
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 inProgress
FinishedInventory
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.
154
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.
155
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
156
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.
157
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
158
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:
crowdingLAND AREA
<POPulation>
using population as an exogenous input and the second computes population.
populationbirths deaths
If you replicate the second into the first you get:
crowdingLAND AREA
<POPulation>
population 0births 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:
crowdingLAND AREA
populationbirths deaths
159
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.
160
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.
161
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.
162
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.
163
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.
164
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.
165
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
166
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.
167
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:
population births++
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.
168
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.
169
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.
170
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.
171
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.
172
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.
173
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.
174
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.
175
(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.
176
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.
177
? 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.
178
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.
179
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.
180
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.
181
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.
182
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 + ?)
183
(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."
184
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
185
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
186
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.
187
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.
188
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.
189
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.
190
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.
191
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.
192
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.
193
>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:
194
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.
195
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
196
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 in 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 l ine for the Text Editor will give you more details about the exact nature of the syntax error.
197
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.
198
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.
199
- (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
200
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.
201
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.
202
? 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
203
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.
204
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
205
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.
206
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
207
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.
208
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 s imultaneous 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 nextSAVEPER.
209
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
210
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.
211
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.
212
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.
213
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.
214
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~~|
215
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|
216
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.
217
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 Population800
400
00 5 10 15 20 25 30 35 40 45 50 55 60 65 70 75 80 85 90 95 100
Time
Population - GAME RabbitPopulation - 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.
218
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:
FRACTION REV SALES
TIME TO ADJUST SALES FORCE
WAGE RATEPRICE
sales force effectivenessavailability of alternatives
value of innovation
InstalledProduct
indicated sales forcesales force
revenueproduct sales
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 ~|
219
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
220
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.
221
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.
222
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:
223
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
224
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:
225
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:
226
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).
227
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
228
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.
229
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.
230
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:
cost
revenue profit
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:
231
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.
232
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
233
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.
234
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 t ime. 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
235
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
236
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.
237
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
238
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
239
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.
240
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
241
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.
242
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.
243
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
244
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.
245
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
246
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
247
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
248
*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.
249
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.
250
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.
251
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.
252
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,
253
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
254
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
255
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.)
256
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.
257
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.
258
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
259
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.
260
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.
261
workforce
des workforce
net hiretime adjust workforce
des production
net hire noise
exp sales
inv correction
sales
TIME AVG SALES
productivity noise
inventory
time correct inventory
des inventory
productivity
inventory coverage
production
meas inventory
inventory meas noise
meas workforce
workforce meas noise
norm productivity
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
800 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.
262
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:
263
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.090 10 20 30 40 50 60 70 80 90 100
Time (month)
Actual Inventory (data.vdf) widgetMeasured Inventory (data.vdf) widgetSimple Simulation (simple.vdf) widgetKalman 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:
264
Actual Inventory versus potential measurement434.52
388.19
341.86
295.52
249.1980 82 84 86 88 90 92 94 96 98 100
Time (month)
Actual Inventory (data.vdf) widgetMeasured Inventory (data.vdf) widgetSimple Simulation (simple.vdf) widgetKalman 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.250 10 20 30 40 50 60 70 80 90 100
Time (month)
Actual Inventory (data.vdf) widgetSimple simulation (simple.vdf) widgetFilter 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.
265
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
266
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.
267
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:
268
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.
269
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.
270
Changes Controls (Not PLE or PLE Plus)
Save Constant/Lookup Settings to a file a llows 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.
271
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.
272
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:
273
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:
274
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)
275
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:
276
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).
277
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
278
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.
279
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
280
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.
281
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
282
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.
283
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
284
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.
285
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
286
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 (Raw 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.
287
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.
288
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 you loaded from to make it easier to load multiple datasets from another directory.
Graphs
or in Vensim PLE
289
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
290
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)
291
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
292
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.
293
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.
294
295
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 functions. 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 Equation Editor can be used from both the Sketch Tools (acting as a drill) and the Analysis Tools (acting as a drill press).
296
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
297
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.
298
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.
299
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.
300
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
301
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.
302
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
303
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 Subscript 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.
304
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.
305
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.
306
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 cost8 M
6 M
4 M
2 M
00 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:
307
Graph for total cost8 M
00 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
308
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.
309
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 workforce200
800 10 20 30 40 50 60 70 80 90 100
Time (month)
workforce - Step person
310
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.
? ?
? ?
? ?
311
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.
312
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.
313
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
314
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
315
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.
316
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.
317
? 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
318
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.
319
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):
320
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.
321
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.
322
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.
323
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.
324
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
325
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.
326
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.
327
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.
328
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.
329
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
330
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 displays 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.
331
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 values 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-
332
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.
333
Currenttruncated normal noise - time histogram
200
150
100
50
00-1
1-22-3
3-44-5
5-6
6-77-8
8-9
9-1010-11
11-12
12-1313-14
14-15
15-1616-17
17-18
18-1919-20
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:
Currenttruncated normal noise - time histogram
0.2
0.15
0.1
0.05
00-1
1-22-3
3-44-5
5-6
6-77-8
8-9
9-1010-11
11-12
12-1313-14
14-15
15-1616-17
17-18
18-1919-20
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.
334
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.
335
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
336
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.
337
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.
338
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.
339
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).
340
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
341
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.
342
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.
343
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
200100 102 104 106 108 110 112 114 116 118 120
workforce
inventory : step widget
Can be created using the definition:
344
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
200100 105.8 111.5 117.3 123
workforce
inventory : step widgetinventory : 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:
345
Workforce/Inventory with Inventory Correction @ 4 and 2400
200100 105.8 111.5 117.3 123
workforce
inventory : step widgetinventory : 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:
346
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
347
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.
348
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.
349
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.
350
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.
351
: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.
352
: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:
353
Base run from the WORLD model.10 B Capital units
1e+012 Resource units2 Satisfaction units
6 B People40 B Pollution units
0 Capital units0 Resource units.4 Satisfaction units0 People0 Pollution units
1900 1930 1960 1990 2020 2050 2080Time (Year)
Capital - base Capital unitsNatural Resources - base Resource unitsquality of life - base Satisfaction unitsPopulation - base PeoplePollution - 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]
354
: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
NoneNot Much
Lots
Early Now A century laterDuring 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-BY-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 t ime 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.
355
: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
356
: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 QualityImproved Quality Control
A Simple bar graph of cumulative cost
0 50 M 100 M 150 M 200 M
Design
Production
Testing
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
357
Task DefinitionWork Completed
Work Done
0 150,000 300,000 450,000 600,000
Task1
Task2
Task3
Task4
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:
CurrentPopulation Pyramids
Female
0 75 150 225 300
ag 65ag 60ag 55ag 50ag 45ag 40ag 35ag 30ag 25ag 20ag 15ag 10ag 5
ag under
Male
075150225300
358
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.
359
: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.
360
: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 \/
361
: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:
362
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.
363
? 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.
364
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.
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
365
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.
366
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.
367
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
368
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.
369
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
370
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.
371
? 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
372
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:
373
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
374
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.
375
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.
376
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.
377
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.
378
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
379
? 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.
380
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).
381
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.
382
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.
383
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.
384
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.
385
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 l ines 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.
386
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.
387
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.
388
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.
389
? 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.
390
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.
391
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
392
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.
393
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
394
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.
395
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.
396
‡ - 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.
397
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.
398
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
399
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 - Same 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 .
400
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).
401
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.
402
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.
403
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.
404
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.
405
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
406
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
407
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.
408
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:
Populationbirths deaths
birth rateaverage lifetime
Comment
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
409
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
410
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,font,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
411
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
412
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 Input 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.
413
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)
414
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:
010
Price
quan
tity
0
100
S1
S2
and that there are two demander with the demand curves shown below:
415
010
Price
quan
tity
0
100
D1
D2
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.
010
quan
tity
0
100
demand
supply
Price
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.
010
quan
tity
0
100 d3
supply
d2
d1
Price
416
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:
010
quan
tity
0
100 d3
amount demanded from suppliers by priority
d2
d1
priority
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:
417
Priority Response Shapes1
0.75
0.5
0.25
00 1 2 3 4 5 6 7 8 9 10
Priority
RetangularTriangularExponentialNormal
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.
418
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 e lement 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
419
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:
420
Shipments
800
600
400
200
00 10 20 30 40 50 60 70 80 90 100
Time (Month)
Shipments[Boston] : CurrentShipments[Dayton] : CurrentShipments[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
00 10 20 30 40 50 60 70 80 90 100
Time (Month)
Shipments[Boston] : CurrentShipments[Dayton] : CurrentShipments[Fresno] : Current
By experimenting with the priorities, shapes and widths you should be able to get something that meets your needs.
421
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
422
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.
423
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.
424
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
425
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
426
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
427
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
428
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
429
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
430
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
431
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_BACKWARD 101 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
432
Macros 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 MVSS 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
433
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
434
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
435
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 Options 322 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
436
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
437
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
438
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
439
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 ORDER 130 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
440
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