I mentioned in a previous post that I was experimenting with version control for energy models in my daily work. I’ve been using Mercurial and TortoiseHG ever since and I’ve learned a significant amount about how version control tools can be useful in energy modelling. In this post I describe in more detail my own version control workflow, and its pros and cons.
For those who are not familiar with version control systems (VCS), sometimes called source code management or revision control tools, at their basic level, these tools allow tracking, organizing and manipulating versioned plain text files. Software developers use these tools to keep track of who made what change to software source code when, as well as to “merge” and “branch” documents as different options are tested. Each version is “committed” to the “repository” with a “commit message” describing the changes being committed. The repository contains all versions of all files in a space-efficient way—only the differences between files are stored. Any version of any file (or set of files) can be retrieved at any time. All versions of all files and commit messages are searchable.
These features make VCS tools extremely interesting for energy modelling as well. All our files are plain text and modellers also make large numbers of changes which can be a challenge to keep track of. The two most popular tools are Git and Mercurial. I personally find Mercurial to be more intuitive, so this is what I’ve been using, but this will be subjective and ultimately both tools can achieve the same goals.
Comparison of Workflows
To really illustrate the power of VCS tools I wanted to describe a typical modelling workflow with and without a VCS tool.
Current Energy Modelling Workflow
- Create initial osm and sketchup files, creating several versions as we go because osm files are easily corrupted. Versions R1, R2 and R3 are created.
- Export initial idf file. Make changes, saving copies of the file as we go. These versions get us up to R5.
- Decide to change the window-to-wall ratio so we update the osm file to R4 then merge the new geometry into the idf file making version R6. Note that now the R4 version of the osm file is newer than the R4 and R5 versions of the idf file (confusing!).
- Make a few more changes to the idf file, bringing us to R8.
- Write a memo describing preliminary results using the R8 energy model and send this to the client.
- Make more changes while waiting for the client’s review and save versions R9 and R10.
- Client asks to know what the impact of several specific changes. To keep the results consistent with the memo the client is reviewing, we need to make changes to the version used for the memo. Hopefully we will remember that this is version R8. Save this version as R8a.
- Make a few more changes while the client decides whether to keep the optional changes, creating revisions R11 and R12.
- The client asks to keep the changes made after the memo. We must now remember which file contained the changes (R8a) and manually incorporate these into R12, making R13.
As you can see, this whole process gets confusing very quickly and gets even worse when working on a large, multi-building project or when evaluating various options at once.
Version Control Workflow
- Create initial osm and sketchup files. Commit changes to these as we work and commit each one with a very brief comment. If any corruption occurs with the osm we can easily revert to a previous version using the commit messages to identify the version to which we are restoring.
- Export initial idf file. Make changes and commit each change with a comment.
- Decide to change the window-to-wall ratio so we update the osm file and commit changes with a short note.
- Copy new windows into the idf file and commit the changes with a comment.
- Make a few more changes and commit each with a comment.
- Write a memo describing preliminary results using the current version of the model and send this to the client. Tag this version as “prelim_memo” so that we will be able to find it again easily.
- Make more changes while waiting for the client’s review and commit each with a comment.
- Client asks to know what the impact of several specific changes. To keep the results consistent with the memo the client is reviewing, we need to make changes to the version used for the memo. Use the “update” feature to update our working directory to the version tagged “prelim_memo”. All our files are now in the exact state they were when re issued the memo. Make the changes and commit the changes. This creates a new “branch” and we will “bookmark” this branch “option1”.
- Update to the main branch and make a few more changes while the client decides whether to keep the optional changes. Commit the changes with comments.
- The client asks to keep the changes made after the memo. We can now “merge” the “option1” branch into the main branch incorporating the changes into the most recent version of our model.
This process can also be a bit confusing without some background in version control systems, however, it is also clear that everything is tracked with almost every step involving “commit messages”. These messages are a key part of the advantages to this workflow.
Visually Tracking Model History
The above examples can be a bit confusing, even for seasoned energy modellers, but we often have to deal with far more complex sets of options. The commit messages and visual “graph log” can help us track the various revisions made to a file. What does this actually look like in TortoiseHG? I created a simple example and a screenshot of the repository can be seen below:
The “Graph” column is a very useful to see the progress of the model and although the commit messages in this example are very generic, they are still useful. In a real project the modeller could use simple messages like this or there could be be many, many more revisions, each with a more detailed commit message.
- Lets you “try something” without worrying about messing something up – all versions are stored and retrievable.
- Allows you to “branch” your model into different versions when significant scenarios are being examined
- Allows tagging versions such as “these results issued to client” or simply the old R1, R2, tags if desired.
- Each change committed is accompanied by a “Commit message” which allows tracking train of thought in your modelling process, documenting changes, reasons, etc.
- “Changesets” can be examined, showing only the specific changes made between versions. This is useful to answer questions like “what did I change since this system stopped working?”.
- Commit messages are searchable and time-stamped. Find when you made a change mentioning arbitrary terms like “huidification” or “boiler”.
- All versions of all files in the repository are searchable at once.
- Complicated: This system has a steep learning curve, especially without a background in related concepts, i.e. software development.
- Keeping a copy on the server can be annoying. The whole repository should be kept there for backup purposes (depending on your company’s IT policies), but needs to be synced.
- Comparing results of models from different “versions” or “branches” can get complicated. Only one “state” can exist in a folder at a time. If you want to see multiple versions at once it can be a challenge.
Overall I’m convinced that the version control workflow is worth using, there are still some kinks to work out and the learning curve makes it difficult to simply say “everyone should use it”. However, many full-fledged energy modelling tools also have a steep learning curve so if you can learn the energy modelling tool itself, you can learn this too! I hope to write a future post about the details of setting up a repository for energy modelling purposes.