1 Introduction

This page attempts to introduce the reader to getting to know what a shell is and how said shells work in terminals or consoles.

On a second part, introduces the reader to getting to know how to use OpenFOAM in said shells.

The text may seem rather informal, so feel free to improve this wiki page!

1.1 Learning how to use a shell

Well, this section will seem to be rather lazy to you, but it's best to point the reader to one of the best tutorials there is on this subject, namely: Learning the shell

There you'll learn all of the necessary basics on how to use the shell to your benefit. Additionally, here are a few more essential hints:

Today's terminal/consoles used in modern Linux Distributions have interactive mouse and keyboard controls. You can find out which are they by checking the menus on them, as well as learning from there some of the keyboard shortcuts you can use.

Shift+Insert - Same as the previous command, namely it pastes what's on the clipboard.

Do not forget that the shell environment on Linux and other POSIX Operating Systems are case-sensitive! This means that, for example, the following two commands are considered different:

icoFoam - this command exists when OpenFOAM is properly installed.

icoFOAM - this doesn't exist... at least not on a normal installation of OpenFOAM.

1.2 Learning how to manipulate the environment

In this section the objective is to understand how the shell environment works. This is a necessary learning step for understanding how you can take advantage of OpenFOAM's way of interacting with the shell.

1.2.1 Setting and using variables

In essence, the shell environment is a memory space where variables are defined, so that programs know where they are working and what they can or even should do. These variables can be defined in two ways:

Mainly for local usage, which they are visible only for the current shell environment. In other words, the variable won't be shared with a script or application you run the the current shell. Examples:

MY_VARIABLE=A sentence or path to something or even a value
X=1y=2MY_OTHER_HOME=/home/school

For global usage, but only in the sense that all applications launched from this shell will henceforth know that said variable has got that particular value assigned. This is the main type of shell variables used by OpenFOAM. Examples on bash:

MY_VARIABLE=A sentence or path to something or even a value
export MY_VARIABLE
exportX=1exporty=2exportMY_OTHER_HOME=/home/school

You can see and use these variables in the following ways:

echo $MY_OTHER_HOME

This shows you what the variable MY_OTHER_HOME contains.

ls -l $MY_OTHER_HOME

This shows the folder contents of the path defined in that variable, assuming said path exists.

cd $MY_OTHER_HOME

This will change directory to that path you've just checked.

1.2.2 Variable related commands

There are a few more commands you should learn to understand how manipulate and make use of these variables:

source

This command runs a script as if you were typing the commands yourself directly on the current shell environment. Another name for this specific command is the dot/period symbol . which does basically the same, but it's only accessible on some shells. For example, the following two commands are identical on bash:

This command is a quick way to see what variables currently are defined in the current shell environment. The env command can do a lot more than this, but that's for you to later study for yourself which you can check by running:

man env

export

As already shown in examples above, this defines a shell variable as globally seen on the current shell. When executed alone, it shows what variables have been exported and are available.

alias

This is for another type of variable: the aliases. It gives the ability to define short commands that execute longer commands you usually use. A very simple and usual example available in modern Linux Distributions is the alias ll, which is in reality can be an alias for:

ls -l

Here are a few more examples:

To see the currently defined aliases:

alias

To see the alias currently defined for ll:

alias ll

To define an alias for sourcing/activating OpenFOAM's 2.1.1 shell environment:

sourceof211='source ~/OpenFOAM/OpenFOAM-2.1.1/etc/bashrc'

You can also use quotes instead of apostrophes and use the HOME variable:

sourceof211="source $HOME/OpenFOAM/OpenFOAM-2.1.1/etc/bashrc"

2 OpenFOAM Environment Variables

The OpenFOAM shell environment is basically the normal shell environment that you usually get when you finish installing your favourite Linux Distribution, but with a lot of new shell environment variables that are associated to OpenFOAM. These new OpenFOAM related shell variables are only available after you have sourced the etc/bashrc script that OpenFOAM has got. For example, if you have OpenFOAM 2.2.2 installed in your personal folder according to the official instructions, then only after you run this command:

source$HOME/OpenFOAM/OpenFOAM-2.2.2/etc/bashrc

will you have the OpenFOAM shell environment activated!

Once the OpenFOAM environment is activated, to know which variables exist on your current shell, try running one of these commands:

env
export

If you already have a working OpenFOAM environment, you should see these variables among the output from the above commands:

WM_PROJECT_DIR
FOAM_APPBIN

Try the following commands if you can't seem them clearly:

If env worked:

env | grep WM_PROJECT_DIR

If export worked:

export | grep WM_PROJECT_DIR

So, from all of the variables that are loaded onto the shell environment, how to tell apart those that are from/for OpenFOAM? Usually the ones started with WM_ and FOAM_ are usually related to OpenFOAM. If you want to see the content of one of those variables, for example WM_PROJECT_DIR, then run:

echo$WM_PROJECT_DIR

In case it points to a file or folder, you can see what it has or even to go into it:

ls -l $WM_PROJECT_DIRcd$WM_PROJECT_DIR

2.1 OpenFOAM's own alias commands

As already partially addressed in section Variable related commands, there is another side to the shell environment: the aliases. Read that section again to review what they are meant for.

OpenFOAM provides several alias commands which can come in handy, which are automatically loaded into the shell environment from the file $WM_PROJECT_DIR/etc/aliases.sh. You can see which ones they are by either looking into that file or by simply running:

alias

If you need to know what a specific alias command stands for, simply indicate which one you're asking about. For example, to see what foam is associated to, run:

alias foam

It should give you this:

aliasfoam='cd $WM_PROJECT_DIR'

2.2 Using aliases to help manage multiple OpenFOAM versions

Usually, when you follow the official installation instructions, it usually tells you to do something like this:

In order to use the installed OpenFOAM package, complete the following

Open the .bashrc file in the user’s home directory in an editor, e.g. by typing in a terminal window (note the dot)

gedit ~/.bashrc

At the bottom of that file, add the following line (see Note 1) and save the file

source /opt/openfoam221/etc/bashrc

Open a new terminal window (see Note 2) and test that the icoFoam application, from the OpenFOAM package, is working by typing

icoFoam -help

A “Usage” message should appear. Your installation and user configuration is complete.

The problem is that this will constrain your machine to a single OpenFOAM installation. The most common way to go around this is to rely on alias created commands that help you choose which OpenFOAM environment you want to use. For example, if you have OpenFOAM 2.2.1 installed in /opt and which to install foam-extend 3.0 at $HOME/foam/, then you can change the current line you have in your ~/.bashrc file (remember, it's the same as $HOME/.bashrc), from this:

Save the file and start a new terminal. From now on, whenever you start a new terminal/console window or tab, the OpenFOAM environment is not available by default. You will have to run one of the alias created commands to activate the desired environment.

Therefore, start a new terminal and run one of the alias commands. Based on the example above:

To activate the OpenFOAM 2.2.1 environment, run:

of221

To activate the foam-extend 3.0 environment, run:

fe30

If all goes well, you now have on your terminal the ready to be used environment for the chosen OpenFOAM. This now means that whenever you need another version of OpenFOAM, you must start a new terminal! Unless of course, your current environment is for OpenFOAM 2.0 or above, as explained in the section Unloading the shell environment.

2.2.1 Unable to change the shell environment until I log-out

Some Linux Distributions will source the contents of the file ~/.bashrc when you graphically log-in. This means that until you log-out, the OpenFOAM shell environment will still be activated. To check if you need to log-out, it's simple:

After you've made the changes you wanted to the file ~/.bashrc, start a new terminal window.

Check if there are any OpenFOAM unwanted environment variables active. For example, the following command will not give you an empty line if the OpenFOAM shell environment is still active:

But the official instruction are more robust, since the code in-between will check if the file exists, before sourcing it.

The trick here is that we can rely on the environment variable FOAM_INST_DIR to take care of telling OpenFOAM's etc/bashrc file where to find that OpenFOAM is installed. If we wish to add this strategy to the alias methodology for having more than one OpenFOAM installation, it should be as simple as changing this:

aliasof211='source ~/OpenFOAM/OpenFOAM-2.2.1/etc/bashrc'

For example for having the main installation folder at /usr/local/OpenFOAM, to this:

3.1.2 Using the in-line variable settings

Valid versions:

Also introduced with OpenFOAM 2.0, is the possibility to change default options in-line with the sourcing of the file etc/bashrc. It's not applicable to all variables (e.g. FOAM_INST_DIR), but among many possible variables, it's possible to define the architecture, platform, optimization level and MPI setting to be used. One such example is present in the community installation instructions for OpenFOAM 2.1.1 on Ubuntu 12.10, where these command lines are provided:

#here you can change 4 to the number of cores you've gotsource$HOME/OpenFOAM/OpenFOAM-2.1.1/etc/bashrc WM_NCOMPPROCS=4WM_MPLIB=SYSTEMOPENMPI WM_ARCH_OPTION=32echo"alias of211='source \$HOME/OpenFOAM/OpenFOAM-2.1.1/etc/bashrc $FOAM_SETTINGS'" >> $HOME/.bashrc

Well, the last line is a bit more cryptic, since the echo command is appending to the file $HOME/.bashrc the alias command we want to add to it. But the important details to take from this are:

These variables:

WM_NCOMPPROCS=4WM_MPLIB=SYSTEMOPENMPI WM_ARCH_OPTION=32

were defined directly into the sourcing command, without the need to edit any file.

The variable FOAM_SETTINGS is where OpenFOAM's bashrc script saves the previous list of given variables.

Therefore, in a single line, it was possible to define that we wanted to:

Use the maximum of 4 parallel processes when building OpenFOAM (1 is the default);

Use the system's Open-MPI installation;

To build the 32-bit architecture of OpenFOAM.

3.1.3 Using preference files

Valid versions:

Similarly to Using the in-line variable settings, it's possible to define preference files to have written all of the options we want to use for the OpenFOAM shell environment, which will be initialized by OpenFOAM's etc/bashrc file. The default file name is prefs.sh and is searched for in the following preference order (exemplified for OpenFOAM 2.2.2):

$HOME/.OpenFOAM/2.2.2/prefs.sh

$HOME/.OpenFOAM/prefs.sh

$HOME/OpenFOAM/site/2.2.2/prefs.sh

$HOME/OpenFOAM/site/prefs.sh

$HOME/OpenFOAM/OpenFOAM-2.2.2/etc/prefs.sh

This path list is provided by OpenFOAM's shell script foamEtcFile:

foamEtcFile -list

You can find examples for the prefs.sh file in OpenFOAM's etc folder. For example, at the following locations:

Other names of this file can be used, as long as you use the same trick from the section Using the in-line variable settings; for example, if you have the file $HOME/.OpenFOAM/2.2.2/prefs-32.sh, then you can source the OpenFOAM environment like this:

source$HOME/OpenFOAM/OpenFOAM-2.2.2/etc/bashrc prefs-32.sh

3.2 Searching for files

It's very easy to find yourself very lost when you can't figure out what should be written inside a specific dictionary file. Fortunately, this can easily be overcome if you know some helpful tricks:

Finding all dictionary files that end with "Dict" in the tutorials folder:

find $FOAM_TUTORIALS -name "*Dict"

Finding all dictionary files that end with "Dict" in the applications folder:

3.2.1 How to learn new searching strategies

In Linux (or any POSIX systems), when in doubt about some commands, simply type man and the command. Although some other commands might be part of the shell, so in those cases, you'll probably have to man bash in case bash is the shell being used. For more about the man pages, read the Wikipedia article.

Searching online with the same commands will also give you an online version of each command, e.g.:

As for the long combo for searching (find+xargs+grep), it can be found after searching for this very specific reason: finding files that have a keyword, text or expression. One such example is given here: Linux - Find string in files

In addition, on Wikipedia is also shown some use scenarios for find/xargs/grep: Xargs at Wikipedia

3.2.2 Using foamSearch

Valid versions:

foamSearch was introduced in OpenFOAM 4.0 and is explained starting from section 4.4 on the OpenFOAM User Guide. It makes it a bit easier to search for entries on tutorial cases, because it doesn't require to memorize the whole find/xargs/grep combo.