A comprehensive guide to compilation of OpenFOAM on Ubuntu and Windows WSL.

Michael Bloomberg once wisely noted that “the first step in solving any problem is to identify that there is one.” Today, I want to tackle a common challenge that many encounter at the outset of their journey into Computational Fluid Dynamics (CFD): How do you install OpenFOAM? It’s a question I’ve been approached with countless times, especially by those starting their MSc or embarking on undergraduate projects. While the OpenFOAM website offers instructions for installation, it can sometimes be overwhelming, with one page leading to another and steps getting mixed up. To simplify this process, I aim to provide a ‘one-stop-shop’ guide for installing and compiling OpenFOAM.

Now, you might wonder why I emphasize “compiling” instead of just “installing” or using pre-built versions. The distinction lies in the fact that compiling OpenFOAM involves building the tool from scratch. It’s akin to installing a game or software, but with the added benefit of customization. As a researcher, I often need to modify the code, enhance solver functionalities, introduce custom conditions to CFD simulations, or even incorporate external solvers or modules. These tasks necessitate compiling OpenFOAM, as pre-built packages lack the essential tools for CFD researchers, such as visualization tools (e.g., ParaView/runTimePostProcessing) or external-solver modules (e.g., PETSc).

Before delving into installation options, here’s a crucial heads-up: OpenFOAM is inherently a Linux-based program. Therefore, you’ll need a Linux-based operating system, like Ubuntu, or run Linux on Windows using Windows Subsystem for Linux (WSL). WSL allows you to install a Linux distribution, such as Ubuntu, on Windows and use Linux applications seamlessly. Familiarity with navigating a Linux-based system is essential, and there are various cheat sheets available for quick learning of Linux terminal commands. Moving forward, let’s assume you have a Linux-based system and are comfortable navigating through the command line.

Now, there are two main avenues for installing or compiling OpenFOAM on your system:

• Installing Using Pre-Compiled Binary Packages: This is a straightforward method that involves using packages already compiled for your system.
• Compiling the Source Code: For those seeking customization and the ability to modify OpenFOAM, compiling from the source code is the way to go.

Installing Using Pre-Compiled Binary Packages

Ubuntu

1. To integrate OpenFOAM with your system, you’ll need to incorporate the signing key and repository locations. Typically, this step is a one-time requirement per distribution. Execute the following command in your bash terminal to add the repository. Note that your password will be requested during this process:

   curl https://dl.openfoam.com/add-debian-repo.sh | sudo bash
   

2. Keep your repository information up-to-date by refreshing the system:

   sudo apt-get update
   

3. Choose and install the preferred OpenFOAM package from the options below:

   • Minimalist: Contains essential OpenFOAM components such as solvers, utilities, and libraries. Excludes tutorials and code modification capabilities.

      sudo apt-get install openfoam2312
     

   • Traditional: Includes the minimalist package along with the developer package, enabling code modifications. Surprisingly, tutorials are not included.

      sudo apt-get install openfoam2312-dev
     

   • Everything: As the name implies, this package encompasses EVERYTHING. It is the preferred choice for installing OpenFOAM with pre-compiled packages.

      sudo apt-get install openfoam2312-default
     

4. To access OpenFOAM in your terminal, simply type:

   openfoam2312
   

This installation method ensures that OpenFOAM operates in a self-contained environment. Your tutorials and simulations run within a container, safeguarding the overall system. If you ever need to remove OpenFOAM, use the following command:

sudo apt-get autoremove openfoam2312-default

Windows

Installing OpenFOAM on Windows becomes straightforward if you’ve already set up Windows Subsystem for Linux (WSL). If not, I’ll cover the required steps in an upcoming article. Assuming WSL is installed, follow the same steps as the Ubuntu installation, and everything should seamlessly fall into place!

Compiling the Source Code

Ubuntu/Windows WSL

While the installation of pre-compiled binaries in the earlier sections was relatively straightforward, compiling OpenFOAM from source presents a more intricate process. However, for a dedicated researcher, mastering the art of compiling OpenFOAM, whether on a personal system or an HPC cluster, is a crucial skill. Let’s dive into the steps.

First Steps

Begin by opening the Ubuntu terminal or the Windows WSL terminal and checking the present working directory. Execute the following command in your command line:

pwd

This should display an output similar to the example below:

/mnt/c/WINDOWS/system32

To compile OpenFOAM, you must be in your $HOME directory. Navigate to it by typing:

cd ~

Now, the terminal should have moved to the $HOME directory. Once here, obtain the files required for compiling OpenFOAM:

1. Create a directory named OpenFOAM:

     mkdir OpenFOAM
   

2. Enter the OpenFOAM directory and acquire the necessary files. Find the links to these files using the wget command here.

     cd OpenFOAM
     wget https://dl.openfoam.com/source/v2312/OpenFOAM-v2312.tgz
     wget https://dl.openfoam.com/source/v2312/ThirdParty-v2312.tgz
   

3. The last step involves downloading two files, ‘OpenFOAM-v2312.tgz’ and ‘ThirdParty-v2312.tgz,’ into the OpenFOAM directory. These files are GZIP compressed TAR archive files (.tgz). To decompress them, type in:

     tar -xzvf OpenFOAM-v2312.tgz ### Wait for the process to finish before typing in the next command.
     tar -xzvf ThirdParty-v2312.tgz  ### This should take longer than the previoud step.
   

4. Now, you should see two folders named ‘OpenFOAM-v2312’ and ‘ThirdParty-v2312.’

System dependencies

Before embarking on the OpenFOAM build, it’s crucial to ensure that your system meets the necessary requirements. These system prerequisites encompass the background toolchain and dependencies essential for running OpenFOAM. Among these requirements are a functioning C++14 compiler and the GNU `make’ build toolchain. Without delving into the details of each dependency, here are the steps to satisfy these prerequisites. Note that each command may prompt you to install the corresponding packages; respond with ‘y’ as suggested.

Execute the following commands on your bash command line; this process should take approximately 5 minutes.

sudo apt-get update

sudo apt-get install build-essential autoconf autotools-dev cmake gawk gnuplot

sudo apt-get install flex libfl-dev libreadline-dev zlib1g-dev openmpi-bin libopenmpi-dev mpi-default-bin mpi-default-dev

sudo apt-get install libgmp-dev libmpfr-dev libmpc-dev

sudo apt-get install libfftw3-dev libscotch-dev libptscotch-dev libboost-system-dev libboost-thread-dev libcgal-dev

Source and compile OpenFOAM

Now that the necessary files are in place, and the system dependencies are installed, proceed to source OpenFOAM:

source ~/OpenFOAM/OpenFOAM-v2312/etc/bashrc

After sourcing the OpenFOAM environment, test the system readiness with:

foamSystemCheck

This step should confirm that “OpenFOAM is ready for compilation.”

Next, change the main OpenFOAM directory ($WM_PROJECT_DIR). If this step fails, the environment is not correctly configured:

foam

At this juncture, it’s time to compile OpenFOAM. This process may take anywhere from 30 minutes to 6 hours. Various options are available to expedite the process, including utilizing multiple processors during code compilation. To compile with all cores (-j), reduce output verbosity (-s, -silent), enable queuing (-q, -queue), and log the output to a file (e.g., log.linux64GccDPInt32Opt) for later inspection, execute the following command:

./Allwmake -j -s -q -l

Post-compilation steps

1. Upon the successful completion of the compilation in the previous step, assuming no errors occurred, close the terminal and open a new one.

2. Set up the source alias in your bashrc by entering the following command:

   echo 'alias OF2312='source ~/OpenFOAM/OpenFOAM-v2312/etc/bashrc'' >> ~/.bashrc
   

3. This action creates an alias in your .bashrc file. Now, close this terminal and open a new one.
4. With the alias created, type OF2312 in the new terminal to activate/source the OpenFOAM 2312 environment.
5. Once activated, enter foamInstallationTest to confirm the successful build.
6. Test any tutorial, for example:

   foamTestTutorial -full incompressible/simpleFoam/pitzDaily
   

7. Alternatively, manually perform the previous step:

   # Create the user "run" directory:
   mkdir -p "$FOAM_RUN"
   # Change to the user "run" directory:
   run
   # Copy tutorial
   cp -r "$FOAM_TUTORIALS"/incompressible/simpleFoam/pitzDaily ./
   # Run the tutorial
   ( cd pitzDaily && blockMesh && simpleFoam )
   

As we conclude this guide on installing and compiling OpenFOAM, you’ve now equipped yourself with the foundational knowledge to navigate through the intricacies of this powerful tool. We’ve covered everything from installing pre-compiled binaries to the more involved process of compiling from source. In our next article, “First Steps: Setting up your first case,” we will delve into the practical aspect of applying your newly acquired OpenFOAM environment. Whether you’re embarking on your first CFD simulation or refining your skills, this next installment will guide you through the initial steps of setting up your first case. Get ready to explore the exciting world of Computational Fluid Dynamics hands-on!

Stay tuned for an immersive journey into the practical application of OpenFOAM. Until then, happy simulating!