freefoam — The Cross-Platform CFD Toolkit
FreeFOAM is a cross-platform toolkit for computational fluid dynamics (CFD). It consists of a large collection of C++ libraries, allowing the user to write new solvers for partial differential equations using a notation very close to the mathematical one. FreeFOAM comes with a comprehensive set of solvers for a wide range of problems and accompanying pre-/and post-processing utilities.
FreeFOAM is based on the fantastic Open-Source OpenFOAM software. The goal of the FreeFOAM project is to remove the system-dependencies from OpenFOAM and make it generally more useable and easier to install.
The freefoam(1) command is used to invoke the actual FreeFOAM
applications. It was mainly created to avoid putting a large number of
binaries on the system PATH
, cluttering the namespace unnecessarily. It also
allows for the user to easily add her own applications to the search path,
without having to extend the PATH
variable or being root.
freefoam(1) uses the following mechanism to find the application <name>:
FREEFOAM_PATH
variable is set, it is prepended to the above
described search path. It is a colon-separated list of directories.
PATH
to the search path.
environment variables: FREEFOAM_PATH specify an alternative path where to search for applications
The following sections give a short description for all the available standard solvers and utilities. More information is available from the individual manual pages.
Below you find an overview of the small helper scripts provided by FreeFOAM.
FreeFOAM offers a number of global configuration options. These include
Unfortunately the OpenFOAM library (on which FreeFOAM builds) and some applications require the following files to be present for start-up:
It finds them in the following places (in the specified order, picking the first hit):
$FREEFOAM_CONFIG_DIR
environment
variable
where the versions in above directory names depend on the version of the FreeFOAM application to be run.
All FreeFOAM applications accept the options -doc and -srcDoc. The former locates and displays the API documentation of the application, the latter the source code. This, however, requires that FreeFOAM is able to locate the API documentation and knows which program to use for display.
By default FreeFOAM uses the API documentation provided on http://freefoam.sf.net/doc/API because most users will not want to install the sizeable documentation package. The method FreeFOAM uses to locate the documentation files is via index files which are conventional FreeFOAM dictionaries. Each of them contains an entry docDir specifying the documentation root location (such as http://freefoam.sf.net/doc/API) and a dictionary called docFiles mapping the application name to the names of the corresponding HTML documentation and source page.
These documentation indices are found by querying the list Documentation::doxyDocIndices in the global controlDict file. If multiple documentation indices are specified, the first index that provides documentation for the given application is picked.
FreeFOAM can automatically open a browser window displaying the HTML documentation for you. The entry Documentation::docBrowser in the global controlDict can be used to change which program is used for this. In this string the token %f gets replaced by the filename to open.
The lists DebugSwitches, InfoSwitches and OptimisationSwitches in the global controlDict file determine some global run-time behaviour of FreeFOAM. The entries in DebugSwitches can be set to 1 for more verbose output in the specified class.
The InfoSwitches::writePrecision setting determines the write precision in the output to the terminal (i.e. not the output written to files). Whether a job-info file should be created can be specified by enabling InfoSwitches::writeJobeInfo.
For files that are modifieable during run-time (e.g. to change the interval at which the output is created), FreeFOAM compares the modification times of these files in order to determine whether they have to be re-read. The setting OptimisationSwitches::fileModificationSkew determines the minimum modification-time difference in seconds for a file to be considered changed.
The setting OptimisationSwitches::commsType determines whether inter-process communications are either blocking, scheduled or nonBlocking.
OptimisationSwitches::floatTransfer causes to convert double values to float before transferring them through the communications library. This saves some bandwidth at the loss of accuracy.
The sum operation across processors can be executed either in a linear or a tree fashion. Especially for a large number of processors, tree-summation is significantly faster. The threshold at which to switch from linear to tree-summation is determined by OptimisationSwitches::nProcsSimpleSum.
FreeFOAM very often relies on dynamically loading libraries (a.k.a plugins).
If the library name is given as an absolute path, FreeFOAM tries to load it
directly. To locate libraries specified just by their name or with a relative
path, FreeFOAM first tries to find the library in one of the directories
specified in the list LibrarySearchPaths in the global controlDict and, if
the library was not found, falls back to the mechanism provided by your
operating system (i.e. for Linux systems this would be the LD_LIBRARY_PATH
and the default search path).
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):
FREEFOAM_PSTREAM_LIBRARY
is set,
FreeFOAM will try to load the library specified by it.
PstreamImplementation
exists in the global
controlDict file (see above), it reads the value of the entry
PstreamImplementation::configName
therein. This entry can be overridden by
setting the FREEFOAM_PSTREAM_CONFIG
environment variable. It then expects
that a sub-dictionary of PstreamImplementation
with the name specified in
FREEFOAM_PSTREAM_CONFIG
or PstreamImplementation::configName
exists. If
that sub-dictionary contains the entry PstreamImplementation::library
, it
will try to load a library specified by the value of that entry.
Please note that this library is also considered to be a plugin, and thus is located in the same way as described above.
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_PSTREAM_CLASS
,
FREEFOAM_IPSTREAM_CLASS
and FREEFOAM_OPSTREAM_CLASS
for the class
names to be instantiated.
PstreamImplementation
to be present in the global controlDict, reads the
value of FREEFOAM_PSTREAM_CONFIG
or the entry
PstreamImplementation::configName
and similarly to the library loading,
loads the sub-dictionary specified by that value. It then expects to find
the entries PstreamImplementation::Pstream
,
PstreamImplementation::IPstream
and PstreamImplementation::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 above. 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
.
Some of the tutorial scripts need to run FreeFOAM applications in parallel.
However, how to do so differs strongly from system to system and between
parallel communication libraries. This is why the command line to start an
application in parallel is configureable in the parRunTemplate
setting.
${NPROCS}, ${PAROPTS}, ${APPLICATION} and ${ARGS} are
placeholders for the number of processors to use, options for the parallel
communications system, the application to run and its arguments, respectively.
Note that the -parallel option is NOT included in ${ARGS}.
FREEFOAM_CONFIG_DIR
FREEFOAM_PATH
FREEFOAM_PSTREAM_CONFIG
FREEFOAM_PSTREAM_LIBRARY
FREEFOAM_PSTREAM_CLASS
FREEFOAM_IPSTREAM_CLASS
FREEFOAM_OPSTREAM_CLASS
The user guide is available from http://freefoam.sourceforge.net/doc/UserGuide and the Doxygen-generated API documentation can be accessed at http://freefoam.sourceforge.net/doc/API.