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.  Running OpenFOAM in 32-bit mode


2. System requirements
~~~~~~~~~~~~~~~~~~~~~~
  OpenFOAM is developed and tested on Linux, but should work with other
  Unix style systems.  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 contact your
  system administrator.

  If the user wishes to run OpenFOAM in 32/64-bit mode they should consult
  the appendix "A. Running OpenFOAM in 32-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 an etc/
  directory in the OpenFOAM release. e.g. in

      $HOME/OpenFOAM/OpenFOAM-<VERSION>/etc/

      where <VERSION> corresponds to the version 1.4, 1.5, ...

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

        . $HOME/OpenFOAM/OpenFOAM-<VERSION>/etc/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 etc/cshrc file by adding the
    following line to the end of your $HOME/.cshrc file:

        source $HOME/OpenFOAM/OpenFOAM-<VERSION>/etc/cshrc

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

        source $HOME/.cshrc


  3.1. Installation in alternative locations
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    OpenFOAM may also be installed in alternative locations. However, the
    installation directory should be network available (e.g., NFS) if
    parallel calculations are planned.

    The environment variable 'FOAM_INST_DIR' can be used to find and source
    the appropriate resource file. Here is a bash/ksh/sh example:

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

    and a csh/tcsh example:

        setenv FOAM_INST_DIR /data/app/OpenFOAM
        foamDotFile=$FOAM_INST_DIR/OpenFOAM-<VERSION>/etc/bashrc
        if ( -f $foamDotFile ) source $foamDotFile


    The value set in '$FOAM_INST_DIR' will be used to locate the remaining
    parts of the OpenFOAM installation.


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.  You will first need to
  compile or obtain a recent version of gcc (we recomend gcc-4.3.?) for
  your platform, which may be obtained from http://gcc.gnu.org/.

  Install the compiler in
  $WM_PROJECT_INST_DIR/ThirdParty/gcc-<GCC_VERSION>/platforms/$WM_ARCH$WM_COMPILER_ARCH/
  and change the gcc version number in $WM_PROJECT_DIR/etc/settings.sh and
  $WM_PROJECT_DIR/etc/settings.csh appropriately and finally update the
  environment variables as in section 3.

  Now go to the top-level source directory $WM_PROJECT_DIR and execute the
  top-level build script './Allwmake'.  In principle this will build
  everything, but if problems occur with the build order it may be 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 maintain it for
  future releases.


5. Testing the installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~
  To check your installation setup, execute the 'foamInstallationTest'
  script (in the bin/ directory of the OpenFOAM installation). 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
  <USER>-<VERSION> (e.g. 'chris-1.5' for user chris and OpenFOAM version 1.5)
  and create a directory named 'run' within it, e.g. by typing:

      mkdir -p $HOME/OpenFOAM/${USER}-${WM_PROJECT_VERSION}/run

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

      cp -r $WM_PROJECT_DIR/tutorials $HOME/OpenFOAM/${USER}-${WM_PROJECT_VERSION}/run

  Run the first example case of incompressible laminar flow in a cavity:

      cd $HOME/OpenFOAM/${USER}-${WM_PROJECT_VERSION}/run/tutorials/icoFoam/cavity
      blockMesh
      icoFoam


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. Running OpenFOAM in 32-bit mode on 64-bit machines
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  Linux users with a 64-bit machine may install either the OpenFOAM 32-bit
  version (linux) or the OpenFOAM 64-bit version (linux64), or both.
  The 64-bit is the default mode on a 64-bit machine.  To use an installed
  32-bit version, the user must set the environment variable $WM_32 (to
  anything, e.g. "on") before sourcing the etc/bashrc (or etc/cshrc) file.
  Unsetting WM_32 and re-sourcing the etc/bashrc (or etc/cshrc) file will
  set up the user to run in 64-bit mode.