ipedrojm/wsifoam repository overview

⁠Installation guidelines

Docker containers enable binaries compiled on a given Linux environment to be run on other platforms without any performance degradation. Docker allows you to run wsiFoam in any OS, without having to install OpenFOAM: simply download this precompiled code ready to be run out of the box!

Please follow these installation guidelines carefully in order to get the latest version of wsiFoam.

1. Installation of docker

• Windows/macOS users to install docker from here⁠ (if you are using an old version of Windows/macOS which is incompatible with docker, please install the Docker Toolbox from here⁠). Download the corresponding installer and execute it like any other traditional Windows/macOS program (additional Windows installation instructions can be found here⁠ while additional macOS installations instructions can be found here⁠).
• Linux users to run the command:

sudo apt install docker.io

1. Running docker

• Windows/macOS users to lunch a new docker terminal as suggested at the end of the installation process.
• Linux users to start the docker daemon:

sudo service docker start

1. Download the wsiFoam image

Download the latest version of wsiFoam with the following command:

docker create -ti --name wsicontainer -v ${1:-$HOME}/shared:/home/docker/shared ipedrojm/wsifoam:latest

This will take some time depending on your internet connection (it will download 650MB approximately). This command needs to be executed only once and will download a docker image, which cannot be modified.

1. Start the wsiFoam container

Contrarily to docker images, docker containers can be modified. This container will be used to make changes, compile new code, run simulations, etc. Run the wsiFoam container based on the previous image by typing the following command:

docker stop wsicontainer && docker start -i wsicontainer

The docker terminal will automatically switch into an Ubuntu terminal. A greeting message will be displayed to select the OpenFOAM or FOAM-Extend environment. Furthermore, running the following command:

runCase damBreakMartinMoyce1952

will copy this tutorial case into your home directory and execute it.

In future iterations simply lunch a docker terminal and start the wsiFoam container by typing the command specified in this section.

1. Visualising data with ParaView

ParaView is not installed in the docker image for a good reason. Therefore you need to install a version of ParaView compatible with your OS from here⁠. After this, lunch ParaView and:

1. click on File>Open,
2. select Files of type>All types(*),
3. navigate to your simulation directory and open the file with ** .OpenFOAM* extension,
4. select OpenFOAM files.

If that file is not present in your simulation directory, you can easily generate it by typing the command:

paraFoam -touchAll

1. About shared volumes

The directory /home/docker/shared is shared between the docker container and your OS. This means that any files and folders within that directory can be seen inside and outside the container allowing ParaView to access them. This is a great feature but it can compromise docker's performance in cases involving intensive I/O operations, e.g. running simulations. There a are two possible ways to overcome this:

1. run simulations outside the shared directory /home/docker/shared even though the data will not be accessible from your OS. Once the simulation has finished, the data can be quickly moved to the shared directory and visualised with ParaView;
2. run simulations inside the shared directory /home/docker/shared making sure that:

• the variable runTimeModifiable no; is set in the controlDict dictionary file and
• the solver's log file remains outside the shared directory.