Hey there,
It’s Robin from CFD Engine & I’ve got a huge time saver for you this week.
A super-fast way to find the help buried deep in your OpenFOAM files – perfect for discovering how to use a particular functionObject or checking the syntax of something new.
Let’s go…
Imagine the scenario
You’re trying to add a cellZone to your snappyHexMeshDict but it’s complaining – what do you do? 😕
Well, there are 450+ “tutorials” already on your system, there’s bound to be an example hiding in one of them – but which one?
What you need is a tool that can rip through all of the tutorials in a fraction of a second & pull out the 15 that use the cellZoneInside keyword.
Meet ripgrep…
ripgrep
You’ve probably tripped over grep by now. It’s on every Unix-like computer, where it’s used to scan through files (or output from other commands) to find the lines that match what you’re looking for.
ripgrep is the same deal, except it’s faster & arguably easier to use. It doesn’t search through binary or hidden files (unless you tell it to) & it’s recursive by default, dropping down through your directory tree to find every last match. It’s a bit like Googling the contents of your own hard drive.
It’s freely-available, it’s open-source & you can find it here.
Installation
You can install ripgrep almost anywhere & if you’re using a package manager, you can do it with a single command – see this list for popular options.
Alternatively, you can grab a stand-alone binary for Windows, Mac or Linux – ideal, if you don’t have permission to install stuff in the traditional sense.
There’s no configuration required & it should be ready to go (via the rg command) straight away.
Use Cases
I recommend a scroll through the user guide, but in the meantime, here are a few things you could try from your $FOAM_TUTORIALS directory…
Basic search
rg foamDictionary
This command will show us which files (out of the 9000+ in the tutorials) contain foamDictionary & on which lines it was found.
Produce a list
rg -l foamDictionary
Adding -l will just show us a list of the files which contain a match (not the lines).
Find something you can’t spell
rg -i cellzoneinside
Using -i will ignore the case of the characters to find all possible variations of cellzoneinside (revealing that it’s actually spelt cellZoneInside in the process).
Limit your search
rg -i cellzoneinside -g snappyHexMeshDict
Ths will repeat the previous search, but only look in snappyHexMeshDict files. Useful when a keyword occurs in multiple dictionaries, but you’re only interested in one.
Find a functionObject by name
rg -l 'type\s+add'
We can combine a couple of operators to find functionObjects by name. This command will list all of the files that include the word type followed by some whitespace \s+, followed by our functionObject name, in this case add.
Extras
There’s loads more functionality & it’s worth checking out the user guide, but here are a couple of my most used features:
- Adding
--statsto your command will add info on how many lines & files were matched, plus how many files it searched & how long it took. - In its quest for speed
ripgrepdoesn’t guarantee the order of results. So, if you need sorted results, you can add--sort pathto your command & it will do exactly that (but run a little slower).
ripgrep can also do search & replace but, with great power comes great responsibility, so I’ll leave this one to you to discover.
Finders Keepers
I use this tool most days to help me find a fix when something isn’t working, or to refresh my memory on how to use a particular feature – it’s my quick check before I start Googling.
You could probably achieve the same with regular Unix grep, but I like rg for its speed & that I can usually remember how to drive it 🤓 I think it warrants a place in any OpenFOAMers toolkit.
Let me know what you reckon & if you’re going to give it a whirl. Also, if you have any other little command-line gems that you’d like me to share, then drop me a note.
Until next week, stay safe,
