| blob | 59942eceab068ba6a4f2b8c8abdd0abd879c9f3a |
1 FreeFOAM README for version 1.5.0-1
2 ===================================
3 MichaelWild <themiwi@users.sourceforge.net>
4 v1.5.0-0, 7 Nov 2008
5 :Author Initials: MW
6 :linkcss!:
7 :numbered:
8 :toc:
9 http://freefoam.sourceforge.net
11 Copyright
12 ---------
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.
19 System requirements
20 -------------------
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
24 still far off.
26 Required software to build FreeFOAM
27 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
28 git::
29 Currently you need git to obtain the FreeFOAM source code. http://git.or.cz
30 CMake::
31 In order to build FreeFOAM you need to have CMake with version 2.6.2 or
32 newer installed. http://cmake.org
33 Build system::
34 CMake requires a native build system. On Unix like platforms I recomment
35 using GNU Make. http://www.gnu.org/software/make
36 C\+\+ compiler::
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
40 flex::
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
43 zlib::
44 zlib compression library. http://www.zlib.net
45 METIS::
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
49 MGridGen::
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
53 libccmio::
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
58 Optional software
59 ~~~~~~~~~~~~~~~~~
60 Parallel Library::
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.
68 ParMetis::
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
73 ParaView::
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.
78 http://paraview.org
79 M4::
80 Some of the provided tutorial cases require the M4 macro processor.
81 http://www.gnu.org/software/m4/
83 Installation
84 ------------
85 This section needs serious expanding, but the short version is:
87 - Install the prerequisites. If your distribution does not have
88 METIS, ParMetis, MGridGen or libccmio be not worried, FreeFOAM
89 can handle those for you.
90 - Clone the FreeFOAM repository (here the clone is placed in $HOME/Source/FreeFOAM):
91 +
92 ---------------------------------------------------------------------------
93 $ mkdir -p $HOME/Source
94 $ git clone git://repo.or.cz/freefoam.git $HOME/Source/FreeFOAM
95 $ cd $HOME/Source/FreeFOAM
96 ---------------------------------------------------------------------------
97 - Create a build tree and _cd_ into it:
98 +
99 ---------------
100 $ mkdir build
101 $ cd build
102 ---------------
103 - Start CMake-configuration:
104 +
105 ---------------
106 $ ccmake ..
107 ---------------
108 - Press the +c+ key. Use the arrow keys to navigate up and down and press +enter+ to
109 edit a field. To commit the change, press +enter+ again, or +ESC+ to abandon the change.
110 ON/OFF fields are toggled by pressing +enter+.
111 * Set +CMAKE_BUILD_TYPE+ to +Release+ for an optimized build.
112 * If CMake complains that it can't find MPI, and you don't want to install it, disable
113 +FF_USE_MPI+. If, instead, you want to use GAMMA or PVM, enable +FF_USE_GAMMA+ or
114 +FF_USE_PVM+, respectively. You can also enable more than one of the options.
115 +
116 [NOTE]
117 Currently only MPI and the dummy implementation are available.
118 +
119 * Select the default Pstream implementation by setting +FF_DEFAULT_PSTREAM+
120 by setting it to one of +dummy+, +mpi+, +pvm+ or +gamma+. This setting
121 will only influence the contents of the global controlDict file.
122 * If CMake told you it couldn't find ParaView:
123 . Set +ParaView_DIR+ to the path of the ParaView build directory if you have it.
124 . If you do not want to build the ParaView plugins, disable +FF_BUILD_PARAVIEW_PLUGINS+
125 * If you do not have METIS, ParMetis, MGridGen or libccmio installed, enable
126 +FF_BUILD_PRIVATE_METIS+, +FF_BUILD_PRIVATE_PARMETIS+, +FF_BUILD_PRIVATE_PARMGRIDGEN+ or
127 +FF_BUILD_PRIVATE_CCMIO+ respectively. CMake will then try to download and build
128 the selected libraries for you. Conversely, if you one of the libraries is provided
129 by your system, you can turn the respective setting to +OFF+. Please note that if
130 you system provides only +ParMetis+, you do not have to install +METIS+, as the
131 former also contains +METIS+.
132 * If you plan on installing FreeFOAM, set +CMAKE_INSTALL_PREFIX+ to the base directory
133 under which FreeFOAM should reside.
134 * For more fine-grained control over what gets installed where, adjust
135 +FF_INSTALL_CONFIG_PATH+, +FF_INSTALL_HEADER_PATH+, +FF_INSTALL_LIB_PATH+,
136 +FF_INSTALL_FRAMEWORK_PATH+, +FF_INSTALL_PV3FOAMREADER_PATH+,
137 +FF_INSTALL_PVFOAMREADER_PATH+ and +FF_INSTALL_USERDFOAM_PATH+.
138 * If you want FreeFOAM to use +float+ as the floating point type instead of
139 +double+, change +FF_DOUBLE_PRECISION+ to +OFF+.
140 - Hit the +c+ key again. If you enabled +FF_BUILD_PRIVATE_CCMIO+, CMake will fail
141 to download https://wci.llnl.gov/codes/visit/3rd_party/libccmio-2.6.1.tar.gz.
142 Please follow the instructions in the error message on how to work around this
143 problem, or download the file manually and place it in +ThirdParty/ccmio/+
144 (relative to the build directory). Then hit +c+ again.
145 - You shouldn't get any errors anymore now. Keep pressing +c+ until
146 the ccmake displays "++Press [g] to generate and exit++" in the legend at
147 the bottom of the interface.
148 - Press +g+ to generate the Makefiles and exit the ccmake interface.
149 - Start the native build tool. If you used the +Makefile+ generator
150 (which is the default for Unix-platforms), type
151 +
152 ----------------
153 $ make
154 ----------------
155 - If you have a multi-core/processor machine, you can speed things up
156 significantly by telling Make to run independent jobs in parallel.
157 A good choice for the number of parallel jobs to run is the
158 number of CPU's/cores you have in your machine plus 1 (to compensate
159 for disk-latency). For a typical dual-core machine, run
160 +
161 ----------------
162 $ make -j3
163 ----------------
164 - If you want to, you can now install FreeFOAM (depending on the
165 +CMAKE_INSTALL_PREFIX+ and the individual +FF_INSTALL_*_PATH+
166 it is possible that you have to do this as root, i.e. use
167 +su+ or +sudo+). However, this is optional and hasn't been
168 tested thoroughly, so you might overwrite some important files
169 of your system!
170 +
171 ---------------
172 $ make install
173 ---------------
175 Using FreeFOAM
176 ~~~~~~~~~~~~~~
177 - Make sure that your shell can find the FreeFOAM executables. If you want
178 to run FreeFOAM from the build tree (i.e. without installing), append
179 +<build_dir>/bin+ to your +PATH+ variable:
180 +
181 ----------
182 $ export PATH=$PATH:$HOME/Source/FreeFOAM/build/bin
183 ----------
184 +
185 This assumes that your build directory is +$HOME/Source/FreeFOAM/build+,
186 which should be the case if you followed above instructions. If it isn't,
187 you will have to adjust above command appropriately.
188 +
189 - On some systems it might be necessary to adjust the library search
190 path (although CMake should have taken care of this by using +RPATH+
191 on Linux and +install_name+ on Mac OS X):
192 +
193 -------------
194 $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/Source/FreeFOAM/build/lib/FreeFOAM-1.5.0
195 -------------
196 +
197 Again, this is assuming that your build tree is in +$HOME/Source/FreeFOAM/build+.
198 +
199 - Unfortunately the OpenFOAM library (on which FreeFOAM builds) and some
200 applications require some files to be present for start-up. It finds those
201 in the following places (in the specified order, picking the first hit):
202 +
203 --
204 1. Under the directory specified in the '$FREEFOAM_CONFIG_DIR' environment variable
205 2. In '$HOME/.FreeFOAM/1.5.0-0'
206 3. In '$HOME/.FreeFOAM'
207 4. In '<prefix>/<FF_INSTALL_CONFIG_PATH>', where '<prefix>' is the
208 installation prefix and '<FF_INSTALL_CONFIG_PATH>' is the value you
209 specified for the 'FF_INSTALL_CONFIG_PATH' property when configuring
210 FreeFOAM using ccmake. The former defaults to '/usr/local', the latter
211 to 'etc/FreeFOAM-1.5.0'.
212 --
213 +
214 So, if you want to run FreeFOAM from the build tree (i.e. without running
215 +make install+), you have the option to place the files under your home directory
216 or set an environment variable. The former can be achieved by:
217 +
218 --------------
219 $ mkdir -p $HOME/.FreeFOAM/1.5.0-0
220 $ cp $HOME/Source/FreeFOAM/etc/controlDict $HOME/.FreeFOAM/1.5.0-0
221 $ cp $HOME/Source/FreeFOAM/etc/cellModels $HOME/.FreeFOAM/1.5.0-0
222 $ cp -r $HOME/Source/FreeFOAM/etc/thermoData $HOME/.FreeFOAM/1.5.0-0
223 --------------
224 +
225 Or, if you prefer setting the environment variable:
226 +
227 ---------------
228 $ export FREEFOAM_CONFIG_DIR=$HOME/Source/FreeFOAM/etc
229 ----------------
230 +
231 Notice that this time '$HOME/Source/FreeFOAM' refers to the
232 root of the source tree, i.e. where your clone of the FreeFOAM
233 repository is. Adjust it to your actual setup.
235 - Both, FreeFOAM and OpenFOAM abstract the parallel operations into
236 the +Pstream+ library, making it firstly rather simple to switch between
237 parallel implementations and secondly to port the software to a new
238 communications library. However, FreeFOAM uses a much more flexible
239 mechanism of determining which +Pstream+ implementation library to
240 load than OpenFOAM. The latter did this by adjusting the +LD_LIBRARY_PATH+.
241 As FreeFOAM wants to be a well behaved Linux citizen, this is not an
242 option. Instead, FreeFOAM dynamically loads the desired +Pstream+
243 library at startup. The following list details how FreeFOAM determines
244 what library to load (if at all):
245 +
246 --
247 1. If the environment variable +FREEFOAM_PSTREAM_LIBRARY+ is set,
248 FreeFOAM will try to load the library specified in the value of
249 the variable.
250 2. If the sub-dictionary +PstreamImplementation+ exists in the global
251 +controlDict+ file (see above), it reads the value of the entry
252 +configName+ therein. It then expects that a sub-dictionary of
253 +PstreamImplementation+ with the name specified in +configName+
254 exists. If that sub-dictionary contains the entry +library+,
255 it will try to load a library spedified by the value of that
256 entry.
257 --
258 +
259 After FreeFOAM (possibly) loaded the library, it will try to instantiate
260 concrete implementations of the abstract base classes +PstreamImpl+,
261 +IPstreamImpl+ and +OPstreamImpl+. Which classes are to be instantiated
262 is determined as follows:
263 +
264 --
265 1. FreeFOAM queries the environment variables +FREEFOAM_PSTREAM_CLASS+,
266 +FREEFOAM_IPSTREAM_CLASS+ and +FREEFOAM_OPSTREAM_CLASS+ for the class
267 names to be instantiated.
268 2. Otherwise it requires the sub-dictionary +PstreamImplementation+
269 to be present in the global +controlDict+, reads the value of
270 +configName+ and similarly to the library loading,
271 loads the sub-dictionary specified by that value. It then expects
272 to find the entries +Pstream+, +IPstream+ and +OPstream+ which
273 specify the names of the classes to load.
274 --
275 +
276 This means that you can create a global +controlDict+ file containing
277 (among other things) something like the following:
279 PstreamImplementation
280 {
281 //configName dummy;
282 configName mpi;
284 dummy
285 {
286 library libdummyPstream.so;
287 Pstream dummyPstreamImpl;
288 OPstream dummyOPstreamImpl;
289 IPstream dummyIPstreamImpl;
290 }
292 mpi
293 {
294 library libmpiPstream.so;
295 Pstream mpiPstreamImpl;
296 OPstream mpiOPstreamImpl;
297 IPstream mpiIPstreamImpl;
298 }
299 }
300 +
301 This way the administrator can provide a glocal +controlDict+ in
302 the FreeFOAM installation. Every user can then override that +controlDict+
303 by supplying her own file in her home directory as detailed
304 above. In order to select a particular +Pstream+ implementation for
305 a specific communications library, the user can then either adjust
306 the +PstreamImplementation::configName+ entry in the global
307 +controlDict+ file, set the +FREEFOAM_PSTREAM_CONFIG+ variable
308 or for full control, set the variables +FREEFOAM_PSTREAM_LIBRARY+,
309 +FREEFOAM_PSTREAM_CLASS+, +FREEFOAM_IPSTREAM_CLASS+ and
310 +FREEFOAM_OPSTREAM_CLASS+.
312 - Now you should be able to run the tutorial cases. For this copy the
313 +tutorials+ directory to some convenient place:
314 +
315 ---------------
316 $ mkdir -p $HOME/FreeFOAM/$LOGNAME-1.5.0/run
317 $ cp -r $HOME/Source/FreeFOAM/tutorials $HOME/FreeFOAM/$LOGNAME-1.5.0/run/
318 $ cd $HOME/FreeFOAM/$LOGNAME-1.5.0/run
319 ---------------
320 +
321 And try to run e.g. the 'cavity' tutorial case:
322 +
323 ---------------
324 $ cd icoFoam
325 $ blockMesh -case cavity
326 $ checkMesh -case cavity
327 $ icoFoam -case cavity
328 ---------------
329 +
330 Things should run smoothly and finish without an error.
332 WARNING: Currently the utility +paraFoam+ does not work, as it hasn't been
333 adapted to FreeFOAM. You have to make sure that ParaView finds the
334 plugins (by e.g. setting the +PV_PLUGIN_PATH+ environment variable to
335 the directory containing libPV3FoamReader.so) yourself. Then create an empty
336 file called +<something>.OpenFOAM+ (where +<something>+ is a name of
337 your choice) *in* the case directory and then start ParaView using
338 `paraview{nbsp}+++--data+++=<casedirectory>/<something>.OpenFOAM`.
339 Alternatively you can also start ParaView without any of the command
340 line arguments and then open the '<something>.OpenFOAM' file from within ParaView.
343 Configuration reference
344 ~~~~~~~~~~~~~~~~~~~~~~~
345 +CMAKE_BUILD_TYPE+::
346 One of +<empty>+, +Debug+, +Release+, +RelWithDebInfo+ and +MinSizeRel+.
347 +CMAKE_INSTALL_PREFIX+::
348 Installation prefix
349 +FF_DOUBLE_PRECISION+::
350 If set to +ON+ FreeFOAM will be compiled using +double+ as the
351 floating point type. If set to +OFF+ it will use +float+.
352 +FF_INSTALL_BIN_PATH+::
353 Installation path of the binaries. If not absolute, it is relative to
354 +CMAKE_INSTALL_PREFIX+.
355 +FF_INSTALL_CONFIG_PATH+::
356 Installation path of the configuration files. If not absolute, it is
357 relative to +CMAKE_INSTALL_PREFIX+.
358 +FF_BUILD_FRAMEWORK+::
359 If this is enabled, the libraries are built as frameworks. Only available on Mac OS X.
360 +FF_INSTALL_HEADER_PATH+::
361 Installation path of the header files. If not absolute, it is
362 relative to +CMAKE_INSTALL_PREFIX+. On Mac OS X, and if
363 +FF_BUILD_FRAMEWORK+ is enabled, this setting is ignored.
364 +FF_INSTALL_LIB_PATH+::
365 Installation path of the libraries. If not absolute, it is
366 relative to +CMAKE_INSTALL_PREFIX+.
367 +FF_INSTALL_FRAMEWORK_PATH+::
368 Installation path of the Mac OS X frameworks. If not absolute, it is
369 relative to +CMAKE_INSTALL_PREFIX+. This is only available and takes
370 effect if FreeFOAM is compiled on Mac OS X, and if
371 +FF_BUILD_FRAMEWORK+ is enabled.
372 +FF_INSTALL_PV3FOAMREADER_PATH+::
373 Installation path of the ParaView3 plugins. If not absolute, it is
374 relative to +CMAKE_INSTALL_PREFIX+.
375 +FF_INSTALL_PVFOAMREADER_PATH+::
376 Installation path of the ParaView2 plugins. If not absolute, it is
377 relative to +CMAKE_INSTALL_PREFIX+.
378 +FF_INSTALL_USERDFOAM_PATH+::
379 Installation path of the Ensight plugin. If not absolute, it is
380 relative to +CMAKE_INSTALL_PREFIX+.
381 +FF_USE_GAMMA+::
382 If enabled, FreeFOAM will use the GAMMA parallel communications library.
383 +FF_USE_MPI+::
384 If enabled, FreeFOAM will use the MPI parallel communications library.
385 This is required in order to build some of the libraries and utilities.
386 +FF_USE_PVM+::
387 If enabled, FreeFOAM will use the PVM parallel communications library.
388 +FF_DEFAULT_PSTREAM+::
389 The default Pstream selection in the global controlDict file.
390 +FF_BUILD_PARAVIEW_PLUGINS+::
391 Whether to build the ParaView plugins. If enabled, FreeFOAM requires a
392 ParaView build tree and the +ParaView_DIR+ variable set to the path of it.
393 +FF_BUILD_PRIVATE_CCMIO+::
394 Automatically download and build libccmio. Unfortunately this process will
395 fail in the download step, since CMake currently does not support +https+
396 URLs. But you will get specific instructions from the build system on how to
397 get around this problem.
398 +FF_BUILD_PRIVATE_METIS+::
399 Automatically download and build METIS.
400 +FF_BUILD_PRIVATE_PARMETIS+::
401 Automatically download and build ParMetis.
402 +FF_BUILD_PRIVATE_PARMGRIDGEN+::
403 Automaticall download and build ParMGridGen/MGridgen.
404 +FF_BUILD_DOXYGEN_DOCS+::
405 Enable building of the Doxygen API documentation. To actually build it,
406 execute +make doc+.
408 Documentation
409 -------------
410 http://www.OpenFOAM.org/doc
412 Help
413 ----
414 - http://freefoam.sourceforge.net
415 - https://lists.sourceforge.net/lists/listinfo/freefoam-user
416 - http://www.OpenFOAM.org/discussion.html *please only ask questions related
417 to _OpenFOAM_ there*.
419 Reporting Bugs in FreeFOAM
420 --------------------------
421 http://freefoam.sourceforge.net
423 ////////////////////////////////////////////////////////
424 Process with: asciidoc README
426 Vim users, this is for you:
427 vim: ft=asciidoc sw=2 expandtab fenc=utf-8
428 ////////////////////////////////////////////////////////