Fuzzy finding 'FOAM features

Hey there 👋

It’s Robin from CFD Engine and you might not realise it, but the answers to many of your day-to-day OpenFOAM questions are already on your machine.

The kind of stuff we’re all Googling – how do I use a particular feature? what does so-and-so dictionary look like? does this need a semi-colon? – they’re all hiding in the code base.

You just need to know where to look 👀

There are a few scripts to help you (like foamSearch, foamInfo & foamToC) but how about something a little more interactive?

Meet fzf, an open-source fuzzy finder that makes light work of discovering those hidden answers.

Fuzzy what?

fzf is an interactive command line tool that takes a list of stuff & filters it, based on what you’ve typed in.

It’s cross-platform, it’s easy to install, it’s fast & it looks like this 👇

An example of the default operation of fzf

In this case, I passed it a list of all the tutorial files, and narrowed them down by typing fvoptions.

It didn’t matter that I didn’t use an upper-case “O”, it still found them all, that’s the fuzzy bit.

Okay, but it gets much more useful when you combine it with other commands.

For example, this little combo could be used to find a file in your case directory & then open it in vim 🤓

vim $(fzf)

Handy, but we can do better…

An OpenFOAM feature finder

What if we want to find things inside our OpenFOAM files, not just the files themselves?

We can do that.

If we pass fzf the contents of our files (as well as their names), we can start matching that too.

If we turn on fzf’s preview feature, we can peek at those matched files while we’re typing our search terms.

Here’s how that can look…

An labelled example what fzf looks like searching OpenFOAM files

Our search term (1) is down at the bottom, then we have our list of matches (2) & a preview of the current match (3) along with the rest of the file.

The list & the preview will update as we change our search term.

That example was combing through almost a million lines of text from the tutorials to find examples of OpenFOAM features in use (here’s a .gif on LinkedIn that shows it working in real time) 👍

Give it a go?

Here are the install instructions for fzf - it’s available wherever you have a command line 😉

To get the example I just showed, we need to team it with two other utilities

We need something to output a long list of text, plus something to preview the files.

Here’s an option that should work with grep & less which are probably already available on your command line 👇

fzf + grep + less

A code snippet to use fzf, grep and less to search the OpenFOAM tutorial files

grep passes the contents of the $FOAM_TUTORIALS to fzf, which in turn uses less to preview the files.

If you want a slightly better looking version that includes syntax highlighting in the preview window, ignores hidden files & uses a faster version of grep, then install ripgrep & bat & use this command instead 👇

fzf + ripgrep + bat

A code snippet to use fzf, ripgrep and bat to search the OpenFOAM tutorial files

It’s not the kind of command any of us will remember, so I’ve stuck mine in my shell aliases (~/.bash_aliases) & called it gtfo –get that function object– 😄

Here’s a gist if you want to copy-&-paste any of it.

Have a dig through the fzf repo to see what the switches do, or check out some of the other use cases – it’s well worth browse.

Fuzzy finding fun

There you have it, a quick way of mining your OpenFOAM installation for answers to those everyday questions.

It’s local, intuitive & it’s in sync with your OpenFOAM version (even if you’re still using OF-v2.0.1) 🫢

In my case, it’s replaced a bunch of Googling, but let me know how you find it 🙏

Until next week, stay safe,