FreeFOAM README for version 0.1.0

1. Copyright

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

2. System requirements

FreeFOAM is developed and tested on Linux, but should work with other Unix style systems, notably Mac OS X ©. The support for Microsoft Windows is a goal, which, however, is still far off.

2.1. Required software to build FreeFOAM

git: Currently you need git to obtain the FreeFOAM source code. http://git.or.cz
CMake: In order to build FreeFOAM you need to have CMake with version 2.6.2 or newer installed. http://cmake.org
Build system: CMake requires a native build system. On Unix like platforms GNU Make is recommended. http://www.gnu.org/software/make
C++ compiler: In order to build FreeFOAM you need a C++ compiler with good support for template expressions. The g++ compiler from GCC-4.3 and above will do fine. http://gcc.gnu.org
flex: The flex lexer generator. Version 2.5.33 is known to work. For more recent versions there have been reports of problems. http://flex.sourceforge.net
zlib: zlib compression library. http://www.zlib.net
METIS: The METIS graph partitioning library, version 5.0pre2. If your package manager doesn’t contain it, you can also have FreeFOAM build it automatically for you (see the installation section). http://glaros.dtc.umn.edu/gkhome/metis/metis/overview

2.2. Optional software

Parallel Communications Library

In order to run FreeFOAM in parallel, a communications library is required. The following list gives an overview of the available options:

MPI (Message Passing Interface): There are many implementations of the MPI standard. The one that has been tested and is known to work with FreeFOAM is OpenMPI.
PVM (Parallel Virtual Machine) is available from http://www.csm.ornl.gov/pvm.
GAMMA (Genoa Active Message MAchine) is available from http://www.disi.unige.it/project/gamma.

ParMetis

If you use an MPI library, the ParMetis library is required. If your package manager doesn’t contain this library, FreeFOAM can build it automatically for you (refer to the installation notes below). http://glaros.dtc.umn.edu/gkhome/metis/parmetis/overview

MGRIDGEN

MGRIDGEN is a grid coarsening library for multi-grid solvers. FreeFOAM can build this automatically for you (refer to the installation notes below). http://glaros.dtc.umn.edu/gkhome/mgridgen/overview

Warning

The license of MGRIDGEN and PARMGRIDGEN is unknown and the upstream authors so far have not answered any inquiries to resolve the issue. If you enable the use of MGRIDGEN and PARMGRIDGEN you alone are responsible for ensuring that you don’t violate any license conditions applying to these libraries. The authors of FreeFOAM will and cannot take any responsibility for your actions.

libccmio

pro-STAR © input/output library. FreeFOAM can build this automatically for you (refer to the installation notes below). https://wci.llnl.gov/codes/visit/3rd_party/libccmio-2.6.1.tar.gz

Warning

The license of libccmio © is proprietary and requires the consent of the copyright holders (CD-adapco) to download and use the library. Further it is not allowed to redistribute it in any form. The request for permission of inclusion with Debian was answered as follows by Geoffrey Prewett:

Gerber,

Sorry for the delay in response.  I checked back with our development director,
and he felt that it would be best to not include libccmio with Debian.
Instead, we would prefer to continue our current policy and keep it on our
web/FTP and have people ask for it.  There are three reasons for this:

1) We don't support STAR on Debian, and don't want to give the impression that we do.
2) We would like to keep a list of people that we give the library to.
3) This is not a general purpose library;  its sole purpose is to communicate
between our products.  Accepting outside changes risks committing a change that
would break our own software in possibly subtle ways.

So I regret to tell you that my company has declined to permit libccmio to be
distributed as part of Debian.

Regards,
Geoff Prewett

ParaView

If you want to build the ParaView plug-ins, you need a ParaView with the development headers and the corresponding CMake configuration files (ParaViewConfig.cmake, ParaViewUse.cmake, ParaViewLibraryDepends*.cmake). Most likely this means that you have to build ParaView yourself. http://paraview.org

M4

Some of the provided tutorial cases require the M4 macro processor. http://www.gnu.org/software/m4/

Doxygen

Automatic API-documentation generator. Required to build the source documentation. http://www.doxygen.org

3. Installation

This section needs serious expanding, but the short version is:

Install the prerequisites. If your distribution does not have METIS, ParMetis, MGRIDGEN or libccmio be not worried, FreeFOAM can handle those for you.

Clone the FreeFOAM repository (here the clone is placed in $HOME/Source/FreeFOAM):

$ mkdir -p $HOME/Source
$ git clone git://repo.or.cz/freefoam.git $HOME/Source/FreeFOAM

Create a build tree and cd into it:

$ mkdir $HOME/Source/FreeFOAM-build
$ cd $HOME/Source/FreeFOAM-build

Start CMake-configuration:
```
$ ccmake ../FreeFOAM
```
Press the c key. Use the arrow keys to navigate up and down and press enter to edit a field. To commit the change, press enter again, or ESC to abandon the change. ON/OFF fields are toggled by pressing enter. Advanced options can be displayed by hitting the t key.
- Set CMAKE_BUILD_TYPE to Release for an optimized build.
- If CMake complains that it can’t find MPI, and you don’t want to install it, disable FF_USE_MPI. If, instead, you want to use GAMMA or PVM, enable FF_USE_GAMMA or FF_USE_PVM, respectively. You can also enable more than one of the options.
  
  Note
  Currently only MPI implementation is available.
- Select the default Pstream implementation by setting FF_DEFAULT_PSTREAM to one of dummy, mpi, pvm or gamma. This setting will only influence the contents of the global controlDict file.
- If CMake told you it couldn’t find ParaView:
  1. Set ParaView_DIR to the path of the directory containing ParaViewConfig.cmake, which is most likely the ParaView build directory.
  2. If you do not want to build the ParaView plug-ins, disable FF_BUILD_PARAVIEW_PLUGINS
- If you do not have METIS or ParMetis, enable FF_BUILD_PRIVATE_METIS or FF_BUILD_PRIVATE_PARMETIS, respectively. CMake will then try to download and build the selected libraries for you. Conversely, if one of the libraries is provided by your system, you can turn the respective setting to OFF. Please note that if your system provides only ParMetis, you do not have to install METIS, as the former also contains METIS in an older version.
- If you want to use the MGridGen agglomeration method for the GAMG solver, you need to enable FF_ENABLE_PARMGRIDGEN and if the library is not installed on your system ensure that FF_BUILD_PRIVATE_PARMGRIDGEN is enabled. See above regarding the unknown license status of this package.
- In order to build ccm26ToFoam, a conversion utility for grids generated with ProStar/ccm © version 2.6, enable the setting FF_ENABLE_CCMIO and if libccmio is not installed on your system, also FF_BUILD_PRIVATE_CCMIO. Refer to the above description of the libccmio package for the license restrictions which apply to this package.
- If you plan on installing FreeFOAM, set CMAKE_INSTALL_PREFIX to the base directory under which FreeFOAM should reside.
- For more fine-grained control over what gets installed where, adjust FF_INSTALL_CONFIG_PATH, FF_INSTALL_HEADER_PATH, FF_INSTALL_LIB_PATH, FF_INSTALL_FRAMEWORK_PATH, FF_INSTALL_PV3FOAMREADER_PATH, FF_INSTALL_PVFOAMREADER_PATH and FF_INSTALL_USERDFOAM_PATH. Paths not starting with a slash (/) will be relative to CMAKE_INSTALL_PREFIX. If you include a leading slash, the paths are absolute.
- If you want FreeFOAM to use float as the floating point type instead of double, change FF_DOUBLE_PRECISION to OFF.
Hit the c key again. If you enabled FF_BUILD_PRIVATE_CCMIO, CMake will fail to download https://wci.llnl.gov/codes/visit/3rd_party/libccmio-2.6.1.tar.gz. Please follow the instructions in the error message on how to work around this problem, or download the file manually and place it in ThirdParty/ccmio/ (relative to the build directory). Then hit c again.
You shouldn’t get any errors anymore now. Keep pressing c until ccmake displays "Press [g] to generate and exit" in the legend at the bottom of the interface.
Press g to generate the Makefiles and exit the ccmake interface.
Start the native build tool. If you used the Makefile generator (which is the default for Unix-platforms), type
```
$ make
```
If you have a multi-core/processor machine, you can speed things up significantly by telling Make to run independent jobs in parallel. A good choice for the number of parallel jobs to run is the number of CPU’s/cores you have in your machine plus 1 (to compensate for disk-latency). For a typical dual-core machine, run
```
$ make -j3
```
If you want to, you can now install FreeFOAM (depending on the CMAKE_INSTALL_PREFIX and the individual FF_INSTALL_*_PATH it is possible that you have to do this as root, i.e. use su or sudo).
```
$ make install
```

3.1. Using FreeFOAM

If you didn’t change CMAKE_INSTALL_PREFIX and FF_INSTALL_BIN_PATH chances are that you can start using FreeFOAM right after you installed it without any further steps being necessary.

3.1.1. Global Configuration Files

Unfortunately the OpenFOAM library (on which FreeFOAM builds) and some applications require some files to be present for start-up. It finds those in the following places (in the specified order, picking the first hit):

Under the directory specified in the $FREEFOAM_CONFIG_DIR environment variable
In $HOME/.FreeFOAM/0.1.0
In $HOME/.FreeFOAM
In the installation directory of the configuration files. There are two possible places for this:

<CMAKE_INSTALL_PREFIX>/<FF_INSTALL_CONFIG_PATH>

if you specified <FF_INSTALL_CONFIG_PATH> as a relative path.

<FF_INSTALL_CONFIG_PATH>

if you specified <FF_INSTALL_CONFIG_PATH> as an absolute path.

The default location is /usr/local/etc/FreeFOAM/1.0.

3.1.2. Selecting the Parallel Communications Library

Both, FreeFOAM and OpenFOAM abstract the parallel operations into the Pstream library, making it rather simple to firstly switch between parallel implementations and secondly port the software to a new communications library. However, FreeFOAM uses a much more flexible mechanism of determining which Pstream implementation library to use than OpenFOAM. The latter does this by adjusting the LD_LIBRARY_PATH environment variable. As FreeFOAM wants to be a well behaved Linux citizen, this is not an option. Instead, FreeFOAM dynamically loads the desired Pstream library at startup (i.e. as a plug-in). The following list details how FreeFOAM determines what library to load (if at all):

If the environment variable FREEFOAM_PSTREAM_LIBRARY is set, FreeFOAM will try to load the library specified by it.
If the sub-dictionary PstreamImplementation exists in the global controlDict file (see Global Configuration Files), it reads the value of the entry configName therein. It then expects that a sub-dictionary of PstreamImplementation with the name specified in configName exists. If that sub-dictionary contains the entry library, it will try to load a library specified by the value of that entry.

After FreeFOAM (possibly) loaded the library, it will try to instantiate concrete implementations of the abstract base classes PstreamImpl, IPstreamImpl and OPstreamImpl. Which classes are to be instantiated is determined as follows:

FreeFOAM queries the environment variables FREEFOAM_PSTREAM_CLASS, FREEFOAM_IPSTREAM_CLASS and FREEFOAM_OPSTREAM_CLASS for the class names to be instantiated.
For any of the variables not set, it requires the sub-dictionary PstreamImplementation to be present in the global controlDict, reads the value of configName and similarly to the library loading, loads the sub-dictionary specified by that value. It then expects to find the entries Pstream, IPstream and OPstream which specify the names of the classes to load.

This means that one can create a global controlDict file containing (among other things) something like the following:

PstreamImplementation
{
    //configName dummy;
    configName mpi;

    dummy
    {
        library libdummyPstream.so;
        Pstream dummyPstreamImpl;
        OPstream dummyOPstreamImpl;
        IPstream dummyIPstreamImpl;
    }

    mpi
    {
        library libmpiPstream.so;
        Pstream mpiPstreamImpl;
        OPstream mpiOPstreamImpl;
        IPstream mpiIPstreamImpl;
    }
}

This way the administrator can provide a global controlDict in the FreeFOAM installation. Every user can then override that controlDict by supplying her own file in her home directory as detailed in Global Configuration Files. In order to select a particular Pstream implementation for a specific communications library, the user can then either adjust the PstreamImplementation::configName entry in the global controlDict file, set the FREEFOAM_PSTREAM_CONFIG variable or for full control, set the variables FREEFOAM_PSTREAM_LIBRARY, FREEFOAM_PSTREAM_CLASS, FREEFOAM_IPSTREAM_CLASS and FREEFOAM_OPSTREAM_CLASS.

3.1.3. Running FreeFOAM From the Build Tree

You can use FreeFOAM without installing it first, directly from the build tree. However, this might take a little bit more effort to set up because most likely you will have to adjust the following environment variables:

PATH: Must contain $HOME/Source/FreeFOAM-build/bin
LD_LIBRARY_PATH: Must contain $HOME/Source/FreeFOAM-build/lib
FREEFOAM_CONFIG_DIR: Should point to $HOME/Source/FreeFOAM-build/etc

Where it is assumed that you followed the installation instructions. If you used different paths for downloading and compiling FreeFOAM, you will have to adjust these names. Refer to Extending Search Paths And Setting Environment Variables Permanently if you need help setting these variables.

3.2. Running the tutorials

Now you should be able to run the tutorial cases. For this copy the tutorials directory to some convenient place:

$ mkdir -p $HOME/FreeFOAM/$LOGNAME-0.1.0/run
$ cp -r $HOME/Source/FreeFOAM-build/tutorials $HOME/FreeFOAM/$LOGNAME-0.1.0/run/
$ cd $HOME/FreeFOAM/$LOGNAME-0.1.0/run

And try to run e.g. the cavity tutorial case:

$ cd icoFoam
$ blockMesh -case cavity
$ checkMesh -case cavity
$ icoFoam -case cavity

Things should run smoothly and finish without an error.

3.3. Build Configuration Reference

CMAKE_BUILD_TYPE: One of <empty>, Debug, Release, RelWithDebInfo and MinSizeRel. Refer to the CMake documentation for more detail.
FF_DOUBLE_PRECISION: If set to ON FreeFOAM will be compiled using double as the floating point type. If set to OFF it will use float.
FF_BUILD_FRAMEWORK: If this is enabled, the libraries are built as frameworks. Only available on Mac OS X.
CMAKE_INSTALL_PREFIX: Installation prefix under which to install FreeFOAM.
FF_INSTALL_BIN_PATH: Installation path of the binaries. If not absolute, it is relative to CMAKE_INSTALL_PREFIX.
FF_INSTALL_CONFIG_PATH: Installation path of the configuration files. If not absolute, it is relative to CMAKE_INSTALL_PREFIX.
FF_INSTALL_HEADER_PATH: Installation path of the header files. If not absolute, it is relative to CMAKE_INSTALL_PREFIX. On Mac OS X, and if FF_BUILD_FRAMEWORK is enabled, this setting is ignored.
FF_INSTALL_LIB_PATH: Installation path of the libraries. If not absolute, it is relative to CMAKE_INSTALL_PREFIX.
FF_INSTALL_FRAMEWORK_PATH: Installation path of the Mac OS X frameworks. If not absolute, it is relative to CMAKE_INSTALL_PREFIX. This is only available and takes effect if FreeFOAM is compiled on Mac OS X, and if FF_BUILD_FRAMEWORK is enabled.
FF_INSTALL_PV3FOAMREADER_PATH: Installation path of the ParaView3 plug-ins. If not absolute, it is relative to CMAKE_INSTALL_PREFIX.
FF_INSTALL_PVFOAMREADER_PATH: Installation path of the ParaView2 plug-ins. If not absolute, it is relative to CMAKE_INSTALL_PREFIX.
FF_INSTALL_USERDFOAM_PATH: Installation path of the Ensight plug-in. If not absolute, it is relative to CMAKE_INSTALL_PREFIX.
EXECUTABLE_PREFIX: Prefix which get prepended to the name of the executables. This defaults to ff_ and serves the disambiguation of names.
FF_USE_GAMMA: If enabled, FreeFOAM will use the GAMMA parallel communications library.
FF_USE_MPI: If enabled, FreeFOAM will use the MPI parallel communications library. This is required in order to build some of the libraries and utilities.
FF_USE_PVM: If enabled, FreeFOAM will use the PVM parallel communications library.
FF_DEFAULT_PSTREAM: The default Pstream selection in the global controlDict file.
FF_BUILD_PARAVIEW_PLUGINS: Whether to build the ParaView plug-ins. If enabled, FreeFOAM requires a ParaView build tree and the ParaView_DIR variable set to the path of it.
FF_ENABLE_CCMIO: Enable the use of libccmio. This is required to build the grid conversion utility ccm26ToFoam. Note that you need the permission of the copyright holders (CD-adapco) to download, build and use the library. Refer to the description of the package for the details.
FF_BUILD_PRIVATE_CCMIO: Automatically download and build libccmio. Unfortunately this process will fail in the download step, since CMake currently does not support https URLs. But you will get specific instructions from the build system on how to get around this problem.
FF_BUILD_PRIVATE_METIS: Automatically download and build METIS.
FF_BUILD_PRIVATE_PARMETIS: Automatically download and build ParMetis.
FF_ENABLE_PARMGRIDGEN: Enable the use of PARMGRIDGEN and MGRIDGEN which is required to build MGridGenGamgAgglomeration providing the MGridGen agglomeration method for the GAMG solver. Be aware that if you use these libraries, that you alone are responsible to comply with the license restrictions associated with them. Refer to the description of the package for more information.
FF_BUILD_PRIVATE_PARMGRIDGEN: Automatically download and build PARMGRIDGEN and MGRIDGEN.
FF_BUILD_DOXYGEN_DOCS: Enable building of the Doxygen API documentation. The documentation will only be built once and is not updated automatically. This is because it depends on a huge number of files and would make dependency tracking very slow and difficult to maintain. To force the re-generation of the API documentation execute make apidoc.

7. Troubleshooting

7.1. The FreeFOAM Executables Are Not Found By The Shell

There are three possible reasons for this:

Your shell (notably csh, tcsh and zsh) requires you to refresh the cache of available executables. You can do so by entering the command:
```
$ rehash
```
If rehashing didn’t solve the problem, the problem most likely is that you installed FreeFOAM into a non-standard location by changing the configuration variables CMAKE_INSTALL_PREFIX or FF_INSTALL_BIN_PATH in which case the executables where installed into a directory not searched by the shell. In this case you have to add the installation directory of the executables to the PATH variable. There are two possible locations:

<CMAKE_INSTALL_PREFIX>/<FF_INSTALL_BIN_PATH>

if you specified FF_INSTALL_BIN_PATH as a relative path

<FF_INSTALL_BIN_PATH>

if you specified FF_INSTALL_BIN_PATH as an absolute path

After extending the PATH variable with the installation directory of the executables, you should be able to run all FreeFOAM applications as any other binary available on the system. See Extending Search Paths And Setting Environment Variables Permanently for instructions on how to extend the search path.
This option is similar to the previous solution and applies if you want to run FreeFOAM from the build tree (i.e. without running make install). In this case you again have to make sure that your shell finds the executables built by CMake by extending the PATH variable. Further, you have to tell FreeFOAM where to find the global configuration files (see Global Configuration Files). Here, you have the option to place the files under your home directory or set an environment variable. The former can be achieved by:
```
$ mkdir -p $HOME/.FreeFOAM/0.1.0
$ cp $HOME/Source/FreeFOAM-build/etc/controlDict $HOME/.FreeFOAM/0.1.0
$ cp $HOME/Source/FreeFOAM-build/etc/cellModels $HOME/.FreeFOAM/0.1.0
$ cp -r $HOME/Source/FreeFOAM-build/etc/thermoData $HOME/.FreeFOAM/0.1.0
```
The latter (and recommended) method is to set the environment variable FREEFOAM_CONFIG_DIR to $HOME/Source/FreeFOAM-build/etc. Adjust paths to the build tree to your actual setup.

7.2. Starting Any FreeFOAM Application Fails Because Some Libraries Cannot Be Found

Although CMake should have taken care of this by using RPATH on Linux and install_name on Mac OS X, it might be necessary on some systems to adjust the library search paths:

LD_LIBRARY_PATH: This variable is used by all Unix like systems (e.g. Linux, Mac OS X, etc.)
DYLD_LIBRARY_PATH: This variable is used by Mac OS X.

If you installed FreeFOAM, there are (as with the executables), two possible installation directories:

<CMAKE_INSTALL_PREFIX>/<FF_INSTALL_LIB_PATH>: if you specified FF_INSTALL_LIB_PATH as a relative path.
<FF_INSTALL_LIB_PATH>: if you specified FF_INSTALL_LIB_PATH as an absolute path.

If you are trying to run from the build tree, you have to include $HOME/Source/FreeFOAM-build/lib/FreeFOAM/0.1 in the above mentioned search paths (where you have to adjust the location of the build tree to your actual setup).

7.3. A Running FreeFOAM Application Aborts Because It Can’t dlopen A Library

FreeFOAM (and OpenFOAM) often dynamically load libraries at run-time (a.k.a plug-ins) to add features the user requested without requiring that the whole application be recompiled. This makes it very simple to add new boundary conditions, turbulence and combustion models etc. However, it also requires that FreeFOAM must be able to find these libraries at run-time. The operating system function which does the loading of the libraries (dlopen) usually tries to find the library with the given name in several places; namely a default search path and a search path configured by one or multiple environment variables such as LD_LIBRARY_PATH or DYLD_LIBRARY_PATH (on Mac OS X). The details vary from platform to platform, so you best consult the documentation of dlopen for the details.

Additionally FreeFOAM allows you to configure a custom search path for plug-ins in the global controlDict file by listing the directories to be searched in the list LibrarySearchPaths. By default FreeFOAM is configured to search for plug-ins in the location where CMake installed them.

If you want to add your own plug-in libraries (e.g. you want to add your own boundary conditions class), you most probably will want to extend this search path.

8. Extending Search Paths And Setting Environment Variables Permanently

The way one sets environment variables and extends the executable and library search paths permanently strongly depends on the shell used. Usually one has to create or change an initialization file in the users home directory. In the following this will be discussed very briefly for the popular shells BASH and tcsh. However, if you need more help or want information on using the shell, there is an excellent tutorial available at http://linuxcommand.org.

8.1. BASH

The BASH shell is the default shell for most Linux/Unix distributions. Most systems configure the BASH shell such that it reads the text file $HOME/.bashrc when starting up, so this is the place where one appends customizations of the environment variables. On some systems this file is not processed by default (notably Mac OS X). In this case you can use $HOME/.bash_profile.

8.1.1. Referencing A Variable

To retrieve the value stored in a shell variable or environment variable, one prefixes its name with the dollar ($) character.

8.1.2. Setting A Variable

The syntax for setting a variable and making it available to child-processes of the shell is the following:

$ export variable_name=variable_value

Note that no white-space characters are allowed surrounding the = sign.

8.1.3. Extending A Search Path

The shell and other Unix system facilities use environment variables to locate executables and dynamically linked libraries. These search paths consist of strings naming directories in which the executables and libraries should be searched for. The individual paths are separated by a colon (:) character. To add the e.g. the directory $HOME/bin to the search path for executables, one would do the following:

$ export PATH=$PATH:$HOME/bin

which appends $HOME/bin to the end of the PATH variable.

8.2. TCSH

Some users and administrators prefer to use a C-Shell, such as the TCSH. Here you can use e.g. the file $HOME/.tcshrc to customize the environment.

8.2.1. Referencing A Variable

As with the BASH, one retrieves the value stored in a shell variable or environment variable by prefixing its name with the dollar ($) character. Sometimes it is also necessary to protect the variable name by surrounding it with curly braces ({ and }).

8.2.2. Setting A Variable