Using Git with OpenFOAM

How do you build yours?

Building a CFD model is an iterative process (pun intended). And unless you get it all right first time (kudos to you), you’ll likely go through several iterations in search of your ideal case setup.

Perhaps you start with a few mesh iterations? Refining, coarsening, layering, adapting and improving before you get to a mesh you (& your solver) are happy with. Maybe you’ll go through several iterations of solver settings? Under-relaxing, scheming & pre-conditioning until you get a nice, robust convergence. But how do you keep track of what you’ve changed along the way? Do you favour a collection of subtly-different (but unexplained) case names (RUN01, RUN01fixed, RUN01final etc)? Perhaps you favour the MassivelyLongFileNamesWhichHintAtSomeOfTheChangesYouJustMade approach? Or are you that little bit more organised and rock a text file (or colour-coded spreadsheet) that details the changes? Whatever works right?

Except, does it still work when you come back to it in 6 months time? Or when someone else has to pick up when you’re sick? How about when you need to unwind a change that didn’t quite work out? Or when you’re looking to get your hands on the team mate that has been fixing things without you knowing?

For those of you familiar with OpenFOAM you’ll know that all of the settings that make up a case are scattered across a large number of files, in a handful of directories. This “text files in a directory structure” approach is one of the reasons that I ❤ OpenFOAM. Still, it shouldn’t be too difficult to keep track of what changed in all those text files across all those directories - right? It turns out that it is, but don’t despair, meet Git, your OpenFOAM life saver.

What’s Git?

Git is a version control system. Think of it a little bit like the revision history you get for a single document in Google Docs (or in Microsoft Word with Track Changes on). You can inspect/review/rewind all of the changes that have been made, including who made the change & when they were made. With Git you choose when your revision snapshots are recorded, what files are stored in that snapshot and you add some explanation/record of the reasons behind the changes. So, kinda like revision history, only better.

Git started life as a tool to manage the source code of the Linux project. A project with many thousands of files spread over many hundreds of directories, with many, many collaborators. It was designed to be fast & efficient at that huge scale. In other words – it eats OpenFOAM cases for breakfast.

Git is also a distributed version control system, in that it lives on your local machine & doesn’t need a complex server setup to manage things in the background. As a consequence, many of the operations are lightning fast & it can be used entirely offline. But, if you need to collaborate with others (locally or remotely) Git has powerful tools for that too. Tools designed to cope with multiple people editing multiple local copies of the same file & ultimately incorporating (or merging) those changes back into a master copy.

Git does a lot of other things & can get pretty complex. But, with just the basics, you could consider Git as your undo button for OpenFOAM. Take it a little bit further, with a few extra commands, and it can be a real OpenFOAM life saver.

How does it work with OpenFOAM?

Git is primarily a developer’s source code management tool. But this isn’t about using Git to manage source code. This is about providing version control for your OpenFOAM case files and bringing a degree of traceability, undo-ability and consistency to your OpenFOAM projects. In other words tracking the who, what, why of all changes to all you project files.

The 3 ways I make of use Git in my projects are:

1) Evolution & Tinkering (AKA, Branching)

One of Git’s killer features is it’s fast (almost instantaneous) branching. Branching is a way to create a safe area for you to make changes to your case. Those changes only exist in that safe area (the branch) until you choose to either delete the branch or incorporate them (called a merge in Git) into your master model. Branches can be particularly useful for storing model variations, like different flow conditions, whilst ensuring cases remain consistent in all other respects.

Trivial example – you want to test out a different turbulence model. You might duplicate the case and make changes to that. But using Git, you would create a new branch, make the required changes & test the new turbulence model. If it doesn’t work out, you can simply switch back to your original version (safely stowed while you were experimenting) and take up where you left off. Or, if the new turbulence model improved things, then you could merge the changes back to your master model & make that the standard from here on in.

2) Project Journalling

If you’re anything like me you don’t get all of the project settings right first time. You probably make a lot of changes to a lot of files on route to getting it all working. Git can record all of these changes very quickly in a snapshot (called a commit). Each time you make a commit, Git forces you to leave a message outlining why you made those changes. This leads you to comment on changes that you might not have bothered to record otherwise. This workflow can replace your current collection of spottily-named test cases with a single, comprehensive record of the development of your project that almost reads like a journal.

Typically I commit (record the changes) every time I try something new. Commits often include several changes to several files but sometimes it’s just a single character, often a missing semi-colon. A combination of appropriate branching and frequent commits gives us most of our OpenFoam life saver. But we can take it a step further.

3) Off-Site Backups

Everyone knows they should be backing up their important stuff. But it’s a pain, so we’ll do it later. You probably already backup everything off-site anyway – right? Well, Git makes it trivial to upload your project (called a push in Git) to a remotely-hosted Git repository. And, with services like GitHub and Bitbucket offering remote Git repositories for free, we’d be daft not to make that off-site backup.

Just to note, I don’t commit volume mesh, or any other large files that can be easily recreated with very little man-time. I also don’t commit input geometry, I archive it remotely, but not in a Git repo. You could commit that stuff, but I definitely wouldn’t push it remotely.

The remaining config. files for an OpenFOAM case are typically pretty small (the motorBike tutorial is only 128KB) and so they upload quickly. In addition, Git has a few tricks for minimising the amount of data it transfers when files change. So, subsequent uploads are even speedier than that first push. Downloading a repository (called a pull in Git) and keeping that new copy up-to-date is also trivial thanks to Git.

What else could you do with Git?

I’ve only scratched the surface of Git here, it has a lot more to offer as you begin to adopt it. For example, Git is particularly good at making life easy for teams collaborating on a single project fileset, whether the team members are local or scattered across the globe.

Aside from the above lifesaving qualities, it’s Git’s potential for smoother cloud CFD workflows that really interests me. In particular, the combination of Git & Docker. If your complete CFD project resided in a remotely-hosted Git repository and your complete CFD environment resided in a remotely-hosted Docker registry then that could have interesting implications for your cloud CFD workflow. “2 pulls & you’re away” you could say, but I wouldn’t get a T-shirt with that on ;-)

Useful Git Resources

I know I haven’t included any code snippets in this article, but if you’re interested in trying Git out and learning how to use it then check out some of the links below. In particular, I’d recommend Try Git as your first stop. Followed by Pro Git & Getting Git Right (say it out loud) if you’re still keen.

Learn More

• Try Git – 15min crash course in Git, from Github;
• Getting Git Right – well-structured (& great looking) online Git reference portal;
• Pro Git – comprehensive book about Git, freely-available in several formats;
• Ry’s Git Tutorial – another ebook about Git, this time taking the shape of a tutorial. Currently freely-available on Kindle;
• Stack Overflow – long list of Git resources;

GUI Clients

• SourceTree – Free Git client for Windows & Mac
• GitHub Desktop – Great GUI tool for Windows & Mac even if you don’t use GitHub;

Hosting

• GitHub – remote Git hosting ( it’s where OpenFOAM lives );
• Bitbucket – remote Git hosting with a very generous free plan;