View source for Installation/Working with the Shell


= 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!

== 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: [http://linuxcommand.org/lc3_learning_the_shell.php 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:
** {{tt|Ctrl+Shift+C}} - Copy selection from the terminal/console window.
** {{tt|Ctrl+Shift+V}} - Paste what's on the [http://en.wikipedia.org/wiki/Clipboard_%28computing%29 clipboard memory], to the terminal's shell.
** {{tt|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 [http://en.wikipedia.org/wiki/POSIX POSIX] Operating Systems are case-sensitive! This means that, for example, the following two commands are considered different:
** {{tt|icoFoam}} - this command exists when OpenFOAM is properly installed.
** {{tt|icoFOAM}} - this doesn't exist... at least not on a ''normal'' installation of OpenFOAM.

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

=== 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:
<ol>
<li>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:
<bash>MY_VARIABLE=A sentence or path to something or even a value
X=1
y=2
MY_OTHER_HOME=/home/school</bash></li>
<li>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:
<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</bash></li>
</ol>

You can see and use these variables in the following ways:
; {{tt|echo $MY_OTHER_HOME}}
: This shows you what the variable {{tt|MY_OTHER_HOME}} contains.
; {{tt|ls -l $MY_OTHER_HOME}}
: This shows the folder contents of the path defined in that variable, assuming said path exists.
; {{tt|cd $MY_OTHER_HOME}}
: This will change directory to that path you've just checked.

=== Variable related commands ===
There are a few more commands you should learn to understand how manipulate and make use of these variables:
; {{tt|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 '''{{tt|.}}''' which does basically the same, but it's only accessible on some shells. For example, the following two commands are identical on {{tt|bash}}:
<bash>source ~/OpenFOAM/OpenFOAM-2.1.1/etc/bashrc
. ~/OpenFOAM/OpenFOAM-2.1.1/etc/bashrc</bash>

; {{tt|env}}
: This command is a quick way to see what variables currently are defined in the current shell environment. The {{tt|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: <bash>man env</bash>

; {{tt|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.

; {{tt|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 {{tt|ll}}, which is in reality can be an alias for: <bash>ls -l</bash>
: Here are a few more examples:
:* To see the currently defined aliases: <bash>alias</bash>
:* To see the alias currently defined for {{tt|ll}}: <bash>alias ll</bash>
:* To define an alias for ''sourcing''/''activating'' OpenFOAM's 2.1.1 shell environment: <bash>source of211='source ~/OpenFOAM/OpenFOAM-2.1.1/etc/bashrc'</bash>
:* You can also use quotes instead of apostrophes and use the {{tt|HOME}} variable: <bash>source of211="source $HOME/OpenFOAM/OpenFOAM-2.1.1/etc/bashrc"</bash>

= OpenFOAM Environment Variables =

Now it's time to put into practice what you learned in the section [[#Learning how to manipulate the environment|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 {{tt|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:
<bash>source $HOME/OpenFOAM/OpenFOAM-2.2.2/etc/bashrc</bash>
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:
<bash>env
export</bash>
If you already have a working OpenFOAM environment, you should see these variables among the output from the above commands:
<bash>WM_PROJECT_DIR
FOAM_APPBIN</bash>
Try the following commands if you can't seem them clearly:
* If {{tt|env}} worked: <bash>env | grep WM_PROJECT_DIR</bash>
* If {{tt|export}} worked: <bash>export | grep WM_PROJECT_DIR</bash>

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 {{tt|WM_}} and {{tt|FOAM_}} are usually related to OpenFOAM. If you want to see the content of one of those variables, for example {{tt|WM_PROJECT_DIR}}, then run:
<bash>echo $WM_PROJECT_DIR</bash>
In case it points to a file or folder, you can see what it has or even to go into it:
<bash>ls -l $WM_PROJECT_DIR
cd $WM_PROJECT_DIR</bash>

== OpenFOAM's own alias commands ==
As already partially addressed in section [[#Variable related commands|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 {{tt|$WM_PROJECT_DIR/etc/aliases.sh}}. You can see which ones they are by either looking into that file or by simply running:
<bash>alias</bash>
If you need to know what a specific {{tt|alias}} command stands for, simply indicate which one you're asking about. For example, to see what {{tt|foam}} is associated to, run:
<bash>alias foam</bash>
It should give you this:
<bash>alias foam='cd $WM_PROJECT_DIR'</bash>

== Using aliases to help manage multiple OpenFOAM versions ==
Usually, when you follow the official installation instructions, it usually tells you to do [http://openfoam.org/download/2-2-1-ubuntu/#user-configuration something like this]:
: In order to use the installed OpenFOAM package, complete the following
:# Open the {{tt|.bashrc}} file in the user’s home directory in an editor, e.g. by typing in a terminal window (note the dot) <bash>gedit ~/.bashrc</bash>
:# At the bottom of that file, add the following line (see '''Note 1''') and save the file <bash>source /opt/openfoam221/etc/bashrc</bash>
:# Open a '''new''' terminal window (see '''Note 2''') and test that the {{tt|icoFoam}} application, from the OpenFOAM package, is working by typing <bash>icoFoam -help</bash>
:# 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 {{tt|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 {{tt|/opt}} and which to install foam-extend 3.0 at {{tt|$HOME/foam/}}, then you can change the current line you have in your {{tt|~/.bashrc}} file (remember, it's the same as {{tt|$HOME/.bashrc}}), from this:
<bash>source /opt/openfoam221/etc/bashrc</bash>
To this:
<bash>alias of221='source /opt/openfoam221/etc/bashrc'
alias fe30='source $HOME/foam/foam-extend-3.0/etc/bashrc'</bash>
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 {{tt|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: <bash>of221</bash>
* To activate the foam-extend 3.0 environment, run: <bash>fe30</bash>

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|Unloading the shell environment]].

=== Unable to change the shell environment until I log-out ===
Some Linux Distributions will source the contents of the file {{tt|~/.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 {{tt|~/.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: <bash>echo $WM_PROJECT_DIR</bash>

=== Cheat sheet of alias commands for OpenFOAM environments ===
Feel free to add to this list:
<ul>
<li>For when you have everything in your home folder:
<bash>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'
</bash>
</li>

<li>For OpenFOAM versions installed in the {{tt|/opt}} folder:
<bash>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'
</bash>
</li>
</ul>

== Unloading the shell environment ==
{{versionInfo}}{{version2.0}}{{version2.1}}{{version2.2}}

As of OpenFOAM 2.0, it's possible to unload the OpenFOAM environment by simply running:
<bash>wmUNSET</bash>
This way you can load up another OpenFOAM shell environment, without having to start a new terminal.

= Advanced Topics =

== 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|How to easily change the installation folder]]
* [[#Using the in-line variable settings|Using the in-line variable settings]]
* [[#Using preference files|Using preference files]]

=== How to easily change the installation folder ===
This is briefly explained in the official installation instructions, for example, quoting from section [http://openfoam.org/download/2-2-1-source/ Setting environment variables for alternative locations for OpenFOAM 2.2.1 at openfoam.org]:
<blockquote><bash>export FOAM_INST_DIR=/data/app/OpenFOAM
foamDotFile=$FOAM_INST_DIR/OpenFOAM-2.2.1/etc/bashrc
[ -f $foamDotFile ] && . $foamDotFile </bash></blockquote>
That is a convoluted way of simply running:
<bash>export FOAM_INST_DIR=/data/app/OpenFOAM
. $FOAM_INST_DIR/OpenFOAM-2.2.1/etc/bashrc</bash>
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 {{tt|FOAM_INST_DIR}} to take care of telling OpenFOAM's {{tt|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:
<bash>alias of211='source ~/OpenFOAM/OpenFOAM-2.2.1/etc/bashrc'</bash>
For example for having the main installation folder at {{tt|/usr/local/OpenFOAM}}, to this:
<bash>alias of211='export FOAM_INST_DIR=/usr/local/OpenFOAM; source $FOAM_INST_DIR/OpenFOAM-2.2.1/etc/bashrc'</bash>

=== Using the in-line variable settings ===
{{versionInfo}}{{version2.0}}{{version2.1}}{{version2.2}}

Also introduced with OpenFOAM 2.0, is the possibility to change default options in-line with the ''sourcing'' of the file {{tt|etc/bashrc}}. It's not applicable to all variables (e.g. {{tt|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 [[Installation/Linux/OpenFOAM-2.1.1/Ubuntu#Ubuntu_12.10|OpenFOAM 2.1.1 on Ubuntu 12.10]], where these command lines are provided:
<bash>#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</bash>
Well, the last line is a bit more cryptic, since the {{tt|echo}} command is appending to the file {{tt|$HOME/.bashrc}} the alias command we want to add to it. But the important details to take from this are:
# These variables: <bash>WM_NCOMPPROCS=4 WM_MPLIB=SYSTEMOPENMPI WM_ARCH_OPTION=32</bash> were defined directly into the sourcing command, without the need to edit any file.
# The variable {{tt|FOAM_SETTINGS}} is where OpenFOAM's {{tt|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.

=== Using preference files ===
{{versionInfo}}{{version1.7}}{{version2.0}}{{version2.1}}{{version2.2}}{{version1.6-ext}}{{version3.0-ext}}

Similarly to [[#Using the in-line variable settings|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 {{tt|etc/bashrc}} file. The default file name is {{tt|prefs.sh}} and is searched for in the following preference order (exemplified for OpenFOAM 2.2.2):
# {{tt|$HOME/.OpenFOAM/2.2.2/prefs.sh}}
# {{tt|$HOME/.OpenFOAM/prefs.sh}}
# {{tt|$HOME/OpenFOAM/site/2.2.2/prefs.sh}}
# {{tt|$HOME/OpenFOAM/site/prefs.sh}}
# {{tt|$HOME/OpenFOAM/OpenFOAM-2.2.2/etc/prefs.sh}}

This path list is provided by OpenFOAM's shell script {{tt|foamEtcFile}}:
<bash>foamEtcFile -list</bash>

You can find examples for the {{tt|prefs.sh}} file in OpenFOAM's {{tt|etc}} folder. For example, at the following locations:
* {{version1.7}} [https://github.com/OpenCFD/OpenFOAM-1.7.x/blob/master/etc/prefs.sh-EXAMPLE etc/prefs.sh-EXAMPLE]
* {{version2.0}} [https://github.com/OpenFOAM/OpenFOAM-2.0.x/blob/master/etc/config/example/prefs.sh etc/config/example/prefs.sh]
* {{version2.1}} [https://github.com/OpenFOAM/OpenFOAM-2.1.x/blob/master/etc/config/example/prefs.sh etc/config/example/prefs.sh]
* {{version2.2}} [https://github.com/OpenFOAM/OpenFOAM-2.2.x/blob/master/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|Using the in-line variable settings]]; for example, if you have the file {{tt|$HOME/.OpenFOAM/2.2.2/prefs-32.sh}}, then you can source the OpenFOAM environment like this:
<bash>source $HOME/OpenFOAM/OpenFOAM-2.2.2/etc/bashrc prefs-32.sh</bash>

== 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 {{tt|tutorials}} folder: <bash>find $FOAM_TUTORIALS -name "*Dict"</bash>
* Finding all dictionary files that end with "Dict" in the {{tt|applications}} folder: <bash>find $FOAM_APP -name "*Dict"</bash>
* Finding which tutorial files use the boundary condition "slip": <bash>find $FOAM_TUTORIALS -type f | xargs grep -sl 'slip'</bash> More on this topic in the section [[#How to learn new searching strategies|How to learn new searching strategies]]
* Find where the code for the boundary condition "slip" is located: <bash>find $FOAM_SRC -name "*slip*"</bash>

=== How to learn new searching strategies ===
In Linux (or any [http://en.wikipedia.org/wiki/POSIX POSIX] systems), when in doubt about some commands, simply type {{tt|man}} and the command. Although some other commands might be part of the shell, so in those cases, you'll probably have to {{tt|man bash}} in case bash is the shell being used. For more about the ''man pages'', read the [http://en.wikipedia.org/wiki/Man_page Wikipedia article].

Searching online with the same commands will also give you an online version of each command, e.g.:
* [http://unixhelp.ed.ac.uk/CGI/man-cgi?xargs xargs]
* [http://unixhelp.ed.ac.uk/CGI/man-cgi?grep grep]
* [http://unixhelp.ed.ac.uk/CGI/man-cgi?find 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: [http://www.liamdelahunty.com/tips/linux_find_string_files.php Linux - Find string in files]

In addition, on Wikipedia is also shown some use scenarios for find/xargs/grep: [http://en.wikipedia.org/wiki/Xargs Xargs at Wikipedia]

=== Using <tt>foamSearch</tt> ===

{{versionInfo}}{{version4}}

{{tt|foamSearch}} was introduced in [http://openfoam.org/release/4-0/#case-management OpenFOAM 4.0] and is explained starting from [http://cfd.direct/openfoam/user-guide/fvschemes/ 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 {{tt|find/xargs/grep}} combo.

Example from the OpenFOAM User Guide [http://cfd.direct/openfoam/user-guide/fvschemes/ section 4.4]:
<bash>foamSearch $FOAM_TUTORIALS ddtSchemes.default fvSchemes</bash>

[[Category:Installing OpenFOAM - Other Details]]