Placeholder canvas
Generic selectors
Exact matches only
Search in title
Search in content
Post Type Selectors
Search in posts
Search in pages

Go Home

SDM-Doc

About SDM-DOC

The SDM-Doc tool is a standalone Java program that reads a System Dynamics model in Vensim.mdl format, analyzes the model for a specific set of attributes, and generates an HTML-formatted file viewable on standard web browsers such as Firefox, Google Chrome, and Microsoft Edge. The ability to read XMILE-formatted models is currently under development and the version available for download on this webpage is capable of reading XMILE-formatted models and analyzing and reporting on a subset of the available features within XMILE. There are no guarantees on the correctness of the analysis and output at this point. 

The SDM-Doc tool was developed by the Decision and Infrastructure Sciences Division at Argonne National Laboratory, and was inspired by Oliva’s (2002) work on HTML model documentation.  For a description of the tool and its purpose, see Documentation for model transparency by Martinez-Moyano, I.J. (2012) which can be viewed for free as a member of the Society (Join Now!). 

SDM-Doc is provided under a BSD open source license.

SDM-Doc/Java Version 1.4.7

(October 12, 2021)

This version of the software analyzes and reports on (but not limited to):

  • Counts by variable type and variable characteristics.
  • View diagrams.
  • Automatic loop discovery.
  • Detailed listing of each variable with: equation, units, comment, used by, views, summary loop statistics, thumbnail results of baseline model run (provided model is executable. Multiple groupings by variable type are presented.
  • Detailed loop statistics by variable.
  • Loop lists.
  • Variable Link details.
  • Link Polarities.
  • Units used.
  • Endogenous and exogenous variable analysis.

The generated HTML report uses hyperlinks to allow for quick navigation through the report. SDM-Doc does support languages other than English when translation files have been registered with the tool. Currently, partial translations are available for Japanese and Spanish. Users can provide translations through SDM-Doc-generated Word file that are edited and loaded into the tool.

SDM-Doc also provides a suite of tools that can be applied to System Dynamics models in Vensim.mdl format. These tools provide the ability to:

  • Extract and Replace Comments: The comment field for each variable is extracted and written to a Microsoft Word file. Word is used to edit the comments within the model. The contents of the Word file is then loaded and a new version of the model is written to a file with the edited comments.
  • Extract and Replace Variables Names: The variable names are extracted and written to a Word file. Word is used to make any changes to the names of existing variables. Then the Word file is loaded and a new version of the model is written to a file with the updated variables.
  • Adjacency Matrix to Map Conversion: A formatted adjacency matrix is read and converted into a map of the variables.
  • Run Loop Length Analysis: A standalone version of loop analysis is performed and report generated

Download the Zip file appropriate for your operating system and extract the files onto your computer. Executable scripts are provided for running the tool.

Windows 64-bit
Unix (no jre)

Additional Downloads:

SDM-Doc/Java Source Code

To provide feedback and for more information please contact Ignacio J. Martinez-Moyano, Ph.D., Argonne National Laboratory at (630) 252-8824.

The SDM-Doc tool was developed by the Global Security Sciences Division at Argonne National Laboratory, and was inspired by Oliva’s (2002) work on HTML model documentation.

For a description of the tool and its purpose, see:

SDM-Doc is provided under a BSD open source license.

Two versions of the SDM-Doc tool are available:

  • The Java version (ver 1.2.89, June 1, 2017).
  • The .NET version (ver 5.0, Jul 23, 2014)

SDM-Doc/Java Version 1.2.89 (June 1, 2017)

The Java version provides a number of new enhancements to the original Java version 1.0. New capabilities include but not limited to:

  • Stock and Flow Diagrams are included
  • The model will be translated into pure Java
  • The model will be executed to generate thumbnail graphs of variable values (provided model is runnable)
  • Thumbnail variable value graphs can be included in report
  • Loop detection is enhanced to allow for time and number of loops limitations
  • Loop detection is enhanced to allow for automatic discovery of maximum loop length
  • Loop reporting is enhanced to include variable pair loops in common
  • Loop reporting is enhanced to include quick access to loop contents by variable

This point release contains a new feature as well as a few minor bug fixes for the previous version (version 1.2.71).

  • A new feature, visible on the main screen, allows the user to reuse saved data from a previous execution of the tool. This is primarily intended to be a time-saving feature. When working with large models, it is sometimes useful to repeatedly execute the tool while changing parameters such as the maximum loop size. Four types of data can be reused. These are the generated View images, the generated source code/classes, the thumbnail images of the results and the link polarities. In order to be a candidate for reuse, the modification time of the Vensim MDL file must be older than the creation/modification time of the generated files (i.e. the model cannot have been modified since the files were generated). The GUI widgets that control reuse will be disabled if not eligible for reuse. The output directory can be annotated with a time stamp and link size. Thus there can be multiple directories from which the filed could be reused. The user is given the capability to select from multiple output directories if they exist.
  • Fixed a bug in the delay functions that delayed the results of the function by 1 dt.

The software is distributed as a Zip file. Simply download the Zip file appropriate for you operating system and extract the files onto your computer. Executable scripts are provided for running the tool.

Download the Windows-specific 64 bit environment Zip file here.

Download the Windows-specific 32 bit environment Zip file here.

Download the Unix-specific Zip file here. Note that the Unix-specific Zip does not include jre.

Download the latest SDM-Doc/Java User Guide here Note: a new version will be available shortly.

Download the latest SDM-Doc/Java Source Code here.

Sample output generated by the SDM-Doc tool:

To provide feedback:

For more information:

Ignacio J. Martinez-Moyano, Ph.D.

Argonne National Laboratory

(630) 252-8824

imartinez@anl.gov