README-OpenFOAM

   1 #                            -*- mode: org; -*-
   2 #
   3 #+TITLE:             OpenFOAM README for version 1.6
   4 #+AUTHOR:                      OpenCFD Ltd.
   5 #+DATE:                         July 2009
   6 #+LINK:                  http://www.opencfd.co.uk
   7 #+OPTIONS: author:nil ^:{}
   8
   9 * Copyright
  10   OpenFOAM is free software; you can redistribute it and/or modify it under the
  11   terms of the GNU General Public License as published by the Free Software
  12   Foundation; either version 2 of the License, or (at your option) any later
  13   version.  See the file COPYING in this directory, for a description of the GNU
  14   General Public License terms under which you can copy the files.
  15
  16 * System requirements
  17   OpenFOAM is developed and tested on Linux, but should work with other POSIX
  18   systems.  To check your system setup, execute the foamSystemCheck script in
  19   the bin/ directory of the OpenFOAM installation. If no problems are reported,
  20   proceed to "3. Installation"; otherwise contact your system administrator.
  21
  22   If the user wishes to run OpenFOAM in 32/64-bit mode they should consult the
  23   section "Running OpenFOAM in 32-bit mode".
  24
  25 *** Qt (from http://trolltech.com/products/qt)
  26     The ParaView 3.6.1 visualisation package requires Qt to be installed on the
  27     system.  ParaView's producers state that ParaView is only officially
  28     supported on Qt version 4.3.x.  However, we have found in limited tests that
  29     ParaView works satisfactorily with newer versions of Qt than 4.3.x.  To
  30     check whether Qt4 is installed, and the version, type:
  31     + qmake --version
  32
  33     Both 32- and 64-bit version of ParaView were compiled with Qt-4.4.3 (with
  34     openSuSE-11.1).  If the user finds that a ParaView binary fails to run, then
  35     it is almost certainly due to a conflict in compiled and installed Qt
  36     versions and they will need to consult the section below on "Compiling
  37     ParaView and the PV3FoamReader module."
  38
  39     The default versions of Qt used by some GNU/Linux releases are as follows.
  40     + ubuntu-7.10:   Version 4.3.2
  41     + ubuntu-8.04:   Version 4.3.4
  42     + ubuntu-9.04:   Version 4.5.0
  43     + openSuSE-10.2: Version 4.2.1 - too old
  44     + openSuSE-10.3: Version 4.3.1
  45     + openSuSE-11.0: Version 4.4.0
  46     + openSuSE-11.1: Version 4.4.3
  47
  48     Compilation and running of ParaView has been successful using the libraries
  49     downloaded in the "libqt4-dev" package on ubuntu.
  50
  51     If you don't have an appropriate version of Qt installed you can download
  52     the sources from TrollTech e.g.:
  53     ftp://ftp.trolltech.com/qt/source/qt-x11-opensource-src-4.3.5.tar.bz2
  54     and compile and install in /usr/local or some other location that does to
  55     conflict with the pre-installed version.
  56
  57 * Installation
  58   Download and unpack the files in the $HOME/OpenFOAM directory as described in:
  59   http://www.OpenFOAM.org/download.html
  60
  61   The environment variable settings are contained in files in an etc/ directory
  62   in the OpenFOAM release. e.g. in
  63
  64   + $HOME/OpenFOAM/OpenFOAM-1.6/etc/
  65
  66   1) EITHER, if running bash or ksh (if in doubt type 'echo $SHELL'), source the
  67     etc/bashrc file by adding the following line to the end of your
  68     $HOME/.bashrc file:
  69
  70     + . $HOME/OpenFOAM/OpenFOAM-1.6/etc/bashrc
  71
  72     Then update the environment variables by sourcing the $HOME/.bashrc file by
  73     typing in the terminal:
  74
  75     + . $HOME/.bashrc
  76
  77   2) OR, if running tcsh or csh, source the etc/cshrc file by adding the
  78     following line to the end of your $HOME/.cshrc file:
  79
  80     + source $HOME/OpenFOAM/OpenFOAM-1.6/etc/cshrc
  81
  82     Then update the environment variables by sourcing the $HOME/.cshrc file by
  83     typing in the terminal:
  84
  85     + source $HOME/.cshrc
  86
  87 *** Installation in alternative locations
  88     OpenFOAM may also be installed in alternative locations. However, the
  89     installation directory should be network available (e.g., NFS) if parallel
  90     calculations are planned.
  91
  92     The environment variable 'FOAM_INST_DIR' can be used to find and source the
  93     appropriate resource file. Here is a bash/ksh/sh example:
  94
  95     + export FOAM_INST_DIR=/data/app/OpenFOAM
  96     + foamDotFile=$FOAM_INST_DIR/OpenFOAM-1.6/etc/bashrc
  97     + [ -f $foamDotFile ] && . $foamDotFile
  98
  99     and a csh/tcsh example:
 100
 101     + setenv FOAM_INST_DIR /data/app/OpenFOAM
 102     + foamDotFile=$FOAM_INST_DIR/OpenFOAM-1.6/etc/bashrc
 103     + if ( -f $foamDotFile ) source $foamDotFile
 104
 105     The value set in '$FOAM_INST_DIR' will be used to locate the remaining parts
 106     of the OpenFOAM installation.
 107
 108 * Building from Sources (Optional)
 109   If you cannot find an appropriate binary pack for your platform, you can build
 110   the complete OpenFOAM from the source-pack.  You will first need to compile or
 111   obtain a recent version of gcc (we recomend gcc-4.3.?) for your platform,
 112   which may be obtained from http://gcc.gnu.org/.
 113
 114   Install the compiler in
 115   $WM_PROJECT_INST_DIR/ThirdParty/gcc-<GCC_VERSION>/platforms/$WM_ARCH$WM_COMPILER_ARCH/
 116   and change the gcc version number in $WM_PROJECT_DIR/etc/settings.sh and
 117   $WM_PROJECT_DIR/etc/settings.csh appropriately and finally update the
 118   environment variables as in section 3.
 119
 120   Now go to the top-level source directory $WM_PROJECT_DIR and execute the
 121   top-level build script './Allwmake'.  In principle this will build everything,
 122   but if problems occur with the build order it may be necessary to update the
 123   environment variables and re-execute 'Allwmake'.
 124
 125   If you experience difficulties with building the source-pack, or your platform
 126   is not currently supported, please contact <enquiries@OpenCFD.co.uk> to
 127   negotiate a support contract and we will do the port and maintain it for
 128   future releases.
 129
 130 * Testing the installation
 131   To check your installation setup, execute the 'foamInstallationTest' script
 132   (in the bin/ directory of the OpenFOAM installation). If no problems are
 133   reported, proceed to getting started with OpenFOAM; otherwise, go back and
 134   check you have installed the software correctly and/or contact your system
 135   administrator.
 136
 137 * Getting Started
 138   Create a project directory within the $HOME/OpenFOAM directory named
 139   <USER>-1.6 (e.g. 'chris-1.6' for user chris and OpenFOAM version 1.6)
 140   and create a directory named 'run' within it, e.g. by typing:
 141
 142   + mkdir -p $FOAM_RUN/run
 143
 144   Copy the 'tutorial' examples directory in the OpenFOAM distribution to the
 145   'run' directory.  If the OpenFOAM environment variables are set correctly,
 146   then the following command will be correct:
 147
 148   + cp -r $WM_PROJECT_DIR/tutorials $FOAM_RUN
 149
 150   Run the first example case of incompressible laminar flow in a cavity:
 151
 152   + cd $FOAM_RUN/tutorials/incompressible/icoFoam/cavity
 153   + blockMesh
 154   + icoFoam
 155   + paraFoam
 156
 157   Refer to the OpenFOAM User Guide at http://www.OpenFOAM.org/doc/user.html for
 158   more information.
 159
 160 * Compiling Paraview 3.6.1 and the PV3FoamReader module
 161   If there are problems encountered with ParaView, then it may be necessary to
 162   compile ParaView from sources.  The compilation
 163   is a fairly simple process using the supplied makeParaView script that
 164   has worked in our tests with other packages supplied in the ThirdParty
 165   directory, namely cmake-2.6.4 and gcc-4.3.3.  Execute the following:
 166   + cd $WM_THIRD_PARTY_DIR
 167   + rm -rf paraview-3.6.1/platforms
 168   + makeParaView
 169
 170   The PV3FoamReader module is an OpenFOAM utility that can be compiled in the
 171   usual manner as follows:
 172   + cd $FOAM_UTILITIES/postProcessing/graphics/PV3FoamReader
 173   + ./Allwclean
 174   + ./Allwmake
 175
 176 *** Compiling Paraview with a local version of Qt
 177     If the user still encounters problems with ParaView, it may relate to the
 178     version of Qt, in which case, it is recommended that the user first
 179     downloads a supported version of Qt /e.g./ 4.3.5 as described in the section
 180     on "Qt".  The user should unpack the source pack in the $WM_THIRD_PARTY_DIR.
 181     Then the user can build Qt by executing from within $WM_THIRD_PARTY_DIR:
 182     + makeQt
 183
 184     The user should then compile ParaView using the local version of Qt by
 185     executing makeParaView with the -qmake option, giving the full path of the
 186     newly built qmake as an argument:
 187     + makeParaView -qmake <path_to_qmake>
 188
 189     The user must then recompile the PV3FoamReader module as normal (see above).
 190
 191 * Documentation
 192   http://www.OpenFOAM.org/doc
 193
 194 * Help
 195   http://www.OpenFOAM.org http://www.OpenFOAM.org/discussion.html
 196
 197 * Reporting Bugs in OpenFOAM
 198   http://www.OpenFOAM.org/bugs.html
 199
 200 * Running OpenFOAM in 32-bit mode on 64-bit machines
 201   Linux users with a 64-bit machine may install either the OpenFOAM 32-bit
 202   version (linux) or the OpenFOAM 64-bit version (linux64), or both.  The 64-bit
 203   is the default mode on a 64-bit machine.  To use an installed 32-bit version,
 204   the user must set the environment variable WM_ARCH_OPTION to 32 before
 205   sourcing the etc/bashrc (or etc/cshrc) file.