Tutorials/Before Getting Started

From OpenFOAMWiki

1 Introduction

Actually, this is more of a disclaimer than an introduction, because:

  1. This page aims to give you, the reader, a good sense of direction when it comes to using OpenFOAM technology.
  2. This page will not explain any specific details about how to use OpenFOAM and any Forks and Variants is has (which is why we'll refer to it as OpenFOAM technology).
  3. This page is an attempt at making you, the reader, better prepared on how to get started on using OpenFOAM technology.


Requirements before you continue reading this page (feel free to skip this at your own risk):

  1. Be aware that OpenFOAM technology is open and free as a technology and as in freedom, as described by the Free Software Foundation: What is free software?
    • This does not mean that it's cost-free. The primary cost associated to using OpenFOAM technology is Time... and since time is money, that's where its real costs reside.
  2. OpenFOAM and any and all of its variants and forks are bound by the GNU General Public License. It's advisable that you get a bit familiar with what this allows you to do or not, as described here: Frequently Asked Questions about the GNU Licenses
  3. OPENFOAM® is a trade mark. So much that you'll see this very often:
    This offering is not approved or endorsed by OpenCFD Limited, the producer of the OpenFOAM software and owner of the OPENFOAM® and OpenCFD® trade marks.
  4. Be prepared to read a lot of information!


Last but not least: Feel free to update this wiki page with new information!


2 Names and References

The following are the primary references when it comes to OpenFOAM technology:

Beyond this, there are several forks and variants, which are documented here: Forks and Variants - including the details on what a fork and variant is in this context.


3 State of Mind

Looks like a weird section name, isn't it? Well, this is because OpenFOAM technology defies the currently traditional mind set of most software users.

You're probably more familiar with friendly and forgiving Graphical User Interfaces (GUI), with varying degrees of friendliness. And you possibly want to use OpenFOAM technology in Windows or Mac OS X. Well, if you're looking for any or all of those, then have a look at the following wiki pages:


This is because the primary target Operating System for OpenFOAM is Linux and there is no official GUI. The reasons for this are explained here:


But even if you find a good GUI, sooner or later you will need to have the following state of mind when it comes to using OpenFOAM technology:

  1. First of all, do not think about this as being too hard or too complex. But it can (and it will) take a considerable amount of time to get to know it well enough.
  2. Complexity is in the eye of the beholder - This to say that you should never - not ever - try to solve your final problem directly... at least not until you've gained enough experience.
    • And experience can only be gained if you start with one or more very simple example cases and then gradually add complexity, one detail at a time.
  3. Do not speed through any available instructions you can find. You should always carefully read and study the available instructions when it comes to OpenFOAM technology and CFD.
  4. Every single detail matters more than you're likely willing to care about. This will be exemplified in the next section Common mistakes.
  5. Have a journal where you write down of what you've done, what errors you've made and how you've fixed them. Sooner or later, you'll repeat those same errors and/or have to reproduce the same results.
  6. Keep in mind that Computational Fluid Dynamics (CFD) and OpenFOAM technology are tools of science and mathematics, through the use of digital/computational power. In other words:
    • Science: You should always keep in mind that what you're using and doing needs to be validated whenever possible. More details in section Verify/validate your results.
    • Mathematics: CFD relies on tons of mathematics, specially computational mathematics. More details in section Mathematical constraints
    • Computational power: RAM, disk space, numerical precision, and so on. These limitations will dictate what you can or cannot do with CFD and OpenFOAM technology. More details in section Computational limitations.


3.1 Common mistakes

When it comes to mathematics, science and computers, the smallest detail can be the difference between success and failure. When it comes to OpenFOAM, the following are some of the most common mistakes:

Forgetting about units
OpenFOAM mostly works in SI units. So make sure that:
  1. Your geometry should be in metre, or at least that the final mesh should be in metre.
  2. Check the units defined with the usual vector structure that OpenFOAM uses, e.g. [0 2 -2 0 0 0], which is usually defined for field files and for some parameters in dictionary files.
Punctuation in dictionary and field files to be read by OpenFOAM
OpenFOAM tries to keep things simple enough:
  • Space character is used as a separator between values;
  • Semi-colons (;) are the standard line terminators for the definition of a particular value.
  • Brackets ({}) are the standard dictionary block delimiters.
  • Curved parenthesis (()) are the standard vector, matrix and list grouper.
  • Square parenthesis ([]) are usually for defining dimensions and units.

A somewhat group of examples of a bad definition of values in a dictionary files:

   type Fixed Value
   velocity 0, 2, 0;
   acceleration 0.2 m/s2;

The correct corresponding settings would be, for example:

   type fixedValue;
   velocity (0 2 0);
   acceleration [0  1 -2 0 0 0] 0.2;
Spaces in paths
OpenFOAM sort-of doesn't like names with spaces and that start with numbers. This is because the complexity of verifying the validity of such names would increase greatly and could reduce computational performance. For example:
  • Bad: /home/ofuser/Desktop/My very First test simulation
  • Good: /home/ofuser/Desktop/My1stTestSimulation
Letter case is extremely important
For example, Vector and vector are not the same word for OpenFOAM's dictionary parsing mechanism.


3.2 Verify/validate your results

One or more of the following are advisable:

  1. Whenever possible, you should always compare the case set-up you're using, with the results achieved for the same case in a real experimental environment.
  2. Always check if a group of settings works as intended. For example:
    1. Imagine you're testing new inlet boundary condition (i.e. one that you don't have experience with), for making the fluid flow from one inlet to another outlet, within a complex 10 metre pipe.
    2. Then you should first test with a small test case, such as a simple cube with 1 metre on each side, and check if the results are correct.
    3. This way you'll prove that the new boundary condition works as expected.
  3. Verify the results with a higher resolution mesh, to see how much the results will change. For more details on this, search for more details about this topic: Convergence and Mesh Independence Study.
  4. Models have limitations on the ranges of simulations where they can be used. For example, the turbulence models of the categories RANS, LES and DNS have all their own purposes, for simulating different scales of fluid interaction. Therefore, you should study, validate, verify and confirm, in order to be very well aware of how well your simulation represents the real/physical experiment.


3.3 Mathematical constraints

Here the details can get a bit weirder. CFD relies on numerical methods, which are applied to computational calculations, for solving the various equations that need to be solved. In addition, most methods used in CFD for solving fluid flow will rely on creating a discrete representation of the physical experiment you're trying to simulate.

Not very clear, was it? Then here is a simplified analogy: Digital Photography

  1. In digital photography we have to rely on pixels for representing our image.
  2. With each new generation of digital cameras, more resolution is possible for each individual picture, which means that more quality will have the final photo.
  3. If for each inch of length you have 10 pixels, then your image won't have much quality. For example, this is an image with only 31x36 pixel:
    Before getting started - example 00.png
  4. But if you have a resolution of 100 pixels per inch, you will get a lot more detail. But it depends on if your lens is able to provide that quality. For example:
    204x197 pixel picture, digitally scaled from the image 31x36 pixel.
    204x197 pixel picture, digitally scaled from an image of roughly 100x100 pixel.
  5. All 3 pictures are essentially the representation of the same object, with different resolutions and resulting quality.
  6. Try for yourself with image editing software to see what kinds of transformations you can do images and the resulting quality you get.


This is pretty much what the first paragraph of this section is trying to explain: the numerical methods to be used for modelling your simulation, also depend on the mesh resolution you have available and the quality you're aiming for, as well as any additional mathematical treatments are put into place to try and improve the quality of the resulting resolution. As for figuring out which one is the right one... well, that's an art akin to photography ;)


3.4 Computational limitations

All of the following details in a computer are important for achieving results when using CFD:

RAM
Acronym for Random Access Memory, is the main processing memory of your computer. This is where the CPU will be storing its intermediate calculations. How much RAM and how fast it is, will limit how many cells you mesh can have and how fast you can run the simulation.
CPU
Acronym for Central Processing Unit. Currently we're in the middle of a development phase in computer history where the CPUs are absorbing more and more features, such as:
  • Dedicated calculation units for multimedia operations (audio, video, encoding, network);
  • Dedicated calculation structures for vector mathematics (where blocks of vector can be operated explicitly in parallel);
  • Dedicated graphics processing units.
Anyway, aside from all of these neat futuristic features, what matters in the CPU is usually the top speed it can achieve with all of the cores in parallel, and how efficiently it can access the RAM. Essentially, this will dictate how fast you can perform simulations.
In addition to this, it also depends on how many bits your CPU can process in each cycle. The usual kinds of bit capacity are 32-bit and 64-bit processors.
Disk performance and dimensions
This is where you can permanently store the data, both initial settings, snapshots of intermediate results, as well as the final results. Therefore, it all depends on how much disk space your simulations will need and how frequently they will store data to disk.


Then there are the limitations of numerical precision, which usually sums up to this: Are you using single or double precision?

  • Single precision: also named 32-bit floating point values, which are roughly limited to 1e-38 to 1e38 and 8-9 decimal digits.
  • Double precision: also named 64-bit floating point values, which are roughly limited to 1e-308 to 1e308 and 14-16 decimal digits.

This essentially dictates the quality of the results, which might strongly depend on the kind of simulation you're performing. How can you know which one is better for you? Well, what did you read in the previous section Mathematical constraints, you should at least create a simple test case that represents your desired simulation and test using 32 or 64-bit.

Either way, people nowadays mostly use 64-bit floating point values, because it allows them to use today's 64-bit CPUs to the fullest, even if it requires twice as much memory as single precision. The benefit of using 32-bit would only come from a need to have results as fast if and as possible.


All of this information is for you to keep in mind that you should try to be fully aware of the limitations you're dealing with. Continuing the example given in the previous section Mathematical constraints, this is similar the limitations of digital photography are:

  • How much space you have in the SD card, for storing pictures.
  • How many pictures you need to take per second.
  • How much resolution do you need in each one of your pictures. In other words, what's the level of detail you need?
  • Can post-processing techniques help getting you acceptable photos, in case you cannot use the desired hardware?


4 How to get started with OpenFOAM

Learning how to use OpenFOAM is something that has to be done gradually, whether you like it or not.

There are essentially 3 ways you can learn about using OpenFOAM technology:

  1. Read/view and study anything and everything you can find about OpenFOAM technology.
  2. Subscribe and participate in one or more courses that teach how to use OpenFOAM technology.
  3. Experiment on your own.


As to where to actually start, follow the study concept given in the following subsections. And it's strongly advisable that you first check the whole list of steps, before starting with the very first step, since there might be some other way you prefer to get started.

Note: Even if you're already familiar with each level/topic, it's always good to come back and check what new stuff exists.


4.1 The first steps

The following are essentially part of the Rite of Passage of starting with OpenFOAM technology. This is because these are all of the basis you will need to get started with OpenFOAM. You might want to try and do some of these out of order, which you can, but you might find it a bit more difficult if you do so:

  1. Even before you try to install OpenFOAM, it's advisable that you first learn more about how to use the shell (also know as the command line interface), which is where this page tries to assist you: Installation/Working with the Shell
  2. You might also look into text editors, such as Gedit, Kate, Nedit, Nano, Vi/Vim, Emacs or any other text editor. This is because the text editor will be the second most important interface you'll need for using OpenFOAM.
  3. Install OpenFOAM or foam-extend or any other fork or variant (see the page OpenFOAM for more details). In a nutshell, the following are the main locations for installations instructions:
  4. While the installation is going on, familiarise yourself with the wiki page Frequently Asked Questions (or check the longer page version if you prefer everything in a single page).
    • There you'll find a lot of vital information that you'll eventually need, therefore it's good that you at least have the idea of some the frequent questions that are already answered there.
    • Those lists will gradually increase in size, as time progresses and people contribute to them.
  5. Once the installation is completed with success, start reading the User Guide, from one of the following locations:
    • Official OpenFOAM online page for the manuals and guides: OpenFOAM® Documentation - direct links to the OpenFOAM User Guide:
    • In your local OpenFOAM installation (or fork/variant) you can find it by running one of the following commands:
      • For OpenFOAM 3.0 and older (including OpenFOAM+ and foam-extend):
        echo $WM_PROJECT_DIR/doc/Guides-a4/UserGuide.pdf
      • For OpenFOAM 4 and newer:
        echo $WM_PROJECT_DIR/doc/Guides/OpenFOAMUserGuide-A4.pdf
  6. Feeling too lazy to continue reading? Then checkout this wiki page that has several videos on YouTube, that explain a lot about OpenFOAM: Tutorials/JozsefsYouTubeVideoTutorials
  7. More videos: Initiative taken by Indian Institute of Technology (IIT)
  8. Feeling like reading once again? Here's a detailed list of books and other material to read: 101 Things to read when starting with OpenFOAM by Sourceflux

4.2 Books that can teach you about OpenFOAM technology

This list is currently not sorted in any particular order:

4.3 Courses that teach about OpenFOAM technology

There are so many, that they've been placed in a dedicated page for them here: Main_Courses


4.4 Extending your knowledge

  1. First of all, have a very-very-Very good look at the front-page on this wiki: Main Page - there you'll see essentially everything you need for learning more about OpenFOAM technology. The information there is highly condensed, but very well organized. Consider it your daily training for keeping your attention to details as sharp as possible.
  2. The official OpenFOAM Programmer's Guide exists, but it isn't fully supported. Either way, it is continuing it's development at its own pace. You can find it at the following locations:
    • Online version: OpenFOAM Programmer's Guide at SF.net
    • The local version in your OpenFOAM installation can be found by running this command:
      echo $WM_PROJECT_DIR/doc/Guides-a4/ProgrammersGuide.pdf
  3. Community created wiki pages, aimed to complement the official guides: OpenFOAM_guide
  4. In the Handy links page you can find a link farm, where you can find several important sources of more information, including resources from existing open courses and workshops.
  5. Remember what was indicated in the chapter State of Mind, namely about keeping a journal? Well, go back again to the front-page on this wiki: Main Page - and start browsing the pages of each link you find. Take your own notes of what interests you. Keep in mind that this is extremely important when it comes to learning how to use OpenFOAM. For example, from there, here are some interesting core pages:


4.5 Blogs about OpenFOAM technology

These are not sorted in any particular order:


4.6 Screencasts for OpenFOAM - Build your own OpenFOAM project

In the following screencasts you will find an interesting OpenFOAM project generation from scratch. In addition tricks, tips and experience of Tobias Holzmann are given. The screencast is divided into nine different sub-topics that are also interesting for more advanced OpenFOAM users.