Open Foam User Manual PFM

User Manual: Pdf

Open the PDF directly: View PDF PDF.
Page Count: 316 [warning: Documents this large are best viewed by clicking the View PDF Link!]

OpenFOAM
A little User-Manual
Gerhard Holzinger∗†
30th January 2018
Abstract
This document is a collection of my own experience on learning and using OpenFOAM. Herein, knowledge
and background information is assembled which may be useful to others when learning to use OpenFOAM.
WARNING:
During the assembly of this manual OpenFOAM and other tools, e.g. pyFoam, have been continuously
updated. This manual was started with OpenFOAM-2.0.x installed and over the time the author has worked
with all major point releases of OpenFOAM and the development versions. Consequently it is possible that
some parts my be outdated by the time you read this. Furthermore, functionalities may have been extended,
modified or superseded. Nevertheless, this manual is intended to cast some light on the inner workings of
OpenFOAM and explain the usage in a rather practical way.
Furthermore, this document is, and will always be, work in progress. As it is extended whenever something
interesting is encountered or learned, parts of the document will always be fragmentary. All errors and
omissions are the sole product of the author.
All information contained in this manual can be found in the internet (http://www.openfoam.org,http:
//www.cfd-online.com/Forums/openfoam/); or it was gathered by trial and error (What happens if ...?
Why did that happen?!).
This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark.
∗K1MET GmbH, Linz, Austria, http://www.k1-met.com
†Particulate Flow Modelling, Johannes Kepler University, Linz, Austria, http://www.jku.at/pfm/
1
Contents
1 Getting help 11
2 Lessons learned 12
2.1 Philosophy .............................................. 12
2.2 Learning by using OpenFOAM ................................... 13
2.3 Learning by tinkering with OpenFOAM .............................. 14
I Installation 15
3 Install OpenFOAM 15
3.1 Prerequistes .............................................. 15
3.2 Download the sources ........................................ 15
3.3 Compile the sources ......................................... 16
3.4 Install paraView ........................................... 16
3.5 Remove OpenFOAM ......................................... 16
3.6 Install several versions of OpenFOAM ............................... 17
4 Updating the repository release of OpenFOAM 17
4.1 Version management ......................................... 17
4.2 Check for updates .......................................... 18
4.3 Check for updates only ........................................ 18
4.4 Install updates ............................................ 19
4.5 Problems with updates ........................................ 19
5 Install third-party software 20
5.1 Install pyFoam ............................................ 20
5.2 Install swak4foam ........................................... 20
5.3 Compile external libraries ...................................... 21
6 Setting up the environment 21
6.1 Sourcing OpenFOAM ........................................ 21
6.2 Useful helpers ............................................. 22
II General Remarks about OpenFOAM 23
7 Units and dimensions 23
7.1 Unit inspection ............................................ 23
7.2 Dimensionens ............................................. 25
7.3 Kinematic viscosity vs. dynamic viscosity ............................. 26
7.4 Pitfall: pressure vs. pressure .................................... 26
8 Files and directories 27
8.1 Required directories ......................................... 27
8.2 Supplemental directories ....................................... 28
8.3 Files in system ............................................ 28
9 Controlling OpenFOAM 29
9.1 The means of exerting control .................................... 29
9.2 Syntax of the dictionaries ...................................... 30
9.3 The controlDict ........................................... 32
9.4 Run-time modifcations of dictionaries ............................... 37
9.5 The fvSolution dictionary ..................................... 37
9.6 Command line arguments ...................................... 37
This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 2
10 Usage of OpenFOAM 38
10.1 Use OpenFOAM ........................................... 38
10.2 Abort an OpenFOAM simulation .................................. 40
10.3 Terminate an OpenFOAM simulation ............................... 41
10.4 Continue a simulation ........................................ 44
10.5 Do parallel simulations with OpenFOAM ............................. 44
10.6 Using tools .............................................. 48
III Pre-processing 49
11 Mesh basics 49
11.1 Basics of the mesh .......................................... 49
12 Geometry creation & other pre-processing software 50
12.1 blockMesh ............................................... 50
12.2 CAD software ............................................. 50
12.3 Salome ................................................. 51
12.4 GMSH ................................................. 51
13 blockMesh 52
13.1 The block ............................................... 52
13.2 The blockMeshDict ......................................... 52
13.3 Create multiple blocks ........................................ 62
13.4 Grading ................................................ 63
13.5 Parametric meshes by the help of m4 and blockMesh ....................... 65
13.6 Trouble-shooting ........................................... 69
14 snappyHexMesh 70
14.1 Documentation ............................................ 70
14.2 Work flow ............................................... 70
14.3 Example: Bath Tub ......................................... 71
15 foamyHexMesh 73
15.1 Crude comparison between a snappy and a foamy bath tub ................... 74
16 cfMesh 75
16.1 Usage ................................................. 75
17 checkMesh 77
17.1 Definitions ............................................... 78
17.2 Pitfalls ................................................. 83
17.3 Useful output ............................................. 86
18 extrudeMesh 86
18.1 Control ................................................ 86
19 Salome 89
19.1 Export & Conversion ......................................... 89
20 Gmsh 90
21 enGrid 90
22 Mesh converters 91
22.1 fluentMeshToFoam and fluent3DMeshToFoam ........................... 91
22.2 ideasUnvToFoam ........................................... 91
22.3 Pitfall: length units ......................................... 92
This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 3
23 Other mesh manipulation tools 92
23.1 transformPoints ............................................ 92
23.2 topoSet ................................................ 92
23.3 setsToZones .............................................. 93
23.4 refineMesh ............................................... 93
23.5 renumberMesh ............................................ 94
23.6 subsetMesh .............................................. 97
23.7 createPatch .............................................. 97
23.8 stitchMesh ............................................... 97
24 Surface mesh manipulation tools 97
24.1 surfaceAdd .............................................. 97
24.2 surfaceSubset ............................................. 98
24.3 surfaceFeatureExtract ........................................ 98
24.4 Third party surface manipulation tools ............................... 98
24.5 The Linux command line ...................................... 98
25 Initialize Fields 99
25.1 Basics ................................................. 99
25.2 setFields ................................................100
25.3 mapFields ...............................................102
26 Case manipulation 106
26.1 changeDictionary ...........................................106
26.2 The allmighty Linux Terminal ....................................108
IV Modelling 111
27 Turbulence-Models 111
27.1 Organisation .............................................111
27.2 Categories ...............................................116
27.3 RAS-Models ..............................................116
27.4 LES-Models ..............................................118
27.5 Pitfalls .................................................119
28 Eulerian multiphase modelling 122
28.1 Phase model class ..........................................123
28.2 Phase system classes .........................................128
28.3 Turbulence modelling ........................................130
28.4 Interfacial momentum exchange ...................................130
28.5 Diameter models ...........................................131
29 Boundary conditions 133
29.1 Base types ...............................................133
29.2 Primitive types ............................................134
29.3 Derived types .............................................134
29.4 Pitfalls .................................................134
29.5 Time-variant boundary conditions .................................135
30 The fvOption framework 136
30.1 Controlling space & time ......................................136
30.2 Porosity models ............................................137
31 The Lagrangian world 138
31.1 Background ..............................................138
31.2 Libraries ................................................139
31.3 Cloudy, with a chance of particles ..................................140
31.4 Cloudy Templates ..........................................142
31.5 Run-time post-processing ......................................144
31.6 Times of Use .............................................144
31.7 Sub models ..............................................145
This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 4
V Solver 147
32 Solution Algorithms 147
32.1 SIMPLE ................................................147
32.2 PISO ..................................................149
32.3 PIMPLE ................................................149
32.4 Block-coupled solution ........................................149
33 pimpleFoam 150
33.1 Governing equations .........................................150
33.2 The PIMPLE Algorithm – or, what’s under the hood? ......................152
34 twoPhaseEulerFoam 157
34.1 General remarks ...........................................157
34.2 Solver algorithm ...........................................157
34.3 Momentum exchange between the phases .............................159
34.4 Kinetic Theory ............................................162
35 twoPhaseEulerFoam-2.3 162
35.1 Physics ................................................162
35.2 Naming scheme ............................................162
35.3 Solver capabilities ..........................................163
35.4 Turbulence models ..........................................163
35.5 Energy equation ...........................................170
35.6 Momentum equation .........................................171
35.7 Interfacial interaction ........................................173
35.8 Interfacial momentum exchange ...................................176
35.9 MRF method - avoiding errors ...................................182
36 multiphaseEulerFoam 182
36.1 Fields .................................................182
36.2 Momentum exchange .........................................183
37 driftFluxFoam 184
37.1 Governing equations .........................................184
37.2 incompressibleTwoPhaseInteractingMixture ..........................186
37.3 Mixture viscosity models .......................................186
37.4 Relative velocity models - hindered settling ............................188
37.5 settlingFoam .............................................190
VI Postprocessing 192
38 functions 192
38.1 Stay up to date ............................................192
38.2 Definition ...............................................193
38.3 Control ................................................194
38.4 probes .................................................195
38.5 fieldAverage ..............................................196
38.6 faceSource ...............................................197
38.7 cellSource ...............................................198
38.8 Execute C++ code as functionObject ...............................199
38.9 Execute functions after a simulation has finished .........................200
39 sample 201
39.1 Usage .................................................201
39.2 sampleDict ..............................................201
39.3 Update OpenFOAM-4 ........................................203
40 ParaView 203
40.1 View the mesh ............................................204
41 postProcess 204
41.1 Usage .................................................205
This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 5
VII External Tools 206
42 pyFoam 206
42.1 Installation ..............................................206
42.2 pyFoamPlotRunner ..........................................206
42.3 pyFoamPlotWatcher .........................................206
42.4 pyFoamClearCase ...........................................211
42.5 pyFoamCloneCase ..........................................211
42.6 pyFoamDecompose ..........................................211
42.7 pyFoamDisplayBlockMesh ......................................212
42.8 pyFoamCaseReport ..........................................213
43 swak4foam 213
43.1 Installation ..............................................213
43.2 simpleSwakFunctionObjects .....................................214
44 blockMeshDG 215
44.1 Installation ..............................................215
44.2 Usage .................................................215
44.3 Pitfalls .................................................215
VIII Updates 217
45 General remarks 217
46 OpenFOAM 217
46.1 OpenFOAM-2.1.x ...........................................217
46.2 OpenFOAM-2.2.x ...........................................217
46.3 OpenFOAM-2.3.x ...........................................217
IX Source Code & Programming 219
47 Understanding some C and C++ 219
47.1 Definition vs. Declaration ......................................219
47.2 Namespaces ..............................................219
47.3 const correctness ...........................................220
47.4 Function inlining ...........................................221
47.5 Constructor (de)construction ....................................222
47.6 Object orientation ..........................................224
47.7 Templates ...............................................224
48 Under the hood of OpenFOAM 225
48.1 Solver algorithms ...........................................226
48.2 Namespaces ..............................................226
48.3 Keyword lookup from dictionary ..................................226
48.4 OpenFOAM specific datatypes ...................................229
48.5 OpenFOAM specific macros for convenient programming .....................237
48.6 Time management ..........................................238
48.7 The registry ..............................................247
48.8 I/O - input & output .........................................251
48.9 Making an argument – passing arguments .............................255
48.10Turbulence models ..........................................256
48.11Debugging mechanism ........................................259
48.12A glance behind the run-time selection and debugging magic ..................260
49 General remarks on OpenFOAM programming 264
49.1 Preparatory tasks ...........................................264
49.2 Start from existing code .......................................265
49.3 Create the source code from scratch ................................266
49.4 Using a user-created libraries ....................................267
49.5 Pitfalls .................................................267
49.6 Tips ..................................................268
This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 6
X Theory 269
50 Discretization 269
50.1 Temporal discretization .......................................269
50.2 Spatial discretization .........................................269
50.3 Continuity error correction .....................................269
51 Momentum diffusion in an incompressible fluid 272
51.1 Governing equations .........................................272
51.2 Implementation ............................................272
52 The incompressible k-turbulence model 273
52.1 The k-turbulence model in literature ...............................273
52.2 The k-turbulence model in OpenFOAM .............................274
52.3 The k-turbulence model in bubbleFoam and twoPhaseEulerFoam ...............276
52.4 Modelling the production of turbulent kinetic energy .......................277
53 Some theory behind the scenes of LES 281
53.1 LES model hierarchy .........................................281
53.2 Eddy viscosity models ........................................282
54 The use of phi 286
54.1 The question .............................................286
54.2 Implementation ............................................286
54.3 The math ...............................................288
54.4 Summary ...............................................289
55 Derivation of the IATE diameter model 289
55.1 Number density transport equation .................................290
55.2 Interfacial area transport equation .................................290
55.3 Interfacial curvature transport equation ..............................292
55.4 Interaction models ..........................................294
55.5 Appendix ...............................................298
56 Derivation of the MRF approach 300
56.1 Preliminary observations .......................................300
56.2 Mass conservation equation .....................................300
56.3 Momentum conservation equation ..................................301
56.4 Notes on the implementation of the MRF Approach .......................302
XI Appendix 305
57 Useful Linux commands 305
57.1 Getting help ..............................................305
57.2 Finding files ..............................................305
57.3 Find files and scan them .......................................306
57.4 Scan a log file .............................................306
57.5 Running in scripts ..........................................307
57.6 diff ...................................................308
57.7 Case setup ...............................................309
57.8 Miscellaneous .............................................309
58 Archive data 310
Bibliography 313
List of Abbreviations 316
This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 7
List of Figures
1 The top face of the generic block of Figure 3 ............................. 50
2 The STL mesh of a circular area generated by OpenSCAD ...................... 51
3 The generic block ............................................. 52
4 A block with a poly-line at the left side. The red line indicates the poly-line. This figure makes
it obvious that edges defines in the blockMeshDict serve to compute the locations of the block’s
internal nodes. The block itself however, does not obey the poly-line. ................ 56
5 The initial velocity field depending on the order of the wall and banana.Left: Setting as in
Listing 96. Right:wall and banana have changed places. ...................... 59
6 The mesh of two merged blocks ..................................... 61
7 The mesh of two merged blocks. .................................... 61
8 Two connected blocks .......................................... 62
9 Two unconnected blocks ......................................... 63
10 The mesh of a stirred tank with a Rushton impeller, stator baffles and an aeration device. . . . . 68
11 The blocks of a parametric mesh consisting of nine blocks. ...................... 70
12 A bath tub. The outlet patch is marked grey at the very bottom of the drain tube. ........ 71
13 A badly chosen featureAngle causes snappy to add incomplete boundary layers. ......... 72
14 The boundary layers added by snappy. On the left, layer addition went as we intended it to do; on
the right, we see the effect of the (missing) keyword slipFeatureAngle of the addLayersControls
dictionary of snappyHexMeshDict.................................... 72
15 A collapsing boundary layer. Maybe we did not want the mesh that way, however, we told snappy
to create it exactly that way. ...................................... 73
16 A bath tub with a background mesh enclosing the STL-surface of the bath tub. .......... 74
17 SnappyBathTub ............................................. 74
18 FoamyBathTub .............................................. 75
19 Poor feature edge resolution caused by not providing information on feature edges. Note, the
whole geometry is bounded by a single patch. ............................. 76
20 Resolved feature edge of the bath tub. In this case, the boundary consists of two patches: the
top surface and the rest. ......................................... 77
21 Definition of non-orthogonality for internal faces ........................... 78
22 Definition of non-orthogonality for boundary faces .......................... 79
23 Definition of skewness of internal faces ................................. 80
24 Definition of skewness of boundary faces ................................ 82
25 Face warpage ............................................... 83
26 A distorted mesh ............................................. 84
27 Sets created by checkMesh in the sets directory. ........................... 86
28 The mesh for a 2D study generated from an STL surface. ...................... 87
29 A cheap 90°pipe bend. The outlet patch of the original mesh was extruded along the sector of
a circle. .................................................. 88
30 Subsequent mesh extrusions: sector,linearNormal and linearDirection............. 88
31 Grow a wall! The walls patch of the pipe mesh was extruded using the linearNormal model. . . 89
32 Mesh export issue in Salome with the UNV format. .......................... 89
33 An extruded 2D mesh of quad elements created with Gmsh. ..................... 90
34 Meshes by enGrid: left: tet-mesh with prismatic boundary layer, right: polyhedral mesh with
boundary layer. .............................................. 91
35 A faulty cell set definition. The red cells are part of the cell set. All other cells are blue. ..... 93
36 An example of a refined mesh. The refined region is marked in red. ................. 94
37 A simple mesh with 8 cells and different cell labelling schemes. ................... 95
38 The connectivity graph of our mesh. .................................. 95
39 The matrix structure of the connectivity graph of Figure 38 ..................... 96
40 Scrambled cell sets caused by mesh renumbering ........................... 97
41 The mapped field .............................................105
42 The unmapped fields ...........................................106
43 Established flow and modified boundary condition ..........................108
44 The class hierarchy of the basis of the old turbulence model framework. ..............112
45 The class hierarchy of the basis of the new turbulence model framework. ..............113
This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 8
46 The (templated) class hierarchy of the new turbulence model framework. ..............114
47 The class hierarchy of the elementary turbulence models of the new turbulence model framework. 115
48 The class hierarchy of a selection of turbulence models of the new turbulence model framework. . 116
49 Modelling approach on the example of a gas-liquid two-phase system. ...............123
50 Modelling approach on the example of a gas-liquid two-phase system. ...............131
51 Schematic diagrams of doubly-linked lists. ...............................141
52 The class hierarchy needed for intrusive lists of objects of type T;..................142
53 The class hierarchy of the class basicKinematicCloud........................143
54 A set of polygons has been defined to count and remove traversing particles. In this case of a
cylinder in laminar cross-flow, particles are inserted through the inlet patch. The ParticleCollector
cloud function object was set to remove all counted particles, which is clearly visible in this snapshot.146
55 Flow chart of the SIMPLE algorithm ..................................148
56 Flow chart of the PISO algorithm ....................................149
57 Flow chart of the PIMPLE algorithm ..................................153
58 Flow chart of the main loop of twoPhaseEulerFoam ..........................158
59 Flow chart of the operations in alphaEqn.H ..............................160
60 Air volume fraction of the bubble column. Initial field (left) and solution at t= 10 s (right). . . . 169
61 Linear blending: f1 over α........................................175
62 Hyperbolic blending: f1 over α.....................................176
63 Velocity vectors of the gaseous phase at the inlet boundary (red vectors) in an aerated stirred
tank. That the gas inlet boundary lies within the MRF zone. On the left, we see the initial
condition and on the right we see the boundary condition after the constraints by the MRF
method have been applied. ........................................182
64 A part of the directory tree after the simulation ended ........................196
65 The content of the postProcessing folder ..............................198
66 Directory tree after compilation of a coded functionObject ......................200
67 Select the proper representation to view the mesh ...........................204
68 The Courant number plotted with pyFoamPlotWatcher........................207
69 The Courant number based on the relative velocity plotted with pyFoamPlotWatcher .......208
70 The average volume fraction plotted with pyFoamPlotWatcher and a custom regular expression . 210
71 The execution time plotted over time with pyFoamPlotWatcher....................211
72 Screenshot of pyFoamDisplayBlockMesh ................................213
73 Double grading problem .........................................216
74 Class hierarchy of some injection models for Lagrangian particles. An intermediate base class is
used to reduce code duplication from closely related, yet different injection models. ........229
75 The three arguments of Eq. (143) plotted over x...........................241
76 A partial view of the class hierarchy involving regIOobject;.....................247
77 The base classes of the class objectRegistry;.............................248
78 Graphic representation of inheritance of the turbulence model classes. ...............257
79 Inheritance of RAS turbulence models .................................258
80 First layer of the class hierarchy of the LES models of OpenFOAM .................282
81 Class hierarchy of the eddy viscosity models in OpenFOAM .....................283
82 A screenshot of Meld ...........................................309
List of Tables
1 Run-time cavity test case ........................................ 39
2 Comparison of hard disk space consumption .............................. 40
3 Valid and invalid face definitions .................................... 50
4 Overview of diameter modelling in Eulerian multiphase solvers ...................131
5 Levels of coupling between Lagrangian particles and (Eulerian) flow ................138
6 Turbulence model combinations for phase-inversion cases. ......................170
7 Naming scheme of quanities of twoPhaseEulerFoam ..........................217
8 Comparison of the eddy viscosity models of OpenFOAM .......................283
9 Comparison of disk space reduction ...................................310
10 Comparison of disk space reduction ...................................310
This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 9
11 Comparing the resulting file size of the mesh archive file for various conditions/treatments. All file
or folder sizes were determined with the Linux command du -sh FILE. The mesh was compressed
using the LZMA algorithm at maximum compression: tar -cv constant/polyMesh | lzma -9
> polyMesh.tar.xz............................................311
This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 10
1 Getting help
Apart from this manual, there are lots of resources on the internet to find help on OpenFOAM.
•The OpenFOAM User Guide
http://www.openfoam.org/docs/user/
•The CFD Online Forum
http://www.cfd-online.com/Forums/openfoam/
•The OpenFOAM Wiki
http://openfoamwiki.net/index.php/Main_Page
The OpenFOAM Wiki is maintained by a community of developers behind the OpenFOAM-extend project.
This wiki covers not only the OpenFOAM but also tools that developed for OpenFOAM, e.g. pyFoam or
swak4foam.
•The CoCoons Project
http://www.cocoons-project.org/
This is a community driven effort to create a documentation on solvers, utilities and modelling.
•The materials of the course CFD with open source software of Chalmers University
http://www.tfd.chalmers.se/~hani/kurser/OS_CFD/
•The CAELinux Wiki
http://caelinux.org/wiki/index.php/Doc:OpenFOAM
CAELinux is a collection of open source CAE software including several CFD codes (OpenFOAM,
Code_Saturne, Gerris, Elmer).
•Q&A on the internets
You can find questions – and hopefully answers – on the various Q&A sites on the internets, such as
StackExchange (http://stackexchange.com/), which is a collection of Q&A site specific to a topic or
region of interest.
There, a site specific to OpenFOAM is currently proposed and is in need of participation.
http://area51.stackexchange.com/proposals/88229/openfoam-technology
Currently, OpenFOAM questions tend to get posted on the Computational Science Q&A site .
http://scicomp.stackexchange.com/
•Word of mouth
https://github.com/ParticulateFlow/OSCCAR-doc/blob/master/openFoamUserManual_PFM.pdf
This is where this manual is hosted.
This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 11
2 Lessons learned
•For production-use we strongly recommend to use the point-releases of OpenFOAM. As the development
versions of OpenFOAM continuously get updated, OpenFOAM’s behaviour might change. Thus, users are
advised to base their work entirely on point-releases of OpenFOAM. That way, once your simulation cases
run, they will run indefinitely, or as long as you are able to install the respective version of OpenFOAM
on a computer.
•Keep an eye on developments in OpenFOAM. A more recent version might provide some functionality or
feature you desperately need. Even if you added this feature yourself to e.g. your custom solver or model,
the developers of OpenFOAM might provide a cleaner or more powerful implementation of that feature.
As it is easily possible to install several versions of OpenFOAM side by side on a computer, play around
with the latest version.
•Build the source-code documentation of your local installation. It is located e.g. in $HOME/OpenFOAM/
OpenFOAM-2.3.x/doc/Doxygen if you installed OpenFOAM in your home directory. This makes you
independent of being online and the doxygen gives you e.g. a very well-structured overwiew of a classes
methods and members.
•Study the code. Even as “the documentation is in the code” does not sound helpful at all, the code in
fact tells you what is going on provided you are able to make sense of the C++ syntax. Become familiar
with basic concepts of object-oriented (OO) software design.
•The more I used and tinkered with OpenFOAM, the more I am convinced that its design is really ingenious.
However, it takes time and effort to come to this conclusion. It is also probably a matter of taste.
•Document your own work and stuff you tried. There is no need to create hundreds of pages, but paper or
dead electrons have a longer memory as mere mortal humans. Furthermore, the fact “I have already tried
X at some point in the past, and I wrote it down at Y” is more likely to be remembered than “I tried X,
and that’s how it went in all detail”.
2.1 Philosophy
OpenFOAM is largely following the general rules of the UNIX philosophy – see e.g. Eric S. Raymond [14] or
http://www.catb.org/esr/writings/taoup/html/ch01s06.html – by accident, by design or by law.
1. Rule of Modularity: Write simple parts connected by clean interfaces.
We see this rule in action, when we take a look at all the small pre- and post-processing
2. Rule of Clarity: Clarity is better than cleverness.
3. Rule of Composition: Design programs to be connected to other programs.
OpenFOAM’s extensive use of text files can be interpreted as a consequence of the Rule of Composition.
The structured, textual formal makes it easy to define and interpret OpenFOAM’s in- and output.
4. Rule of Separation: Separate policy from mechanism; separate interfaces from engines.
5. Rule of Simplicity: Design for simplicity; add complexity only where you must.
6. Rule of Parsimony: Write a big program only when it is clear by demonstration that nothing else will do.
Again, OpenFOAM is a large collection of specialized tools, rather than a big monolithic – one size fits
nobody – monster.
7. Rule of Transparency: Design for visibility to make inspection and debugging easier.
Here, we quote Eric S. Raymond1: “A software system is transparent when you can look at it and
immediately understand what it is doing and how.” CFD is admittedly very complex, however, the close-
to-mathematical notation of OpenFOAM’s high-level code, can be seen as an example of OpenFOAM’s
obedience to the Rule of Transparency.
8. Rule of Robustness: Robustness is the child of transparency and simplicity.
1http://www.catb.org/esr/writings/taoup/html/ch01s06.html
This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 12
9. Rule of Representation: Fold knowledge into data so program logic can be stupid and robust.
Although this rule was stated without object-orientation in mind, we can observe, that OpenFOAM’s data
structures and classes absorb much of the complexity. Thus, the top level solver source code looks quite
unspectacular.
10. Rule of Least Surprise: In interface design, always do the least surprising thing.
We see this rule in action, when we look at all the shared command line options. All tools that support
time selection offer common options, such as latestTime or noZero.
11. Rule of Silence: When a program has nothing surprising to say, it should say nothing.
This rule is obeyed by most function objects, which provide the user with the choice of deactivating
writing to the Terminal. This output may be useful during testing. As soon as the case is properly set up,
however, it is sufficient for the function object to write its output to the corresponging file in the folder
postProcessing.
12. Rule of Repair: When you must fail, fail noisily and as soon as possible.
Ever noticed the FOAM FATAL ERROR messages?
13. Rule of Economy: Programmer time is expensive; conserve it in preference to machine time.
If we allow ourselves a very broad view of this rule, we might postulate, that OpenFOAM’s mechanism to
specify default values for keywords2is one example for following this rule from a user’s perspective, i.e.
it is the user’s time which is conserved.
14. Rule of Generation: Avoid hand-hacking; write programs to write programs when you can.
We can see the heavy use of templates as an example of OpenFOAM following the Rule of Generation.
The TurbulenceModels framework3is an example of a modelling framework, which is coded once and
applied in several different incarnations.
However, this applies only in a wider sense, since this rule was stated not with C++’s templates in mind.
15. Rule of Optimization: Prototype before polishing. Get it working before you optimize it.
16. Rule of Diversity: Distrust all claims for “one true way”.
OpenFOAM offers the user plenty of choice such as the solvers to use, the solution algorithms, and
discretisation and interpolation schemes.
17. Rule of Extensibility: Design for the future, because it will be here sooner than you think.
OpenFOAM sometimes exhibits a different behaviour based on its version, or the format of the input files.
See Section 29.4.1 for an example on differences in the input syntax of fixedValue boundary conditions.
The important lesson in this case is to allow for evolution of the code without breaking compatibility.
2.2 Learning by using OpenFOAM
•Numerical errors can ruin your day in CFD. Not every simulation crash is the fault of some bug in
OpenFOAM. The numerics of CFD is also keen to crash simulations.
•Never deactivate the unit checking of OpenFOAM. FYI: It can be done in the global controlDict in the
etc directory of your OpenFOAM installation.
•Many classes provide optional debug information. Debug flags can be controlled via a global controlDict
as well as the case’s controlDict.
•Play around! A great part of learning is trial and error. Although many of us regard themselves as
scientists or aspire to become scientists, never disregard the value of plain trail and error.
2See Section 48.3.2
3See Section 27.
This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 13
2.3 Learning by tinkering with OpenFOAM
2.3.1 I learned something today.
•Have a look at the test directory in the applications folder of your installation, e.g. in $HOME/OpenFOAM/
OpenFOAM-2.3.x/applications/test. There, you find examples of how to use certain data structures,
which may be exactly what you need when implementing something.
•Create your own test application, if you are about to implement something new. With a test application,
you can keep the problem nearly primitive, thus, allowing yourself more mental freedom to explore and
to learn. Later, you might be more likely to implement your solver / library with less bugs and errors.
•OpenFOAM makes heavy use of C++’s language features and other smart moves in OO software design.
Thus, make sure you understand the basics of the following concepts / language features before you try
to study / modify the code of OpenFOAM. Your life gets easier if you do.
inheritance virtually everything of OpenFOAM is described and implemented using the concept of classes.
Classes can be derived from other classes to implement an is a relationship, i.e. every cat is an animal
but not vice versa.
Note: C++ support multiple inheritance, i.e. a class can be derived from a number of classes, not just
one. Other programming languages are (slightly) different in this aspect, e.g. Java allows you to derive
only from one class, however, you can implement interfaces.
poly-morphism is a wider concept, however it applies also to inheritance and classes.
templates allow the user to write code for as-of-yet unspecified data types. Container classes are the prime
example for the use of templates (or generics as this concept is called in Java).
Examples of the excellent use of the aforementioned concepts is the turbulence modelling framework discussed
in Section 27.1.2, or the lagrangian modelling framework discussed in Section 31.2.
2.3.2 Trouble with the code?
it does not compile
•Due to the heavy use of templates the syntax and the compiler error messages are quite lengthy and often
hard to read. However, the compiler error message might contain exactly the information you need to
track down the error, e.g. a data-type mismatch. Familiarize yourself with C++’s syntax if you haven’t
already.
it does not run
•Spurious crashes (e.g. caused by floating point errors) may be an indication of class members being
un-initialized.
•No offence, but it’s most probably your fault.
This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 14
Part I
Installation
3 Install OpenFOAM
3.1 Prerequistes
OpenFOAM is easily installed by following the instructions from this website: http://www.openfoam.org/
download/git.php.
First of all, you need to make sure all required packages are installed on your system. This is easily done
via the package management software. OpenFOAM is a software made primarily for Linux systems. It can also
be installed on Mac or Windows plattforms. However, the authors uses a Ubuntu-Linux system, therefore this
manual will be based on the assumption that a Linux system is used.
su do apt - ge t i ns ta ll git - core
sudo apt - get ins tall build - essential flex bison cmake zlib1g - dev qt4 - dev - tool s libqt4 - dev
gnu pl ot libr eadl ine - dev libxt - d ev
su do apt - ge t i ns ta ll libscotch - dev lib openmp i - de v
Listing 1: Installation of required packages
If OpenFOAM is to be used by a single user, then the User Manual suggests to install OpenFOAM in the
$HOME/OpenFOAM directory.
3.2 Download the sources
First of all the source files need to be downloaded. This is done with the version control software Git. After-
wards we change into the new directory and check for updates. All steps to perform the described operations
are listed in Listing 2.
cd $HOME
mkdir Ope nFO AM
cd OpenFOAM
gi t c lone g it : // g it hu b . com / Ope nF OA M / Op enFOAM -2.1. x . git
cd OpenFOAM -2.1. x
git pull
Listing 2: Installation von openFOAM
Prior to compiling the sources some environment variables have to be defined. In order to do that a line (see
Listing 3) has to added to the file $HOME/.bashrc.
sou rce $ HOME / O pe nF OA M / Op enFOAM -2.1. x / et c / ba sh rc
Listing 3: Addition to .bashrc
When the command source $HOME/.bashrc is issued or when a new Terminal is opened this change is
effective. Now with the defined environment variables OpenFOAM can be installed on the system. Before
compiling a system check can be made by running foamSystemCheck.
use r@host :∼/ O penF OAM / OpenFOAM -2.1. x$ f oa mSyst em Ch eck
Checking ba sic s ystem ... --- - ---- - ----- - ---- - ----- - ---- - --
Shell : / bi n / bash
Host: host
OS : Linux vers ion 2.6.32 -39 - ge neric
User: user
Syste m c heck : P ASS
==================
Continue OpenFOAM inst all ation .
IThis offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 15
Listing 4: foamSystemCheck
3.3 Compile the sources
If the system check produced to error messages then OpenFOAM can be compiled. This is done by executing
./Allwmake. This is an installation script that takes care of all required operations. Compiling OpenFOAM
can be done by using more than one processor to save time. In order to do this, an environment variable needs
to be set before invoking ./Allwmake. Listing 5shows how to compile OpenFOAM using 4 processors.
exp ort W M_NCOMP PROC S =4
./ Allwma ke
Listing 5: Parallel compilation using 4 processes.
For working with OpenFOAM a user directory needs to be created. The name of this directory consists of
the username and the version number of OpenFOAM. With version 2.1.x this folder needs to be named like
this: user-2.1.x
3.4 Install paraView
paraView is a post processing tool, see http://www.paraview.org/. The OpenFOAM Foundation distributes
paraView from its homepage and recommends to use this version. The source code can be downloaded from
http://www.openfoam.org/ in an archive, e.g. ThirdParty-2.1.0.tgz. This archive has to be unpacked into
a folder named correspondingly to the OpenFOAM directory, e.g. ThirdParty-2.1.x when OpenFOAM-2.1.x
is used. This naming scheme is mandatory because there is an environment variable that points to the location
of paraView. As there is no development of paraView by the OpenFOAM developers, there is no repository
release of third-party tools.
Subsequently paraView can be compiled by the use of an installation script. Afterwards some plug-ins for
paraView need to be compiled.
cd $WM_THIRD_PARTY_DIR
./makeParaView
cd $ FOA M_ UTIL ITI ES / p ost Pr oce ss ing / g raphics / PV 3Re aders
wmSET
./ Allwclean
./ Allwma ke
Listing 6: Installation of paraView
3.5 Remove OpenFOAM
If OpenFOAM is to be removed from the system, then a few simple operations do the job4, provided the
installation was done following the installation guidelines of OpenFOAM5.
Listing 7shows how OpenFOAM can be removed from the system. We assume, we want to remove an
installation of OpenFOAM-2.0.1. The first line changes the working directory to the installation directory of
OpenFOAM. This folder contains all files of the OpenFOAM installation. Listing 8shows the content of the
~/OpenFOAM. In this example, two versions of OpenFOAM are installed.
The second line removes all files of OpenFOAM and the third line removes the files of the user related to
OpenFOAM. The last line of Listing 7removes a hidden folder. If there are several versions of OpenFOAM
installed, then this folder should not be removed.
4http://www.cfd-online.com/Forums/openfoam-installation/57512-completely-remove-openfoam-start-fresh.html
5http://www.openfoam.org/download/git.php
IThis offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 16
cd ∼/OpenFOAM
rm -rf Open FOAM - 2.0.1
rm - rf user -2.0.1
cd
rm -rf ∼/. OpenF OAM
Listing 7: Removing OpenFOAM
cd ∼/OpenFOAM
ls -1
user -2. 0. x
user -2. 1. x
Op enF OAM - 2.0. x
Op enF OAM - 2.1. x
ThirdParty -2 .0. x
ThirdParty -2 .1. x
Listing 8: Content of ~/OpenFOAM
Another thing to remove is the entry in the .bashrc file in the home directory. Delete the line shown in
Listing 3.
3.6 Install several versions of OpenFOAM
It is possible to install several versions of OpenFOAM on the same machine. However due to the fact that Open-
FOAM relies on some environment variables some precaution is needed. See http://www.cfd-online.com/
Forums/blogs/wyldckat/931-advanced-tips-working-openfoam-shell-environment.html for detailed in-
formation about OpenFOAM and the Linux shell.
The most important fact about installing several versions of OpenFOAM is to keep the seperated.
4 Updating the repository release of OpenFOAM
4.1 Version management
OpenFOAM is distributed in two different ways. There is the repository release that can be downloaded using
the Git repository. The version number of the repository release is marked by the appended x, e.g. OpenFOAM
2.1.x. This release is updated regularly and is in some ways a development release. Changes and updates are
released quickly, however, there is a larger possibility of bugs in this release. Because this release is updated
frequently an OpenFOAM installation of version 2.1.x on one system may or will be different to another instal-
lation of version 2.1.x on an other system. Therefore, each installation has an additional information to mark
different builds of OpenFOAM. The version number is accompanied by a hash code to uniquely identify the
various builds of the repository release, see Listing 9. Whenever OpenFOAM is updated and compiled anew,
this hash code gets changed. Two OpenFOAM installations are on an equal level, if the build is equal.
Bui ld : 2. 1. x -9 d 3 44 f 6a c 6a f
Listing 9: Complete version identification of repository releases
Apart from the repository release there are also pack releases. These are upadated periodically in longer
intervals than the repository release. The version number of a pack release contains no x, e.g. OpenFOAM
2.1.1. In contrast to the repository release all installations of the same version number are equal. Due to the
longer release cycle the pack release is regarded to be less prone to software bugs.
There are several types of those releases. The are precompiled packages for widely used Linux distributions
(Ubuntu, SuSE and Fedora) and also a source pack. The source pack can be installed on any system on which
the source codes compile (usually all kinds of Linux running computers, e.g. high performance computing
clusters, or even computers running other operation systems, e.g. Mac OSX6or even Windows7).
6See http://openfoamwiki.net/index.php/Howto_install_OpenFOAM_v21_Mac
7See http://openfoamwiki.net/index.php/Tip_Cross_Compiling_OpenFOAM_in_Linux_For_Windows_with_MinGW
IThis offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 17
4.2 Check for updates
If OpenFOAM was installed from the repository release, updating is rather simple. To update OpenFOAM
simply use Git to check if there are newer source files available. Change in the Terminal to the root directory
of the OpenFOAM installation and execute git pull.
If there are newer files in the repository Git will download them and display a summary of the changed files.
use r@host :∼$ cd $FOAM_INST_DIR
use r@host :∼/ O penF OA M$ cd OpenFOAM -2.1. x
use r@host :∼/ O penF OAM / OpenFOAM -2.1. x$ git pu ll
rem ot e : C ou nt ing ob je ct s : 67 , done .
remot e : Comp re ss in g obj ec ts : 1 00% ( 13 /1 3) , done .
remot e : T otal 44 ( d elta 32) , r eused 43 ( delta 31)
Unp ac ki ng ob ject s : 100% ( 44 /44) , d one .
Fr om git :/ / g ithu b . com / Op en FO AM / O pen FOAM -2.1. x
72 f 00f7 ..21 ed3 7f m aster -> origi n / master
Updating 72 f00f7 ..21 ed37f
Fast - forwar d
.../ ext rude / ex tr udeT oRegi on Mesh / c reat eSh el lMe sh . C | 10 + -
.../ ext rude / ex tr udeT oRegi on Mesh / c reat eSh el lMe sh . H | 7 + -
.../extrudeToRegionMesh/extrudeToRegionMesh.C | 157 ++++++++-----
.../ Tem plates / Kin ema ti cCl ou d / Kin em ati cC lou d .H | 6 + -
.../ Tem plates / Kin ema ti cCl ou d / Kin em aticC loudI . H | 7 +
.../ base Cla sse s / kinem aticC lo ud / ki ne mat ic Clo ud . H | 47 ++++++ -
6 f il es c han ged , 193 i ns ert io n s ( +) , 41 d ele ti on s ( -)
Listing 10: There are updates available
If OpenFOAM is up to date, then Git will output a corresponding message.
use r@host :∼/ O penF OAM / OpenFOAM -2.1. x$ git pu ll
Alr eady up - to - date .
Listing 11: OpenFOAM is up to date
4.3 Check for updates only
If you want to check for updates only, without actually making an update, Git can be invoked using a special
option (see Listings 12 and 13). In this case Git only checks the repository and displays its findings without
actually making any changes. The option responsible for this is --dry-run. Notice, that git fetch is called
instead of git pull 8.
use r@host :∼$ cd O pe nF OAM / Op enFOA M -2.0. x/
use r@host :∼/ O penF OAM / OpenFOAM -2.0. x$ git fetch --dry - run - v
remot e : Cou nt ing o bj ects : 189 , done .
remot e : Comp re ss in g obj ec ts : 1 00% ( 57 /5 7) , done .
remote : To tal 120 ( delt a 89) , reus ed 93 ( delta 62)
Rec eiving ob jects : 100% (120/120) , 17.05 KiB , done .
Res olvi ng de ltas : 10 0% ( 89/8 9) , com plet ed with 56 l ocal obje cts .
Fr om git :/ / g ithu b . com / Op en FO AM / O pen FOAM -2.0. x
5ae2802..97cf67d master -> origin/master
use r@host :∼/ O penF OAM / OpenFOAM -2.0. x$
Listing 12: Check for updates only – updates available
use r@host :∼$ cd O pe nF OAM / Op enFOA M -2.1. x/
use r@host :∼/ O penF OAM / OpenFOAM -2.1. x$ git fetch --dry - run - v
Fr om git :/ / g ithu b . com / Op en FO AM / O pen FOAM -2.1. x
= [ up to date ] ma ster -> origi n / mast er
use r@host :∼/ O penF OAM / OpenFOAM -2.1. x$
Listing 13: Check for updates only – up to date
8git pull calls git fetch to download the remote files and then calls git merge to merge the retrieved files with the local files.
So checking for updates is actually done by git fetch.
IThis offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 18
4.4 Install updates
After updates have been downloaded by git pull the changed source files need to be compiled in order to
update the executables. This is done the same way as is it done when installing OpenFOAM. Simply call
./Allwmake to compile. This script recognises changes, so unchanged files will not be compiled again. So,
compiling after an update takes less time than compiling when installing OpenFOAM.
4.4.1 Workflow
Listing 14 shows the necessary commands to update an existing OpenFOAM installation. However this applies
only for repository releases (e.g. OpenFOAM-2.1.x). The point releases (every version of OpenFOAM without
an x in the version number) are not updated in the same sense as the repository releases. For simplicity an update
of a point release (OpenFOAM-2.1.0 →OpenFOAM-2.1.1) can be treated like a complete new installation, see
Section 3.6.
The first two commands in Listing 14 change to the directory of the OpenFOAM installation. Then the
latest source files are downloaded by invoking git pull.
The statement in red can be omitted. However if the compilation ends with some errors, this command
usually does the trick, see Section 4.5.2. The last statement causes the source files to be compiled. If wclean all
was not called before, then only the files that did change are compiled. If wclean all was invoked then
everything is compiled. This may or will take much longer.
If there is enough time for the update (e.g. overnight), then wclean all should be called before compiling.
This will in most cases make sure that compilation of the updated sources succeeds.
cd $FOAM_INST_DIR
cd OpenFOAM -2.1. x
git pull
wclean all
./ Allwma ke
Listing 14: Update an existing OpenFOAM installation. The complete workflow
4.4.2 Trouble-shooting
If compilation reports some errors it is helpful to call ./Allwmake again. This reduces the output of the
successful operations considerably and the actual error messages of the compiler are easier to find.
4.5 Problems with updates
4.5.1 Missing packages
If there has been an upgrade of the operating system9it can happen, that some relevant packages have been
removed in the course of the update (e.g. if these packages are only needed to compile OpenFOAM and the OS
’thinks’ that these packages aren’t in use). Consequently, if recompiling OpenFOAM fails after an OS upgrade,
missing packages can be the cause.
4.5.2 Updated Libraries
When libraries have been updated, they have to be recompiled. Otherwise solvers would call functions that are
not (yet) implemented. In order to avoid this problem the corresponding library has to be recompiled.
wclean all
Listing 15: Prepare recompilation with wclean
The brute force variant would be, to recompile OpenFOAM as a whole, instead of recompiling a updated
library.
9An upgrade of an OS is indicated by a higher version number of the same (Ubuntu 11.04 →Ubuntu 11.10). An update leaves
the version number unchanged.
IThis offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 19
4.5.3 Updated sources fail to compile
In some cases, e.g. when there were changes in the organisation of the source files, the sources fail to compile
right away. Or, if there is any other reason the sources won’t compile and the cause is not found, then a complete
recompilation of OpenFOAM may be the solution of choice. Although compiling OpenFOAM takes its time,
this may take less time than tracking down all errors.
To recompile OpenFOAM the sources need to be reset. Instead of deleting OpenFOAM and installing it
again, there is a simple command that takes care of this.
git cl ean - dfx
Listing 16: Reset the sources using git
The command listed in Listing 16 causes git to erase all files git does not track. That means all files that
are not part of the git-repository are deleted. In this case, this is the official git-repository of OpenFOAM. git
clean removes all files that are not under version control recursively starting from the current directory. The
option -d means that also untracked folders are removed.
After the command from Listing 16 is executed, the sources have to be compiled as described in Section 3.3.
4.5.4 Own code fails to run
Updating your repository release of OpenFOAM leads to interesting effects. When libraries of OpenFOAM are
updated, their implementation might change. Even if the updated code is fully compatible with the previous
one, the compiled libaries might look different after the update. Thus, even if the update maintains code-
compatibility10, the update might break binary compatibility. Thus, a recompilation of your own code following
the update of the underlying OpenFOAM installation is required.
Lost binary compatibility after an update of OpenFOAM leads to segmentation faults when loading a library
with lost binary compatibility. This happens because our own solvers dynamically load the required libraries of
OpenFOAM at start-up and the memory layout of certain objects of the library has changed since the update.
See the following resources for further information on this topic:
•https://community.kde.org/Policies/Binary_Compatibility_Issues_With_C%2B%2B
•https://en.wikipedia.org/wiki/Binary_code_compatibility
•https://en.wikipedia.org/wiki/Source_code_compatibility
Losing binary compatibility happens not after every update, and it also does not happen to every library.
Thus, you may encounter such problems long after the update, and after you successfully used other solvers
and libraries of your creation. Thus, the source of the issues described in this Section may not be immediately
clear to the user. Thus, if your code suddenly fails to run properly for no good reason, recomile and see what
happens.
5 Install third-party software
The software presented in this section is optional. Without this software OpenFOAM is complete and perfectly
useable. However, the software mentioned in this section can be very useful for specific tasks.
5.1 Install pyFoam
See http://openfoamwiki.net/index.php/Contrib_PyFoam#Installation for the instructions on the instal-
lation of pyFoam.
5.2 Install swak4foam
See http://openfoamwiki.net/index.php/Contrib/swak4Foam for instructions on installing swak4foam.
10This is the general behaviour of an update. In an ideal world only newer versions are allowed to introduce incompatibility.
IThis offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 20
5.3 Compile external libraries
There is the possibility to extend the functionality of OpenFOAM with additional external libraries, i.e. libraries
for OpenFOAM from other sources than the developers of OpenFOAM. One example of such an external library
is a large eddy turbulence model from https://github.com/AlbertoPa/dynamicSmagorinsky. The source
code is stored in OpenFOAM/AlbertoPa/.
Such a library is compiled with wmake libso. This is also the case when libraries of OpenFOAM have been
modified. The reason why typing wmake libso is sufficient is because all information wmake requieres is stored
in the files Make/files and Make/options. These files tell wmake – and therefore also the compiler – where to
find necessary libraries and where to put the executable. A more detailed description of this two files can be
found in Section 49.2.2.
To use an external library the solver needs to be told so. See Section 9.3.3.
cd O penFOAM / AlbertoPa / d ynam icSma go ri ns ky
wmake libso
Listing 17: Compilation of a library
6 Setting up the environment
6.1 Sourcing OpenFOAM
OpenFOAM makes use of plenty of environment variables, see Section 9.1.1 for a brief discussion. In order to use
OpenFOAM, we need to assign values to the variables. Another task enabling the convenient use of OpenFOAM
is to add the directories in which OpenFOAM executables are located to the system’s $PATH variable.
The name of this section stems from the Linux command source, which is used in setting up the proper
environment for using OpenFOAM. Setting up the environment for using OpenFOAM can be done in two ways,
which are discussed below. Each of these variants involves editing a .bashrc file11. This .bashrc file can be
either a systemwide one for systemwide installations, or belonging to the user who installed OpenFOAM in
his/her home directory.
Once the OpenFOAM environment has been sourced in a Terminal, OpenFOAM is ready to use as long as
the Terminal is open.
6.1.1 Permanently sourcing OpenFOAM
If we only use one OpenFOAM installation, we could permanently source OpenFOAM. In this case, once this is
set up, OpenFOAM is ready for use without any further user action. To achieve this, we add the following line
to the appropriate .bashrc file. In the case of a single user’s installation, this would be the file $HOME/.bashrc.
The $HOME/.bashrc file is loaded every time a Terminal is opened. Thus, if we add the command of Listing 18
to the $HOME/.bashrc file, then OpenFOAM is ready to use, whenever the user opens a Terminal. This also
applies to login shells, thus remote connections via SSH or systems without any graphical desktop are covered
as well.
sourc e $HOME / O pe nF OA M / Op enF OAM -4.0/ etc / b ashr c
Listing 18: Permanently sourcing OpenFOAM
6.1.2 Sourcing OpenFOAM on demand
Permanently sourcing OpenFOAM is impossible if we want to use several OpenFOAM versions alongside each
other. If we have OpenFOAM-3.0 and OpenFOAM-4.1 installed on our system, where should/does $FOAM_SRC
point to?
In this case, we need a solution to set up the OpenFOAM environment on demand for a specific version
of OpenFOAM. Again, we need to add instructions to the .bashrc file. However, now we add definitions for
aliases. An alias is a placeholder for a set of instructions, which are to executed only on demand. Since, we
11If you for some reason unthinkable to the author do not want to edit any .bashrc file, you can simply enter the instruction
shown in Listing 18 into the Terminal whenever you want to use OpenFOAM.
IThis offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 21
add the alias definitions to the .bashrc file, the aliases we defined are available in every Terminal. However,
in contrast to sourcing OpenFOAM permanently, the OpenFOAM environment is set up only when we invoke
the alias. An alias is a conventient way to save on typing effort, since we can assign one or several commands
of arbitrary length12 to a rather short alias. We are free to choose the alias’ name, as long as this name does
not collide with an existing command13.
In Listing 19 two aliases are shown for enabling OpenFOAM-3.0 and OpenFOAM-4.1. If we want to use
OpenFOAM-3.0, we simply type of30 into the Terminal, this will source the environment for OpenFOAM-3.0.
The use of these four letter aliases, which include the major and minor version number of OpenFOAM, saved
us from typing a 46 character command to enable the OpenFOAM environment.
alias o f30 =’ s ou rce $HOME / O pe nF OAM / Op enFOAM -3 .0/ etc / bashrc ’
alias o f41 =’ s ou rce $HOME / O pe nF OAM / Op enFOAM -4 .1/ etc / bashrc ’
Listing 19: Sourcing OpenFOAM on demand by using an alias
6.2 Useful helpers
12There is a limit on how long a single command can be. On the author’s Linux system, this is north of 2 million bytes.
13We can, in fact, define an alias which has the same name as an existing command. In this case, the alias “shadows” the
corresponding command. This is used in Ubuntu Linux to add some eye candy, e.g. for ls, which is shadowed by alias ls=’ls
–color=auto’. In this case, the Terminal expands the alias, whenever a user types ls.
IThis offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 22
Part II
General Remarks about OpenFOAM
7 Units and dimensions
This section discusses the treatment of physical units (e.g. meter, second, etc.) and dimensions (scalar, vector,
etc.) in OpenFOAM. In OpenFOAM physical units are referred to as dimensions and they are covered by the
class dimensionSet. The dimensionality (a quantity being a scalar or a vector) is treated implicitely by the
data types. The data types scalar or vector do not need any further specification of their dimensionality.
7.1 Unit inspection
Basically, OpenFOAM uses the International System of Units, short: SI units. Nevertheless, also other units
can be used. In that case it is important to remember, that some physical constant, e.g. the universal gas
constant, are stored in SI units. Consequently the values need to be adapted if other units that SI should be
used.
OpenFOAM performs in addition to its calculations also a inspection of the physical units of all involved
variables and constants. For fields, like the velocity, or constants, like viscosity, the unit has to be specified.
The unit is defined in the dimension set. Units in the International System of Units are defined as products of
powers of the SI base units.
[Q] = kgαmβsγKδmolAζcdη(1)
A dimension set contains the exponents of (1) that define the desired unit. With the dimension set OpenFOAM
is able to perform unit checks.
dim ens ion s [0 1 -2 0 0 0 0];
Listing 20: False dimensions for U
--> FOAM FATAL ERROR :
inc ompatib le dim ens ions for ope rat ion
[U[0 1 -3 0 0 0 0] ] + [U [0 1 -4 0 0 0 0] ]
Fr om fu nc t io n c he c kM et h od ( c on st fvMatrix < T ype >& , c on st f vM at rix < Type >&)
in file / h ome / user / O penF OA M / OpenFOAM -2.1. x / src / f in it eV ol um e / lnI nc lu de / f vMat ri x .C at l ine
1316.
FOAM a bor ting
Listing 21: Incompatible dimensions for summation
Listing 20 shows an incorrect definition of the dimension of the velocity, e.g. in the file 0/U.m/s2has been
defined instead of m/s. OpenFOAM recognises this false definition, because mathematical operations do not
work out anymore. Listing 21 shows a corresponding error message produced by two summands having different
units. Therefore, OpenFOAM aborts and displays an error message.
7.1.1 An important note on the base units
The order in which the base units are specified differs between OpenFOAM and many publications dealing with
SI units, compare (2) and (3). The order of the base units as it is used by OpenFOAM swaps the first two base
units. As the list of base units in [3,2] starts with the metre followed by the kilogram, OpenFOAM reverses this
order and begins with the kilogram followed by the metre. Also the fourth, fifth and sixth base units appear in
a different position.
[Q]OpenFOAM = kgαmβsγKδmolAζcdη(2)
[Q]SI = mαkgβsγAδKmolζcdη(3)
II This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 23
Eq. (2) is based on the source code of OpenFOAM, see Listing 22. Eq. (3) is based on [3,2].
1// - D efine an enu me ra ti on f or t he names of the dim en si on ex po nents
2enum dimensionType
3{
4MASS , // kil ogr am kg
5LENGTH , // metre m
6TIME , // second s
7TEMPERATURE , // Kelvin K
8MOLES , // mole mol
9CURRENT , // Ampere A
10 LUMINOUS_INTENSITY // Candela Cd
11 };
Listing 22: The definition of the order of the base units in the file dimensionSet.H
The reason for changing the order of the base units may be motivated from a CFD based point of view.
For fluid dynamics involving compressible flows as well as reactive flows and combustion the first five units of
OpenFOAM’s set of base units suffice.
7.1.2 Input syntax of units
Listing 23 shows the definition of a phase in a two-phase problem. Notice the difference between the first two
definitions and the third one. The unit of dis defined by the full set of seven exponents, whereas the other two
units (rho and nu) are defined only by five exponents. Apparently it is allowed to omit the last two exponents
(defining candela and ampere).
Defining units with five entries (for kilogram, metre, second, kelvin and mol) seems to be perfectly ap-
propiate. Neither the OpenFOAM User Guide [39] or the OpenFOAM Programmer’s Guide [38] mention this
behaviour. Defining a unit with an other number of values than five or seven leads to an error (see Listing 24).
phaseb
{
rho rho [ 1 -3 0 0 0 ] 1000;
nu nu [ 0 2 -1 0 0 ] 1e -06;
d d [ 0 1 0 0 0 0 0 ] 0.00048;
}
Listing 23: Definition of the unit
--> FOAM FATAL IO ERROR :
wrong t oken type - expected Scalar , found on line 22 the punctua tio n token ’] ’
fi le : / home / user / O pe nF OAM / user -2 .1. x/ run / t woP ha seE ul er Foa m / bed / co ns ta nt / t ra ns por tP rop er tie s ::
phase b :: nu at line 2 2.
From f unc tion operator > >( Ist ream & , Scalar &)
in file lnI nclude / Scala r .C at line 91.
FOAM exiting
Listing 24: Erroneous definition of units
7.1.3 Programming syntax of units
Single numbers or entire fields in OpenFOAM are not only read from file, they are also calculated from ex-
isting ones or they created completely new, independent of existing quantities. Let’s take a look on how to
create dimensioned quantities from the programming point of view. In OpenFOAM there are dimensioned
and undimensioned data types, e.g. there are the data types scalar and dimensionedScalar. The type
dimensionedScalar is basically a scalar with an additional dimensionSet.
II This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 24
Calculating dimensioned quantities
Calculated fields inherit their dimension set from the involved operations and operands. Listing 25 shows the
creation of the kinetic energy field Kfrom the square of the velocity fields14. The newly created field, bears
the name K, as this is passed as an argument to the constructor. The dimension set of the field Kis derived
from the constructor’s second argument. Since all mathematical operations on numeric types are mirrored for
dimensions, any mathematical operation on a dimensioned type not only yields a numerical result, it also yields
a resulting dimension. In this case the resulting dimension is square metre per square second.
1Info << " C reat ing field ki neti c e nergy K \n " << endl;
2volScalarField K("K", 0.5* magSq r (U ));
Listing 25: Computing the kinetic energy fields
Creating dimensioned quantities
When creating a dimensioned quantity from scratch, the dimension set needs to be stated explicitely. In Listing
26 the dimension set is explicitely passed to the constructor of dimensionedScalar as the second argument.
Note the use of the five argument constructor of dimensionSet. As the last two SI units (for current and lu-
minous intensity) are scarcely needed in fluid dynamics, the five argument constructor is a convenience feature
of this data type.
1dimensionedScalar foo(" fo o ", d im en si on Se t (0 , 3 , 0 , 0 , 0) , s calar ( 1.0) )
Listing 26: Create a new variable of the dimensionedScalar datatype
Always explicitely stating the dimension set with its 5 or 7 exponents would seriously bloat the code for no
benefit. Thus, there are a number of global constants of the data type dimensionSet. These constants define
the most common dimension sets and offer a very convenient short-hand notation15 as seen in Listing 27.
1dimensionedScalar bar(" ba r ", dimless , scala r (0.0) )
Listing 27: Create a new variable of the dimensionedScalar datatype
Since all mathematical operations performed on the numeric part of a dimensioned quantity are also per-
formed on the dimension set, the class dimensionSet implements mathematical operations. We can use these
and the global short-hands to define the dimension set of our new dimensioned quantity. In Listing 28, we
needlessly compute the dimension set for a velocity, however, this Listing demonstrates the use of mathematical
operations on dimension sets.
1dimensionedScalar baz(" ba z ", d im Le ng th / dimT ime , 42.0)
Listing 28: Create a new variable of the dimensionedScalar datatype
7.2 Dimensionens
Fields in fluid mechanics can be scalars, vectors or tensors. There are in OpenFOAM different data types to
distinguish between quantities of different dimension.
volScalarField A scalar field throughout the whole computaional domain, e.g. pressure.
volScalarField p
volVectorField A vector field throughout the whole domain, e.g. velocity.
volVectorField U
14The kinetic energy is defined in textbooks as k=1/2ρu2, which involves the fluid density ρ, which the definition in Listing
25 is lacking. However, the fluid density field rho enters the scene as second argument in the terms of the energy transport
equation, as can be seen in the temporal derivative and convective terms of rhoPimpleFoam’s energy equation: fvc::ddt(rho, K)
+ fvc::div(phi, K). Thus, OpenFOAM’s kinetic energy Kis in fact a specific kinetic energy.
15You can find these definitions in $FOAM_SRC/OpenFOAM/dimensionSet/dimensionSets.C
II This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 25
volTensorField A tensor field throughtout the whole domain, e.g. Reynolds stresses.
volTensorField Rca
surfaceScalarField A scalar field, defined on surfaces (surfaces of the finiten volumes), e.g. flux.
surfaceScalarField phi
dimensionedScalar A scalara constant throughout the whole domain (i.e. no field quantity).
dimensionedScalar nu
7.2.1 Dimension check
The data type defines also, as described before, the dimension of a quantity. The dimension of a quantity defines
the syntax how quantities have to be entered.
Listing 30 shows the error message OpenFOAM displays when the value of a scalar quantity is entered as a
vector (Listing 29).
dim ens ion s [ 0 0 0 0 0 0 0 ];
int erna lFi eld unifo rm ( 0 0 0 ) ;
boundaryField
{
inlet
{
type fix edV alue ;
value unifo rm 0;
}
Listing 29: Erroneous definition of α
--> FOAM FATAL IO ERROR :
wrong t oken type - expected Scalar , found on line 19 the punctua tio n token ’( ’
fi le : / home / user / O pe nF OAM / user -2 .1. x/ run / t woP ha seE ul er Foa m / bed /0 / alpha :: int er na lFi el d at line
19.
From f unc tion operator > >( Ist ream & , Scalar &)
in file lnI nclude / Scala r .C at line 91.
FOAM exiting
Listing 30: Error message caused by invalid dimension
7.3 Kinematic viscosity vs. dynamic viscosity
To determine if OpenFOAM uses the kinematic viscosity [Ns/m2=Pas] or the dynamic viscosity [m2/s] one
has simply to take a look on the dimension.
nu nu [ 0 2 -1 0 0 0 0 ] 0. 01;
Listing 31: dimensions of the viscosity
The type of viscosity is primarily determined by the used solver, e.g. compressible or incompressible.
7.4 Pitfall: pressure vs. pressure
The definition of pressure in OpenFOAM differs between the compressible and incompressible solvers. Com-
pressible solvers work with the pressure itself. Incompressible solvers use a modified pressure. The reason for
this is, because of ρ=const the incompressible equations are divided by the density and to eliminate density
entirely the modified pressure is introduced into the pressure term.
ˆp=p
ρ(4)
For this reason the entries in the 0/p files differ depending on the solver in use. This is visible by the unit of
pressure.
II This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 26
7.4.1 Incompressible
The unit of the pressure in an incompressible solver is defined by (4)
[ˆp] = N
m2·m3
kg = N m
kg =kgm
s2·m
kg =m2
s2(5)
dim ens ion s [0 2 -2 0 0 0 0];
Listing 32: Unit of pressure - incompressible
7.4.2 Compressible
The unit of the pressure in a compressible solver is the physical unit of pressure.
[p] = N
m2=
kgm
s2
m2=kg
ms2(6)
dim ens ion s [ 1 -1 -2 0 0 0 0 ];
Listing 33: Unit of pressure - compressible
7.4.3 Pitfall: Pressure in incompressible multi-phase problems
When solving a multi-phase problem in an Eulerian-Eulerian fashion, for each phase a momentum equation is
solved. In most cases it is assumed that the pressure is equal in all phases. For this reason the incompressible
equations can not be divided by the density, because each phase has a different density and therefore, the
modified pressure would be differnt for each phase. To avoid this issue, incompressible Euler-Euler solvers, like
bubbleFoam,twoPhaseEulerFoam or multiPhaseEulerFoam, use the physical pressure like compressible solvers
do.
8 Files and directories
OpenFOAM saves its data not in a single file, like Fluent does, it uses several different files. Depending on its
purpose a specific file is located in one of several folders.
8.1 Required directories
An OpenFOAM case has a minimal set of files and directories. The directory that contains those folders is
called the root directory of the case or case directory. Listing 34 shows the output of the commands pwd and
ls when they are invoked from a case directory. The first command returns the absolute path of the current
working directory. The second command prints the contents of the current folder. When ls is invoked without
any options it returns the names of all non-hidden files and folders. In this case there are three subdirectories
(0,constant and system). The fact that these three items are directories and not files is indicated by a different
color. If ls is called with the option -l are more detailed list is printed. This detailed list indicates if an entry
is a file or a directory.
use r@host :∼/ O penFOAM / user -2. 1. x/ run / ico Foam / c avit y$ pwd
/ ho me / user / Op en FOAM / user - 2.1. x / run / i co Foam / cav ity
use r@host :∼/ O penFOAM / user -2. 1. x/ run / ico Foam / c avit y$ ls
0 constant system
use r@host :∼/ O penFOAM / user -2. 1. x/ run / ico Foam / c avit y$ ls -l
ins gesamt 12
drwxrwxr -x 2 user group 4096 Okt 2 14:53 0
drwxrwxr -x 3 user group 4096 Okt 2 14 :53 constant
drwxrwxr -x 2 user group 4096 Okt 2 14 :53 sys tem
Listing 34: Case directory
II This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 27
0This is the first of the time-directories. It contains the initial and boundary conditions of all variable quan-
tities. A case does not have to start at time t= 0. However, if there is no specific reason for a case to
start at another time that t= 0, a case will always begin at time t= 0. The name of a time-directory is
simply the number of elapsed seconds.
constant This folder contains all files dealing with constant quantities as well as the mesh.
polymesh This is a subdirectory of constant. In this folder all files defining the mesh reside.
system In this folder all files that control the solver or other tools are located
In the course of computing the case two kinds of folders are created. First of all, at defined times all information
is written two the harddisk. A new time-directory is created with the number of elapsed seconds in its name. In
this folder all kinds of files are saved. The number of files is equal or larger than in the 0-directory containing
the initial conditions.
The second category of directory subsumes all kinds of folders created for all kind of reasons or by all kind
of tools, see Section 8.2 for a brief introduction to some of the more common of them.
8.2 Supplemental directories
Directories described in this Section may be created in the course of a computation.
8.2.1 processor*
If a case is solved in parallel, i.e. the case is computed using more than one processor at the time. In this case
the computational domain has to be decomposed into several parts, to divide the problem between the involved
parallel processes. The tool that is used to decompose the case created the processor*-directories. The * stands
for a consecutive number starting with 0. So, if a case is to be solved using 4 parallel processes, then the domain
has to be split into 4 parts. Therefore, the folders processor0 to processor3 are created.
Every one of the parallel*-directories contains a 0- and also a constant-directory containing only the mesh.
The system-directory remains in the case folder. See Section 10.5 for more information about conducting parallel
calculations.
8.2.2 functions
functions or functionObjects perform all kind of operations during the computation. Each function creates a
folder of the same name to save its data in. See Section 38 for more information about functions.
8.2.3 sets
If the tool sample has been used, then all data generated by sample is stored in a folder named sets. See Section
39 for more information about sample.
8.3 Files in system
In the directory named system there are three files for controlling the solver. This files are necessary to run a
simulation. Besides them there may also be additional files controlling other tools.
8.3.1 The main files
This files have to be present in the system folder to be able to run a calculation
controlDict This file contains the controls related to time steps, output interval, etc.
fvSchemes In this file the finite volume discretisation schemes are defined
fvSolution This files contains controls related to the mathematical solver, solver algorithms and tolerances.
II This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 28
8.3.2 Additional files
This list contains a selection of the most common files to be found in the system-directory.
probesDict Alternative to the use of the file probesDict,probes can also be defined in the file controlDict.
decomposeParDict Used by decomposePar. In this file the number of subdomains and the method of decom-
position are defined.
setFieldsDict Necessary for the tool setFields to initialise field quantities.
sampleDict Definitions for the post-processing tool sample.
9 Controlling OpenFOAM
9.1 The means of exerting control
Classical UNIX applications know several means of controlling their configuration [14]:
•System-wide run-control files
An example for these are files in /etc on Linux or UNIX systems. For OpenFOAM, such system-wide
run-control files are located in $FOAM_ETC, which might be home/user/OpenFOAM/OpenFOAM-3.0.0/etc.
There, we can find the global controlDict, controlling OpenFOAM’s behaviour installation-wide.
•System-wide environment variables
Such a system-wide variable on a Linux system is $HOSTNAME, which is the name associated to identify
the computer within a network. This name is the same for all users logged in at a certain machine, and
it can and should not be changed by a user. For OpenFOAM such system-wide environment variables are
$FOAM_ETC,$FOAM_INST_DIR or $WM_THIRD_PARTY_DIR. This variables are equal for all users of a certain
installation.
The distinction between system-wide and user-defined settings blurs, when we install OpenFOAM in our
home directory, then we are the administrator and the single user of our installation. This distinction was
made for clusters, which provide one installation to many users.
•User-defined run-control files
A perfect example of a user-defined run-controlled file is the file .bashrc in the user’s home directory.
This file contains user-specific settings. During the installation process of OpenFOAM, this file needs to
be edited to make the OpenFOAM installation available to the user.
•User-set environment variables
These aren’t quite common. On a Linux or UNIX system, a user might set the $EDITOR variable, then
applications, which might call an editor can simply query this variable to call the preferred editor of the
user.
•Switches and arguments passed on the command line
These are very common. A widely known example are the command line arguments -h,-help or --help
for displaying a summary of the application usage.
The order of the above listed means of control is descending from the system-level down to the per-execution
level. With the freedom to choose between five mechanisms to control the behaviour of an application comes
great responsibility to the software developer to choose wisely. Nobody wants to pass the same, never-changing
command line arguments every time an application in run. Otherwise, user often do not have the possibility to
edit system-wide run-control files, so these might be a bad location for settings which change on a daily basis.
9.1.1 Variables
Variables are the best place to store information, which is repeatedly needed. E.g. it would make no sense to
specify the installation directory of OpenFOAM in every run-control file which needs to know where OpenFOAM
is installed on the system, instead a variable $FOAM_INST_DIR is defined in one of OpenFOAM’s global run-
control files. In all other run-control files, which need to know the installation path, this variable is used. Thus,
information redundancy is avoided. Imagine the poor cluster administrators, if some information were stored
II This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 29
in multiple places, and this information were to change. Good luck finding and updating ALL occurances of
this data.
Variables offer the freedom to use the same name (i.e. the variable) regardless of what the actual information
is. OpenFOAM is always installed at $FOAM_INST_DIR, whether that is /home/user/OpenFOAM,/opt/OpenFOAM
or /home/user/Desktop/important_softWare.
9.1.2 Dictionaries
Dictionaries are the run-control files of OpenFOAM. Most of the controls of OpenFOAM are set in so called
dictionaries. An important dictionary is the file controlDict. Dictionaries offer a convenient way to store
structured information of arbitrary size, which would be rather impossible using variables or command line
arguments. Imagine typing all contents of controlDict every time you run a solver.
The distinction between global and local dictionaries saves ourselves from messing up the OpenFOAM
installation when fiddling with a case’s set-up.
9.1.3 Command line arguments
Besides the dictionaries, there are also command-line arguments to control certain aspects of OpenFOAM’s
solvers and utilities. Command line arguments are the best way to pass information to an application that
might change from one run to the other, even when the case is the same.
An example is the -parallel command line switch. Regardless of whether we run a case with a single
process or in parallel, the case’s settings are unchanged. Thus, it would be inconsistent to tell the solver to run
in parallel via a case file.
Command line switches are command line arguments, which do not need any additional information. Adding
-help to a solver name is sufficient to make the solver display its usage summary. A command line argument,
on the other hand, needs additional information. An example is the -time argument used to tell post-processing
tools on which time steps to act upon. Passing -time alone without any further information leaves the tool
clueless and it will issue an error message.
9.2 Syntax of the dictionaries
The dictionaries need to comply a certain format. The OpenFOAM User Guide states, that the dictionaries
follow a syntax similar to the C++ syntax.
The file format follows some general principles of C++ source code.
The most basic format to enter data in a dictionary is the key-value pair. The value of a key-value pair can
be any sort of data, e.g. a number, a list or a dictionary.
9.2.1 Keywords - the banana test
As OpenFOAM offers no graphical menus, in some cases allowed entries are not visible at a glance. If a key
expects a value of a finite set of data, then the user can enter a value that is definitely not applicable, e.g.
banana. Then OpenFOAM produces an error message with a list of allowed entries.
--> FOAM FATAL IO ERROR :
e xp e ct e d s t ar tT im e , f i r st Ti m e o r l at e st T im e f o un d ’ b ana na ’
Listing 35: Wrong keyword, or the banana test
Listing 35 shows the error message that is displayed when the value banana is assigned to the key startFrom
that controls at which time a simulation should start. The error message contains a note that is formated in
this way: expected X, Y or Z found ABC.
If in a dictionary several key-value pairs are erroneous, only the first one produces an error, as OpenFOAM
aborts all further operations.
II This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 30
Pitfall: assumptions & default values
In some cases the banana test behaves differently than expected. Listing 36 shows the warning message Open-
FOAM returns, when the banana test is used with the control compression of controlDict. See Section 9.3.2
for a description of this control. In this case, OpenFOAM does not abort but continues to run the case. In-
stead of returning an error message and exiting, OpenFOAM simply assumes a value in place of the invalid entry.
--> FOAM W arning :
Fr om f un ctio n IOs tr eam :: com pr ess io nE nu m ( co nst w ord &)
in file db / IOs trea ms / IOstreams / IOst ream . C at line 80
ba d c o mp re ssi on s pe ci fi er ’ bana na ’ , u sing ’ u nc om pr es se d ’
Listing 36: Failed banana test
9.2.2 Mandatory and optional settings
Some settings are expected by the solver to be made. If they are not present, OpenFOAM will return an error
message. Other settings have a default value, which is used if the user does not specify a value. In this sense,
settings can be divided into mandatory and optional ones.
As mandatory settings causes an error if they are not set, a simulation can be run only if all mandatory
settings were made.
About errors
•There will be an error when mandatory settings were not made.
•There is no error message if an optional setting (that is necessary) was omitted. All optional controls have
a default value and will be in place.
•There is no error message if a setting was made and that setting is not needed. The solver simply ignores
it. Consequently the definition of a variable time step in controlDict does not necessarily mean, that the
simulation is performed with variable time steps, e.g. if icoFoam (a fixed time step solver) is used.
•Sometimes an error message points to the setting of a keyword that is actually not faulty. See Section
9.2.3.
See Section 48.3 for a detailed discussion – including a thorough look at some source code – about reading
keywords from dictionaries.
9.2.3 Pitfall: semicolon (;)
Similar to C++, lines are terminated by a semicolon. Listing 37 shows the content of the file U1 in the 0-
directory. The line defining the boundary condition (BC) for the outlet was not terminated properly. Listing
38 shows the provoked error message. This error message does not mention outlet, but rather walls –keyword
walls is undefined. The definiton of the boundary condition for the walls comes after the outlet definition. One
reason for this may be, that OpenFOAM terminates reading the file after the missing semicolon causes a syntax
error, and therefore the boundary condition for the walls remain undefined.
This example demonstrates that the error messages are sometimes not very meaningful if they are taken
literally. The error was made at the definiton of the BC for the outlet. If only the definition. of the BC of the
walls is examined, the cause for the error message will remain unclear, because the BC definition of the walls is
perfectly correct.
dim ens ion s [0 1 -1 0 0 0 0];
i nt ern alF iel d uni fo rm (0 0 0 ) ;
boundaryField
{
inlet
{
type fix edV alue ;
II This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 31
value unifo rm (0 0 0.03704) ;
}
outlet
{
type zeroGradient
}
walls
{
type fix edV alue ;
value unifo rm (0 0 0) ;
}
}
Listing 37: Missing semicolon in the definition of the BC
--> FOAM FATAL IO ERROR :
key word wa lls is un de fine d in d ic ti on ar y "/ home / use r / Op en FO AM / user - 2.1. x / run / t wo Ph ase Eu le rFo am
/ ca se /0/ U1 :: b ou nd ar yF ie ld "
fi le : / home / user / O pe nF OAM / user -2 .1. x/ run / t woP ha seE ul er Foa m / ca se / 0/ U1 :: b ou nd ar yF ie ld fr om line
25 to line 47.
From fu nction d ictio nary :: subDic t ( const w ord & key word ) const
in file db / dictio nar y / d ictionary . C at line 461.
FOAM exiting
Listing 38: Error message caused by missing semicolon
9.2.4 Switches
Besides key-value pairs there are switches. These enable or disable a function or a feature. Consequently, they
only can have a logical value.
Allowed values are: on/off, true/false or yes/no. See Section 48.4.1 for a detailed discussion about valid
entries.
9.3 The controlDict
In this dictionary controls regarding time step, simulation time or writing data to hard disk are located.
The settings in the controlDict are not only read by the solvers but also by all kinds of utilities. E.g. some
mesh modification utilities obey the settings of the keywords startFrom and startTime. This has to be kept
in mind when using a number of utilities for pre-processing.
9.3.1 Time control
In this Section the most important controls with respect to time step and simulation time are listed. This list
makes no claim of completeness.
startFrom controls the start time of the simulation. There are three possible options for this keyword.
firstTime the simulation starts from the earliest time step from the set of time directories.
startTime the simulation starts from the time specified by the startTime keyword entry.
latestTime the simulation starts from the latest time step from the set of time directories.
startTime start time from which the simulation starts. Only relevant if startFrom startTime has been
specified. Otherwise this entry is completely ignored16.
stopAt controls the end of the simulation. Possible values are {endTime, nextWrite, noWriteNow, writeNow}.
endTime the simulation stops when a specified time is reached.
16If the simulation is set to start from firstTime or latestTime, this keyword can be omitted or the value of this keyword can be
anything – startTime banana does not lead to an error, what would be the case if the simulation started from a specific start time.
II This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 32
writeNow the simulation stops after the current time step is completed and the current solution is
written to disk.
endTime end time for the simulation
deltaT time step of the simulation if the simulation uses fixed time steps. In a variable time step simulation
this value defines the initial time step.
adjustTimeStep controls whether time steps are of fixed or variable length.17 If this keyword is omitted, a
fixed time step is assumed by default.
runTimeModifiable controls whether or not OpenFOAM should read certain dictionaries (e.g. controlDict)
at the beginning of each time step. If this option is enabled, a simulation can be stopped by using setting
stopAt to one of these values {nextWrite, noWriteNow, writeNow}, see Section 10.2.
9.3.2 Data writing
In controlDict the controls regarding data writing can be found. Often, it is not necessary to save every time
step of a simulation. OpenFOAM offers several ways to define how and when the data is to be written to the
hard disk.
writeControl controls the timing of writing data to file. Allowed values are {adjustableRunTime, clockTime,
cpuTime, runTime, timeStep}.
runTime when this option is chosen, then every writeInterval seconds the data is written.
adjustableRunTime this option allows the solver to adjust the time step, so that every writeInterval
seconds the data can be written. Otherwise the times at which data is written does not exactly match
the entry in writeInterval. I.e. for a 1 s interval the data is written at t= 1.0012,2.0005, . . . s.
timeStep the data is written every writeInterval time steps.
writeInterval scalar that controls the interval of data writing. This value gets its meaning from the value
assigned to writeControl.
writeFormat controls how the data is written to hard disk. It is possible to write text files or binary files.
Consequently, the options are {ascii, binary}.
writePrecision controls the precision of the values written to the hard disk.
writeCompression controls whether to compress the written files or not. By default compression is disabled.
When it is activated, all written files are compressed using gzip.
timeFormat controls the format that is used to write the time step folders.
timePrecision specifies the number of digits after the decimal point. The default value is 6.
purgeWrite this setting control whether to clear out old time steps. The default value is 0, which means
that no clearing out will be conducted. For enabling clearing out old time steps, valid values are positive
integer numbers. If enabled with a non-zero value N, only the last Ntime steps will be retained. Once
the simulation has written Ntime steps to disk, for every new time step saved, the oldest one will be
deleted. The initial time step is not affected and will always remain in the case18.
17This keyword is important only for solvers featuring variable time stepping. A fixed time step solver simply ignores this control
without displaying any warning or error message.
18In the file TimeIO.C we see, that each time we reach write-time, the current time step is added to a FIFO stack. Subsequently,
the stack’s size is checked against the purgeWrite value. If the stack is larger, then one item will be removed.
II This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 33
Pitfall: timePrecision
OpenFOAM is able to automatically increase the value of timePrecision parameter if need arises, e.g. due
to a reduction in (dynamic) time step size19. This is typically the case when a simulation diverges and the
(dynamic) time step gets decreased by orders of magnitudes. However, simulations that do not diverge may
also create the need for an increase in time precision.
Inc reased the ti mePr eci sion from 6 to 7 to di sti nguish bet ween t ime Nam es at time 4.708 84
Listing 39: Exemplary solver output in the case of an automatic increase of the timePrecision value.
If a simulation that increased its time precision is to be restarted or continued from the latest time step, then
the chosen time precision may not be sufficient to represent the present time step values, i.e. a timePrecision
of 3 is not sufficient to represent the latest time step at t= 0.1023 s. OpenFOAM will apply rounding to the
reach the selected number of digits behind the comma. Consequently, OpenFOAM will fail to find files at time
t= 0.102 s.
This behaviour is hard to detect for an unaware user. The only clue for detection lies in this case in the
fourth digit behind the comma, which is present in only in the name of the time step directory but not in
the timeName that is looked up by OpenFOAM. Listing 40 shows the according error message and a directory
listing of the case directory. It is up to the reader to decide whether this is an easy to spot error. The author
took some time, which motivated him to elaborate on this issue in this little collection of errors and misbehaviour.
--> FOAM FATAL IO ERROR : canno t fi nd file
file : / home / ger hard / O penFOAM / user -2.3. x/ run / icoFoam / c avity / 0.10 2/ p at line 0.
From fu nct ion reg IOo bje ct :: readStream ()
in file db / reg IOobj ect / r eg IOobj ec tRead . C at line 73.
FOAM exiting
use r@host :∼/ O penFOAM / user -2. 3. x/ run / ico Foam / c avit y$ ls
0 0.1023 constant sys tem
use r@host :∼/ O penFOAM / user -2. 3. x/ run / ico Foam / c avit y$
Listing 40: Exemple of an error caused by an automatic increase of the timePrecision value in the previous
simulation run. We fail to restart the simulation as OpenFOAM is not able to find the correct time step.
9.3.3 Loading additional Libraries
Additional libraries can be loaded with an instruction in controlDict. Listing 41 shows how an external library
(in this case a turbulence model that is not included in OpenFOAM) is included. This model can be found
athttps://github.com/AlbertoPa/dynamicSmagorinsky/.
libs ( " l ib dyna mi cSma gori ns kyMo de l . so" ) ;
Listing 41: Load additional libraries; controlDict entry
9.3.4 functions
functions, or functionObjects as they are called in OpenFOAM, offer a wide variety of extra functionality, e.g.
probing values or run-time post-processing. See Section 38.
functions can be enabled or disabled at run-time.
19A dynamic increase of the timePrecision value in simulations with fixed time steps indicates a setting in which the time
precision is not sufficient to adequately represent the time step. This leads to a automatic increase of time precision after the first
time step is written to disk. I.e. if ∆tcan’t be represented with timePrecision number of digits after the comma, then t1+ ∆t
also can’t be represented. Thus, t1and t1+ ∆twould get the same time name and would consequently be indistinguishable. See
Section 48.6.3 on more implementation details on this matter.
II This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 34
9.3.5 Outsourcing a dictionary
Some definitions can be outsourced in a seperate dictionary, e.g. the definition of a probe-functionObject.
All inclusive
In this case the probe is defined completely in controlDict.
functions
{
probes1
{
ty pe pro bes ;
f un c ti o nO b je c tL i bs (" l ib sa m pl i ng . so ") ;
fields
(
p
U
);
out pu tCo nt rol out put Time ;
outputInterval 0.01;
probeLocations
(
(0.5 0.5 0.05)
);
}
}
Listing 42: Definition of a probe in controlDict
Seperate probesDict
In this case the definition of the probe is done in a seperate file – the probesDict. In controlDict the name of
this dictionary is assigned to the keyword dictionary. This dictionary has be located in the system-directory of
the case. It is not possible to assign the path of this dictionary to this keyword.
functions
{
probes1
{
ty pe pro bes ;
f un c ti o nO b je c tL i bs (" l ib sa m pl i ng . so ") ;
dic tio nary probesDict ;
}
}
Listing 43: External definition of probes; Entry in controlDict
fields
(
p
U
);
out pu tCo nt rol out put Time ;
outputInterval 0.01;
probeLocations
(
(20.5 0.5 0. 05)
);
Listing 44: Definition of probes in the file probesDict
II This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 35
Everything external
There is also the possibility to move the whole definition of a functionObject into a seperate file. In this case
the macro #include is used. This macro is similar to the pre-processor macro if C++.
functions
{
# inclu de " cut tingP lane "
}
Listing 45: Completely external definition of a functionObject; Entry in controlDict
cuttingPlane
{
type surfaces ;
f un c ti o nO b je c tL i bs (" l ib sa m pl i ng . so ") ;
out pu tCo nt rol out put Time ;
sur fac eF orm at r aw ;
fields ( alpha1 );
interpolationScheme cellPoint;
surfaces
(
yNormal
{
type cuttingPlane;
pla neType poi nt And No rma l ;
pointAndNormalDict
{
bas ePoint (0 0.1 0) ;
normalVector (0 1 0);
}
int er po la te tr ue ;
}
);
}
Listing 46: Definition of a cuttingPlane functionObject in a seperate file named cuttingPlane
9.3.6 Pitfalls
timePrecision
If the time precision is not sufficient, then OpenFOAM issues a warning message and increases the time precision
without aborting a running simulation.
Listing 47 shows such a warning message. The simulation time exceeded 100 s and OpenFOAM figured that
the time precision was not sufficient anymore.
--> FOAM W arning :
From f unc tion Time :: o per ator ++()
in file db / Time / Time . C at l ine 1024
Inc reased the ti mePr eci sion from 6 to 13 to disting uis h between timeNames at time 100.001
Listing 47: Warning message: automatic increase of time precision
A side effect of this increase in time precision was a slight offset in simulation time. The time step of this
simulation was 0.001 s and the time steps were written every 0.5 s. As it is clearly visible in Listing 48, the
names of the time step folders indicate this offset. This effect on the time step folder names was the reason, the
automatic increase of time precision was noticed by the author.
However, automatic increase of time precision has no negative effect on a simulation. This purpose of this
section is to explain the cause for this effect.
II This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 36
101.5000000002
101.0000000002
100.5000000002
100
99.5
99
98.5
Listing 48: Time step folders after increase of time precision
9.4 Run-time modifcations of dictionaries
If the switch runTimeModifiable is set true,on or yes; certain files (e.g. controlDict or fvSolution) are read anew,
if a file has changed. In this way, e.g. the write interval can be changed during the simulation. If OpenFOAM
detects a run-time modification it issues a message on the Terminal.
reg IOo bject :: read IfMo dif ied () :
Re - r ea ding ob ject con tr ol Di ct from f ile "/ home / user / O pe nF OAM / user -2 .1. x/ run /
mul ti ph aseEu le rF oam / bub bleCo lumn / system / c ont rolDict "
Listing 49: Detected modifaction of controlDict at run-time of the solver
9.5 The fvSolution dictionary
The file fvSolution contains all settings controlling the solvers and the solution algorithm. This file must
contain two dictionaries. The first controls the solvers and the second controls the solution algorithm.
9.5.1 Solver control
The solvers dictionary contains settings that determine the work of the solvers (e.g. solution methods, toler-
ances, etc.).
9.5.2 Solution algorithm control
The dictionary controlling the solution algorithm is named after the solution algorithm itself. I.e. the name of
the dictionary controlling the PIMPLE algorithm is PIMPLE. Note, that the name of this dictionary is in upper
case letters unlike most other dictionaries.
Listing 50 shows an example of a PIMPLE dictionary. See Section 33.2 for a detailed discussion on the PIM-
PLE algorithm.
PIMPLE
{
nOuterCorrectors 1;
nCo rre ctors 2;
nNonOrthogonalCorrectors 0;
pRefCell 0;
pRe fVa lue 0;
}
Listing 50: The PIMPLE dictionary
9.6 Command line arguments
OpenFOAM’s solvers and utilities can be controlled by a set of command line arguments. Some of them are
common to all or many executables, some might be special to a certain tool.
9.6.1 Getting help: -help
The most important command line argument is -help. This is common to all solvers and tools of OpenFOAM
and it displays a summary of the respective tool.
II This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 37
9.6.2 Getting in control: -dict
Certain tools expect to find a specific dictionary containing necessary information. With the -dict option, the
user can tell the executable, where to look for the dictionary. To the authors knowledge, all tools expecting a
dictionary assume a default location and filename. E.g. in older versions of OpenFOAM blockMesh expected to
find a dictionary named blockMeshDict in the constant/polyMesh sub-directory of the case’s root, in newer
versions it checks also the system directory. If the use chooses to put the dictionary containing into a different
folder, he or she can do so, however, the path to the dictionary now needs to be passed using the -dict command
line argument.
no control dict
The help summary displayed by -help, in some cases, describes the -dict options as follows: read control dic-
tionary from specified location. However, the dictionary specified with the -dict option is not the controlDict.
Thus, all entries that go into controlDict need to go into controlDict. For some tools the description of
the -dict option seems a little ambiguous. What is meant by control dictionary in this case is the dictio-
nary controlling this specific tool, such as blockMeshDict controlls blockMesh or snappyHexMeshDict controls
snappyHexMesh.
10 Usage of OpenFOAM
10.1 Use OpenFOAM
In the most simple case, Listing 51 represents a complete simulation-run.
blockMesh
checkMesh
icoFoam
paraFoam
Listing 51: Compute a simple simulation case
The first command, blockMesh, creates the mesh. The geometry has to be defined in blockMeshDict.checkMesh
performs, as the name suggests, checks on the mesh. The third command is also the name of the solver. All
solvers of OpenFOAM are invoked simply by their name. The last command opens the post-processing tool
ParaView.
There are additional tasks that extend the sequence of commands shown in Listing 51. These can be
•Convert a mesh created by an other meshing tool, e.g. import a Fluent mesh
•Initialise fields
•Set up an parallel simulation; see Section 10.5
10.1.1 Redirect output and save time
The solver output can be printed to the Terminal or redirected to a file. Listing 52 shows how the solver output
is redirected to a file named foamRun.log.
mpi run - np N ico Fo am - p ar al lel > f oa mR un . log
Listing 52: Redirect output to a file
Redirecting the solver output does not only create a log file, it also save the time that is needed to print the
output to the Terminal. In some cases this can reduce simulation time drastically. However, writing to hard
disk also takes its time.
II This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 38
Time steps Cells Print to Terminal Redirect to file
executionTime clockTime executionTime clockTime
5000 400 6,36 9 4,6 6
10000 400 12,71 18 9,22 10
12500 400 15,8 23 11,54 12
25000 400 32,33 47 22,99 23
5000 1600 9,74 11 9,3 10
5000 6400 282,19 283 282,83 283
Table 1: Run-time cavity test case
executionTime is the time the processor takes to calculate the solution of the case. clockTime is the time
that elapses between start and end of the simulation, this is the time the wall clock indicates. The value of
the clockTime is always larger than the value of the executionTime, because computing the solution is not the
only task the processor of the system performs. Consequently, the value of the ClockTime depends on external
factors, e.g. the system load.
Redirect output to nowhere
If the output of a program is of no interest it can be redirected to virtually nowhere to prevent it from being
displayed on the Terminal. Listing 53 shows haw this is done. /dev/null is a special file on unix-like systems
that discards all data written to it.
mpi run - np N ico Fo am - p ar al le l > / dev / null
Listing 53: Redirect output to nowhere
10.1.2 Run OpenFOAM in the background, redirect output and read log
In Section 10.1.1 the redirection of the solver output was explained. To monitor the progress of running
calculation the end of the log can be read with the tail command.
Listing 54 shows how a simlation with icoFoam is started and the solver output is redirected. The &at
the end of the line causes the invoked command to be executed in the background. The Terminal remains
therefore available. Otherwise the Terminal would be waiting for icoFoam to finish before executing any further
commands.
The second command invoked in Listing 54 prints the last 5 lines of the log file to the Terminal. tail returns
the last lines of a text file. Without the parameter -n tail returns by default the last 10 lines.
use r@host :∼/ O penFOAM / user -2. 1. x/ run / ico Foam / c avit y$ icoF oam > foamR un . log &
[1] 10416
use r@host :∼/ O penFOAM / user -2. 1. x/ run / ico Foam / c avit y$ tail foamRu n .log -n 5
Exe cuti onT ime = 0.74 s ClockTime = 1 s
Time = 1.12
Cou ra nt Nu mber mean : 0.4 44 32 9 ma x : 1 .7 04 27
use r@host :∼/ O penFOAM / user -2. 1. x/ run / ico Foam / c avit y$
Listing 54: Read redirected output from log file while the solver is running
10.1.3 Save hard disk space
OpenFOAM saves the data of the solution in intervals in time directories. The name of a time directory rep-
resents the time of the simulation. Listing 55 shows the content of a case directory after the simulation has
finished. Besides the three folders that define the case (0,constant and system) there are more time directories
and a probes1 -folder present.
II This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 39
use r@host :∼/ O penFOAM / user -2. 1. x/ run / ico Foam / c avit y$ ls
0 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1 const ant probe s1 syste m
use r@host :∼/ O penFOAM / user -2. 1. x/ run / ico Foam / c avit y$
Listing 55: List folder contents
The probes1 -directory contains the data generated by the functionObject named probes1. The time-directories
contain the solution data of the whole computational domain. Listing 56 shows the contents of the 0- and the
0.1 -directory. Typically, time-directories generated in the course of the computation contain more data than
the 0-directory defining the initial conditions.
use r@host :∼/ O pe nF OA M / user -2 .1. x/ run / i co Fo am / c av it yBi na ry$ l s 0
p U
use r@host :∼/ O pe nF OA M / user -2 .1. x/ run / i co Fo am / c av it yBi na ry$ l s 0 .1
p phi U unifo rm
use r@host :∼/ O pe nF OA M / user -2 .1. x/ run / i co Fo am / c av it yBi na ry$
Listing 56: List folder contents
Using binary files or compressing files
In general the time-directories use the majority of the hard disk space a completed case takes. If the time-
directories are saved in binary instead of ascii format, these use generally a little less space. Another advantage
of storing time step data in binary format, the time step data has full precision.
OpenFOAM also offers the possibility to compress all files in the time step directories. For compression
OpenFOAM uses gzip, this is indicated by the files names in the time step directories, i.e. alpha1.gz instead
alpha1.
Table 2shows a comparison of hard disk use. The most reduction is achieved by compressing ascii data files.
However, storing the time step data in ascii has the disadvantage that the numerical precision is limited to the
number of digits stated with the writePrecision keyword in the controlDict. In this case writePrecision
was set to 6, i.e. numbers have up to 6 significant digits. Compressing the binary files shows less effect than
compressing the ascii files, which indicates that the binary files contain less redundant bytes.
Write settings Used space reduction
ascii 45.5 MB
ascii,compressed 16.7 MB 28.8 MB -63.3 %
binary 33.8 MB 11.7 MB -25.7 %
binary,compressed 28.8 MB 16.7 MB -36.7 %
Table 2: Comparison of hard disk space consumption
Make sure to avoid unnecessary output
Disk space can easily be wasted by writing everything to disk. Not only writing too many time steps to disk
can waste space, functionObjects can be the culprit too. See 38.6.3.
10.2 Abort an OpenFOAM simulation
An OpenFOAM simulation ends when the simulation time reaches the value specified with the endTime keyword
in controlDict. However, we also need to be able to stop a simulation prematurely. This section explains how
to end a simulation in a controlled manner, i.e. the current state of the solution is written to the harddisk in
order to be able to continue the simulation at a later time.
As a prerequisite, the runTimeModifiable flag has to be enabled in controlDict. This keyword controls
whether controlDict is monitored for changes during the run-time of the simulation. This is necessary for this
method to work. Otherwise, the simulation will stop at endTime.
To abort a simulation we simply need to change the value of the stopAt entry in controlDict from endTime
to writeNow. When OpenFOAM detects the change and re-reads controlDict, this causes OpenFOAM to finish
its current time step and write the state of the solution to disk before ending the run.
II This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 40
10.3 Terminate an OpenFOAM simulation
This section describes how to terminate a running OpenFOAM simulation. See Section 10.2 on how to abort a
simulation in a controlled manner, i.e. saving the current solution and stop the simulation.
This section explains how terminate a running simulation immediately and without saving the current
solution. Use this approach when you wouldn’t use the solution anyway, e.g. because you chose incorrect
settings.
10.3.1 Terminate a process in the foreground
If a command is executed in the Terminal without any additional parameters the process runs in the foreground.
The Terminal is therefore busy and can not be used until the process is finished. When a process is running
in the foreground it can easily terminated by pressing CTRL +C. Listing 57 features the GNU command
sleep. The only function of this command is to pause for a specified amount of time. With this command the
permature termination of a process can be tried.
use r@host :∼$ s leep 3
use r@host :∼$
Listing 57: Keep the Terminal busy
10.3.2 Terminate a background process
If a process runs in the background, the Terminal is free to be used for further tasks while the process is
running. In this case, the background process can not be terminated by pressing CTRL +Cbecause the
Operating System can not tell which background process the user wants to terminate.
Identify the process
On UNIX based systems every process is identified by a unique number. This is the PID, the process identifier.
The PID is equivalent to a licence plate for a car. During run-time this number is unique. However, after a
process has finished the PID of this process is available for other, later processes.
To find out which processes are currently running, invoke the command ps. This lists all running processes.
Without any further parameters only the processes that were executed from the current Terminal are listed.
Listing 58 shows the result if a new Terminal is opened and ps is called. The first entry – bash – is the Terminal
itself. The second entry – ps – is the only other process active at the time ps looks for all running processes.
The PID is listed in the first column of Listing 58. Depending on the parameters passed to ps the output can
be formatted differently.
use r@host :∼$ ps
PID TTY TIME CMD
13490 pts /1 00:00: 00 bash
13714 pts /1 00:00: 00 ps
use r@host :∼$
Listing 58: List processes in a fresh Terminal
The output of 58 is rather dull. However, there are lots of parameters telling ps what to do. The option -e
makes ps list all systemwide running processes. The output of such a call can be quite long, because ps lists all
processes started by the users as well as all system processes20.
The option -F controls the output format of ps. In this case -F stands for extra full. This means the output
contains a lot of information. Another option to display much information is -l. This option truncates the
names of the processes to 15 characters, whereas -F displays not only the full name of the process, it also
displays the parameters with which the processes were called.
ps - eF
Listing 59: List all running processes of the system
ps displays much information about a process. For terminating a process only the PID is necessary.
20System processes are processes run by the Operating System itself.
II This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 41
Search in the list of processes
The output of ps is a list which can be quite long. To terminate a certain process its PID has to be known.
Searching a number in a list of numbers can be quite painful and errorprone. Therefore it would be handy to
search in the list ps has returned for the desired process.
Before all else, grep does the trick. And now for something more detailed. grep is a program that searches
the lines of its input for a certain pattern. grep can use a file or the standard input as its input. As it is
unpractical to redirect the output of ps into a file only for grep to read it, we directly redirect the output of ps
to the input of grep. This is achieved by the use of a pipe.
Listing 60 shows how this is done. The first part of the command invoked – ps -eF – calls ps to list
all processes currently running in great detail. The option -F is used to make sure long process names can
be distinguished, e.g. to tell buoyantBoussinesqPimpleFoam apart from buoyantBoussinesqSimpleFoam.
Both are standard solvers of OpenFOAM. The bold part are the first 15 characters of the solver’s name. If the
option -F was omitted and both solvers were running, the results of ps would be ambiguous.
The second part of the command invoked in Listing 60 shows the call of grep.grep can be called with one or
two arguments. If only one argument is passed to grep,grep uses the standard input as input. If grep is called
with two parameters, the second argument has to specify the file from which grep has to read. As grep is called
with only one argument, it reads from the standard input.
Because it would be even more boring to type the list returned by ps we redirect the output of ps to the
standard input of grep. This is done by the pipe. The character |marks the connection of two processes in the
Terminal. The command left of the |passes its output directly to the command specified right of the |.
Now we can read and interpret Listing 60. It shows the output of the search for all running processes con-
taining the pattern Foam. In this case a parallel computation is going on. The first line of the result is mpirun.
This process controls the parallel running solvers. The next four lines are the four instances of the solver. How
parallel simulation works is explained in Section 10.5. The second last entry of the result is grep waiting for
input21. The last line of the result is the pdf viewer which displays this document at that time. This example
shows that is important to choose the pattern wisely, the search may return unexpected results.
use r@host :∼$ ps -ef | grep Fo am
user 11005 5117 0 17: 11 pts /2 00: 00:0 5 mpirun -np 4 twoPhas eEule rFoam - p ar al le l
user 11006 11005 99 17:11 pts /2 00:40:27 twoP has eEul erFoam - p ar all el
user 11007 11005 99 17:11 pts /2 00:40:28 twoPhas eEul erFoam - p ar al lel
user 11008 11005 99 17:11 pts /2 00:40:27 twoPhas eEul erFoam - p ar al lel
user 11009 11005 99 17:11 pts /2 00:40:26 twoP has eEul erFoam - p ar all el
us er 1 16 73 1 11 16 0 17:52 p ts / 12 0 0: 00 :0 0 grep - - co lor = au to Foam
us er 3 2041 1 0 Aug01 ? 00: 00 :3 1 evi nce / tm p / lyx _t mp di r . J 18 462 / l yx _t mp bu f0 / op en
FoamUserManual_CDLv2.pdf
use r@host :∼$
Listing 60: Search for processes
List only specified processes
You can tell ps directly in which processes you are interested. The option -C of ps makes ps list only those
processes that stem from a certain command. Listing 61 shows the output when ps -C twoPhaseEulerFoam
is typed into the Terminal. In this case also there are four parallel processes running. Notice, that only the
processes directly related to the solvers are shown. No other results are displayed unlike in Listing 60.
One has to bear in mind, that ps -C does not search for patterns. If the command name passed to ps as an
argument is misspelled, ps will not display the desired result. Listing 62 shows the effect of typos in this case.
The truncation of the process name in the list does not affect the search if the passed command name is equal
or longer than the truncated process name. The first two commands issued in Listing 62 result in a list of all
running instances of the solver. If the passed argument is shorter than the truncated process name – the third
command – ps does not output any results. Also if there is a typo in the passed argument, ps does not find
anything.
use r@host :∼$ ps -C twoP hase Eul erFo am
PID TTY TIME CMD
21On most Unix-like systems processes connected by a pipe are started at the same time. For this reason grep is already running
while ps is listing all running processes.
II This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 42
11006 pts /2 00:47: 44 tw oP haseE ul erF o
11007 pts /2 00:47: 44 two Pha se Euler Fo
11008 pts /2 00:47: 44 two Pha se Euler Fo
11009 pts /2 00:47: 43 tw oP haseE ul erF o
use r@h ost :∼$
Listing 61: List all instances of twoPhaseEulerFoam
use r@host :∼$ ps -C twoPhaseEulerFoa
PID TTY TIME CMD
12741 pts /0 00:00: 34 two Pha se Euler Fo
12742 pts /0 00:00: 34 two Pha se Euler Fo
12743 pts /0 00:00: 34 two Pha se Euler Fo
12744 pts /0 00:00: 34 two Pha se Euler Fo
use r@host :∼$ ps -C two Phas eEul erFo
PID TTY TIME CMD
12741 pts /0 00:00: 36 two Pha se Euler Fo
12742 pts /0 00:00: 36 two Pha se Euler Fo
12743 pts /0 00:00: 36 two Pha se Euler Fo
12744 pts /0 00:00: 36 two Pha se Euler Fo
use r@host :∼$ ps -C twoPhaseEulerF
PID TTY TIME CMD
use r@host :∼$ ps -C twP hase Eule rFoa
PID TTY TIME CMD
Listing 62: List all instances of twoPhaseEulerFoam – the effect of typos
Terminate
The operating system interacts with running processes using signals. The user can also send signals to processes
using the command kill.kill sends by default the termination signal. To identify the process to which the signal
is to be sent, the PID of this process has to be passed as an argument.
Listing 63 shows how the programm sleep is executed, all running processes are listed, the running instance
of sleep is terminated and the running processes are listed again. When ps was executed the second time, a
message is displayed stating the process has been terminated22. If the process would not have been terminated
the message at the “natural” end of the process would be like in Listing 6423.
use r@host :∼$ sleep 20 &
[1] 13063
use r@host :∼$ ps
PID TTY TIME CMD
12372 pts /0 00:00: 00 bash
13063 pts /0 00:00: 00 sleep
13064 pts /0 00:00: 00 ps
use r@host :∼$ kill 1 3063
use r@host :∼$ ps
PID TTY TIME CMD
12372 pts /0 00:00: 00 bash
13065 pts /0 00:00: 00 ps
[1]+ Be endet sleep 20
use r@host :∼$
Listing 63: Terminate a process using kill
use r@host :∼$ s leep 1 &
[1] 13126
use r@host :∼$ ps
PID TTY TIME CMD
12372 pts /0 00:00: 00 bash
13127 pts /0 00:00: 00 ps
[1]+ Fertig sleep 1
use r@host :∼$
22On other systems this message is displayed immediately – see Listing 65. In this case the procedure was tried on the local
computing cluster.
23A system with English language setting the message would read Terminated if the process would have been terminated and
Done if the process would have been allowed to finish.
II This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 43
Listing 64: The natural end of a process
use r@clust er user > sleep 10 &
[1] 31406
use r@clust er user > k ill 31406
user@cluster user>
[1] T erm ina ted sleep 10
user@cluster user>
Listing 65: Terminate a process using kill on a different machine
10.4 Continue a simulation
If a simulation has ended at the end time or if it has been aborted there may be the need to continue the
simulation. The most important setting to enable a simulation to be continued has to be made in the file
controlDict. There, the keyword startFrom controls from which time the simulation will be started.
The easiest way to continue a simulation is to set the startFrom parameter to latestTime. Then, if
necessary, the value of endTime needs to be adjusted. After this changes, the simulation can be continued by
simply invoking the solver in the Terminal.
10.5 Do parallel simulations with OpenFOAM
OpenFOAM is able to do parallel simulations. There is no great difference between calculating a case with one
single process or using many parallel processes. The only obvious additional task is to split the computation
domain into several pieces. This step is called domain decomposition. After the domain is decomposed several
instances of the solver are running the case on a subdomain each. Additionally, the invokation of the solver
differs from the single process case.
10.5.1 Starting a parallel simulation
To enable a simulation using several parallel instances of a solver, OpenFOAM uses the MPI standard in the
implementation of OpenMPI. OpenMPI ensures that all parallel instances of the solver run synchronously.
Otherwise the simulation would generate no meaningful results. In order to be able to manage all parallel
processes the simulation has to started using the command mpirun.
Listing 66 shows how a parallel simulation using 4 parallel processes is started. The solver outputs are
redirected into a file called > foamRun.log and the simulation runs in the background of the Terminal. So the
same Terminal can be used to monitor the progress of the calculation. See Section 10.1.2 for a discussion about
running a process in the background.
The output message in the Listing shows the PID of the running instance of mpirun. This PID can be used
to terminate the parallel calculation, like it is explained in Section 10.3.2.
use r@host :∼$ m pi run - np 4 ico Fo am - p ar al le l > f oa mR un . l og &
[1] 11099
use r@host :∼$
Listing 66: Run OpenFOAM with 4 processes
The number of processes, in this case 4, has to be equal the number of processor* folders. These folders are
created by decomposePar and their number is defined in decomposeParDict. See Section 10.5.2 for information
about domain decomposition.
If this numbers – the number of processor* folders and the number of parallel processes with which mpirun
is invoked – are not equal OpenFOAM issues an error message similar to Listing 67. In this case the domain
was decomposed into 4 subdomains and it was tried to start the parallel simulation with 2 processes. If the
parallel simulation is called with too many processes, OpenFOAM issues an error message like in Listing 68.
The first example shows, that OpenFOAM reacts differently whether the parallel job was started with loo little
or too many processes.
II This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 44
[0] --> FOAM FATAL ERROR :
[0] "/ h ome / use r / Op en FO AM / user - 2.1. x / run / i co Foam / c avity / syste m / dec omp os eP arD ic t " s pe ci fi es 4
pro ces sor s but job was start ed with 2 pro ces sor s .
Listing 67: Run OpenFOAM with too little parallel processes
[0] --> FOAM FATAL ERROR :
[0] numbe r of pr oce ssor di rec tor ies = 4 is not equal to the nu mber of p roc essors = 8
Listing 68: Run OpenFOAM with too many parallel processes
Pitfall: -parallel
The parameter -parallel is important. If this parameter is omitted, the solver will be executed ntimes.
Listing 69 shows the output of the command ls when it is run with mpirun with two processes. In this case ls
is simply run twice.
If the parameter -parallel is missing, the same happens as in the case of ls. The simulation is run by n
processes at roughly the same time. Listing 70 shows the first lines of output of a situation where the -parallel
parameter was omitted. All solvers start the calculation of the whole case and write their output to the Ter-
minal. The output appears on the Terminal in the order as it is generated by the solvers – in other words, the
output on the Terminal is completely disarranged. If the -parallel parameter is missing, there is also no check
if the processor* folders are present.
use r@host :∼/ O penFOAM / user -2. 1. x/ run / ico Foam / c avit y$ mpirun -np 2 ls
0 constant system
0 constant system
use r@host :∼/ O penFOAM / user -2. 1. x/ run / ico Foam / c avit y$
Listing 69: Run ls using 2 processes
use r@host :∼/ O penFOAM / user -2. 1. x/ run / ico Foam / c avit y$ mpirun -np 4 icoFoam
/*---------------------------------------------------------------------------*\
| === === === | |
| \\ / F ield | O penF OAM : The Open Sour ce CFD T oolbox |
| \\ / O p er at ion | V er sion : 2.1. x |
| \\ / A nd | Web : ww w . Op en FO AM . org |
| \\/ M anip ula tion | |
\*---------------------------------------------------------------------------*/
Bui ld : 2. 1. x -6 e 8 9b a 0b c d1 5
Exec : ico Foam
Date : Jan 29 2013
Time : 10: 51: 12
Host : "host"
PID : 25622
/*---------------------------------------------------------------------------*\
| === === === | |
| \\ / F ield | O penF OAM : The Open Sour ce CFD T oolbox |
| \\ / O p er at ion | V er sion : 2.1. x |
| \\ / A nd | Web : ww w . Op en FO AM . org |
| \\/ M anip ula tion | |
\*---------------------------------------------------------------------------*/
Bui ld : 2. 1. x -6 e 8 9b a 0b c d1 5
Exec : ico Foam
Listing 70: Run icoFoam without the -parallel parameter
Pitfall: domain decomposition
If there was no domain decompositin prior to starting a parallel simulation, OpenFOAM will issue an corre-
sponding error message.
II This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 45
[0] --> FOAM FATAL ERROR :
[0] t wo Ph as eEu le rFo am : can not op en case dir ec to ry "/ home / u ser / Op en FO AM / user - 2.1. x / run /
two Ph as eEul erF oa m / te stC olum n / proce sso r0 "
[0]
[0] FOAM p arallel run exiting
Listing 71: Missing domain decomposition
Pitfall: domain resonstruction
After a parallel simulation has ended, all data is residing in the processor* folders. If paraView is started –
without prior domain reconstruction – paraView will only find the data of the 0 directory.
10.5.2 Domain decomposition
Before a parallel simulation can be started the domain has to be decomposed into the correct number of
subdomains – one for each parallel process. The parallel processes calculate on their own subdomain and
exchange data of the border regions at the end of each time step. This is also the reason why the parallel
processes have to be synchonous. Otherwise, processes with a lower computational load would overtake other
processes and they would exchange data from different times.
Just before starting the simulation the domain has to be decomposed. The tool decompsePar is used for
this purpose. Other operations, e.g. initialising fields using setFields have to take place before the domain
decomposition. decomposePar reads from decomposeParDict in the system directory. This file has to contain
al least the number of subdomains and the decomposition method.
decomposePar creates the processor* directories in the case directory. Inside the processor* folders a 0and
aconstant folder are created. The 0folder contains the initial and boundary conditions of the subdomain and
the constant folder contains a polyMesh folder containing the mesh of the subdomain.
All parallel processes read from the same system directory, as the information stored there is not affected
by the domain decomposition. Also the files in the constant directory are not altered.
Pitfall: Existing decomposition
If the domain has already been decomposed and decomposePar is called again, e.g. because the number of
subdomains has been changed or some fields have been reinitialised, OpenFOAM issues an error message.
Listing 72 shows an example. In this case the domain has already been decomposed into 2 subdomains and the
attempt is made to decompose it again. OpenFOAM always issues an error message, whether the number of
subdomains has changes or not.
The resulting error message proposes two possible solutions. The first is to invoke decomposePar with the
-force option to make decomposePar remove the processor* folders before doing its job. The second proposed
solution is to manually remove the processor* folders. In this case the error message contains the proper com-
mand to do so. The user can retype the command or copy and paste it into the Terminal.
--> F OA M F AT AL ER RO R : C ase is a lre ad y d eco mp o se d w ith 2 d omain s , u se th e - f or ce o pt io n or
manually
remove processor d ire cto ries bef ore decompo sin g . e .g.,
rm -rf / home / user / Ope nF OA M / user -2.1 . x/ run / ico Foam / c avit y / pr oc es so r *
Listing 72: Already decomposed domain
Time management with decomposePar
In the course of an update of OpenFOAM decompose gained the option -time. This enhancement took place
between the release of OpenFOAM 2.1.0 and OpenFOAM 2.1.1. Such enhancements typically first appear in
the respository release OpenFOAM 2.1.x. So, it may be, that some installations of OpenFOAM 2.1.x contain
this feature and some not depending on the time of installation or the time of the last update.
The option time lets the user specify a time from which or a time range in which the domain is to be
decomposed. Listing 73 shows some examples of how this option works.
II This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 46
The option -latestTime makes decomposePar use the latest time step as starting time step for the subdo-
mains.
use r@host :∼/ O penFOAM / user -2. 1. x/ run / ico Foam / c avit y$ ls
0 0.1 0.2 con stant probes1 processor0 p roc ess or1 p roc essor2 system
use r@host :∼/ O pe nF OA M / user -2 .1. x/ run / i co Fo am / cav it y$ de com po seP ar -time 0 .1 :0 .2 - f orce > / dev /
null
use r@host :∼/ O penFOAM / user -2. 1. x/ run / ico Foam / c avit y$ ls pr ocessor0
0.1 0.2 co nst ant
use r@host :∼/ O pe nF OA M / user -2 .1. x/ run / i co Fo am / cav it y$ de com po seP ar -time 0.2 - f orce > / dev / null
use r@host :∼/ O penFOAM / user -2. 1. x/ run / ico Foam / c avit y$ ls pr ocessor0
0.2 co nst ant
use r@host :∼/ O penFOAM / user -2. 1. x/ run / ico Foam / c avit y$
Listing 73: Time management with decomposePar
10.5.3 Domain reconstruction
To be able to look at the results the data has to be reassembled again. This job is done by reconstructPar. This
tool collects all data of the processor* folders and reconstructs the original domain using all the generated time
step data. After reconstructPar has finished the data of the whole domain resides in the case directory and the
data of the subdomains resides in the processor* folders.
Listing 74 shows the content of the case directory after a parallel simulation has finished. The first command
is a simple call of ls to display the contents of the case directory. This is not different from the situation before
the parallel simulation was started with the exception of the log file. However, this log file could be from a
previous run. So, listing the contents after a parallel simulation has finished carries no real information.
The second command lists the contents of the processor0 directory. In this directory – as well as in all other
processor* folders – there is time step data. The third command reconstructs the domain. After this tool has
finished, the case directory also contains time step data. The last command lists the contents of the processor0
folder again. This data has not been removed. So, a finished parallel case stores its time step data twice and
therefore uses a lot of space.
use r@host :∼/ O penFOAM / user -2. 1. x/ run / ico Foam / c avit y$ ls
0 co nstant foa mRun . log probe s1 proce sso r0 pr oce sso r1 processor 2 pro ces sor 3 syste m
use r@host :∼/ O penFOAM / user -2. 1. x/ run / ico Foam / c avit y$ ls pr ocessor0
0 0.1 0.2 0.3 0.4 0.5 co nst ant
use r@host :∼/ O pe nF OA M / user -2 .1. x/ run / i co Fo am / cav it y$ rec on str uc tPa r > f oa mRe co nst ru ct . lo g &
[1] 26269
use r@host :∼/ O penFOAM / user -2. 1. x/ run / ico Foam / c avit y$ ls
0 0.1 0.2 0.3 0.4 0.5 co nst ant foa mRec onst ruc t . log f oamRun . log pro bes1 p roc essor0
pro ces sor 1 pro cessor2 proc ess or3 sys tem
[1 ]+ F er ti g rec ons tr uct Par > f oa mR eco nst ru ct . lo g
use r@host :∼/ O penFOAM / user -2. 1. x/ run / ico Foam / c avit y$ ls pr ocessor0
0 0.1 0.2 0.3 0.4 0.5 co nst ant
use r@host :∼/ O penFOAM / user -2. 1. x/ run / ico Foam / c avit y$
Listing 74: A finished parallel simulation
Time management
If a simulation has been startet from t=t1the domain has to be reconstructed for times t>t1. Calling re-
constructPar without any options regarding time, the program starts reconstructing the domain at the earliest
time. To prevent the tool from reconstructing already reconstructed time steps the -time option can be used.
Listing 75 shows how simulation results are reconstructed for t≤60 s.
r ec o ns t ru c tP a r - ti me 6 0:
Listing 75: Zeitparameter für reconstructPar
Another option to reconstruct only the new time steps is the command line option -newTimes. By using
this option the proper time span to reconstruct is automatically determined.
II This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 47
10.5.4 Run large studies on computing clusters
Simulating parallel on a machine brings some advantages and enables the user to run even large simulations
on a workstation. However, if the cases is very large, or parametric studies are to be conducted, using the
workstation can be counter productive. Therefore, simulating on a computing cluster is the method of choice
for large scale calculations. The user can follow a two step method.
1. Set up the case and run some test simulations, e.g. for a small number of time steps, on the workstation
to ensure the simulation runs
2. Do the actual simulation on the cluster
The fact, that OpenFOAM runs on a great number of platforms enables the user to do simulations on the
workstation as well as on a big cluster with tens or hundreds of processors.
Run OpenFOAM using a script
Section 57.5 explaines how to set up a script that runs multiple cases.
10.6 Using tools
OpenFOAM consists besides of solvers of a great collection of tools. These tools are used for all kind of
operations.
All solvers and tools of OpenFOAM24 assume that they are called from the case directory. If an executable
is to be called from another directory the path to the case diretory has to be specified. Then the option -case
has to be used to specify this path.
Listing 76 shows the error message displayed by the tool fluentMeshToFoam as it was executed from the
polyMesh directory. The tool added the relative path system/controlDict to the currect working directory.
This resulted in an invalid path to controlDict as the error message tells the user. Actually, the error message
states that the file could not be found. This does not solely imply an invalid path. The file could simply be
missing.
--> FOAM FATAL IO ERROR :
cannot find f ile
fi le : / home / user / O pe nF OAM / user -2 .1. x/ run / i coFo am / t estC as e / con stan t / pol yM esh / syste m / con tr ol Di ct
at line 0.
From fu nct ion reg IOo bje ct :: readStream ()
in file db / reg IOobj ect / r eg IOobj ec tRead . C at line 73.
FOAM exiting
Listing 76: Wrong path
The correct usage of the -case option is shown in Listung 77. There the correct path to the case directory
– two levels upwards – is specified using ../...25
use r@host :∼/ O penF OAM / user -2.1. x/run / icoFo am / tes tCase / con stan t / po lyMe sh$ fl ue nt 3DMes hT oF oa m -
ca se . ./ .. c ase Me sh . m sh
Listing 77: Specify the correct path to the case
24No exeption known to the author.
25On most Linux or Unix systems .refers to the current directory and .. refers to the directory above the current one. To
change in the Terminal one directory upwards on Linux cd .. does the job and on MS-DOS or Windows cd.. is the proper
command.
Also, on Linux systems the tilda refers to the home directory of the current user.
II This offering is not approved or endorsed by ESI®Group, ESI-OpenCFD®or the OpenFOAM®
Foundation, the producer of the OpenFOAM®software and owner of the OpenFOAM®trademark. 48