3 ways to run tutorials in OpenFOAM

Tutorial Requirements

Tutorials – The starting point of almost every simulation

Tutorials are an interactive way of transferring knowledge. They are a kind of recipes which provide you with the necessary steps to complete a particular task. The maintainers of OpenFOAM, OpenFOAM+, and FOAM-extend deliver an extensive collection of tutorials together with the library. For OpenFOAM users, the supplied case setups are the most useful information provided for free. Reading this post to the end will enable you to run all these tutorials avoiding numerous pitfalls.

Tutorials are essential because to start your project in most cases you will:

  1. Select a solver implementing all necessary physics
  2. Check the available tutorials for the solver
  3. Copy, rename and modify the most similar tutorial
  4. Test and run your simulation

Let’s get started

The tutorial collection contains a variety of different case setups. In the following, you will learn three different ways to run OpenFOAM tutorials. To get started, open a terminal window and copy the tutorial collection into your run directory.

1. Simple blockMesh/mySolverFoam tutorials

The lid-driven cavity flow is a common test case for validation. It is also one of the cases thoroughly explained in the OpenFOAM user guide (section 2.1). The way how you create and run simulations in OpenFOAM may seem a bit strange to users who come from a Microsoft-Windows environment or who are used to have a GUI. Instead, solvers, utilities, or scripts in OpenFOAM require a certain directory structure containing control files. Navigate to the cavity folder and type ls -R or tree to get an overview.

All tutorials have a system (control files for solvers and utilities), a constant (mesh, material properties), and a 0 (zero) directory (initial values, boundary conditions). If no further execution scripts are provided, you will always have to run blockMesh, for the mesh creation, and afterward your solver of choice, in our case icoFoam. In rare cases, there are one or two more dictionaries for preprocessing in the system folder (pre -> they are executed before the solver). A possible scenario is an additional setFieldsDict to set initial field values. The corresponding utility to run after blockMesh would be setFields. The applications will give some output which should be saved in log files for later use (and to avoid that the terminal window is overflowing with solver output). &> redirects the standard output and error messages of, for example, blockMesh to the file log.blockMesh. Now it’s time to run our first tutorial:

cavity_vetor_plot
Vector plot of cell-centered velocity colored by its magnitude.

2. Tutorials with Allrun/Allclean scripts

The reactingParcelFilmFoam solver is, as one can guess from the name, a fairly complex application involving many physical models. Pre- and post-processing tasks for such simulations are correspondingly extensive. At this point, running every single application with its options would be too time (and nerve) consuming. Luckily, automating processes comes naturally within a Linux environment via Shell scripts. Basically, all necessary commands are written into a file which is then executed. In the tutorial collection, these scripts are usually called Allrun. For convenience, different scripts can be created for subtasks, e.q. meshing or parallel execution. After the setup is complete, you may want to run a variety of simulations with different parameters. Here it comes handy to have an Allclean script, which resets the case to its initial state. All of this you can find in the hotBoxes tutorial.

Running the tutorial in serial takes about 24h. So it’s wise to run it overnight or/and to use the Allrun-parallel script, which runs the solver on four processors in parallel. (about 9h to complete)

The surface color visualizes the thickness of a cooling film. The Lagrangian particle diameter scales with the mass they carry.

3. Tutorials which require system operations

The last type of tutorials I want to introduce here need system operations. “System operations” basically means that an application (e.g., a solver) compiles and (hopefully) runs user-supplied C++ source code at runtime. Examples are the #codeStream directive or the codedFixedValue boundary condition (same link as before). Since the OpenFOAM 2.3.1 release, system calls are allowed by default. If you run an older version or you want to check your configuration, open the system-wide controlDict and set the allowSystemOperations switch to 1.

Now we are ready to simulate the potential flow around a cylinder. This case is very charming because it allows us to validate our numerical results with an analytical solution. Within the case’s controlDict a coded function object is supplied which later on calculates the numerical error as defined in the picture below. So let’s run the simulation!

Here is a task for you:

  1. Take a close look at the streamlines in the picture below. First, check the alignment between mesh and streamlines. Can you spot under which condition the highest deviations occur?
  2. Open the fvSolution file located in the system directory, set different values for the nNonOrthogonalCorrectors (0, 1, 2, …), and re-run the simulation. How does the error behave?
Streamlines colored by the deviation of the numerical from the analytical solution.
The color of the streamlines indicates the deviation between numerical and analytical solution.

That’s it for this tutorial! With the above information, you are prepared to explore all the tutorials coming with OpenFOAM.

Cheers Andre

3 thoughts on “3 ways to run tutorials in OpenFOAM”

  1. Hi Andre,
    Came across this post while looking for something else. I’m curious about the figure you have shown at the end. That’s a very useful way of learning what to change. Could you please share more about it? To start with, how did you plot it (I’m guessing it’s in paraview)?

    1. Hi Deep,
      The error is computed via a runtime-compiled function in the controlDict:
      $FOAM_TUTORIALS/basic/potentialFoam/cylinder/system/controlDict
      The code computes the difference between numerical and analytical solution. The analytical solution is based on potential flow theory. In the visualization in ParaView, the streamlines (plus tube filter) are colored by the error. In the title of the colormap, I used Latex syntax. To use Latex rendering you need ParaView to be compiled with Python support.
      Cheers, Andre

Leave a Reply to Deep Cancel reply

Your email address will not be published. Required fields are marked *