OpenFOAM

This page describes how to run OpenFOAM in a docker container in Red Cloud. Specifically, these instructions involve the use of OpenFOAM-7 from The OpenFOAM Foundation as provided at https://github.com/OpenFOAM/OpenFOAM-7. This material generally assumes you are familiar with OpenFOAM, and are mostly interested in learning how to run it in a container on Red Cloud.

Launch Instance

To run OpenFOAM, you will need to launch an instance in Red Cloud. Instances come in various "flavors" comprised of different numbers of computational cores and total amount of memory available to those cores. See the Red Cloud Instances documentation for more information. Depending on what sort of computation you want to run in OpenFOAM, you might want to choose a larger flavor with more memory and multiple cores to enable the code to run in parallel, but you will generally want to choose the smallest instance necessary to do your work so as not to use up your subscription more quickly than is required. The last of the tutorials described below is configured to run using 8 processes, so you would need to choose a c8.m64 instance to run that. The Docker container described here is intended to run on CPUs. While there are efforts to port OpenFOAM to GPUs, that is not currently supported by this container.

Launch a Red Cloud instance using the openfoam-docker-2020-09-17 image. See the Red Cloud Linux instances page on how to launch an instance, and the Images page for more information about images on Red Cloud. You can launch an image either directly from the openfoam-docker-2020-09-17 image page, or by following the general instructions for creating a Red Cloud Linux instance and choosing the openfoam-docker-2020-09-17 image as the source for the new instance.

Run and Attach to Docker Container

  1. ssh to the Red Cloud instance

    • Because the openfoam-docker image is based upon an Ubuntu image, the username for your ssh command will be ubuntu, e.g., with a command such as:
      ssh -i my_key.pem ubuntu@<IP address of your instance>

    • See the documentation on Secure Shell (SSH) for more information on connecting to your instance.

  2. Run and attach a docker container containing the OpenFOAM image:
    docker container run -ti openfoam/openfoam7-paraview56

    • After executing this command, you should notice that the command prompt has changed, as the docker container is now running and is providing you with access to a separate bash shell running within the container.

Tutorials

We present here three tutorials that are included in the \$FOAM_TUTORIALS directory. The first two are small and simple enough that they can be run on the smallest Red Cloud instance, c1.m8. The last is a more complicated example run in parallel on a larger instance. Feel free to explore the contents of the \$FOAM_TUTORIALS directory if you'd like to examine other tutorials.

pitzDaily

This example is based on the experimental work of Pitz and Daily (1981). It features a backward facing step. Such a "classic" case is instructive for comparing different turbulence models with respect to the size and shape of the recirculation zone.

  • Now that you are running a bash shell within the OpenFOAM docker container, first make a unique working directory and copy the pitzDaily example code into the directory, by executing the following commands within the docker bash shell:

      WORK_DIR=$FOAM_RUN-$(whoami)-$(date +%s) 
  echo $WORK_DIR
  mkdir -p $WORK_DIR 
  cd $WORK_DIR
  cp -r $FOAM_TUTORIALS/incompressible/simpleFoam/pitzDaily .
  cd pitzDaily

  • Next, let's run the simulations. Execute these commands in sequence. They will run quickly (under a minute), and will produce some printed output.

    • blockMesh
    • simpleFoam

  • If you're curious about where those applications are within the container, you can make use of standard Linux commands to examine the PATH that has been set up within the container, and figure out where these applications are stored:

    • echo $PATH
    • which blockMesh

icoFoam Cavity

This is a second example that we will want to run in a separate subdirectory. First execute the following commands, in order to go back to the working directory (\$WORK_DIR) and copy the code for the cavity example:

 cd $WORK_DIR
 cp -r $FOAM_TUTORIALS/incompressible/icoFoam/cavity/cavity . 
 cd cavity
  • Now run the simulations:
    • blockMesh
    • icoFoam

motorBike

This is a more computationally challenging example, simulating flow around a motorbike with a rider on it. This example is configured to run using 8 processes (by dividing up the problem into 8 subdomains), which we can run on Red Cloud on a c8.m64 instance (or larger). The computation for this tutorial, even when run in a shorter -test mode (as specified below), runs for approximately 30 minutes on 8 cores, so you might not want to run this example unless you'd like to examine the output, or do something similar by adapting this example. (If you run the example without the -test option, it will carry out a much longer computation, so beware.) Like the other tutorials, we will want to run this in a separate subdirectory. First execute the following commands, in order to go back to the working directory (\$WORK_DIR) and copy the code for the motorBike example:

 cd $WORK_DIR
 cp -r $FOAM_TUTORIALS/incompressible/pisoFoam/LES/motorBike . 
 cd motorBike
  • Now run the simulation:
    • ./Allrun -test

Cleaning Up

  • Once you are finished running within your docker container, you can issue the command exit to terminate the bash shell running within the container and return to the outer bash shell running in your Red Cloud instance.
  • If you want to get the data files with the results out of the docker container, you can copy the files from the container to your Red Cloud instance (and then perhaps transfer to your local machine using scp or sftp). Assuming you have exited the container as described in the line above, in order to copy the files out of the container, do the following:
    • Run docker ps -a to see a list of containers that have been run. There might be only one if you've run through these instructions just once. Find the Container ID of the container that you ran the OpenFOAM code in — we'll refer to this below as [CONTAINER_ID]. Alternatively, you can run docker ps -alq just to get the ID of the latest created container.
    • Make a directory in your Red Cloud instance to hold files from the container, e.g.: mkdir tmp_container
    • Run docker cp [CONTAINER_ID]:/home/openfoam tmp_container
    • The previous command should recursively copy all the contents of the /home/openfoam directory in the container to your tmp_container directory in the Red Cloud instance. The specific name of the directory under /home/openfoam will reflect the \$WORK_DIR variable set in the examples above.
  • If you are done using your instance for the time being, you can logout (exit) and then shelve your instance so that you do not continue to accrue charges to your Red Cloud subscription. See our documentation for more information about managing your subscription.