Download OpenFOAM® zip archives

  • Download the recommended OpenFOAM® version

  • and the corresponding ThirdParty software.

  • Unzip those archives to $HOME/OpenFOAM and follow the other installation instructions.

Install OpenFOAM® from package

Note

The current version of CFDEM®coupling compiles only with OpenFOAM® in version 10.

The easiest way to install OpenFOAM® on your system is by using the package manager to install a pre-compiled OpenFOAM package:

  • As a prerequisite for the OpenFOAM® installation you need to download and install additional software packages (see the OpenFOAM webpage for more details). On Ubuntu 18.04 and newer execute the following command in a terminal:

    sudo apt-get install build-essential cmake git ca-certificates flex libfl-dev bison zlib1g-dev libboost-system-dev libboost-thread-dev libopenmpi-dev openmpi-bin gnuplot libreadline-dev libncurses-dev libxt-dev

  • Retrieve the OpenFOAM® package provided by OpenFOAM.org (find complete instructions for Ubuntu), which can easily be installed using the “apt” package manager. Basically the dl.openfoam.org repository must be added once to the list of software repositories. This is done with the terminal command:

    sudo sh -c "wget -O - http://dl.openfoam.org/gpg.key | apt-key add -"
sudo add-apt-repository http://dl.openfoam.org/ubuntu

  • Install the downloaded OpenFOAM® package using the terminal commands:

    sudo apt-get update
sudo apt-get -y install openfoam10

  • “Enable” the installed package by loading the OpenFOAM environment variables in your .bashrc file. Open your .bashrc file from the terminal (here using the default text editor in Ubuntu):

    gedit ~/.bashrc

    and add the following line to the end of the file.

    source /opt/openfoam10/etc/bashrc

    Save the changes.

  • For testing your installation, open a new terminal (!) and test that the simpleFoam application is found. Type into your terminal

    simpleFoam -help

    and execute it. You should get a “Usage” message printed to screen.

OpenFOAM® and MPI

Note

This section discusses cases where a user-provided MPI is to be used with OpenFOAM. This is usually the case on clusters. On normal desktop systems, the default setting, i.e. export WM_MPLIB=SYSTEMOPENMPI should work and does not need to be changed.

Often problems arise configuring OpenFOAM® to work with a specific MPI installation on a cluster. However it has built-in capability to work with nearly any MPI implementation. Set the following variable in the OpenFOAM® bashrc:

export WM_MPLIB=SYSTEMMPI

Defining the following variables in your ~/.bashrc before the sourcing of OpenFOAM® will take care of the rest. This is an example for older MVAPICH installations where there is no libmpi.so, only libmpich.so :

export MPI_ROOT=<path/to/mpi/installation>
export MPI_ARCH_PATH=$MPI_ROOT
export MPI_ARCH_FLAGS="-DMPICH_SKIP_MPICXX"
export MPI_ARCH_INC="-I$MPI_ARCH_PATH/include"
export MPI_ARCH_LIBS='-L$(MPI_ARCH_PATH)/lib -lmpich -lmpichcxx -lmpl -lopa -lrt'

Compiling CFDEM®coupling on different linux distributions

On some systems, like RHEL and CentOS, the MPICXX library is required in addition and you need to manually add it to the system linker paths prior to compilation. To do so, add

CFDEM_ADD_LIBS+=-lmpicxx
CFDEM_ADD_LIBS+=-L/path/to/lmpicxx

to

src/lagrangian/cfdemParticle/etc/addLibs_universal/additionalLibs_solver.

Compiling OpenFOAM® and CFDEM®coupling in debug mode

Set the WM_COMPILE_OPTION parameter in the OF bashrc to Debug and compile OF with the Allwmake script. CFDEM®coupling detects the OpenFOAM® variable and compiles in debug mode.

Install swak4FOAM (optional)

Note

Since migrating CFDEMcoupling to OpenFOAM-10, swak4FOAM is no longer used in the CFDEMcoupling tutorials. Consequently, the swak4FOAM installation is not tested with OpenFOAM versions beyond OpenFOAM-8.

swak4FOAM is a library of tools which open functionality otherwise only available by implementing new models. It is used in some test cases, mostly for post processing. To run these test cases without swak4FOAM, remove the related calls which are usually found in the functions subDict in controlDict.

To install swak4FOAM go to your OpenFOAM folder and run

# clone repo into swak4Foam sub folder
git clone https://github.com/Unofficial-Extend-Project-Mirror/openfoam-extend-swak4Foam-dev.git swak4Foam

# go to cloned folder
cd swak4Foam
# checkout version compatible to OpenFOAM-8
git checkout 0f570f524c0e3be44155cdf0f7623c5403f234d3

# build
./AllwmakeAll

All dependencies and package requirements should already be installed from the package installation during the OpenFOAM installation process.

Note

If encountering compilation problems with swak4FOAM, try first to run the compilation on a single core by running export WM_NCOMPPROCS=1 before invoking ./AllwmakeAll.

Note

Refer to swak4Foam for further documentation on swak4FOAM.

Backward Compatibility

Basically, CFDEM®coupling supports one OpenFOAM® version. Therefore, all settings are prepared for that particular version. Nevertheless we try to maintain backwards compatibility as long as it works with reasonable effort.

The supported OpenFOAM® and Aspherix® versions are stated in:

src/lagrangian/cfdemParticle/cfdTools/versionInfo.H

For using other versions you can manipulate:

src/lagrangian/cfdemParticle/etc/OFversion/OFversion.H

Install git

Git allows you to update the source code very easily with the git pull command. On debian based systems you can run

sudo apt-get install git-core

Similar packages are available on other systems too:

sudo zypper install git-core
sudo yum install git

Note

In this tutorial the git protocol is used to transfer files. If port 9418 is closed for internet connections, please switch to “https://” instead of “git://” for git clone commands.

Install Helyx®OS (optional)

If you are interested in using a GUI based workflow for setting up your coupled CFD-DEM cases we recommend having a look into Helyx®-OS provided by Engys.

Note

This is to be considered only a first “proof of concept” of combining CFDEM®coupling and Helyx®OS, which is planned to be streamlined in the future.

The detailed installation instructions for Helyx®OS basically boil down to downloading the installer from this link.

Then you need to change the permissions of the file by typing to the terminal

chmod 755 HELYX-OS-2.4.0-linux-x86_64.bin

And finally you need to execute the installer in a terminal by typing

./HELYX-OS-2.4.0-linux-x86_64.bin

Note

It is not required to install GUI + Kernel as you can use the OpenFOAM® version installed as described above. So please select only the components HELYX-OS-GUI. During installation the destination folder is being queried. As a default your user home directory is a good starting point. Simply type “echo $HOME” in a terminal to see the path.

For a simple start of Helyx®OS we recommend to add to your ~/.bashrc (right above the definition of CFDEM_VERSION) the path of your Helyx®OS installation (you can find the correct path by looking for the file HELYX-OS.sh):

export CFDEM_HELYXOS_DIR=$HOME/Engys/HELYX-OS/v2.4.0

In order to check your environment variables you can use the command

cfdemSysTest

, which will show your settings and if they are complete and correct. After defining CFDEM_HELYXOS_DIR you can start Helyx®OS by typing to your terminal:

cfdemHelyxOS

After the first start you will have to define the paths to your OpenFOAM® installation. Please add

/opt/openfoam6

to Edit/Preferences/Core Folder.

Install OpenFOAM on Windows

You can run OpenFOAM® and CFDEM®coupling natively on Windows unsing the Windows sub-system for Linux (WSL).

  1. To prepare your Windows system, check that you have updated your Windows 10 to at least version 2004, e.g. displayed in Settings -> System -> Info -> Windows specifications. If you do not have this version installed, run the update from Settings -> Update & Security -> Windows Update.

    Note

    You can force the update of Windows 10 to version 2004 as described in this manual.

  2. Activate WSL by opening the PowerShell as Administrator via the start menu and execute the command:

    Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

    When prompred choose to restart Windows.

  3. When rebooted, open a new PowerShell terminal with Administrator privileges and execute:

    Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform

    Again, when prompred choose to restart Windows.

  4. After the second reboot, start a new PowerShell terminal with Administrator privileges and to switch from WSL1 to the newer version WSL2, execute:

    wsl --set-default-version 2

Now, WSL2 is set up and we proceed by installing a Ubuntu virtual machine which will be used by WSL.

  1. Start by opening the Microsoft Store and search for Ubuntu 20.04. Click Install. This will download the system image and may take some time depending on your internet connection.

  2. Start Ubuntu 20.04 from the start menu. This step will set up Ubuntu. In the process you must choose a username and a password for that user. These do not need to be identical with your Windows credentials.

  3. Within the Ubuntu system run the following commands to update the package repository and install required tools:

    sudo apt update
sudo apt install build-essential

  4. OPTIONAL graphics support Install pre-requisites

    sudo apt install nautilus gedit
sudo apt install xfce4

    Open your bashrc (e.g. using nano)

    nano .bashrc

    and add the line

    export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0

    at the file end. Save the changes. If using nano, this is done using Ctrl + o followed by Ctrl + x.

  5. Create links to acces the Windows file system more easily:

    ln -s /mnt/c/Users/yourUserName/Downloads winDownloads
ln -s /mnt/c/Users/yourUserName/Documents winDocuments

  6. Close the terminal.

  7. Install Paraview on Windows

  8. OPTIONAL graphics support

    To run graphical programs on the Linux machine you need to additionally install an Xserver on your Windows. Fir this purpose we recommend VcXsrv. After installing VcXsrv, start it using the application Xlaunch.

    Note

    When doing so make sure to activate the checkbox “Disable access control”.

    Note

    Modern systems may require to enable “Native opengl” to allow running the Aspherix-GUI.

  9. OPTIONAL graphics support

    Restart the ubuntu terminal.

    In the terminal type

    startxfce4 &

    to start the graphical user interface.

Now, you are ready to proceed with the normal installation of OpenFOAM and CFDEMcoupling as described above within the just set up Ubuntu sub-system.

Note

After the installation of Aspherix-GUI you need to change the path of the Paraview installation to point to the one installed in Windows.