NOTEThe vensim dll is now installed in the system or system32 subdirectory of windows.
There are quite a number of things that have been changed in version 4. The first you will notice is the new behavior of the Sketch tool which has a locking mode to prevent accidental movement. The handle for moving and sizing sketch elements are also only shown when they are useful, making your diagrams appear less cluttered.
We have striven to make Vensim 4 backward compatible with Version 3 so you should not have any difficulty adopting the new release. The important areas where you may need to make changes are compiled simulations, external functions and use of the Vensim DLL. These only apply to Vensim DSS. In a nutshell, external functions are now passed more information about vector arguments and will need to be rewritten to adapt for this. All of the Vensim DLLs have been renamed so that you do not need to rename them to vensim.dll before you use them. In improving naming consistency we have also grouped the compiled simulation and external function support files more closely which may require you to make some changes in your compiled simulation setup.
Using Undo
Undo is now on the Sketch Edit menu and it works. You can Undo multiple operations except those that involve equation editing and some other structural operations which can only be undone to one level.
Venapp Changes‡
Venapp creation can be done using the Venapp Editor which works the same as the sketch editor except it works on Venapps.
We have also added a number of new Venapp commands - also applicable to the Vensim DLL.
Vensim DLL Changes‡
A number of new functions have been added to the Vensim DLL to make it possible to get more infocation about the model you are working with.
Getting Data and Constants from Other Applications
It is now much easier to get information from other applications without going through importing datasets or saving spreadsheet files as .csv files. The existing methods do, however, continue to work and may provide better performance for large quantities of data.
Constants and time series data can now be retrieved directly from Microsoft Excel and Lotus 123 using the new functions GET 123 DATA, GET XLS DATA, GET 123 CONSTANTS and GET XLS CONSTANTS. The data and constants functions work somewhat differently and are treated in turn.
To get constants from a spreadsheet you need to specify the filename where the information is stored, the sheet on which the numbers will be found and the cell at which the numbers start. You can get a single number, a row of numbers or an array of numbers. What you get will depend upon the left hand side of the equation. For example:
myconst = GET XLS CONSTANTS('myfile.xls','mysheet','a1')
will set the model constant myconst to the value in cell a1 of the sheet named mysheet. When subscript ranges are used you can load in more than one number. For example
plant : Plant1,Plant2~~|
size : small,medium,large ~~|
row of constants[size] = GET 123 CONSTANTS('myfile.123','mysheet','B3') ~~|
will get three constant values from row 3 (cells B3, C3 and D3) to fill in row of constants. While
array of vals[plant,size] = GET 123 CONSTANTS('myfile.123','mysheet','B5') ~~|
will get 2 rows of 3 constants starting at cell B5. The values for Plant1 are in row 5 (Cells B5, C5 and D5) while the values for Plant2 are in row 6 (Cells B6, C6 and D6).
Vensim always reads the last subscript going across the columns. The two subscript defining the array do not need to be the only, or even the last, subscripts. For example:
country : USA, Canada ~~|
salesperson : mel,sally,tim ~~|
array2[plant,usa,size,mel] = GET 123 CONSTANTS('myfile.123','mysheet','B5') ~~|
would fill array2 up just as array of vals was - but additional equations would be needed for canada,mel, usa,sally and so on.
When Vensim encounter GET 123 CONSTANTS or GET XLS CONSTANTS it will, each time the model is checked, attempt to retrieve the values from Excel or 123. If Vensim can not do this the model will be treated as having errors and you will not be able to simulate. When you begin a simulation Vensim will again query values so that the simulation uses the most current values. In this case if the values can not be retrieved the originally retrieved values will be used. This means that if you save your model in binary format (.vmf) and give it to someone who does not have Excel or 123 (whichever you are using) the will still be able to simulate - though they won't be able to change the model.
Data links are similar, but not identical to those used for constants. Just as for constants you need to specify a file and sheet name and beginning position. Unlike constants, however, you also need to tell Vensim where to find a row or column containing time values. The arguments to the function are then:
'filename', 'sheetname', 'row number or column letter for time values',
'first cell containing data'
You can have up to one subscript range on the left (Time takes up the other dimension). For example starting with a spreadsheet (data.xls) that looked like this:
1 2 3
10 20 30
40 50 60
70 80 90
You could write the equation
data val := GET XLS DATA('data.xls','datatab','1','A2')
and data val would take on the value 10 at time 1, 20 at time 2 and 30 at time 3. Note that we are using := because these are data equations. You could also have
sub: s1,s2
subbed data[sub] := GET XLS DATA('data.xls','datatab','1','A3')
This would read values from rows 3 and 4. If you want to have time running down instead of across you supply the letter of a row that time is contained in. For example
funny data := GET XLS DATA('data.xls','datatab','A','B2')
Would take on value 20 at time 10, 50 at time 40 and 80 at time 70. Because we told it to start at 'B2' instead of 'B1' the first row is actually ignored.
You do not specify a final value in the GET ... DATA functions. Vensim first finds all the values it can for the time row/col and then looks for corresponding values in the data block. Missing values on the time axis (gaps) do not present a problem though more than 10 cause Vensim to ignore those that remain. If you are using this function to get more than one row/column of numbers using subscripts you can not have gaps in the data in that direction.
Vensim retrieves values as they are displayed in the spreadsheet using dynamic data exchange (DDE). If the application referred to in the function call is not open Vensim will open it. If the application is open but the correct file is not loaded Vensim will tell the application to open that file (Note that if 123 is open but with no file open this will fail). If Vensim can't make a connection you will get a message indicating failure. In some cases the actions Vensim request the other application to take may cause a dialog box to appear in that application and you will need to go to it to correct whatever problems may exist.
Language Changes
We have made some minor modifications to the Vensim modeling language. These are completely backward compatible, but will make some modeling tasks easier.
Recursive subscript definitions: It is now permissible to use Subscript ranges on the right hand side of a subscript definition. This makes it much easier to build up a subscript from subranges. For example
young: age1, age2, age3 ~~|
old : age5, age6, age7 ~~|
age : young,age4, old ~~|
is the same as
young: age1, age2, age3 ~~|
old : age5, age6, age7 ~~|
age : age1, age2, age3, age4, age5, age6, age7 ~~|
You can not use subscript ranges that are defined using a mapping (<->) in this manner. Vensim simple queries the subscript ranges it finds on the right to determine the subscript constants required.
Constant Equations: You can now enter arrays of constants by separating the rows (last subscript range) by semicolons ;. For example
geo :east, west ~~|
polit : rep,dem,other ~~|
voters[geo,polit] = 1,2,3;
3,2,1;~~|
To simplify pasting constants from a spreadsheet you can also use the function TABBED ARRAY to allow you to use Tabs and New Lines to break up the numbers. Thus is you have a block of numbers you need in a spreadsheet you can highlight it, copy it to the clipboard, and paste it into Vensim without doing any more editing.
voters[geo,polit] = TABBED ARRAY(
1 2 3
3 2 1
)
Is the same as the above. Note that extra tabs at the end of the line will cause a syntax error. Also the closing paren must appear on a new line.
Lookup Definitions:It is no longer necessary to define a separate variable for Lookup Functions. You can simply select the Auxiliary Variable subtype "with Lookup" and enter the x,y pairs directly into the lookup box, or edit them graphically with the "As Graph" button. The function used to mark such an equation is
aux = INPLACE LOOKUP(expr,((1,1),(2,2)))
You can still make temporary changes to lookup values in simulation setup mode by clicking directly on the aux variable.
The Lookup Editor also allows for the entry of a reference line. A reference line is a light gray line that appears on the lookup editor for reference. You can use this functionality to record the previous values when changing values and to set up other references. Note that if you add references the resulting model will not be usable in Vensim version 3.0 without removing the reference line.
Autosave
Vensim will automatically save models from the Sketch Editor periodically. The frequency with which this saving is done can be set in the Tools>Options>Settings dialog. If Vensim terminates abnormally and you attempt to open a model that has been autosaved you will be informed that an autosave version exists and asked if you want to keep it. You can disable autosaving by setting the autosave time to 0.
Equation Editor
The equation editor now uses a different font from other dialog boxes. Many people prefer to use a fixed width font in equations and this is now easier to do. Just set the font from the Tools>Options>Fonts dialog.
The functions dropdown now includes an "All" types that will list all available functions - clicking on any of these will bring up the prototype arguments. There is also an Array type to show functions that are useful for arrayed variables.
Subscripts
A number of features have been added to make subscripts easier to use. The subscript control dialog now contains buttons to allow you to switch between the two types of dialogs. It also contains a new button to add a new subscript to the model and an edit button to edit the subscript corresponding to the current tab. Clicking either of these brings up the Equation editor allowing you to change the equation for the subscript.
When editing the equation for a subscript it is possible to rename a subscript element by highlighting it and clicking on the Hilite button in the equation editor. This will rename it wherever it appears in the model.
You can also add and remove subscripts from variables much more easily. To change the subscripts for one or more variables highlight the variables in the sketch and then select Edit>Modify Subscripts. The Subscript Modification dialog will appear. Select the subscripts you want in the order you want them for the variables. Then click OK and the variables will have those subscripts. If the variables already are subscripted any new subscripts will be added or reordered as necessary. If the existing variables have subscripts not in the list these will be removed. Any existing summation or subscript constants matching the new subscripts will be properly retained.
The Subscript Modification dialog also allows you to add subscripts to the beginning of a list, the end of a list or to remove subscripts. For example is pop is subbed pop[sex,age] and you add country at the beginning it would be subbed pop[country,sex,age]. At the end would give pop[sex,age,country]. Removing country would do nothing because country is not in pop[sex,age]. However removing age would leave pop[sex]. If you had SUM(Pop[country,sex,age!]) and removed country you would get SUM(Pop[sex,age!]) but removing age would give SUM(Pop[country,sex])) which will cause an error.
Deletion
The delete tools now deletes whatever it is used on from the model. There is no prompting. Selecting one or more words and hitting the Del key will give you an option of deleting from the model or just from the current view (the Del key replaces the old Edit>Delete from Model and Edit>Delete from View commands). Ctrl+x or Edit>Cut give the same behavior as the Del key except that the contents are also put in the clipboard.
Control Panel
The time axis tab has been modified so that you can type in times. Settings are also retained from session to session for a given model.
The Datasets tab has had buttons added to get information about available and loaded runs. Highlight a run and then click on the button above it. Information about that run - the model it was from, the run switches and any comments types in about the run - will then be displayed. The Load From... button also retains memory of the last directory anything was loaded from to simplify loading more than one run from that directory.
Table and Stats Tools
The Table and Stats tools now show color coded values for different runs. This makes it easier to distinguish the different lines. The color distinction can be turned off from the Tools>Options>Colors & Markings dialog.
The Table and stats tools also have options to work across subscripts at a specific time. This make it easy to show 2 dimensional arrays with the Table tool and to look at stats across elements of a vector or array.
File Dates
Vensim no longer changes the file dates on models that are opened but not modified. The size of the file may, however, change as setting information is still being stored in the files.
New Functions
ALLOCATE BY PRIORITY has been added. It takes the same arguments as MARKETP and does the same thing as ALLOC_P when given the results of the MARKETP call but the two stage process is not necessary. The ALLOCATE BY PRIORITY function is a self looping function. This means that the vector over which allocation is being made must appear as the last subscript in the variable on the left.
ARCCOS - the inverse of the COS function.
ARCSIN- the inverse of the SIN function.
GET 123 CONSTANTS, GET XLS CONSTANTS , GET 123 DATA, GET XLS DATA - see communicating with other applications.
TABBED ARRAY - see language changes.
Note that the use of new functions is not backward compatible with earlier Vensim versions.
Simulating and Optimizing
In addition to simulations and games you can now also start optimizations and sensitivity runs from the toolbar. Just click on the icons and you will get a 2 or three step process to set up things up. For optimizations you will first define a payoff, then set the optimization control parameters, then point Vensim at the right data files. For sensitivity simulations you will first set up the sensitivity control file and then define the save list. The Simulation Control dialog can still be used and does contain some advanced options not available elsewhere.
When you click on the Set button to set up a simulation you will also be able to specify the datasets to be used for the simulation without going through the Simulation Control Dialog.
The run name selection is done using the directory named in the run name editing boxes. This makes it easier to put runs in the same directory when it is not the directory the model is in.
The Constant Changes dialog now has a filter and allows selection of variables by starting to type in their name or by using wildcard such as *pop* and clicking on the filter button. The modification of values has also been changed somewhat to show the value next to the variable name. Pressing the Enter key can still be used to change values and return to the list.
If you are using data that has no values before a simulation starts or that runs out of values later in the simulation you will now receive a warning message indicating that you are out of range.
Sketch Changes
The Sketch Editor now has Undo and Redo menu items under Edit. Visual changes such as moving and sizing words and arrows can be undone to a reasonably large number of levels depending on the exact changes. Changes made using the equation editor, subscripting or grouping can be undone to one level (this is also true of variable merges).
The Sketch editor now has a locked setting that does not allow you to move items. This is the default setting that the sketch will be put in after you simulate the model and perform other tasks. This will prevent inadvertent dragging of objects during analysis. You can still get at word options, only movement with the mouse is blocked.
The handles on arrows and words do not appear except when you select the Size and Move tool in the Sketch Editor. You can still drag words around with other tools.
NOTEIf you can no longer click on Arrow handles to delete or hide them. You will need to click on the arrowhead. Clicking anywhere on the arrow head should work - it is no longer just a portion of the arrowhead that is active.
You can size and move words using the arrow keys. Select the size and move tool. Highlight the words you want to move or size. Use the arrow keys to move them horizontally or vertically. Hold down the shift key and use the arrow keys to size them.
If you pause over a variable in the sketch any comments about that variable and the units of measure are displayed. This behavior can be turned off from the Tools>Options>Sketch dialog.
There is a Layout menu to size and position elements on the sketch. Highlight the words you want to change and then go to the Layout menu. Many of the menu items require that you shift click to select a final word and then you can size other words to be the same and so on. If you drag highlight you will need to shift click twice on the word to first deselect it and then select it.
When you place words in a clear box the size of that box is adjusted automatically to accommodate the words you enter. The box will also be resized if you change the variable or comment name or if you change the font.
There are now 8 levels of hiding to make it easier to expose diagrams bit by bit. The H key toggles between all unhide/all hide - use the home/end keys to move to other hide levels Ctrl+H hides to the current level, Ctrl+h unhides at the previous level. The Magic wand also no longer flips from hide to unhide. Instead separate hide and unhide wands are available.
Exporting Data
We have added an option to have subscript names appear in their own column (row if time is running down) for Excel, 123 and Tab delimited files. This can make it easier to view the results. Use an opening square bracket [ in command mode.
