Structural Dominance Analysis Toolset

v1.01 March 14, 2018.

Sergey Naumov and Rogelio Oliva

MIT System Dynamics Group

Purpose

This toolset integrates into a single piece of software the utilities and algorithms necessary to perform Structural Development Analysis as described in Oliva (2015). Specifically, the toolset automates:

i) the parsing of the Vensim model into the Mathematica notation,

Loop Eigenvalue Elasticity Analysis (LEEA)

ii) the identification of a Shortest Independent Loop Set,

iii) the linearization and computation of the system eigenvalues at specified points in time,

iv) the generation of the tables and graphs of loop gains and loop influence on eigenvalues,

Dynamic Decomposition Weight Analysis (DDWA)

v) the equations and graphs that describe the dynamic decomposition weight of state variables, and

vi) the generation of the tables that report parameter influence on eigenvalues.

A quick description of the ideas behind the toolset and a demonstration of its use can be seen in this video.

The toolset replaces the tools and utilities previously made available with the publication of the articles and book chapters listed below. With the exception of formatting issues (and some typos that were corrected in the second edition of the Encyclopedia chapter), the toolset replicates the results LEEA reported in the following articles. Please refer to the electronic supplements of these publications to obtain the accompanying Vensim models.

Kampmann CE, Oliva R. 2006. Loop eigenvalue elasticity analysis: Three case studies. System Dynamics Review 22(2):141-162.

Kampmann CE, Oliva R. 2008. Structural dominance analysis and theory building in system dynamics. Systems Research and Behavioral Science 25(4):505-519.

Kampmann CE, Oliva R. 2009. Analytical methods for structural dominance analysis in system dynamics. In Meyers R (ed.), Encyclopedia of Complexity and Systems Science, pp. 8948-8967. Springer: New York.

Saleh M, Oliva R, Kampmann CE, Davidsen PI. 2010. A comprehensive analytical approach for policy analysis of system dynamics models. European Journal of Operational Research 203(3):673-683.

Oliva R. 2015. Linking structure to behavior using eigenvalue elasticity analysis. In Rahmandad H, Oliva R, Osgood N (eds.), Analytical Methods for Dynamic Modelers, pp. 207-239. MIT Press: Cambridge, MA.

Oliva R. 2016. Structural dominance analysis of large and stochastic models. System Dynamics Review 32(1):26-51.

In the process of testing the utility, however, we uncover that different set of assumptions were used in the computations of the weight elasticities to parameters in the last four papers. Assessing the implications of different assumptions and expanding the application of DDWA to different time periods, revealed a better set of assumptions and a more consistent interpretation of DDWA. We report and document our findings in

Naumov S, Oliva R. 2018. Refinements to Eigenvalue Elasticity Analysis: Interpretation of parameter elasticities. System Dynamics Review, 34(3):426-437.

The toolset now reports what we believe are the most intuitive results and the DDWA tables generated for the models in Oliva 2015 and Oliva 2016 no longer match the published results.

Input file: Vensim *.mdl format file

Limitations: The utility has the following limitations:

- Spaces or underscores are removed from variable names to be consistent with Mathematica's notation.

- Special characters in variable names, i.e., names that in Vensim require quotes, are modified to be consistent with Mathematica’s notation.

- Dynamic functions (e.g. SMOOTH, DELAY) are not supported; please replace with explicit stock (INTEG) formulations.

- All equations have to be continuously differentiable (C1). As such, the toolset does not support IF_THEN_ELSE, MIN, and MAX functions nor piecewise linear table functions.

- Macros are not supported.

- Arrays are not supported.

Please see list of upcoming improvements below.

Usage

• The toolset requires a Mathemetica license to run and it consists of a Mathematica notebook (“SDA v1.01.nb”) and its companion package (“SDA V1.01.wl”). The toolset was developed to be compatible with Mathematica 11.0.
• A zip file containing these files can be downloaded here. Expand and place the two files the same folder.
• Double-click on the “SDA v1.01.nb” and answer Yes to the query regarding the auto evaluation of initialization cells.
• After a few seconds, the dashboard will appear. If necessary, the size of the dashboard can be adjusted using the zoom function in the lower right corner of the window.
• Load the model by through the Select Model button in the Model Control box and navigating to the appropriate folder to select the file. If there are any errors in the parsing they will be reported in the Messages box at the bottom of the dashboard. If the model is parsed correctly, the Model Control box will report basic Model and Structure information.
• At this point the user has the option to either run the model inside the toolset (only Euler integration is available at this time) or load the Vensim data with the simulation of interest (*.tab file exported from Vensim using all the default options). Select your option through the appropriate button in the Model Control box. Once the model is simulated, or data is imported correctly, the Behavior of model variable and SDA Control boxes of the dashboard will become active.
• The Behavior of model variable box provides access behavior modes graphs of stocks and other model variables. Graphs generated in this box can be exported through the Export as PDF button.
• The SDA Control box provides the inputs controls to select the points in time when the structural analysis will be performed. The toolset is limited to 30 equidistant points in time for analysis. Specify the desired time points by selecting the initial and final times to be used, as well as the interval between the points. Points will be selected with the appropriate interval starting at the initial time and up to when the final time is reached, or 30 points have been identified. Note that these controls allow for easy re-centering of time points or zooming into a specific period of the model simulation time. Once the appropriate times have been selected you can execute the LEEA computations by hitting the appropriate button.
• In the LEEA section, the Eigenvalues button reveals two tabs: the  Evolution tab show changes of system eigenvalues over time, and the  Plot @ time tab plots the eigenvalues in the complex plain at the selected time. The Loops button provides access to four tabs. The Loop List a reference to the set of loops identified as the Shortest Independent Loop Set (SILS) and used in all the analyses. The Loop Gains tab plots the trajectory of the gains of the loops in the SILS over time. The Loop Influence button shows the evolution of the influence of each loop in the SILS on a selected eigenvalue at a point in time, and Loop Influence @ time shows the influence at a particular point in time in a scatter plot with the loop influence in the x axis, and the intensity (and sign) of the influence in the y axis. All information generated by the LEEA can be exported as tables and graphs for further analysis or publication.
• While the LEEA section shows the modes of behavior of the whole system and their evolution over time, for policy design and analysis it might be necessary to understand the effect of these modes on individual stocks of the system at a particular point in time. The DDWA section provides this information. The DDWA computations become available once the time to perform the analysis is selected (radio buttons on the LEEA time scale). The DDWA results are also grouped into two groups. The Decomposition button shows the projection of all eigenvalues on each individual stock in three different formats (equations and absolute and normalized time plots). The Elasticity open ups two tabs. The first tab lists (as a reference) all the stocks and behavior modes (eigenvalues) at the time selected for DDWA. The  Elasticity tab is the main tool for policy analysis as it tabulates the weight and eigenvalue elasticity to all model parameters. The table can be sorted by various columns. Using this information, the user can assess the effect of each parameters on stocks of interest and behavior modes and choose policies that affect the most relevant and effective/efficient parameters. Note that elasticity tables are calculated assuming that stocks are at the level indicated by the base-case simulation, as such, the tables do not report the effect of the parameters on the stocks initial conditions (see Naumov and Oliva 2018 for detailed discussion).
• See Oliva (2015 and 2016) for examples workflow sequence for the analysis of complex models.

Upcoming improvements

We expect to continue to work in the improvement of this toolset. This the list of improvements we are currently planning in deploying:

• Parsing CamelCase Mathematica and other non-traditional Vensim functions

• Automatic adaptation of non-continuous functions (table functions, MIN, MAX, etc.)

• Loading Data from files in Vensim default format (*.vdf)

• Runge-Kutta integration

• Web-based interface with Mathematica engine behind – no need for a user to have a Mathematica license

• Allowing of non-continuous functions (e.g., PULSE, STEP) in input variables

• Support for dynamic functions (e.g., SMOOTH, DELAY)

Please email the authors requests for additional functionality that would improve Structural Dominance Analysis.

Acknowledgments

The algorithms implemented within this toolset are the results to years of collaboration with Christian Erik Kampmann, Mohamed Saleh, and Päl Davidsen. We gratefully acknowledge their contribution to this research. Implementation errors and inaccuracies are the responsibility of the authors of the toolset. Rogelio Oliva also acknowledges the insights and encouragement from multiple conversations on these topics with Burak Güneralp.

History

v1.00 September 2017. Core functionality

v1.01 March 2018. Resolved initialization assumptions and reporting of DDWA output.

© Sergey Naumov and Rogelio Oliva, 2017, 2018.

Last modified: May 7, 2019.