1

Table of Contents

Copyright 1998-2003 Ventana Systems, Inc. Revision Date: April 7, 2003

1 Introduction 9 Vensim Documentation ................................................................................................9

User's Guide 9 Modeling Guide 9 Reference Manual 9 DSS Reference Supplement 10 Readme Notes 10

Version 5 Changes.....................................................................................................10 Vensim Overview .......................................................................................................10

General Navigation 12 Vensim Software ........................................................................................................12

Vensim PLE 12 Vensim PLE Plus 13 Vensim Standard 13 Vensim Professional 13 Vensim DSS 13 Vensim Runtime 13 Vensim Model Reader 13 Vensim Application Runtime 14 Vensim DLL 14 Model Capacities 14

Publishing your Model................................................................................................14 Computer Platforms ...................................................................................................14

Macintosh Notes 15 Technical Notes .........................................................................................................16

Typographic Conventions 16 Mouse Movement Terminology 16

2 The Vensim Modeling Language 18 Mathematical Foundation...........................................................................................18

Integral and Differential Equations 18 Variable Types 19 Causal Models 19 Computational Sequence 20

Variables ....................................................................................................................21 Rules for Variable Names 22

Equations ...................................................................................................................23 Equation Components 23 Equation Format and Conventions 25 Operators 26 :NA: 27

Data Equations...........................................................................................................27 Getting Data from Spreadsheets 29 Shifting Time Points 29

Subscripts ................................................................................................................30 Multiple Equations 31 Subscripting Constants 31 Subscript Functions 32 Mixed Variables Types 33

Advanced Subscript Manipulation ............................................................................33 Numeric Ranges 33 VECTOR ELM MAP 33 Subranges 34 Mapping of Subscript Ranges 35

Simulation Control Parameters ..................................................................................39 Special Variable Names.............................................................................................39

Acceptable Integration Errors 40 Alternative Time Bases 41 RC START TIME 41

Groups .......................................................................................................................41 Definition of Ranges...................................................................................................42 Macros .....................................................................................................................42

Defining Macros 42 Using Macros 43

2

3 Model Settings to Units Checking 45 Model Settings ...........................................................................................................45

Time Bounds 45 Info/Sketch 46 Units Equiv 48

Error Checking ...........................................................................................................50 Equation Editor 50 Text Editor 50

Error Checking Sequence ..........................................................................................51 Syntax Errors and Incomplete Equations ...................................................................52

Syntax Errors and the Text Editor 52 Syntax Errors in a .mdl File 53

Problems with Variable Types..................................................................................53 Subscript Errors .......................................................................................................54

Tracing Subscript Errors 55 Usage Messages .......................................................................................................55

Not Defined 55 Multiple Equations.................................................................................................56 Simultaneous Equations.............................................................................................56

Subscripts and Simultaneous Equations 57 Fixing Simultaneous Equations 57 Iterative Solutions to Active Simultaneous Equations 58

Units Checking ...........................................................................................................59 Units Check Output 59 Source of Units Check Errors 60 Units and Lookup Functions 60 Correcting Units Errors 61

Reforming and Cleaning Models ................................................................................61 4 Functions and Keywords 63

Summary List of Functions.........................................................................................64 Lookups......................................................................................................................67

Using Lookups 68 Special Interpolation Modes (Not PLE or PLE Plus) 70

Detailed Function Descriptions...................................................................................70 5 The Sketch Editor 125

Starting the Sketch Editor.........................................................................................125 Notes on Sketch Behavior 125

Models and Views ...................................................................................................126 Sketches and Views 126 Sketches and Equations 127

Variables, Words and Arrows...................................................................................127 The Edit Menu..........................................................................................................127 The View Menu ........................................................................................................132 The Layout Menu .....................................................................................................135 Status Bar ................................................................................................................136 The Sketch Layout ...................................................................................................137 Defined Variables and Shadow Variables ................................................................138

Defined Variables 138 Shadow Variables 138

Sketch Comments, Valves and Junctions ................................................................139 Sketch Tools ............................................................................................................139

Pointer 140 Variable Class 141 Arrow Class 142 Rate Class 144 Input Output Object 146 Sketch Comment 147 Existing Variable Class 148 Merge 149 Magic Wand 150 Delete 151 Equations Class 152

Building Sketches from Models ................................................................................152 Changing the Appearance of a View........................................................................153

Moving a Word 153 Reshaping an Arrow 153 Reattaching an Arrow 153 Resizing a Box or Circle around a Word 154 Wrapping Text 154 Joining Words 154 Variable Word Options 155 Sketch Comment Options 156 Valve Options 157

3

Arrow Options 157 Editing Equations 159

Sketch Workbench Interactions................................................................................159 Variable Selection 159 Navigation 159 Tool Activation 159 Simulation 159

Free-Form Sketching................................................................................................160 Sketching a Database ..............................................................................................160

6 The Equation Editor 161 Starting the Equation Editor .....................................................................................161 Anatomy of the Equation Editor................................................................................161 Making Changes with the Equation Editor................................................................162

Entering Equations 162 Specifying Units 168 Setting the Range 169 Specifying the Group (Not PLE or PLE Plus) 169 Adding a Comment 169 Navigation inside the Equation Editor (Not PLE or PLE Plus) 170 The Errors Line 171 Dialog Control Buttons 171

Correcting Errors......................................................................................................173 Syntax Errors 173 Semantic Errors and Messages 174

Editing Lookups........................................................................................................174 Moving Points 177 Tracing Lines 177

Creating Subscripts................................................................................................177 Modifying Macros ...................................................................................................177 Variable Types .........................................................................................................178 Returning from the Equation Editor ..........................................................................178

7 The Text Editor 179 Using the Text Editor................................................................................................179

Notes on Text Edit Behavior 179 Text Editor Tool Options 179 The File Menu 180

The Edit Menu..........................................................................................................181 The Insert Menu .......................................................................................................182 The View Menu ........................................................................................................183 The Status Bar .........................................................................................................183 Using a Mouse in the Text Editor .............................................................................184 Selecting Text ..........................................................................................................184 Search and Replace.................................................................................................184 The Text Editor Keys................................................................................................185 Interacting With Models............................................................................................186

Syntax Errors 187 Semantic Errors 187 Causal Tracing 188 Using Sketch Information in the Editor 188

Backup and History Files..........................................................................................189 Backup File-Naming Conventions 189

8 Simulating Models 191 Selecting the Time Range........................................................................................191 Simulating from the Toolbar .....................................................................................191

Running a Game 192 Simulation Control Dialog.........................................................................................193

Standard 193 Changes 194 Sensitivity 195 Advanced 196 Closing the Dialog 197

Simulating the Model................................................................................................197 Simulation Error Messages 197 Work-in-Progress (WIP) Graphs 199 Interrupting Simulations 199

Changing Constant and Lookup Values...................................................................199 Interactive Changes 199 Constant Changes 200 Lookup Changes 201 Constant Input Files (Not PLE or PLE Plus) 202 Getting Constant Changes from Spreadsheets 202

Selecting an Integration Technique..........................................................................203

4

Euler Integration 204 Difference Integration 204 TIME STEP 204 Runge-Kutta Integration 205

Interactive Simulations (Gaming) .............................................................................206 Partial Model Simulation (Not PLE or PLE Plus) ......................................................207 Simulating Incomplete Models .................................................................................208

Placeholder Values 209 Ignoring Variables 209

9 Preparing, Using and Exporting Data 211 Overview 211

Importing Data..........................................................................................................212 Active Links to Spreadsheets 212 .dat Format DATA 212 Tab Delimited and Spreadsheet Data 214 Time Slop 218 Managing Data 218

Using Data to Drive a Model ....................................................................................219 Lookups and Data 220

Loading Data as a Model .........................................................................................220 Exporting Datasets...................................................................................................220

Export Dataset Example 222 Exporting Sensitivity Results ....................................................................................222

10 Advanced Simulation Techniques 226 Overview 226

Save Lists.................................................................................................................226 Simulating with a Save List ......................................................................................228 Sensitivity Simulations (Monte-Carlo).......................................................................228

Distributions 230 File Format 232 Noise in Active Variables 232 Combinatorial Sensitivity 232

Payoff Definitions ...................................................................................................233 File Format 234 Payoff Computation 235 Payoff Definition Examples 236

Optimization ...........................................................................................................236 Specifying Optimization Control 237 Starting the Optimization 238 Optimization Options 239 Examples of Optimization Control Files 245 Optimization Output 246 Additional Files 246 Using Output Files 247 Interrupting and Resuming Optimizations 247

Kalman Filtering .....................................................................................................247 Driving Noise and Initial State Covariance 248 Example 248 Combining Filtering and Optimization 252 Optimizing Everything 253 Time Required for Simulations 254

11 SyntheSim 255 Seeing Behavior 255 Enlarging SyntheSim Graphs 255 Subscripts and SyntheSim Graphs 256

Starting SyntheSim ..................................................................................................257 SyntheSim Toolbar 257 Keeping Results from SyntheSim 259

Changing Constants.................................................................................................259 Using the Keyboard 260 Setting Slider Bounds 260 Changing Constants from the Toolbar (Not PLE or PLE Plus) 261

Changing Lookups ...................................................................................................262 Changing Behavior (Not PLE) ..................................................................................263

Input Modes 264 Freezing Levels 265

Model Errors.............................................................................................................266 Input Output Controls with SyntheSim......................................................................267 Bigger Models ..........................................................................................................267

12 Control Panel and Subscript Control 269 Control Panel ...........................................................................................................269

Time Axis 271

5

Scaling 272 Datasets 273 Graphs 275 Placeholders (Not PLE or PLE Plus) 276

Subscript Control....................................................................................................277 Other Control Windows ..........................................................................................279

13 Toolsets, Tools, and Causal Tracing 280 Sketch and Analysis Tools .......................................................................................280

Sketch Tools 280 The Analysis Tools 281

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

Customizing Tools (Not PLE or PLE Plus) ...............................................................281 Opening and Saving Toolsets (Not PLE or PLE Plus)..............................................282

Toolsets Menu (Not PLE or PLE Plus) 283 The Toolset Editor (Not PLE or PLE Plus) ...............................................................283

Adding Tools 284 Moving Tools 285 Deleting Tools 285

Locking Analysis Tools (Not PLE or PLE Plus) ........................................................285 Activating Analysis Tools..........................................................................................286 Working with Tool Output .........................................................................................287

Menus 287 Moving Among Output Windows 288 Sizing 288 Exporting 288 Saving 289 Selecting Variables into the Workbench 290 Selecting a Time Range 290 Selecting a Vertical Range 291

Causal Tracing .........................................................................................................291 Causal Tracing Example 291

14 Analysis Tools 294 Structural Analysis Tools..........................................................................................294 Tree Diagram ...........................................................................................................295 Outline......................................................................................................................297 Document.................................................................................................................297 Loops .......................................................................................................................300 Dataset Analysis Tools.............................................................................................300 Strip Graph Tool.......................................................................................................300 Sensitivity Graph ......................................................................................................304 Graph .......................................................................................................................305 Table ........................................................................................................................308 Stats.......................................................................................................................311 Bar Graph.................................................................................................................312 Gantt Chart.............................................................................................................316 Runs Compare .........................................................................................................318 Miscellaneous Tools.................................................................................................319 Units Check..............................................................................................................319 Equation Editor.........................................................................................................319 Text Editor..............................................................................................................319 Venapp Editor ........................................................................................................320 Reality Check ...........................................................................................................320

15 Custom Graphs, Tables and Reports 321 Overview 321

The Custom Graph Editor ........................................................................................321 Variable Entry 323 Displaying a Named Graph 324

XY Graphs................................................................................................................325 Getting Values for Variables.....................................................................................326

Displaying the Dataset Name 328 The Custom Table Editor .........................................................................................328

Variable Entry 329 Comment Entry 329 Time Range 329

Custom Graph Definition Files ...............................................................................330 File Format 330 Common Keywords 331

Custom Graphs ........................................................................................................331

6

Graph Tool Keywords 331 Custom Bar Graph .................................................................................................336

Bar Graph Tool Keywords 336 Population Pyramids 338

Custom Tables .......................................................................................................338 Custom Table Keywords 338

Custom Reports .....................................................................................................340 Custom Report Tool Keywords 340 Text for Reports 340 Variables in Reports 341

16 Menus and Common Dialogs 343 Menu Commands.....................................................................................................343

File Menu 343 View/Edit/Layout Menus 345 Model Menu 345 Tools Menu 347 Windows Menu 348 Help Menu 349

Main Toolbar ............................................................................................................349 Printing.....................................................................................................................350

Print Options Dialog 350 Printing In Color 352

Utility Dialogs ...........................................................................................................353 File Selection Dialog 353 Variable Selection Dialog 354 Written Response Dialog 355 Color Selection Dialog 355 List Reorder Dialog 355 Fonts Selection Dialog 356 Query Boxes 357 Message Boxes 357

17 Options 359 Options for PLE and PLE Plus .................................................................................359 The Global Options Dialog .......................................................................................361 Fonts ........................................................................................................................361

Fonts1 362 Fonts2 363

Colors & Markings....................................................................................................363 Graphics...................................................................................................................365 Units (for New Models).............................................................................................367 Startup......................................................................................................................367 Sketch and Sketch Defaults .....................................................................................368

Sketch 368 Sketch Defaults 370

Toolbars ...................................................................................................................371 Settings and Advanced ............................................................................................371

Settings 372 Appendix A Glossary of Terms 376 Appendix B Bibliography 382

Building Models........................................................................................................382 System Dynamics 382

Model Analysis .........................................................................................................382 Filtering and Optimal Control 383 Schweppe Statistics 383 Probability and Statistics 383

Technical Reference ................................................................................................383 Appendix C Converting Models 384

Model Interchange Format .......................................................................................384 Converting DYNAMO Models to Vensim..................................................................384 Converting Stella or ithink Models to Vensim......................................................385

Appendix D File Formats 387 Sketch Information ...................................................................................................387

Objects 388 Appendix E Allocation 391

Difficulty of Getting a Good Formulation 391 Requirements of a realistic allocation logic 391 Market Clearing Allocation 392

7

Prioritization, Demand and Supply Curves 394 Specifying the Curves 395 One-to-many Allocation 397

Many-to-many Allocation..........................................................................................399 Matching Suppliers and Demanders ........................................................................401

8

9

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

10

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

11

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

12

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

13

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 Standard Vensim Standard contains the functionality to build and use dynamic models that do not require subscripts. Like Professional and DSS is has it has modifiable toolsets and the complete menu structure documented in this manual. Functionality not available in Vensim Standard (essentially, Subscripts, Optimization, the Text Editor, and Kalman Filtering) is marked with a dagger or double dagger .

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 Runtime Vensim Runtime is essentially the same as Vensim DSS, but without the ability to make any changes to models. Vensim Runtime will allow you to open sketches and simulate models, but it will not allow you to modify a model in any way. Vensim Runtime also supports external functions and will allow you to open Venapps that have been saved in binary format.

Vensim Runtime is applicable only in very limited circumstances. For those wishing to make models available to others we recommend the Vensim Model Reader or Vensim Application Runtime.

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.

14

Vensim Application Runtime The Vensim Application Runtime is a convenient way to distribute a model with a customized Vensim application interface, or with an interface that used the full Vensim DLL without requiring the recipient to buy a full copy of Vensim DSS.

There is also an unlimited redistribution license available.

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. There are two versions of the DLL. The minimal DLL contains the functionality to simulate models and retrieve data. It is included with Vensim DSS and can be redistributed without charge. Details are in the DSS Reference Supplement.

If you use the full DLL then people using your interface will need the Vensim Application Runtime to use your models.

The Vensim DLL is also available in a multi-context format that is designed to support web servers and is licensed per server. Please contact us for details.

Model Capacities All of the Vensim configurations are available for Window (95/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 save it as a Binary (.vmf) file. Anyone with the Vensim Model Reader will then be able to simulate and experiment with your model. If you would like to use a graph set that is not the default graph set, you must first make it the default graph set from the Graphs tab of the Control Panel (see Chapter 12).

If you are planning on sending out your model using the Model Reader you might want to put navigation icons on the first view of the model to make it easier to explore model structure. See Chapter 5.

More notes on preparing your model for publication are contained in Chapter 19 of the User's Guide.

Computer Platforms

Vensim runs on Window 95, 98, Millennium, NT 4.0, 2000 and XP. Vensim will Run on any power Macintosh and 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.

15

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.

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

16

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.

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

17

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.

18

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

19

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 a particular 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).

20

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

21

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.

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 be assumed exogenous and therefore treated as a Data variable. This makes it easy to run sections

22

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

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

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.

23

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 _ CostThe 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'actionUses 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).

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.

24

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:

net income = taxable income - taxes~~ |

25

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 paired braces { }. The examples below illustrate some different formats for defining equation information.

26

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 byJohn 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):

Assignment Operators

=, := (numeric):, , :IS: (symbolic)

27

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 equal sign = appearing in an equation is the unique assignment operator.

NOTE Precedence can be overridden using parentheses ().

: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 ~~|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.

28

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 incomputing performance.

|production smooth :INTERPOLATE: := planned production raw

~ tons/year~ The interpolated values of planned production,

used for ramping output.

29

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

30

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

31

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 45 6 7 89 10 11 12) ~Person~|

32

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.

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 subscrip