Quick edits with foamDictionary

Hey there,

It’s Robin from CFD Engine and it’s been a while since I brought you some OpenFOAM bits, so here we are – a brief intro into the dictionary-editing magic that is foamDictionary.

Let’s set the scene…

You’ve got a case that has a dictionary edit as part of the process, no problem when you’re working interactively, but a bit of a pain when you want it to run unattended.

Extra tricky when the edit is deep inside a long dictionary like snappyHexMeshDict or something mission critical like controlDict.

You could maintain a couple of versions of your dictionary & swap them out as part of your run script. Or, if you’re a wizard with sed & awk, you could conjure up a regular expression to do a search-and-replace – job done 👏

But…you could use foamDictionary instead, a tool built precisely for this job 🤔

Never heard of it? Let’s go…

A brief intro

foamDictionary can parse & manipulate any OpenFOAM dictionary. It understands the structure of the files, which means you can easily query, change, add & remove entries, directly from the command line.

It’s been in the .com & .org versions for years, but you might not have noticed it.

There are no fancy regular expressions to learn & it’s unlikely to miss out that semi-colon – you know, the one that brings your whole case crashing down around your ears.

It’s best suited for making a small number of discrete changes to individual dictionaries (like changing start/end/write times in controlDict or toggling layers on or off in snappyHexMeshDict).

It doesn’t check your work though, it won’t catch typos in names or complain if you set something up wrong – that’s on you.

Cheat sheet

It’s usefulness will probably depend on the complexity of your workflow, but it’s one of those tools with which experimentation sparks imagination, so have a little play with it.

Here are some examples of the main things you might want to try:

Retrieve entries

Change an existing entry

Add a new entry

Remove entries

Formatting code blocks for emails can be hit & miss (hence the images) but check out this Gist if you want something more cut-&-paste friendly.

More tricks

foamDictionary has some other tricks up it’s sleeve, including skills with #include files & the ability to diff files to see what’s changed – but I’ll save those for future “Three Tiny Tips” emails.

Check out the source code docs for more examples & info.

Alternatively, if you’re looking to make wholesale changes to your case files then you might want to check out changeDictionary where you use (yet another) dictionary to rewrite multiple files in a single execution (think changing a boundary condition across all variables, that kind of thing).

Over to you

Are you a big foamDictionary user? Any interesting use cases you’d care to share?

Or is it new to you? Do you think you might be able to simplify your run scripts with a little bit of foamDictionary magic?

Let me know, I’m always keen to hear how you use the tools (& whether these emails are useful) 🙏

Until next week, stay safe,