README

           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 32-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 32/64-bit mode they should consult
  the appendix "B. 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-dev/etc/

  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-dev/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-dev/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 an alternative location.
    However, the installation directory must be network available
    (eg, 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-dev/etc/bashrc
        [ -f $foamDotFile ] && . $foamDotFile

    and a csh example:

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


    The value set in '$FOAM_INST_DIR' will be used to locate the rest
    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.  First you will need to
  compile or obtain a recent version of gcc (we recommend gcc-4.1.?) for
  your platform which may be obtained from http://gcc.gnu.org/.  Install the
  compiler in $WM_PROJECT_INST_DIR/$WM_ARCH/gcc-4.1.? 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). 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>-dev (e.g. 'chris-dev' for user chris) and create a
  directory named 'run' within it, e.g. by typing:

      mkdir -p $HOME/OpenFOAM/${LOGNAME}-dev/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}-dev/run

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

      cd $HOME/OpenFOAM/${LOGNAME}-dev/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. 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.
  For ~.bashrc:

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

    # or, alternatively

      if /usr/bin/tty -s 2>/dev/null; then
         echo "..."
      fi

  and, for ~.cshrc:

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


B. Running OpenFOAM in 32-bit mode on 64-bit machines
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  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 (linux64) with 64-bit being the default mode. In order to
  set up the user to run in 32-bit mode, 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 sourcing the bashrc file will
  set up the user to run in 64-bit mode.