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
# Print the top-level keywords in this dictionary
foamDictionary system/snappyHexMeshDict -keywords
# Print the addLayersControls sub-dictionary
foamDictionary system/snappyHexMeshDict \
-entry addLayersControls
# List the keywords in addLayersControls
foamDictionary system/snappyHexMeshDict -keywords \
-entry addLayersControls
# Print the ENTRY for nLayerIter in addLayersControls
foamDictionary system/snappyHexMeshDict \
-entry addLayersControls/nLayerIter
# Print the VALUE of nLayerIter in addLayersControls
foamDictionary system/snappyHexMeshDict \
-entry addLayersControls/nLayerIter -value
Change an existing entry
# Set nLayerIter in addLayersControls to 100
foamDictionary system/snappyHexMeshDict \
-entry addLayersControls/nLayerIter -set 100
# Set a value as the result of another command
# e.g. set the number of subdomains to the
# number of procs on the machine
foamDictionary system/decomposeParDict \
-entry numberOfSubdomains -set $(nproc)
Add a new entry
# Add a new top-level entry with a vector
foamDictionary my-include-file -entry top-level-var \
-add "(1 2 3)"
# Add an empty sub-dictionary called newdict
foamDictionary my-include-file -entry newdict -add "{}"
# Add an entry called var into the newdict sub-dictionary
foamDictionary my-include-file -entry newdict/value \
-add 2000
# Add a complete entry:
# eg. add a new geometry file into snappyHexMeshDict
foamDictionary system/snappyHexMeshDict \
-entry geometry/newgeom.obj \
-add "{type triSurfaceMesh; name my-new-geometry;}"
Remove entries
# Remove the complete "newgeom.obj" sub-dictionary
foamDictionary system/snappyHexMeshDict \
-entry geometry/newgeom.obj -remove
Check out this Gist for all of the above entries, in one cheatsheet
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,
