           README for OpenFOAM: The Open Source CFD Toolbox
           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0. Copyright
~~~~~~~~~~~~
OpenFOAM is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.  See the file COPYING in this directory,
for a description of the GNU General Public License terms under which 
you can copy the files.

1. Contents
~~~~~~~~~~~
0.  Copyright
1.  Contents
2.  System requirements
3.  Installation
4.  Building from Sources (Optional)
5.  Testing the installation
6.  Getting started
7.  Documentation
8.  Help
9.  Reporting Bugs
A.  Network settings
B.  Running OpenFOAM in 64 bit mode

2. System requirements
~~~~~~~~~~~~~~~~~~~~~~
OpenFOAM generally requires that the host machine operates a basic
level of networking.  To check your system setup, execute the
foamSystemCheck script in the bin directory of the OpenFOAM
installation. If no problems are reported, proceed to
"3. Installation"; otherwise see the appendix "A. Network settings"
and/or contact your system administrator.

If the user wishes to run OpenFOAM in 64 bit mode they should consult
the appendix "B. Running OpenFOAM in 64 bit mode".

3. Installation
~~~~~~~~~~~~~~~
Download and unpack the files in the $HOME/OpenFOAM directory as
described in: http://www.openfoam.org/download.html

The environment variable settings are contained in files in a
.OpenFOAM-1.3 directory in the OpenFOAM release, i.e. in
$HOME/OpenFOAM/OpenFOAM-1.3/.OpenFOAM-1.3

a) EITHER, if running bash or ksh (if in doubt type 'echo $SHELL'),
source the .OpenFOAM-1.3/bashrc file by adding the following line to
the end of your $HOME/.bashrc file:

. $HOME/OpenFOAM/OpenFOAM-1.3/.OpenFOAM-1.3/bashrc

Then update the environment variables by sourcing the $HOME/.bashrc
file by typing in the terminal:
. $HOME/.bashrc

b) OR, if running tcsh or csh, source the .OpenFOAM-1.3/cshrc file by
adding the following line to the end of your $HOME/.cshrc file:

source $HOME/OpenFOAM/OpenFOAM-1.3/.OpenFOAM-1.3/cshrc

The update the environment variables by sourcing the $HOME/.bashrc
file by typing in the terminal:
source $HOME/.cshrc

4. Building from Sources (Optional)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you cannot find an appropriate binary pack for your platform you 
can build the complete OpenFOAM from the source-pack.  First you will
need to compile or obtain a recent version of gcc (we recommend gcc-3.4.?)
for your platform which may be obtained from http://gcc.gnu.org/.  Install
the compiler in $WM_PROJECT_INST_DIR/$WM_ARCH/gcc-3.4.? and change the 
gcc version number in $WM_PROJECT_DIR/.bashrc and $WM_PROJECT_DIR/.cshrc as
appropriate and update the environment variables as in section 3.

Now go to the top-level source directory $WM_PROJECT_DIR and type ./Allwmake
which is the name of the top-level build script for building the whole of 
OpenFOAM.  In principle this will build everything but sometimes problems 
occur with the build order and it is necessary to update the environment
variables and re-execute Allwmake.  If you experience difficulties with
building the source-pack or your platform is not currently supported please
contact enquiries@OpenCFD.co.uk to negotiate a support contract and we will
do the port and maintiain it in future releases.

5. Testing the installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~
To check your installation setup, execute the 'foamInstallationTest'
script (in the bin directory of the OpenFOAM installation). It checks
all environment variables are set correctly and that the third-party
software are installed as described below. If no problems are
reported, proceed to getting started with OpenFOAM; otherwise, go
back and check you have installed the software correctly and/or
contact your system administrator.

6. Getting Started
~~~~~~~~~~~~~~~~~~
Create a project directory within the $HOME/OpenFOAM directory named
<userName>-1.3 (e.g. 'chris-1.3' for user chris) and create a
directory named 'run' within it, e.g. by typing:

mkdir -p $HOME/OpenFOAM/${LOGNAME}-1.3/run

Copy the 'tutorial' examples directory in the OpenFOAM distribution to the
'run' directory.  If OpenFOAM environment variables are set correctly, then  
the following command will be correct:

cp -r $WM_PROJECT_DIR/tutorials $HOME/OpenFOAM/${LOGNAME}-1.3/run

Run the first example case of incompressible laminar flow in a cavity:
 
cd $HOME/OpenFOAM/${LOGNAME}-1.3/run/tutorials/icoFoam 
blockMesh . cavity 
icoFoam . cavity 

7. Documentation
~~~~~~~~~~~~~~~~
    http://www.openfoam.org/doc

8. Help
~~~~~~~
    http://www.openfoam.org
    http://www.openfoam.org/discussion.html

9. Reporting Bugs in OpenFOAM
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    http://www.openfoam.org/bugs.html


A. Network settings
~~~~~~~~~~~~~~~~~~~
OpenFOAM requires a basic level of networking to be set up.  Firstly,
the host name must be set - to test, type 'uname -a'.  The running
shell must be tcsh, csh, bash or ksh - to test type 'echo $SHELL'

The user must be able to 'ping' the host machine itself (<host>) - to
test, type 'ping -c 1 <host>'

If the ping fails then it is possible that that the entry for the host
machine is missing, incorrect or duplicated in the /etc/hosts
file.  The user can check this by typing 'grep <host> /etc/hosts' which
should return a single line, typically of the form: 
<IPaddress> <host>.<domain> <host>

The <IPaddress> must correspond to that in the networking settings of
the machine which can also be checked by typing on Linux
'/sbin/ifconfig' which should produce lines of output that include
something similar to the following:

eth0  Link encap:Ethernet HWaddr ... 
      inet addr:<IPaddress> ... 

If the user is connected to a network that uses dynamic IP addresses,
they must be particularly careful to ensure that an entry for their
hostname/IP exists in the /etc/hosts file. If the server frequently
reallocates IP addresses across the network, it is advisable that the
/etc/hosts file is updated automatically when any changes occur.

The user should also be able to contact any other machine that it
needs to, either a remote licence host or other machines that are
being used within some parallel computation. Essentially the user
needs to be able to ping these machines as described in preceeding
sections.

The machine must have one of (or both) remote (rsh) and secure shell
(ssh) running on his/her account. To check whether rsh is running
correctly, the user should type 'rsh <host> ls'. Alternatively the
user can check if ssh is running correctly by typing 'ssh <host> ls'. 
In either case, the output to the command should produce a
file/directory listing for the current directory and no other text. If
neither command works, we recommend the user set up rsh for their use
as follows:

Check the rsh executable actually exists, e.g. the path to the
executable should be returned when typing 'which rsh'. Check with the
system administrator that rsh is enabled on the user's account; if
not, request that it is enabled. Create a '.rhosts' file in the $HOME
directory containing entries to access any machines they need to
access, i.e. their own machine and, if different, the licence host
machine. The entries are of the form: '<host> <user>'.

Remote shell accesses the .bashrc (or .cshrc) file and will not run
correctly if there is a problem with this file. In particular the user
should be careful with the following:

The .cshrc (or .bashrc) file should not contain errors that prevent it
from executing fully at startup; all error messages during execution
of the .bashrc (or .cshrc) file should be investigated and acted upon
to eliminate them. echo (print to screen) statements within .bashrc
(or .cshrc) must not be executed during the running of rsh. This does
not mean that echo statements are forbidden from the .cshrc (or
.bashrc) file, but they must be enclosed in a control structure,
e.g. an if statement, that ensures they are not executed when rsh is
executed, e.g. for .bashrc:

if [ "$PS1" ]; then 
echo "..."; fi 

and, for .cshrc: 

if ($?prompt) then ; echo "..." ; endif

B. Running OpenFOAM in 64 bit mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Those users with an installation of Linux on a 64 bit machine may
install either or both of the 32 bit version of OpenFOAM (linux) or
the 64 bit version of FOAM (linuxAMD64).

In order to set up the user to run in 64 bit mode, the user must set
the environment variable $WM_64 (to anything, e.g. "on") before
sourcing the .OpenFOAM/bashrc (or cshrc) file. Unsetting $WM_64 and
sourcing the bashrc file will set up the user to run in 32 bit
mode. With this set up, the setting of $WM_64 can be used as a switch
between 64 and 32 bit modes.
