Command Line Usage

Basic command line usage

Most of the features available in Getting started are also available using the command line. Running:

python -m pysd Teacup.mdl

will translate Teacup.mdl to and run it with the default values. The output will be saved in The command line interface accepts several arguments, this can be checked using the -h/–help argument:

python -m pysd --help

Set output file

In order to set the output file path, the -o/–output-file argument can be used:

python -m pysd -o my_output_file.csv Teacup.mdl


The output file format may be .csv, .tab or .nc.


If -o/–output-file is not given, the output will be saved in a .tab file that starts with the model file name followed by a time stamp to avoid overwriting files.

Activate progress bar

The progress bar can be activated using the -p/–progress argument:

python -m pysd --progress Teacup.mdl

Translation options

Only translate the model file

To translate the model file and not run the model, the -t/–translate command is provided:

python -m pysd --translate Teacup.mdl

Splitting Vensim views in different files

In order to split the Vensim model views in different files, as explained in advanced usage, use the –split-views argument:

python -m pysd many_views_model.mdl --split-views

The previous code will put each model view in a separate Python module. Additionally, if the names of the views include the concepts of subsubmodules (e.g., ENERGY-transformation.efficiency_improvement), the –subview-sep (subview separators) argument may be used to further classify the model equations:

python -m pysd many_views_and_subviews_model.mdl --split-views --subview-sep - .

Note that passing any positional argument right after the –subview-sep argument will raise an error, so it is recommended to pass this argument as the last one.

Outputting various run information

The number of output variables can be modified by passing them as arguments separated by commas, using the -r/return_columns argument:

python -m pysd -r 'Teacup Temperature, Room Temperature' Teacup.mdl

Note that the a single string must be passed after the -r/return_columns argument, containing the names of the variables separated by commas.

Sometimes, variable names have special characters, such as commas, which can happen when trying to return a variable with subscripts. In this case we can save a .txt file with one variable name per row and use it as an argument:

python -m pysd -r output_selected_vars.txt Teacup.mdl

-R/–return-timestamps command can be used to set the return timestamps:

python -m pysd -R '0, 1, 3, 7, 9.5, 13.178, 21, 25, 30' Teacup.mdl


Each time stamp should be able to be computed as initial_time + N x time_step, where N is an integer.


The time outputs can also be modified using the model control variables, explained in next section.

Modify model variables

Modify model control variables

The values of the model control variables (i.e. initial time. final time, time step and saving step) can be modified using the -I/–initial_time, -F/–final-time, -T/–time-step and -S/–saveper arguments, respectively. For example:

python -m pysd -I=2005 --final-time=2010 --time-step=1 Teacup.mdl

will set the initial time to 2005, the final time to 2010 and the time step to 1.


If the -R/–return-timestamps argument is used, the final time and saving step will be ignored.

Modify model variables

To modify the values of model variables, their new values may be passed after the model file:

python -m pysd Teacup.mdl 'Room Temperature'=5

this will set Room Temperature variable to 5. A time series or a lookup can also be passed as the new value of a variable as two lists of the same length:

python -m pysd Teacup.mdl 'Temperature Lookup=[[1, 2, 3, 4], [10, 15, 17, 18]]'

The first list will be used for the time or x values, and the second for the data values. See setting parameter values in Getting started for further details.


If a variable name or the right hand side are defined with white spaces, they must be enclosed in quotes, as in the previous example.

Several variables can be changed at the same time, e.g.:

python -m pysd Teacup.mdl 'Room Temperature'=5 temperature_lookup='[[1, 2, 3, 4], [10, 15, 17, 18]]' 'Initial Temperature'=5

Modify initial conditions of model variables

Sometimes we do not want to change the actual value of a variable but we want to change its initial value instead. An example of this would be changing the initial value of a stock object. This can be done similarly to what was shown in the previous case, but using ‘:’ instead of ‘=’:

python -m pysd Teacup.mdl 'Teacup Temperature':30

this will set initial Teacup Temperature to 30.

Putting it all together

Several commands may be used together. The optional arguments and model arguments go first (those starting with ‘-’ or ‘–‘), then the model file path, and finally the variable or variables to change:

python -m pysd -o my_output_file.csv --progress --final-time=2010 --time-step=1 Teacup.mdl 'Room Temperature'=5 temperature_lookup='[[1, 2, 3, 4], [10, 15, 17, 18]]' 'Teacup Temperature':30

will save step 1 outputs until 2010 in my_output_file.csv, showing a progressbar during integration and setting foo to 5, temperature_lookup to ((1, 10), (2, 15), (3, 17), (4, 18)) and initial Teacup Temperature to 30.