Vensim

Created on 25 mei 2011

Code author: jhkwakkel <j.h.kwakkel (at) tudelft (dot) nl>

convenience functions and classes to be used in combination with Vensim. This module contains frequently used functions with error checking. For more fine grained control, the vensimDLLwrapper can also be used directly.

vensim.be_quiet()

this allows you to turn off the work in progress dialog that Vensim displays during simulation and other activities, and also prevent the appearance of yes or no dialogs.

defaults to 2, suppressing all windows, for more fine grained control, use vensimDLLwrapper directly .

vensim.load_model(file)

load the model

Parameters:file – the location of the .vpm file to be loaded. Exception :raises a VensimError if the model cannot be loaded.

vensim.read_cin_file(file)

read a .cin file

Parameters:file – location of the .cin file. Exception :raises a VensimWarning if the cin file cannot be read.

vensim.set_value(variable, value)

set the value of a variable to value

current implementation only works for lookups and normal values. In case of a list, a lookup is assumed, else a normal value is assumed. See the DSS reference supplement, p. 58 for details.

Parameters:

• variable – name of the variable to set.
• value – the value for the variable. note: the value can be either a list, or an float/integer. If it is a list, it is assumed the variable is a lookup.

vensim.run_simulation(file)

Convenient function to run a model and store the results of the run in the specified .vdf file. The specified output file will be overwritten by default

Parameters:file – the location of the outputfile Exception :raises a VensimError if running the model failed in some way.

vensim.get_data(filename, varname, step=1)

Retrieves data from simulation runs or imported data sets.

Parameters:

• filename – the name of the .vdf file that contains the data
• varname – the name of the variable to retrieve data on
• step – steps used in slicing. Defaults to 1, meaning the full recored time series is returned.

Returns:

an array with the values for varname over the simulation

VensimModelStructureInterface

class vensim.VensimModelStructureInterface(workingDirectory, name)

Bases: model.ModelStructureInterface

This is a convenience extension of ModelStructureInterface that can be used as a base class for performing EMA on Vensim models. This class will handle starting Vensim, loading a model, setting parameters on the model, running the model, and retrieving the results. To this end it implements:

• __init__
• model_init
• run_model

For the simplest case, it is sufficient to only specify _init__ in more detail. That is, specify the uncertainties and the outcomes. For more elaborate cases, for example when using different policies, it might be necessary to overwrite or extent model_init, while for dealing with lookups etc. it might be necessary to also extent run_model. The examples folder contains examples of each of these extensions.

Note

This class relies on the Vensim DLL, thus a complete installation of Vensim DSS is needed.

cinFile

attribute that can be set when one wants to load a cin file

modelFile

The path to the vensim model to be loaded.

note: The model file should be a .vpm file

resultFile

default name of the results file (default: ‘Current.vdf’)

step

attribute used for getting a slice of the results array instead of the full array. This can cut down the amount of data saved. Alternatively, one can specify in Vensim the time steps for saving results

__init__(workingDirectory, name)

interface to the model

Parameters:

• workingDirectory – workingDirectory for the model.
• name – name of the modelInterface. The name should contain only alphanumerical characters.

Note

Anything that is relative to self.workingDirectory should be specified in model_init and not in __init__. Otherwise, the code will not work when running it in parallel. The reason for this is that the working directory is being updated by parallelEMA to the worker’s separate working directory prior to calling model_init.

model_init(policy, kwargs)

Init of the model, The provided implementation here assumes that self.modelFile is set correctly. In case of using different vensim models for different policies, it is recomended to extent this method, extract the model file from the policy dict, set self.modelFile to this file and then call this implementation through calling super.

Parameters:

• policy – a dict specifying the policy. In this implementation, this argument is ignored.
• kwargs – additional keyword arguments. In this implementation this argument is ignored.

run_model(case)

Method for running an instantiated model structure. the provided implementation assumes that the keys in the case match the variable names in the Vensim model.

If lookups are to be set specify their transformation from uncertainties to lookup values in the extension of this method, then call this one using super with the updated case dict.

if you want to use cinFiles, set the cinFile, or cinFiles in the extension of this method to self.cinFile.

Parameters:case – the case to run

Note

setting parameters should always be done via run_model. The model is reset to its initial values automatically after each run.

vensimDLLwrapper

Created on 21 okt. 2010

Code author: jhkwakkel <j.h.kwakkel (at) tudelft (dot) nl>

this is a first draft for wrapping the vensim dll in a pythonic way

by default it is assumed the dll is readily available. If this generates an VensimError, you have to find the location of the dll and either copy it to C:WindowsSystem32 and/or C:WindowsSysWOW64, or use:

vensim = ctypes.windll.LoadLibrary('location of dll')

Typically, the dll can be found in ../AppData/Local/Vensim/vendll32.dll

exception vensimDLLwrapper.VensimError(*args)

base Vensim error

exception vensimDLLwrapper.VensimWarning(*args)

base vensim warning

vensimDLLwrapper.be_quiet(quietflag)

this allows you to turn off the work in progress dialog that Vensim displays during simulation and other activities, and also prevent the appearance of yes or no dialogs.

use 0 for normal interaction, 1 to prevent the appearance of any work in progress windows, and 2 to also prevent the appearance of any interrogative dialogs’

vensimDLLwrapper.check_status()

check status is used to check the current status of the Vensim DLL, for details on the return values check DSS reference chapter 12

vensimDLLwrapper.command(command)

execute a command, for details see chapter 5.

vensimDLLwrapper.contextAdd(wantcleanup)

creates a new context for the server version of Vensim

currently not implemented

vensimDLLwrapper.contextDrop(context)

drops a context that was created by contextAdd

currently not implemented

vensimDLLwrapper.continue_simulation(num_inter)

This method continues the simulation for num_inter Time steps.

Parameters:num_inter – the number of TIME_STEP iterations that should be executed during the continuation

vensimDLLwrapper.finish_simulation()

completes a simulation started with start simulation

vensimDLLwrapper.get_data(filename, varname, tname='Time')

Retrieves data from simulation runs or imported data sets. In contrast to the Vensim DLL, this method retrieves all the data, and not only the data for the specified length.

Parameters:

• filename – the name of the .vdf file that contains the data
• varname – the name of the variable to retrieve data on
• tname – the name of the time axis against which to pull the data, by default this is Time

Returns:

a tuple with an for an array for varname and and array for tname.

vensimDLLwrapper.get_dpval(name, varval)

use this to get the value of a variable during a simulation, as a game is progressing, or during simulation setup. This function is only useful if you are using the double precision Vensim DLL

currently not implemented

vensimDLLwrapper.get_dpvecvals(vecoff, dpvals, veclen)

This is the same as get_vecvals except it takes a double vector to store values. This method is only meaningful in case of the double precision DLL

currently not implemented

vensimDLLwrapper.get_info(infowanted)

Use this function to get information about vensim, for details see DSS reference chapter 12

Parameters:infowanted – field that specifies the info wanted

vensimDLLwrapper.get_sens_at_time(filename, varname, timename, attime, vals, maxn)

Get results from a sensitivity run at a specific type and across sensitivity runs.

currently not implemented

vensimDLLwrapper.get_substring()

Utility function that is designed to make it easier to work with get_varnames, get_info, and get_varattribs.

currently not implemented

vensimDLLwrapper.get_val(name)

This function returns the value of a variable during a simulation, as a game is progressing, or during simulation setup

Parameters:name – the name of variable for which one wants to retrieve the value.

vensimDLLwrapper.get_varattrib(varname, attribute)

This function can be used to access the attributes of a variable.

Parameters:

• varname – name for which you want attribute
• attribute – attribute you want

1 for Units, 2 for the comment, 3 for the equation, 4 for causes, 5 for uses, 6 for initial causes only, 7 for active causes only, 8 for the subscripts the variable has, 9 for all combinations those subscripts create, 10 for the combination of subscripts that would be used by a graph tool, 11 for the minimum value set in the equation editor, 12 for the maximum and 13 for the range, 14 for the variable type (returned as “Level” etc) and 15 for the main group of a variable

vensimDLLwrapper.get_varnames(filter='*', vartype=0)

This function returns variable names in the model a filter can be specified in the same way as Vensim variable Selection filter (use * for all), vartype is an integer that specifies the types of variables you want to see. (see DSS reference chapter 12 for details)

Parameters:

• filter – selection filter, use * for all.
• vartype – variable type to retrieve. See table

Returns:

a list with the variable names

number	meaning
0	all
1	levels
2	auxiliaries
3	data
4	initial
5	constant
6	lookup
7	group
8	subscript
9	constraint
10	test input
11	time base
12	gaming

vensimDLLwrapper.get_varoff(varname)

This function is intended for use with get_vecvals. By filling up a vector of offsets you can speed the retrieval of multiple values

currently not implemented

vensimDLLwrapper.get_vecvals(vecoff, vals, nvals)

gets a vector of values at the current simulation time.

Parameters:

• vecoff – a vector containing offsets as returned by get_varoff
• vals – the location into which the values for variables should be written
• nvals – the number of elements in the vector

currently not implemented

vensimDLLwrapper.set_parent_window(window, r1, r2)

This is used to set a window that will be the owner of an dialogs or message boxes that Vensim presents.

currently not implemented

vensimDLLwrapper.show_sketch(sketchnum, wantscroll, zoompercent, pwindow)

Use this function to display a model diagram :param sketchnum: the number of the view to be shown :param wantscroll: boolean, False means no scrollbar :param zoompercent: specify the zoom percent (between 20 and 500) :param pwindow: the handle to the window that the sketch should appear in

currently not implemented

vensimDLLwrapper.start_simulation(loadfirst, game, overwrite)

Start a simulation that will be performed a bit at a time.

Parameters:

• loadfirst – boolean, if True the run resulting from the simulation should be loaded first in the list of runs
• game – integer, if 0 treat simulation as a normal simulation if 1, start a new game, if 2, continue with a game
• overwrite – boolean, if True, automatically overwrite existing files when simulation starts

vensimDLLwrapper.synthesim_vals(offset, tval, varval)

This is a specialized function that uses memory managed by Vensim to give access to values while SyntheSim is active.

currently not implemented

vensimDLLwrapper.tool_command(command, window, aswiptool)

Perform a command that will cause output to be created, or the printing or exporting of the contents of a currently displayed item.

Parameters:

• command – the command to pass to Vensim, see chapter 5 for details
• window – the handle to the window the results should appear in
• aswiptool – boolean, if True the tool being created is a work in progress graphs that should be kept open to display simulation results

currently not implemented