Installation/Working with the Shell

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.
• Some examples of keyboard shortcuts:
  • Ctrl+Shift+C - Copy selection from the terminal/console window.
  • Ctrl+Shift+V - Paste what's on the clipboard memory, to the terminal's shell.
  • 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:

1. 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=1
   y=2
   MY_OTHER_HOME=/home/school

2. 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
    
   export X=1
   export y=2
   export MY_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:

source ~/OpenFOAM/OpenFOAM-2.1.1/etc/bashrc
. ~/OpenFOAM/OpenFOAM-2.1.1/etc/bashrc

env

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:

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

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

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

2 OpenFOAM Environment Variables

Now it's time to put into practice what you learned in the section Learning how to manipulate the environment and adapt to OpenFOAM's shell environment.

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_DIR
cd $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:

alias foam='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

1. 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

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

   source /opt/openfoam221/etc/bashrc

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

   icoFoam -help

4. 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:

source /opt/openfoam221/etc/bashrc

To this:

alias of221='source /opt/openfoam221/etc/bashrc'
alias fe30='source $HOME/foam/foam-extend-3.0/etc/bashrc'

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:

1. After you've made the changes you wanted to the file ~/.bashrc, start a new terminal window.
2. 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:

   echo $WM_PROJECT_DIR

2.2.2 Cheat sheet of alias commands for OpenFOAM environments

Feel free to add to this list:

• For when you have everything in your home folder:

  alias of15='. $HOME/OpenFOAM/OpenFOAM-1.5/etc/bashrc'
  alias of15x='. $HOME/OpenFOAM/OpenFOAM-1.5.x/etc/bashrc'
  alias of16='. $HOME/OpenFOAM/OpenFOAM-1.6/etc/bashrc'
  alias of16x='. $HOME/OpenFOAM/OpenFOAM-1.6.x/etc/bashrc'
  alias of170='. $HOME/OpenFOAM/OpenFOAM-1.7.0/etc/bashrc'
  alias of171='. $HOME/OpenFOAM/OpenFOAM-1.7.1/etc/bashrc'
  alias of17x='. $HOME/OpenFOAM/OpenFOAM-1.7.x/etc/bashrc'
  alias of200='. $HOME/OpenFOAM/OpenFOAM-2.0.0/etc/bashrc'
  alias of201='. $HOME/OpenFOAM/OpenFOAM-2.0.1/etc/bashrc'
  alias of20x='. $HOME/OpenFOAM/OpenFOAM-2.0.x/etc/bashrc'
  alias of210='. $HOME/OpenFOAM/OpenFOAM-2.1.0/etc/bashrc'
  alias of211='. $HOME/OpenFOAM/OpenFOAM-2.1.1/etc/bashrc'
  alias of21x='. $HOME/OpenFOAM/OpenFOAM-2.1.x/etc/bashrc'
  alias of220='. $HOME/OpenFOAM/OpenFOAM-2.2.0/etc/bashrc'
  alias of221='. $HOME/OpenFOAM/OpenFOAM-2.2.1/etc/bashrc'
  alias of222='. $HOME/OpenFOAM/OpenFOAM-2.2.2/etc/bashrc'
  alias of22x='. $HOME/OpenFOAM/OpenFOAM-2.2.x/etc/bashrc'
   
  alias of15dev='. $HOME/OpenFOAM/OpenFOAM-1.5-dev/etc/bashrc'
  alias of16ext='. $HOME/OpenFOAM/OpenFOAM-1.6-ext/etc/bashrc'
  alias fe30='. $HOME/foam/foem-extend-3.0/etc/bashrc'

• For OpenFOAM versions installed in the /opt folder:

  alias of170opt='. /opt/openfoam170/etc/bashrc'
  alias of171opt='. /opt/openfoam171/etc/bashrc'
  alias of200opt='. /opt/openfoam200/etc/bashrc'
  alias of201opt='. /opt/openfoam201/etc/bashrc'
  alias of210opt='. /opt/openfoam210/etc/bashrc'
  alias of211opt='. /opt/openfoam211/etc/bashrc'
  alias of220opt='. /opt/openfoam220/etc/bashrc'
  alias of221opt='. /opt/openfoam221/etc/bashrc'
  alias of222opt='. /opt/openfoam222/etc/bashrc'

2.3 Unloading the shell environment

Valid versions:

As of OpenFOAM 2.0, it's possible to unload the OpenFOAM environment by simply running:

wmUNSET

This way you can load up another OpenFOAM shell environment, without having to start a new terminal.

3 Advanced Topics

3.1 Advanced topics about the OpenFOAM shell environment

There are several important OpenFOAM shell topics, which can be considered as advanced:

• How to easily change the installation folder
• Using the in-line variable settings
• Using preference files

3.1.1 How to easily change the installation folder

This is briefly explained in the official installation instructions, for example, quoting from section Setting environment variables for alternative locations for OpenFOAM 2.2.1 at openfoam.org:

export FOAM_INST_DIR=/data/app/OpenFOAM
foamDotFile=$FOAM_INST_DIR/OpenFOAM-2.2.1/etc/bashrc
[ -f $foamDotFile ] && . $foamDotFile

That is a convoluted way of simply running:

export FOAM_INST_DIR=/data/app/OpenFOAM
. $FOAM_INST_DIR/OpenFOAM-2.2.1/etc/bashrc

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:

alias of211='source ~/OpenFOAM/OpenFOAM-2.2.1/etc/bashrc'

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

alias of211='export FOAM_INST_DIR=/usr/local/OpenFOAM; source $FOAM_INST_DIR/OpenFOAM-2.2.1/etc/bashrc'

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 got
source $HOME/OpenFOAM/OpenFOAM-2.1.1/etc/bashrc WM_NCOMPPROCS=4 WM_MPLIB=SYSTEMOPENMPI WM_ARCH_OPTION=32
 
echo "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:

1. These variables:

   WM_NCOMPPROCS=4 WM_MPLIB=SYSTEMOPENMPI WM_ARCH_OPTION=32

   were defined directly into the sourcing command, without the need to edit any file.
2. 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:

1. Use the maximum of 4 parallel processes when building OpenFOAM (1 is the default);
2. Use the system's Open-MPI installation;
3. 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):

1. $HOME/.OpenFOAM/2.2.2/prefs.sh
2. $HOME/.OpenFOAM/prefs.sh
3. $HOME/OpenFOAM/site/2.2.2/prefs.sh
4. $HOME/OpenFOAM/site/prefs.sh
5. $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:

• etc/prefs.sh-EXAMPLE
• etc/config/example/prefs.sh
• etc/config/example/prefs.sh
• etc/config/example/prefs.sh

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:

  find $FOAM_APP -name "*Dict"

• Finding which tutorial files use the boundary condition "slip":

  find $FOAM_TUTORIALS -type f | xargs grep -sl 'slip'

  More on this topic in the section How to learn new searching strategies
• Find where the code for the boundary condition "slip" is located:

  find $FOAM_SRC -name "*slip*"

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.:

• xargs
• grep
• find

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.

Example from the OpenFOAM User Guide section 4.4:

foamSearch $FOAM_TUTORIALS ddtSchemes.default fvSchemes