FSI installation instructions

Step-by-step instructions

IMPORTANT: Although I include the links to the official websites for installation instructions, I recommend you follow my instructions for installation (unless my instructions no longer work, or you are a masochist), since the official instructions contain some mistakes and omissions.

These instructions only work for Ubuntu or Windows 10 and above.

MacOS: I recommend installing everything on an Ubuntu virtual machine, since installing OpenFOAM on MacOS is possible (using a Docker image), but the steps after that are only possible with Ubuntu (or similar Linux distro).

Optional: Install ParaView

If you wish to view the results of the simulations, the best way to do this is with ParaView.

Simply download the executable for your operating system from this website.

The same website also hosts excellent tutorials and documentation PDFs - these should be your first resource when learning how to use ParaView.

Windows 10: In order to run ParaView from the command line, you must add paraview.exe to Path:

• Find the folder containing your paraview.exe executable, and copy the folder's location (not the file's location) to your clipboard with CTRL+C.
• In the search bar, type "Edit the system environment variables" and click the first option.
• Click the box labelled "Environment Variables..." in the lower right corner.
• A dialogue box appears. In the lower half labelled "System Variables", scroll to the variable "Path"
• Double click on the "Path" variable.
• Click "New"
• Paste the folder path you copied earlier into the text box that is now selected.
• Click "OK" on all the dialogue boxes.

You can now open files in ParaView from the command line with paraview.exe <file>, replacing <file> the file you wish to open.

Windows 10 and above: Install Ubuntu

I recommend installing Windows Subsystem for Linux instead of setting up a dual-boot partition (use WSL1, discussion of WSL2 below).

• WSL1 Pros: fairly fast read/write in both Ubuntu and Windows file systems. Cons: much slower at read/write in Ubuntu file system than WSL2.
• WSL2 Pros: lightning fast read/write in Ubuntu. Cons: very slow read/write when moving data between Ubuntu and Windows.
• Summary: Use WSL1 if you have a Windows-based ParaView or another app that will read lots of data between file systems.
  • If you want to use WSL2 anyway, I recommend you install ParaView on Ubuntu to avoid reading between file systems. You must also install XMing to view the GUI. See this page and this page for further information.

Install OpenFOAM on Ubuntu

OpenFOAM is an open-source Computational Fluid Dynamics (CFD) package. We will use it to simulate the fluid (air) flow.

The Ubuntu installation instructions as of 31/12/2021 are summarised below (adapted from this website):

curl -s https://dl.openfoam.com/add-debian-repo.sh | sudo bash
sudo apt-get install openfoam2112-default

Append the following line to your ~/.bashrc file, if not already present:

source /usr/lib/openfoam/openfoam2112/etc/bashrc

Restart Ubuntu. Now check the installation completed correctly by running a tutorial case:

cd ~
mkdir -p OpenFOAM-sims/tutorials
cp -r $FOAM_TUTORIALS/incompressible OpenFOAM-sims/tutorials
cd OpenFOAM-sims/tutorials/incompressible/icoFoam/cavity/cavity/
blockMesh > log.blockMesh
icoFoam > log.icoFoam

Note: this used OpenFOAMv2112, but versions >= v1812 should work.

Install FEniCS on Ubuntu

FEniCS is an open-source Finite Element Method (FEM) library. We will use it to simulate how a solid bends as a result of applied forces.

The Ubuntu installation instructions as of 31/12/2021 are summarised below (adapted from this website):

sudo apt-get install software-properties-common
sudo add-apt-repository ppa:fenics-packages/fenics
sudo apt-get update
sudo apt-get install fenics

Install preCICE on Ubuntu

preCICE is an open-source library for coupling simulations together. We will use it to allow OpenFOAM and FEniCS to communicate with each other.

The Ubuntu installation instructions as of 31/12/2021 are summarised below (adapted from this website):

sudo apt update
sudo apt install build-essential cmake libeigen3-dev libxml2-dev libboost-all-dev petsc-dev python3-dev python3-numpy
cd ~
mkdir FSI
cd FSI

Now either install the Ubuntu package directly with the instructions below (which did not work for me)...

wget https://github.com/precice/precice/releases/download/v2.3.0/libprecice2_2.3.0_focal.deb
sudo apt install ./libprecice2_2.3.0_focal.deb

... or install from source:

tar -xzf v2.3.0.tar.gz
cd precice-2.3.0
mkdir build
cd build
cmake -DBUILD_SHARED_LIBS=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=~/FSI/precice-2.3.0 -DPRECICE_MPICommunication=ON .. ### IMPORTANT! INCLUDE THE TWO DOTS!
make -j 4

Test that the cmake command worked as expected:

cd ~/FSI/precice-2.3.0/build
ctest --output-on-failure

If no errors were shown, install the software and test it worked:

make install
make test_install

Note: I used preCICE v2.3.0, but later versions should also work.

Install the OpenFOAM-preCICE adapter

This adapter allows OpenFOAM to talk to preCICE.

The Ubuntu installation instructions as of 23/01/2021 are summarised below (adapted from this website):

cd ~/FSI
git clone https://github.com/precice/openfoam-adapter
cd openfoam-adapter
export LD_LIBRARY_PATH=/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH   ### You might need this line, it depends.
./Allwmake

Install the FEniCS-preCICE adapter

This adapter allows FEniCS to talk to preCICE.

The Ubuntu installation instructions as of 31/12/2021 are summarised below (adapted from this website). This requires Python3, which should already be installed if you followed my previous instructions:

(optional, should not need this line) python3 -m pip install scipy
python3 -m pip install --user fenicsprecice

Summary of how the software works

The following four steps are run in a loop:

1. OpenFOAM sends the aerodynamic forces at each point on the solid to preCICE.
2. FEniCS reads the aerodynamic forces from preCICE, and calculates the displacement of the solid at each point.
3. FEniCS sends the displacement of the solid to preCICE.
4. OpenFOAM reads the displacement from preCICE, and calculates the new aerodynamic forces.

This is a simplification of the process (called a serial explicit coupling). In reality, a better method is to have all four steps occur simultaneously until the residual is low enough (called parallel implicit coupling). This is faster and more accurate.

Further information about coupling is available here.

Test the installation ran correctly

... by running this tutorial case:

cd ~/FSI
git clone --branch=master --depth 1 https://github.com/precice/tutorials.git
cd ~/FSI/tutorials/perpendicular-flap/fluid-openfoam
./run.sh

The command line output should have paused after this output. If it did not pause, something went wrong.

---[precice]  I am participant "Fluid"
---[precice]  Setting up master communication to coupling partner/s

Now open another Ubuntu terminal, and run these commands:

cd ~/FSI/tutorials/perpendicular-flap/solid-fenics
./run.sh

Both terminals should now have log outputs flying. After around 1 minute of computation, both terminals should finish at (roughly) the same time. You can view the results with the following commands, assuming you have installed ParaView on Windows and added the folder containing its .exe file to the Windows PATH environment variable:

cd ~/FSI/tutorials/perpendicular-flap/fluid-openfoam
paraview.exe fluid-openfoam.foam

Congratulations! You should now have a functional FSI installation.

Note that as of 31/12/2021, the unmodified FEniCS-preCICE adapter only works in 2D, so you will have to edit the adapter in order to add 3D FSI functionality, instructions here

Upgrade to 3D

Please see this page.