Revision as of 14:42, 1 January 2014

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:

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
```
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

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:

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

1 Introduction
- 1.1 Learning how to use a shell
- 1.2 Learning how to manipulate the environment
  - 1.2.1 Setting and using variables
  - 1.2.2 Variable related commands
2 OpenFOAM Environment Variables
3 Advanced Topics
- 3.1 Advanced topics about the OpenFOAM shell environment
  - 3.1.1 How to easily change the installation folder
  - 3.1.2 Using the in-line variable settings
- 3.2 Searching for files

3.1.1 How to easily change the installation folder

TODO

3.1.2 Using the in-line variable settings