Installing OpenFOAM in 3 easy steps with RheologicRemix binaries

In this article we give you a step-by-step installation guide for our RheologicRemix binaries. For beginners this is probably the easiest and for professionals the fastest way how to get OpenFOAM with its most important dependencies and tools running on a variety of operating systems.

Before we start, let's get one thing out of the way: OpenFOAM is a trademark owned by ESI and as laid out in their trademark guidelines we are obliged not to create any confusion regarding that. The installation instructions below apply to our RheologicRemix binaries, which are based on OpenFOAM, however, what we are showing here is not approved or endorsed by OpenCFD Limited, the producer of the OpenFOAM software and owner of the OPENFOAM® and OpenCFD® trade marks.

What we do show here is how to install our RheologicRemix binaries, which are based on OpenFOAM and are pre-compiled including common tools and libraries - foremost Paraview and OpenMPI - for a variety of platforms. This is to the best of our knowledge the fastest and simplest way to get OpenFOAM running. We use this process ourselves when we are deploying on a new machine. If you want to have more control over the installation process, because you want to include special compiler flags, libraries or made modifications to the source code, this guide is not for you - look in the Resources Section below for a couple of pointers.

Please note that while Paraview is included in the official package, it usually lags a bit behind the original Paraview release schedule. You might therefore want to install a newer Paraview version independently of the one included here (there are installers for all major linux distributions). For RheologicRemix-3.0.1 the foamyHexMesh and foamyQuadMesh tools are not included - as with the official apt-get package, they need to be compiled independently.

For the Impatient

Issue the following commands in your terminal (adapt the bashrc line to fit your version):

$ cd ~ && wget http://rheologic.net/RheologicRemixLatest
$ tar -xvf RheologicRemixLatest
$ cat bashrc-OpenFOAM-3.0.1 >> .bashrc && source .bashrc

Done. Yes, that's all.

Everybody else: read on!

Prerequisites

Ok, here we go. For this guide I assume that you are on some flavour of linux system and have a basic working knowledge of opening a terminal and running command line programs. Even if not, the following instructions will likely get you there with a bit of googling on how to use unix/linux terminal and command lines. A common scenario is that you are on ubuntu or kubuntu with some kind of graphical window manager. To open a command line window simply click on the ubuntu or kubuntu icon and type in "terminal" in the search window. In most cases this will give you a list of terminal programs that you can use to issue the commands shown below.

Step 1: Download the RheologicRemix Binaries

For your convenience we created a short link to the latest x86-64bit archive suitable for most modern linux distributions: http://rheologic.net/RheologicRemixLatest. In your terminal window you can download this like so:

$ wget http://rheologic.net/RheologicRemixLatest

The downloaded file is simply named RheologicRemixLatest and is a xz-compressed tar archive.

If you need a specific version or if you are on a less common operating system go to the RheologicRemix download page and pick the proper binary for your operating system. Currently we offer versions for ubuntu, CentOs and also for ARM architectures (e.g. RaspberryPi, Android). If you are in doubt about which binary to choose you will most likely want the "ubuntu" binary (this is identical to the RheologicRemixLatest linked above). It is compiled for x86-64bit architectures and will probably work on most modern linux systems, though we have not tested this (let us know if you have!). Please note, that while the download link says something like "Ubuntu-12.04-LTS up to Ubuntu 14" the archive file itself might be named something like RheologicRemix-2.3.x-6586d545d605-Ubuntu-12.04_LTS.tar.xz. Even though the file name does not contain "Ubuntu 14" it works perfectly fine there too (and probably on a lot of other modern linux distributions). If you need them there are also RheologRemixes available based on older versions of OpenFOAM. Click on the appropriate button on the download page to reveal them. To download, simply click on the binary you want to grab and save it in a convenient location. The file that is downloaded is a compressed archive file (tar archive, xz compressed) ending in .tar.xz. As a completely optional step, you can verify the downloaded file using pgp check its integrity with sha256 - skip to the bottom for detailed instructions on verification.

Step 2: Unpack the Binaries

The next step is to unpack the binaries. We'll show how to do this in the user's home directory, to keep paths simple and to demonstrate that the set-up process works perfectly fine with simple user rights. If you want to set up the binaries under a different path, you will have to do some adjustments in the environment variables (see next step). This basically means that as long as you are able to execute commands in a terminal with your account you will probably also be able to get OpenFOAM to run. The archive we downloaded in the previous step contains on its top level one directory called OpenFOAM and a text file called bashrc-OpenFOAM-2.3.0. We are going to extract the archive into the home directory using one of two methods, we are showing here. The first method is to simply use a archiving program to extract the archive into the proper location as shown in the screenshot. In this case I used "Ark" the archiver that comes with KDE, but you are free to use any other program for the purpose of course.
The second method uses the command line in your terminal window and is just as simple; assuming that you saved the archive in your users home directory, simply issue the following command from your home directory (replace the file name with RheologicRemixLatest if you downloaded using the shortlink):

$ tar -xvf RheologicRemix-2.3.x-6586d545d605-Ubuntu-12.04_LTS.tar.xz

You will see a long list of paths whiz by in your terminal as the files are unpacked. This process can take a minute or two depending on the performance of your system. The output will look something like this:

$ tar -xvf RheologicRemix-2.3.x-6586d545d605-Ubuntu-12.04_LTS.tar.xz
bashrc-OpenFOAM-2.3.x
OpenFOAM/OpenFOAM-2.3.x/
OpenFOAM/OpenFOAM-2.3.x/.git/
OpenFOAM/OpenFOAM-2.3.x/.git/refs/
OpenFOAM/OpenFOAM-2.3.x/.git/refs/heads/
OpenFOAM/OpenFOAM-2.3.x/.git/refs/heads/master
...
[ around 70.000 more lines ]
...
OpenFOAM/ThirdParty-2.3.x/openmpi-1.6.5/config.log
OpenFOAM/ThirdParty-2.3.x/openmpi-1.6.5/config.status
OpenFOAM/ThirdParty-2.3.x/openmpi-1.6.5/libtool
OpenFOAM/ThirdParty-2.3.x/openmpi-1.6.5/Makefile
$

Once the archive has finished unpacking everything that you need to run OpenFOAM is on your hard drive. What remains is to set up your working environment and test the installation.

Step 3: Set up Environment Variables

OpenFOAM relies on a number of environment variables in order to determine working directories, library paths and so forth. For convenience we provide a small text file named bashrc-OpenFOAM-2.3.x containing these environment variables. The only thing to change in this file is to tell OpenFOAM the number of processors you want it to run on. I'm assuming that you have 4 cores in your system. Open up the file in your favourite text editor, delete the hash mark (#) from this line #export WM_NCOMPPROCS=4 and save the file (hash marks denote comment lines). The easiest way to let OpenFOAM know about your environment variables is to add them to your .bashrc file. To do so, simply issue the following command from your home directory in your terminal:

$ cat bashrc-OpenFOAM-2.3.x >> .bashrc

To test if this is working type the following into your terminal:

$ source .bashrc
$ env | grep OpenFOAM

If you see a bunch of lines with paths to various OpenFOAM directories: Congratulations! You successfully installed the RheologicRemix and you are good to go!

Verify Installation

While the process itself is complete after setting up the environment variables, I'll run you very quickly through a short test run to check if everything is working properly. For this purpose we will use the simplest OpenFOAM tutorial case called 2D lid driven cavity flow (official tutorial).

Type the following into your terminal window. First we change into the case directory, then we generate the mesh:

$ cd OpenFOAM-2.3.x/tutorials/incompressible/icoFoam/cavity
$ blockMesh
/*---------------------------------------------------------------------------*\
| =========                 |                                                 |
| \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox           |
|  \\    /   O peration     | Version:  2.3.x                                 |
|   \\  /    A nd           | Web:      www.OpenFOAM.org                      |
|    \\/     M anipulation  |                                                 |
\*---------------------------------------------------------------------------*/
Build  : 2.3.x-6586d545d605
Exec   : blockMesh

[ more output ]

Patches
----------------
  patch 0 (start: 760 size: 20) name: movingWall
  patch 1 (start: 780 size: 60) name: fixedWalls
  patch 2 (start: 840 size: 800) name: frontAndBack

End

If there are no errors at this stage you are ready to run your first simulation:

$ icoFOAM
/*---------------------------------------------------------------------------*\
| =========                 |                                                 |
| \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox           |
|  \\    /   O peration     | Version:  2.3.x                                 |
|   \\  /    A nd           | Web:      www.OpenFOAM.org                      |
|    \\/     M anipulation  |                                                 |
\*---------------------------------------------------------------------------*/
Build  : 2.3.x-6586d545d605
Exec   : icoFoam

[ additional output ]

Starting time loop

Time = 0.005

Courant Number mean: 0 max: 0
smoothSolver:  Solving for Ux, Initial residual = 1, Final residual = 8.90511e-06, No Iterations 19
smoothSolver:  Solving for Uy, Initial residual = 0, Final residual = 0, No Iterations 0
DICPCG:  Solving for p, Initial residual = 1, Final residual = 7.55423e-07, No Iterations 35
time step continuity errors : sum local = 5.03808e-09, global = -7.94093e-21, cumulative = -7.94093e-21
DICPCG:  Solving for p, Initial residual = 0.523588, Final residual = 9.72371e-07, No Iterations 34
time step continuity errors : sum local = 1.07766e-08, global = 2.00426e-19, cumulative = 1.92485e-19
ExecutionTime = 0.01 s  ClockTime = 0 s

[ lots of additional output for a number of time steps ]

Time = 0.5

Courant Number mean: 0.222158 max: 0.852134
smoothSolver:  Solving for Ux, Initial residual = 2.32737e-07, Final residual = 2.32737e-07, No Iterations 0
smoothSolver:  Solving for Uy, Initial residual = 5.07002e-07, Final residual = 5.07002e-07, No Iterations 0
DICPCG:  Solving for p, Initial residual = 1.0281e-06, Final residual = 2.77237e-07, No Iterations 1
time step continuity errors : sum local = 4.0374e-09, global = -9.0204e-19, cumulative = -2.44407e-18
DICPCG:  Solving for p, Initial residual = 5.31987e-07, Final residual = 5.31987e-07, No Iterations 0
time step continuity errors : sum local = 6.12557e-09, global = -3.93738e-20, cumulative = -2.48344e-18
ExecutionTime = 0.16 s  ClockTime = 0 s

End

Paraview with OpenFOAM test case and instructions
When you see End in your terminal window another round of congratulations is in order: you just ran a simulation with your new set-up! Let's check if Paraview is working and take a look at the results of our simulation:

$ foamToVTK && paraview --data=VTK/cavity_..vtk

Your will see some output in your terminal while foamToVTK converts the simulation results to vtk-files which can be read by the Paraview program, then Paraview will open. Click on "Apply", select "U" (fluid velocity) from the dropdown and skip forward to the last time step. You should see something like in the screenshot.

That's it! You have set up the RheologicRemix binaries sucessfully in three easy steps and verified the functionality of the set-up by running a simulation and having a look at the result.

If you found this useful, please leave us a comment on our google+ page, if you have questions or other comments, let us know!


Optional: Verify the downloaded archive file

This step is completely optional. Since you should never execute code from unknown sources we provide two ways for you to verify that the archive you downloaded is actually the one created by us. The first way is to download the PGP signature file (ending in ".asc") from the same page you got the archive from. Save this file in the same directory and then type the following command in your terminal (adjust the file names if you downloaded a different archive):

$ gpg --verify RheologicRemix-2.3.x-6586d545d605-Ubuntu-12.04_LTS.tar.xz.asc RheologicRemix-2.3.x-6586d545d605-Ubuntu-12.04_LTS.tar.xz

If the signature matches the file you should see something like this in your terminal:

gpg: Signature made Die 16 Jun 2015 13:57:54 CEST using RSA key ID 3B2974BB
gpg: Good signature from "Andras Horvath "

The second method works by creating a SHA256 hash (think: file fingerprint) of the downloaded archive and compare the fingerprint that you made with the one posted on the download page. If the hashes are the same, the file you downloaded is identical to the one we created. To generate the hash type the following into your terminal:

$ sha256sum RheologicRemix-2.3.x-6586d545d605-Ubuntu-12.04_LTS.tar.xz
832f71c72d943c3072ba72f7741d4f67ecb2c0df6a6c6fe51835cd42d71dab16  RheologicRemix-2.3.x-6586d545d605-Ubuntu-12.04_LTS.tar.xz

The hash should be identical to the one that is posted on our download page.


Resources

Official and in-depth Installation Instructions

 

OpenFOAM Tutorials to get you started