1 FreeFOAM README for version 1.5.0-1
2 ===================================
3 MichaelWild <themiwi@users.sourceforge.net>
9 http://freefoam.sourceforge.net
13 FreeFOAM is free software; you can redistribute it and/or modify it under the
14 terms of the GNU General Public License as published by the Free Software
15 Foundation; either version 2 of the License, or (at your option) any later
16 version. See the file COPYING in this directory, for a description of the GNU
17 General Public License terms under which you can copy the files.
21 FreeFOAM is developed and tested on Linux, but should work with other Unix
22 style systems. With some additional patching it will also work under
23 Mac OS X. The support for Microsoft Windows is a goal, which, however, is
26 Required software to build FreeFOAM
27 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
29 Currently you need git to obtain the FreeFOAM source code. http://git.or.cz
31 In order to build FreeFOAM you need to have CMake with version 2.6.2 or
32 newer installed. http://cmake.org
34 CMake requires a native build system. On Unix like platforms I recomment
35 using GNU Make. http://www.gnu.org/software/make
37 In order to build FreeFOAM you need a C\+\+ compiler with good support for
38 template expressions. The g\+\+ compiler from GCC-4.3 and above will do
39 fine. http://gcc.gnu.org
41 The flex lexer generator. Version 2.5.33 is known to work. For more recent
42 versions there have been reports of problems. http://flex.sourceforge.net
44 zlib compression library. http://www.zlib.net
46 The METIS graph partitioning library, version 5.0pre2. If your package manager
47 doesn't contain it, you can also have FreeFOAM build it automatically for you
48 (see the installation section). http://glaros.dtc.umn.edu/gkhome/metis/metis/overview
50 MGridGen grid coarsening library. FreeFOAM can build this automatically for
51 you (refer to the installation notes below).
52 http://glaros.dtc.umn.edu/gkhome/mgridgen/overview
54 pro-STAR input/output library. FreeFOAM can build this automatically for
55 you (refer to the installation notes below).
56 https://wci.llnl.gov/codes/visit/3rd_party/libccmio-2.6.1.tar.gz
61 In order to run FreeFOAM in parallel, a communications library is required.
62 The following list gives an overview of the available options.
63 - MPI (_Message Passing Interface_): There are many implementations of the MPI
64 standard. The one that has been tested and is known to work with FreeFOAM
65 is http://www.open-mpi.org[OpenMPI].
66 - PVM (_Parallel Virtual Machine_) is available from http://www.csm.ornl.gov/pvm.
67 - GAMMA (_Genoa Active Message MAchine_) is available from http://www.disi.unige.it/project/gamma.
69 If you use an MPI library, the ParMetis library is required. If your package
70 manager doesn't contain this library, FreeFOAM can build it automatically for
71 you (refer to the installation notes below).
72 http://glaros.dtc.umn.edu/gkhome/metis/parmetis/overview
74 If you want to build the http://paraview.org[ParaView] plugins, you need a
75 ParaView with the development headers *and* the corresponding CMake configuration
76 files (ParaViewConfig.cmake, ParaViewUse.cmake, ParaViewLibraryDepends*.cmake).
77 Most likely this means that you have to build ParaView yourself.
82 This section needs serious expanding, but the short version is:
84 - Install the prerequisites. If your distribution does not have
85 METIS, ParMetis, MGridGen or libccmio be not worried, FreeFOAM
86 can handle those for you.
87 - Clone the FreeFOAM repository (here the clone is placed in $HOME/Source/FreeFOAM):
89 ---------------------------------------------------------------------------
90 $ mkdir -p $HOME/Source
91 $ git clone git://repo.or.cz/freefoam.git $HOME/Source/FreeFOAM
92 $ cd $HOME/Source/FreeFOAM
93 ---------------------------------------------------------------------------
94 - Create a build tree and _cd_ into it:
100 - Start CMake-configuration:
105 - Press the +c+ key. Use the arrow keys to navigate up and down and press +enter+ to
106 edit a field. To commit the change, press +enter+ again, or +ESC+ to abandon the change.
107 ON/OFF fields are toggled by pressing +enter+.
108 * Set +CMAKE_BUILD_TYPE+ to +Release+ for an optimized build.
109 * If CMake complains that it can't find MPI, and you don't want to install it, disable
110 +FF_USE_MPI+. If, instead, you want to use GAMMA or PVM, enable +FF_USE_GAMMA+ or
111 +FF_USE_PVM+, respectively. You can also enable more than one of the options.
114 Currently only MPI and the dummy implementation are available.
116 * Select the default Pstream implementation by setting +FF_DEFAULT_PSTREAM+
117 by setting it to one of +dummy+, +mpi+, +pvm+ or +gamma+. This setting
118 will only influence the contents of the global controlDict file.
119 * If CMake told you it couldn't find ParaView:
120 . Set +ParaView_DIR+ to the path of the ParaView build directory if you have it.
121 . If you do not want to build the ParaView plugins, disable +FF_BUILD_PARAVIEW_PLUGINS+
122 * If you do not have METIS, ParMetis, MGridGen or libccmio installed, enable
123 +FF_BUILD_PRIVATE_METIS+, +FF_BUILD_PRIVATE_PARMETIS+, +FF_BUILD_PRIVATE_PARMGRIDGEN+ or
124 +FF_BUILD_PRIVATE_CCMIO+ respectively. CMake will then try to download and build
125 the selected libraries for you. Conversely, if you one of the libraries is provided
126 by your system, you can turn the respective setting to +OFF+. Please note that if
127 you system provides only +ParMetis+, you do not have to install +METIS+, as the
128 former also contains +METIS+.
129 * If you plan on installing FreeFOAM, set +CMAKE_INSTALL_PREFIX+ to the base directory
130 under which FreeFOAM should reside.
131 * For more fine-grained control over what gets installed where, adjust
132 +FF_INSTALL_CONFIG_PATH+, +FF_INSTALL_HEADER_PATH+, +FF_INSTALL_LIB_PATH+,
133 +FF_INSTALL_PV3FOAMREADER_PATH+, +FF_INSTALL_PVFOAMREADER_PATH+ and +FF_INSTALL_USERDFOAM_PATH+.
134 * If you want FreeFOAM to use +float+ as the floating point type instead of
135 +double+, change +FF_PRECISION+ to +SP+.
136 - Hit the +c+ key again. If you enabled +FF_BUILD_PRIVATE_CCMIO+, CMake will fail
137 to download https://wci.llnl.gov/codes/visit/3rd_party/libccmio-2.6.1.tar.gz.
138 Please follow the instructions in the error message on how to work around this
139 problem, or download the file manually and place it in +ThirdParty/ccmio/+
140 (relative to the build directory). Then hit +c+ again.
141 - You shouldn't get any errors anymore now. Keep pressing +c+ until
142 the ccmake displays "++Press [g] to generate and exit++" in the legend at
143 the bottom of the interface.
144 - Press +g+ to generate the Makefiles and exit the ccmake interface.
145 - Start the native build tool. If you used the +Makefile+ generator
146 (which is the default for Unix-platforms), type
151 - If you have a multi-core/processor machine, you can speed things up
152 significantly by telling Make to run independent jobs in parallel.
153 A good choice for the number of parallel jobs to run is the
154 number of CPU's/cores you have in your machine plus 1 (to compensate
155 for disk-latency). For a typical dual-core machine, run
160 - If you want to, you can now install FreeFOAM (depending on the
161 +CMAKE_INSTALL_PREFIX+ and the individual +FF_INSTALL_*_PATH+
162 it is possible that you have to do this as root, i.e. use
163 +su+ or +sudo+). However, this is optional and hasn't been
164 tested thoroughly, so you might overwrite some important files
173 - Make sure that your shell can find the FreeFOAM executables. If you want
174 to run FreeFOAM from the build tree (i.e. without installing), append
175 +<build_dir>/bin+ to your +PATH+ variable:
178 $ export PATH=$PATH:$HOME/Source/FreeFOAM/build/bin
181 This assumes that your build directory is +$HOME/Source/FreeFOAM/build+,
182 which should be the case if you followed above instructions. If it isn't,
183 you will have to adjust above command appropriately.
185 - On some systems it might be necessary to adjust the library search
186 path (although CMake should have taken care of this by using +RPATH+
187 on Linux and +install_name+ on Mac OS X):
190 $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/Source/FreeFOAM/build/lib/FreeFOAM-1.5.0
193 Again, this is assuming that your build tree is in +$HOME/Source/FreeFOAM/build+.
195 - Unfortunately the OpenFOAM library (on which FreeFOAM builds) and some
196 applications require some files to be present for start-up. It finds those
197 in the following places (in the specified order, picking the first hit):
200 1. Under the directory specified in the '$FREEFOAM_CONFIG_DIR' environment variable
201 2. In '$HOME/.FreeFOAM/1.5.0-0'
202 3. In '$HOME/.FreeFOAM'
203 4. In '<prefix>/<FF_INSTALL_CONFIG_PATH>', where '<prefix>' is the
204 installation prefix and '<FF_INSTALL_CONFIG_PATH>' is the value you
205 specified for the 'FF_INSTALL_CONFIG_PATH' property when configuring
206 FreeFOAM using ccmake. The former defaults to '/usr/local', the latter
207 to 'etc/FreeFOAM-1.5.0'.
210 So, if you want to run FreeFOAM from the build tree (i.e. without running
211 +make install+), you have the option to place the files under your home directory
212 or set an environment variable. The former can be achieved by:
215 $ mkdir -p $HOME/.FreeFOAM/1.5.0-0
216 $ cp $HOME/Source/FreeFOAM/etc/controlDict $HOME/.FreeFOAM/1.5.0-0
217 $ cp $HOME/Source/FreeFOAM/etc/cellModels $HOME/.FreeFOAM/1.5.0-0
218 $ cp -r $HOME/Source/FreeFOAM/etc/thermoData $HOME/.FreeFOAM/1.5.0-0
221 Or, if you prefer setting the environment variable:
224 $ export FREEFOAM_CONFIG_DIR=$HOME/Source/FreeFOAM/etc
227 Notice that this time '$HOME/Source/FreeFOAM' refers to the
228 root of the source tree, i.e. where your clone of the FreeFOAM
229 repository is. Adjust it to your actual setup.
231 - Both, FreeFOAM and OpenFOAM abstract the parallel operations into
232 the +Pstream+ library, making it firstly rather simple to switch between
233 parallel implementations and secondly to port the software to a new
234 communications library. However, FreeFOAM uses a much more flexible
235 mechanism of determining which +Pstream+ implementation library to
236 load than OpenFOAM. The latter did this by adjusting the +LD_LIBRARY_PATH+.
237 As FreeFOAM wants to be a well behaved Linux citizen, this is not an
238 option. Instead, FreeFOAM dynamically loads the desired +Pstream+
239 library at startup. The following list details how FreeFOAM determines
240 what library to load (if at all):
243 1. If the environment variable +FREEFOAM_PSTREAM_LIBRARY+ is set,
244 FreeFOAM will try to load the library specified in the value of
246 2. If the sub-dictionary +PstreamImplementation+ exists in the global
247 +controlDict+ file (see above), it reads the value of the entry
248 +configName+ therein. It then expects that a sub-dictionary of
249 +PstreamImplementation+ with the name specified in +configName+
250 exists. If that sub-dictionary contains the entry +library+,
251 it will try to load a library spedified by the value of that
255 After FreeFOAM (possibly) loaded the library, it will try to instantiate
256 concrete implementations of the abstract base classes +PstreamImpl+,
257 +IPstreamImpl+ and +OPstreamImpl+. Which classes are to be instantiated
258 is determined as follows:
261 1. FreeFOAM queries the environment variables +FREEFOAM_PSTREAM_CLASS+,
262 +FREEFOAM_IPSTREAM_CLASS+ and +FREEFOAM_OPSTREAM_CLASS+ for the class
263 names to be instantiated.
264 2. Otherwise it requires the sub-dictionary +PstreamImplementation+
265 to be present in the global +controlDict+, reads the value of
266 +configName+ and similarly to the library loading,
267 loads the sub-dictionary specified by that value. It then expects
268 to find the entries +Pstream+, +IPstream+ and +OPstream+ which
269 specify the names of the classes to load.
272 This means that you can create a global +controlDict+ file containing
273 (among other things) something like the following:
275 PstreamImplementation
282 library libdummyPstream.so;
283 Pstream dummyPstreamImpl;
284 OPstream dummyOPstreamImpl;
285 IPstream dummyIPstreamImpl;
290 library libmpiPstream.so;
291 Pstream mpiPstreamImpl;
292 OPstream mpiOPstreamImpl;
293 IPstream mpiIPstreamImpl;
297 This way the administrator can provide a glocal +controlDict+ in
298 the FreeFOAM installation. Every user can then override that +controlDict+
299 by supplying her own file in her home directory as detailed
300 above. In order to select a particular +Pstream+ implementation for
301 a specific communications library, the user can then either adjust
302 the +PstreamImplementation::configName+ entry in the global
303 +controlDict+ file, set the +FREEFOAM_PSTREAM_CONFIG+ variable
304 or for full control, set the variables +FREEFOAM_PSTREAM_LIBRARY+,
305 +FREEFOAM_PSTREAM_CLASS+, +FREEFOAM_IPSTREAM_CLASS+ and
306 +FREEFOAM_OPSTREAM_CLASS+.
308 - Now you should be able to run the tutorial cases. For this copy the
309 +tutorials+ directory to some convenient place:
312 $ mkdir -p $HOME/FreeFOAM/$LOGNAME-1.5.0/run
313 $ cp -r $HOME/Source/FreeFOAM/tutorials $HOME/FreeFOAM/$LOGNAME-1.5.0/run/
314 $ cd $HOME/FreeFOAM/$LOGNAME-1.5.0/run
317 And try to run e.g. the 'cavity' tutorial case:
321 $ blockMesh -case cavity
322 $ checkMesh -case cavity
323 $ icoFoam -case cavity
326 Things should run smoothly and finish without an error.
328 WARNING: Currently the utility +paraFoam+ does not work, as it hasn't been
329 adapted to FreeFOAM. You have to make sure that ParaView finds the
330 plugins (by e.g. setting the +PV_PLUGIN_PATH+ environment variable to
331 the directory containing libPV3FoamReader.so) yourself. Then create an empty
332 file called +<something>.OpenFOAM+ (where +<something>+ is a name of
333 your choice) *in* the case directory and then start ParaView using
334 `paraview{nbsp}+++--data+++=<casedirectory>/<something>.OpenFOAM`.
335 Alternatively you can also start ParaView without any of the command
336 line arguments and then open the '<something>.OpenFOAM' file from within ParaView.
339 Configuration reference
340 ~~~~~~~~~~~~~~~~~~~~~~~
342 One of +<empty>+, +Debug+, +Release+, +RelWithDebInfo+ and +MinSizeRel+.
343 +CMAKE_INSTALL_PREFIX+::
346 If set to +DP+ FreeFOAM will be compiled using +double+ as the
347 floating point type. If set to +SP+ it will use +float+.
348 +FF_INSTALL_BIN_PATH+::
349 Installation path of the binaries. If not absolute, it is relative to
350 +CMAKE_INSTALL_PREFIX+.
351 +FF_INSTALL_CONFIG_PATH+::
352 Installation path of the configuration files. If not absolute, it is
353 relative to +CMAKE_INSTALL_PREFIX+.
354 +FF_BUILD_FRAMEWORK+::
355 If this is enabled, the libraries are built as frameworks. Only available on Mac OS X.
356 +FF_INSTALL_HEADER_PATH+::
357 Installation path of the header files. If not absolute, it is
358 relative to +CMAKE_INSTALL_PREFIX+. On Mac OS X, and if
359 +FF_BUILD_FRAMEWORK+ is enabled, this setting is ignored.
360 +FF_INSTALL_LIB_PATH+::
361 Installation path of the libraries. If not absolute, it is
362 relative to +CMAKE_INSTALL_PREFIX+. On Mac OS X, and if
363 +FF_BUILD_FRAMEWORK+ is enabled, this is the framework installation
365 +FF_INSTALL_PV3FOAMREADER_PATH+::
366 Installation path of the ParaView3 plugins. If not absolute, it is
367 relative to +CMAKE_INSTALL_PREFIX+.
368 +FF_INSTALL_PVFOAMREADER_PATH+::
369 Installation path of the ParaView2 plugins. If not absolute, it is
370 relative to +CMAKE_INSTALL_PREFIX+.
371 +FF_INSTALL_USERDFOAM_PATH+::
372 Installation path of the Ensight plugin. If not absolute, it is
373 relative to +CMAKE_INSTALL_PREFIX+.
375 If enabled, FreeFOAM will use the GAMMA parallel communications library.
377 If enabled, FreeFOAM will use the MPI parallel communications library.
378 This is required in order to build some of the libraries and utilities.
380 If enabled, FreeFOAM will use the PVM parallel communications library.
381 +FF_DEFAULT_PSTREAM+::
382 The default Pstream selection in the global controlDict file.
383 +FF_BUILD_PARAVIEW_PLUGINS+::
384 Whether to build the ParaView plugins. If enabled, FreeFOAM requires a
385 ParaView build tree and the +ParaView_DIR+ variable set to the path of it.
386 +FF_BUILD_PRIVATE_CCMIO+::
387 Automatically download and build libccmio. Unfortunately this process will
388 fail in the download step, since CMake currently does not support +https+
389 URLs. But you will get specific instructions from the build system on how to
390 get around this problem.
391 +FF_BUILD_PRIVATE_METIS+::
392 Automatically download and build METIS.
393 +FF_BUILD_PRIVATE_PARMETIS+::
394 Automatically download and build ParMetis.
395 +FF_BUILD_PRIVATE_PARMGRIDGEN+::
396 Automaticall download and build ParMGridGen/MGridgen.
400 http://www.OpenFOAM.org/doc
404 - http://freefoam.sourceforge.net
405 - https://lists.sourceforge.net/lists/listinfo/freefoam-user
406 - http://www.OpenFOAM.org/discussion.html *please only ask questions related
407 to _OpenFOAM_ there*.
409 Reporting Bugs in FreeFOAM
410 --------------------------
411 http://freefoam.sourceforge.net
413 ////////////////////////////////////////////////////////
414 Process with: asciidoc README
416 Vim users, this is for you:
417 vim: ft=asciidoc sw=2 expandtab fenc=utf-8
418 ////////////////////////////////////////////////////////