2023 Update

Ventana Systems has improved Vensim's file format and ability to merge changes from different versions of a .mdl file in Vensim version 9.3.5 (and possibly as far back as 9.2). Accordingly, merging different .mdl files should be possible if the following guidelines are followed:

1. Everyone who edits EPS.mdl must use a recent version of Vensim (we know Vensim 9.3.5 works and Vensim 9.0.1 does not work) with a particular set of file format settings. One set that works (using the new Vensim GUI) is:

   • File Format: Vensim versions 9.2 and above
   • Equation order: Alphabetical by group
   • Equation format: As originally entered
   • Override sketch zoom: Autofit to screen
   • [✓] Store user specific settings in a separate file
   • [✓] Disable sketch pan saves

2. One person works on a given sheet at a time (or in a new sheet). There is too much risk of people moving the same variable if they’re working on the same sheet. We can always move elements from a new sheet to one of the existing sheets immediately following a merge, so new sheets can be temporary holding places.

3. You may rename a variable defined on the sheet you are working only if nobody else is currently editing a sheet that includes shadow versions of that variable. (Moving it, recoloring it, drawing or changing arrows to/from it, and changing the equation inside it are all fine because those things don’t affect the visual appearance of its shadow copies. Only renaming is a concern.)

4. Merges of EPS.mdl should be done in GitKraken (or an equally capable merge tool) and should involve human judgment for conflict resolution. Don’t do it blindly – look at the code and make sure the merge is being handled correctly.

Below appears the original version of this page, which reflected the much poorer ability of earlier versions of Vensim to create .mdl files that could be merged. Some of the info may still be useful.

Original Version of This Wiki Page

In order to facilitate multiple developers working on core EPS model structure at once, it is necessary to be able to merge changes within the EPS.mdl file successfully. This wiki page lays out guidelines for how to do this.

Background on EPS.mdl

The Vensim model file EPS.mdl is a text file that is broken into three sections.

• The first section includes all variables' equations. These are sorted alphabetically in recent versions of the Energy Policy Simulator (ever since Vensim's "Reform and Clean on Save" option was enabled for the EPS roughly around the time of EPS 3.0.0 release). It is easy for a human to read and to merge changes.

• The second section contains visual sketch information, such as the placement of variables on each sheet, the color and style of variables, the placement and color/style of arrows, comments, output graphs, and so forth. The data in this section are not human-readable and cannot be merged reliably with success.

• The third section contains various saved values for miscellaneous things. Each type of thing is denoted by a number followed by a colon. Some are part of model structure, such as the list of elements within each subscript (denoted with a leading 6:). Some are information about the UI state, most notably, the currently selected variable (denoted with 5:) and the currently displayed sheet (denoted with 19:).

Supported Git Client for Merging EPS.mdl: GitKraken

The Git client GitKraken sees EPS.mdl as a text file and can merge changes within this file, line-by-line. In contrast, the Git client Sourcetree sees EPS.mdl as a binary file and will not allow you to view or merge line-by-line changes within EPS.mdl. Therefore, GitKraken is required for any developer who merges changes within EPS.mdl. (It is not necessary to have GitKraken to make changes to EPS.mdl that will be merged by someone else, as long as the guidelines below are carefully followed.)

Vensim Views (or "Sheets")

In order for changes in EPS.mdl to be reliably merged with success, it is important to avoid conflicting code in the second section, containing visual sketch information.

Vensim visually divides the sketch into different "views," which are similar to "sheets" in Excel. Within the sketch information section, each view has its own distinct sub-section. Changes to the visual information in one view generally do not affect the visual information in other views. This provides a way to segment work on the EPS and avoid conflicting sketch information upon merging.

Conflicting code in the first section of EPS.mdl, containing equation information, is able to be merged. Code in the third section should also be able to be merged, as long as different developers do not edit the same thing, such as changing the elements of the same subscript.

Vensim Behavior upon Making Changes

When a variable in an existing view is moved, its color changed, arrows changed, shadow variables added, or other visible changes are made to the sketch, Vensim may make changes to the sketch information for many elements in that view. If visual changes were made to different elements of the same view in a different branch, many merge conflicts in the sketch information can result. For example, more than 350 merge conflicts in the sketch information section of EPS.mdl were created when two different (non-conflicting) variables were moved and recolored, and two different new variables were added, in different test branches.

On the other hand, when variables are recolored, moved, and added in different views, Vensim makes many changes to the sketch information, but these changes are non-conflicting, enabling easy merging.

When the content of a variable's equation changes (but no visual changes were made to the sketch), a single line of sketch information changes. This individual line will conflict if the same variable's equation was edited in each of the branches being merged. Testing has found that it does not appear to matter which version of this one changed line of sketch info is retained and which is discarded.

Rules for Developers Working on EPS.mdl Together

Based on the findings above, multiple developers can work on EPS.mdl together, as long as the following guidelines are followed carefully:

1. Delete EPS.vpmx from the model package in each branch being worked on. EPS.vpmx is a compiled binary format of EPS.mdl and cannot be merged. Create a fesh EPS.vpmx file by publishing EPS.mdl after EPS.mdl is merged.

2. Only one developer may alter any visible element in each view. For example, Developer A can move, recolor, add variables, add comments, etc. to the Industry - Main view, but this means that no other developer may make any changes to any visible content in that view.

3. Changing the name of an existing variable affects the visual sketch information in every view where that variable is used (i.e. as a shadow variable). Even if an existing variable isn't used in a particular view right now, a different developer might have added a shadow version of that variable to that view since EPS.mdl was branched. Therefore, developers generally should avoid changing names of existing variables until EPS.mdl is merged. Exception: if a developer is assigned to work on a specific view or views (no other developer is touching those views), the existing variable of interest is used only within those views, and the developer believes it is unlikely that any other developer might start making use of that variable on any view not already assigned to him/herself, it may be relatively safe to change the name of that variable prior to merge.

4. Two developers may make changes to the equations inside different variables in the same view, as long as those changes are strictly confined to the equation content and don't affect visible elements of the sketch, such as variable names, positioning, color, font size, arrows, etc. Caution: some changes to equations may create or remove arrows.

5. Two developers may make changes to the same variable's equation if those changes don't affect sketch information, but nonetheless, this should be avoided. During the merge process, the desired final equation must be worked out manually, and the sketch information for that one variable will show a merge conflict. It appears to be okay to accept either version of the conflicting sketch information in this specific situation. Nonetheless, it is strongly recommended that developers coordinate so that two developers do not alter the same variable's equation prior to the merge of EPS.mdl.

6. A developer can create a new view and build new structure freely within that view. He/She may use shadow variables from other views in the new view. This provides a good way to add complicated new content to EPS.mdl without creating merge conflicts inside existing views. If the new feature is intended to be included in an existing view (this is true of most new features), after the merge of EPS.mdl is complete, the developer who merges changes to EPS.mdl should manually move newly created structure from the new view to the correct place in an existing view and delete the new view. In other words, for most new features, the new view is a temporary holding place for new code that should be removed after the merge of EPS.mdl. (A new feature that is intended to remain in its own view, such as a major new model component, can remain in its own view.)

It is possible to make a relatively self-contained feature that utilizes data from other variables within the EPS (i.e. using shadow variables) by building that feature in a new view. However, it may not be possible to incorporate the outputs of this new feature into the main series of EPS calculations that affect emissions or financial results (such as the totals in the Cross-Sector Totals view) unless the relevant existing views (such as Cross-Sector Totals) are reserved for the same developer who built the new feature in the new view.

Merge Process and Merge Conflicts

If the guidelines above are followed, upon merging EPS.mdl in GitKraken, there should be no meaningful merge conflicts. Two types of merge conflicts are expected in certain situations:

• It is reasonably likely that merge conflicts will arise in the third section for the currently selected variable (denoted with 5:) and the currently displayed sheet (denoted with 19:). Either version of these lines (but not both versions) may be retained - it doesn't matter which.

• If the same variable's equation was edited by two developers, in addition to the equation information for that variable having a merge conflict, the sketch information for that variable will also have a merge conflict. You will need to manually resolve the equation conflict. Testing seems to indicate that it does not matter which version of the sketch information is retained in this specific case.

If you see merge conflicts other than these, do not proceed with the merge. New variables and equations, new views, changes to existing variables, changes to existing views, etc. often generate numerous changes within EPS.mdl, but these changes should not result in merge conflicts. If you see unexpected merge conflicts, stop and understand what is going on before finalizing the merge.