Difference between revisions of "FSI installation instructions"

Latest revision as of 10:10, 5 February 2022

Fluid-structure interaction (FSI) simulations model the interactions between a moving structure and a fluid flowing around it. Below are instructions of how to run FSI with free open-source software.

Step-by-step instructions

Important: Although I include the links to the official websites for installation instructions, I recommend you follow these instructions for installation (unless they no longer work), since the official instructions contain some mistakes and omissions.

These instructions only work for Ubuntu or Windows 10.

Install OpenFOAM

Ensure you have installed OpenFOAM (v1812 or later) - installation instructions here.

Install FEniCS on Ubuntu

Update 05/02/2022 - These instructions are for FEniCS, which is now considered legacy. Ideally FEniCSx should be used instead (todo), but the FEniCSx-preCICE adapter is in its infancy, so FEniCS is still the best option. Note that around 50% of the documentation online is for FEniCS, 50% for FEniCSx, which adds to confusion.

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

Option 1: Install package directly

Note that this did not work for me, but is apparently a method that is possible for some users.

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

Option 2: Install from source

If installing the package directly did not work (like in my case), then 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 and make commands 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:

OpenFOAM sends the aerodynamic forces at each point on the solid to preCICE.
FEniCS reads the aerodynamic forces from preCICE, and calculates the displacement of the solid at each point.
FEniCS sends the displacement of the solid to preCICE.
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.

If you have installed ParaView on Windows and added the folder containing its .exe file to the Windows PATH environment variable, then you can run these commands to visualise the results:

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.

@@ Line 1: / Line 1: @@
+Fluid-structure interaction (FSI) simulations model the interactions between a moving structure and a fluid flowing around it. Below are instructions of how to run FSI with free open-source software.
 == Step-by-step instructions==
-'''''IMPORTANT:''''' Although I include the links to the official websites for Ubuntu installation instructions, I recommend you <u>follow my instructions for installation</u> (unless my instructions no longer work, or you are a masochist), since the official instructions contain some mistakes and omissions.
+'''''Important:''''' Although I include the links to the official websites for installation instructions, I recommend you <u>follow these instructions for installation</u> (unless they no longer work), since the official instructions contain some mistakes and omissions.
-===Install Ubuntu===
+These instructions only work for Ubuntu or Windows 10.
-If you are running a Windows machine (Windows 10 or above), I recommend installing [https://docs.microsoft.com/en-us/windows/wsl/install-manual Windows Subsystem for Linux] (WSL - use WSL1, discussion of WSL2 below) instead of setting up a dual-boot partition.
-*Note: there is a choice between WSL1 and WSL2, with the main difference being that WSL2 has significantly improved read-write speeds compared with WSL1 while staying within the Linux file system, but WSL2 has significantly worse read-write speeds when moving between the Linux and Windows file systems. In practical terms, this means that the Linux-based software (OpenFOAM, FEniCS) will read and write faster, at the expense of Windows-based ParaView installations loading results much slower when post-processing. Since OpenFOAM spends significantly more time solving equations than reading and writing files, and gigabytes of data need to be loaded across file systems for post-processing in Windows, I recommend sticking with WSL1. If you prefer WSL2, you can install ParaView on Ubuntu, installing XMing to view the GUI (see [https://stackoverflow.com/questions/61110603/how-to-set-up-working-x11-forwarding-on-wsl2 this page] and [https://newbedev.com/how-to-set-up-working-x11-forwarding-on-wsl2 this page] for further information)
-===Install OpenFOAM on Ubuntu===
+===Install OpenFOAM===
-The Ubuntu installation instructions as of 31/12/2021 are summarised below (adapted from [https://develop.openfoam.com/Development/openfoam/-/wikis/precompiled/debian this website]):<syntaxhighlight lang="bash">
+Ensure you have installed OpenFOAM (v1812 or later) - [[OpenFOAM installation instructions|installation instructions here]].
-curl -s https://dl.openfoam.com/add-debian-repo.sh | sudo bash
-sudo apt-get install openfoam2012-default
-</syntaxhighlight>
-Ensure that your ~/.bashrc file has the following line appended (with XXXX replaced with your version number):<syntaxhighlight lang="bash">
-source /usr/lib/openfoam/openfoamXXXX/etc/bashrc
-</syntaxhighlight>
-Restart your Ubuntu. Now check the installation completed correctly by running a tutorial case:<syntaxhighlight lang="bash">
-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
-</syntaxhighlight>
-Note: I use OpenFOAMv2012, but later versions should also work.
 ===Install FEniCS on Ubuntu===
+''Update 05/02/2022 - These instructions are for FEniCS, which is now considered legacy. Ideally FEniCSx should be used instead (todo), but the FEniCSx-preCICE adapter is in its infancy, so FEniCS is still the best option. Note that around 50% of the documentation online is for FEniCS, 50% for FEniCSx, which adds to confusion.''
+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 [https://fenicsproject.org/download/ this website]):<syntaxhighlight lang="bash">
 sudo apt-get install software-properties-common
@@ Line 33: / Line 22: @@
 ===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 [https://precice.org/quickstart.html this website]): <syntaxhighlight lang="bash">
 sudo apt update
@@ Line 42: / Line 33: @@
 </syntaxhighlight>
-Now either install the Ubuntu package directly with the instructions below (which did not work for me)...<syntaxhighlight lang="bash">
+==== Option 1: Install package directly ====
+Note that this did not work for me, but is apparently a method that is possible for some users.<syntaxhighlight lang="bash">
 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
 </syntaxhighlight>
-... or install from source:<syntaxhighlight lang="bash">
+==== Option 2: Install from source ====
+If installing the package directly did not work (like in my case), then install from source:<syntaxhighlight lang="bash">
 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!
+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
 </syntaxhighlight>
-Test that the cmake command worked as expected:<syntaxhighlight lang="bash">
+Test that the <code>cmake</code> and <code>make</code> commands worked as expected:<syntaxhighlight lang="bash">
 cd ~/FSI/precice-2.3.0/build
 ctest --output-on-failure
@@ Line 65: / Line 60: @@
 ===Install the OpenFOAM-preCICE adapter===
-The Ubuntu installation instructions as of 31/12/2021 are summarised below (adapted from [https://precice.org/adapter-openfoam-get.html this website]):<syntaxhighlight lang="bash">
+This adapter allows OpenFOAM to talk to preCICE.
+The Ubuntu installation instructions as of 23/01/2021 are summarised below (adapted from [https://precice.org/adapter-openfoam-get.html this website]):<syntaxhighlight lang="bash">
 cd ~/FSI
-wget https://github.com/precice/openfoam-adapter/releases/download/v1.0.0/openfoam-adapter_v1.0.0_OpenFOAMv1812-v2012.tar.gz
+git clone https://github.com/precice/openfoam-adapter
-tar -xzf openfoam-adapter_v1.0.0_OpenFOAMv1812-v2012.tar.gz
+cd openfoam-adapter
-cd openfoam-adapter_v1.0.0_OpenFOAMv1812-v2012/
+export LD_LIBRARY_PATH=/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH   ### You might need this line, it depends.
-export LD_LIBRARY_PATH=/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH ### This line may-or-may-not be needed. YMMV.
 ./Allwmake
 </syntaxhighlight>
-Note: this is for OpenFOAMv2012. Please see the preCICE website for information on adapters for later versions.
 ===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 [https://precice.org/adapter-fenics.html this website]). This requires Python3, which should already be installed if you followed my previous instructions: <syntaxhighlight lang="bash">
 (optional, should not need this line) python3 -m pip install scipy
 python3 -m pip install --user fenicsprecice
 </syntaxhighlight>
+=== Summary of how the software works ===
+The following four steps are run in a loop:
+# OpenFOAM sends the aerodynamic forces at each point on the solid to preCICE.
+# FEniCS reads the aerodynamic forces from preCICE, and calculates the displacement of the solid at each point.
+# FEniCS sends the displacement of the solid to preCICE.
+# 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 [https://precice.org/couple-your-code-overview.html available here].
 ===Test the installation ran correctly===
@@ Line 96: / Line 103: @@
 ./run.sh
 </syntaxhighlight>
-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:<syntaxhighlight lang="bash">
+Both terminals should now have log outputs flying. After around 1 minute of computation, both terminals should finish at (roughly) the same time.
+If you have installed ParaView on Windows and added the folder containing its .exe file to the Windows PATH environment variable, then you can run these commands to visualise the results:<syntaxhighlight lang="bash">
 cd ~/FSI/tutorials/perpendicular-flap/fluid-openfoam
 paraview.exe fluid-openfoam.foam
@@ Line 102: / Line 111: @@
 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 (or download my edited version, TODO add link here) in order to add 3D FSI functionality. Or just wait a few months until I get around to submitting a pull request for my version.
+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 [[FSI 3D Upgrade|here]]
+== Upgrade to 3D ==
+Please see [[FSI 3D Upgrade|this page]].