| blob | 2231e6c9c8b450af59a7cbb86c1846cbe07a2b24 |
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_PV3FOAMREADER_PATH+, +FF_INSTALL_PVFOAMREADER_PATH+ and +FF_INSTALL_USERDFOAM_PATH+.
137 * If you want FreeFOAM to use +float+ as the floating point type instead of
138 +double+, change +FF_DOUBLE_PRECISION+ to +OFF+.
139 - Hit the +c+ key again. If you enabled +FF_BUILD_PRIVATE_CCMIO+, CMake will fail
140 to download https://wci.llnl.gov/codes/visit/3rd_party/libccmio-2.6.1.tar.gz.
141 Please follow the instructions in the error message on how to work around this
142 problem, or download the file manually and place it in +ThirdParty/ccmio/+
143 (relative to the build directory). Then hit +c+ again.
144 - You shouldn't get any errors anymore now. Keep pressing +c+ until
145 the ccmake displays "++Press [g] to generate and exit++" in the legend at
146 the bottom of the interface.
147 - Press +g+ to generate the Makefiles and exit the ccmake interface.
148 - Start the native build tool. If you used the +Makefile+ generator
149 (which is the default for Unix-platforms), type
150 +
151 ----------------
152 $ make
153 ----------------
154 - If you have a multi-core/processor machine, you can speed things up
155 significantly by telling Make to run independent jobs in parallel.
156 A good choice for the number of parallel jobs to run is the
157 number of CPU's/cores you have in your machine plus 1 (to compensate
158 for disk-latency). For a typical dual-core machine, run
159 +
160 ----------------
161 $ make -j3
162 ----------------
163 - If you want to, you can now install FreeFOAM (depending on the
164 +CMAKE_INSTALL_PREFIX+ and the individual +FF_INSTALL_*_PATH+
165 it is possible that you have to do this as root, i.e. use
166 +su+ or +sudo+). However, this is optional and hasn't been
167 tested thoroughly, so you might overwrite some important files
168 of your system!
169 +
170 ---------------
171 $ make install
172 ---------------
174 Using FreeFOAM
175 ~~~~~~~~~~~~~~
176 - Make sure that your shell can find the FreeFOAM executables. If you want
177 to run FreeFOAM from the build tree (i.e. without installing), append
178 +<build_dir>/bin+ to your +PATH+ variable:
179 +
180 ----------
181 $ export PATH=$PATH:$HOME/Source/FreeFOAM/build/bin
182 ----------
183 +
184 This assumes that your build directory is +$HOME/Source/FreeFOAM/build+,
185 which should be the case if you followed above instructions. If it isn't,
186 you will have to adjust above command appropriately.
187 +
188 - On some systems it might be necessary to adjust the library search
189 path (although CMake should have taken care of this by using +RPATH+
190 on Linux and +install_name+ on Mac OS X):
191 +
192 -------------
193 $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/Source/FreeFOAM/build/lib/FreeFOAM-1.5.0
194 -------------
195 +
196 Again, this is assuming that your build tree is in +$HOME/Source/FreeFOAM/build+.
197 +
198 - Unfortunately the OpenFOAM library (on which FreeFOAM builds) and some
199 applications require some files to be present for start-up. It finds those
200 in the following places (in the specified order, picking the first hit):
201 +
202 --
203 1. Under the directory specified in the '$FREEFOAM_CONFIG_DIR' environment variable
204 2. In '$HOME/.FreeFOAM/1.5.0-0'
205 3. In '$HOME/.FreeFOAM'
206 4. In '<prefix>/<FF_INSTALL_CONFIG_PATH>', where '<prefix>' is the
207 installation prefix and '<FF_INSTALL_CONFIG_PATH>' is the value you
208 specified for the 'FF_INSTALL_CONFIG_PATH' property when configuring
209 FreeFOAM using ccmake. The former defaults to '/usr/local', the latter
210 to 'etc/FreeFOAM-1.5.0'.
211 --
212 +
213 So, if you want to run FreeFOAM from the build tree (i.e. without running
214 +make install+), you have the option to place the files under your home directory
215 or set an environment variable. The former can be achieved by:
216 +
217 --------------
218 $ mkdir -p $HOME/.FreeFOAM/1.5.0-0
219 $ cp $HOME/Source/FreeFOAM/etc/controlDict $HOME/.FreeFOAM/1.5.0-0
220 $ cp $HOME/Source/FreeFOAM/etc/cellModels $HOME/.FreeFOAM/1.5.0-0
221 $ cp -r $HOME/Source/FreeFOAM/etc/thermoData $HOME/.FreeFOAM/1.5.0-0
222 --------------
223 +
224 Or, if you prefer setting the environment variable:
225 +
226 ---------------
227 $ export FREEFOAM_CONFIG_DIR=$HOME/Source/FreeFOAM/etc
228 ----------------
229 +
230 Notice that this time '$HOME/Source/FreeFOAM' refers to the
231 root of the source tree, i.e. where your clone of the FreeFOAM
232 repository is. Adjust it to your actual setup.
234 - Both, FreeFOAM and OpenFOAM abstract the parallel operations into
235 the +Pstream+ library, making it firstly rather simple to switch between
236 parallel implementations and secondly to port the software to a new
237 communications library. However, FreeFOAM uses a much more flexible
238 mechanism of determining which +Pstream+ implementation library to
239 load than OpenFOAM. The latter did this by adjusting the +LD_LIBRARY_PATH+.
240 As FreeFOAM wants to be a well behaved Linux citizen, this is not an
241 option. Instead, FreeFOAM dynamically loads the desired +Pstream+
242 library at startup. The following list details how FreeFOAM determines
243 what library to load (if at all):
244 +
245 --
246 1. If the environment variable +FREEFOAM_PSTREAM_LIBRARY+ is set,
247 FreeFOAM will try to load the library specified in the value of
248 the variable.
249 2. If the sub-dictionary +PstreamImplementation+ exists in the global
250 +controlDict+ file (see above), it reads the value of the entry
251 +configName+ therein. It then expects that a sub-dictionary of
252 +PstreamImplementation+ with the name specified in +configName+
253 exists. If that sub-dictionary contains the entry +library+,
254 it will try to load a library spedified by the value of that
255 entry.
256 --
257 +
258 After FreeFOAM (possibly) loaded the library, it will try to instantiate
259 concrete implementations of the abstract base classes +PstreamImpl+,
260 +IPstreamImpl+ and +OPstreamImpl+. Which classes are to be instantiated
261 is determined as follows:
262 +
263 --
264 1. FreeFOAM queries the environment variables +FREEFOAM_PSTREAM_CLASS+,
265 +FREEFOAM_IPSTREAM_CLASS+ and +FREEFOAM_OPSTREAM_CLASS+ for the class
266 names to be instantiated.
267 2. Otherwise it requires the sub-dictionary +PstreamImplementation+
268 to be present in the global +controlDict+, reads the value of
269 +configName+ and similarly to the library loading,
270 loads the sub-dictionary specified by that value. It then expects
271 to find the entries +Pstream+, +IPstream+ and +OPstream+ which
272 specify the names of the classes to load.
273 --
274 +
275 This means that you can create a global +controlDict+ file containing
276 (among other things) something like the following:
278 PstreamImplementation
279 {
280 //configName dummy;
281 configName mpi;
283 dummy
284 {
285 library libdummyPstream.so;
286 Pstream dummyPstreamImpl;
287 OPstream dummyOPstreamImpl;
288 IPstream dummyIPstreamImpl;
289 }
291 mpi
292 {
293 library libmpiPstream.so;
294 Pstream mpiPstreamImpl;
295 OPstream mpiOPstreamImpl;
296 IPstream mpiIPstreamImpl;
297 }
298 }
299 +
300 This way the administrator can provide a glocal +controlDict+ in
301 the FreeFOAM installation. Every user can then override that +controlDict+
302 by supplying her own file in her home directory as detailed
303 above. In order to select a particular +Pstream+ implementation for
304 a specific communications library, the user can then either adjust
305 the +PstreamImplementation::configName+ entry in the global
306 +controlDict+ file, set the +FREEFOAM_PSTREAM_CONFIG+ variable
307 or for full control, set the variables +FREEFOAM_PSTREAM_LIBRARY+,
308 +FREEFOAM_PSTREAM_CLASS+, +FREEFOAM_IPSTREAM_CLASS+ and
309 +FREEFOAM_OPSTREAM_CLASS+.
311 - Now you should be able to run the tutorial cases. For this copy the
312 +tutorials+ directory to some convenient place:
313 +
314 ---------------
315 $ mkdir -p $HOME/FreeFOAM/$LOGNAME-1.5.0/run
316 $ cp -r $HOME/Source/FreeFOAM/tutorials $HOME/FreeFOAM/$LOGNAME-1.5.0/run/
317 $ cd $HOME/FreeFOAM/$LOGNAME-1.5.0/run
318 ---------------
319 +
320 And try to run e.g. the 'cavity' tutorial case:
321 +
322 ---------------
323 $ cd icoFoam
324 $ blockMesh -case cavity
325 $ checkMesh -case cavity
326 $ icoFoam -case cavity
327 ---------------
328 +
329 Things should run smoothly and finish without an error.
331 WARNING: Currently the utility +paraFoam+ does not work, as it hasn't been
332 adapted to FreeFOAM. You have to make sure that ParaView finds the
333 plugins (by e.g. setting the +PV_PLUGIN_PATH+ environment variable to
334 the directory containing libPV3FoamReader.so) yourself. Then create an empty
335 file called +<something>.OpenFOAM+ (where +<something>+ is a name of
336 your choice) *in* the case directory and then start ParaView using
337 `paraview{nbsp}+++--data+++=<casedirectory>/<something>.OpenFOAM`.
338 Alternatively you can also start ParaView without any of the command
339 line arguments and then open the '<something>.OpenFOAM' file from within ParaView.
342 Configuration reference
343 ~~~~~~~~~~~~~~~~~~~~~~~
344 +CMAKE_BUILD_TYPE+::
345 One of +<empty>+, +Debug+, +Release+, +RelWithDebInfo+ and +MinSizeRel+.
346 +CMAKE_INSTALL_PREFIX+::
347 Installation prefix
348 +FF_DOUBLE_PRECISION+::
349 If set to +ON+ FreeFOAM will be compiled using +double+ as the
350 floating point type. If set to +OFF+ it will use +float+.
351 +FF_INSTALL_BIN_PATH+::
352 Installation path of the binaries. If not absolute, it is relative to
353 +CMAKE_INSTALL_PREFIX+.
354 +FF_INSTALL_CONFIG_PATH+::
355 Installation path of the configuration files. If not absolute, it is
356 relative to +CMAKE_INSTALL_PREFIX+.
357 +FF_BUILD_FRAMEWORK+::
358 If this is enabled, the libraries are built as frameworks. Only available on Mac OS X.
359 +FF_INSTALL_HEADER_PATH+::
360 Installation path of the header files. If not absolute, it is
361 relative to +CMAKE_INSTALL_PREFIX+. On Mac OS X, and if
362 +FF_BUILD_FRAMEWORK+ is enabled, this setting is ignored.
363 +FF_INSTALL_LIB_PATH+::
364 Installation path of the libraries. If not absolute, it is
365 relative to +CMAKE_INSTALL_PREFIX+. On Mac OS X, and if
366 +FF_BUILD_FRAMEWORK+ is enabled, this is the framework installation
367 path.
368 +FF_INSTALL_PV3FOAMREADER_PATH+::
369 Installation path of the ParaView3 plugins. If not absolute, it is
370 relative to +CMAKE_INSTALL_PREFIX+.
371 +FF_INSTALL_PVFOAMREADER_PATH+::
372 Installation path of the ParaView2 plugins. If not absolute, it is
373 relative to +CMAKE_INSTALL_PREFIX+.
374 +FF_INSTALL_USERDFOAM_PATH+::
375 Installation path of the Ensight plugin. If not absolute, it is
376 relative to +CMAKE_INSTALL_PREFIX+.
377 +FF_USE_GAMMA+::
378 If enabled, FreeFOAM will use the GAMMA parallel communications library.
379 +FF_USE_MPI+::
380 If enabled, FreeFOAM will use the MPI parallel communications library.
381 This is required in order to build some of the libraries and utilities.
382 +FF_USE_PVM+::
383 If enabled, FreeFOAM will use the PVM parallel communications library.
384 +FF_DEFAULT_PSTREAM+::
385 The default Pstream selection in the global controlDict file.
386 +FF_BUILD_PARAVIEW_PLUGINS+::
387 Whether to build the ParaView plugins. If enabled, FreeFOAM requires a
388 ParaView build tree and the +ParaView_DIR+ variable set to the path of it.
389 +FF_BUILD_PRIVATE_CCMIO+::
390 Automatically download and build libccmio. Unfortunately this process will
391 fail in the download step, since CMake currently does not support +https+
392 URLs. But you will get specific instructions from the build system on how to
393 get around this problem.
394 +FF_BUILD_PRIVATE_METIS+::
395 Automatically download and build METIS.
396 +FF_BUILD_PRIVATE_PARMETIS+::
397 Automatically download and build ParMetis.
398 +FF_BUILD_PRIVATE_PARMGRIDGEN+::
399 Automaticall download and build ParMGridGen/MGridgen.
400 +FF_BUILD_DOXYGEN_DOCS+::
401 Enable building of the Doxygen API documentation. To actually build it,
402 execute +make doc+.
404 Documentation
405 -------------
406 http://www.OpenFOAM.org/doc
408 Help
409 ----
410 - http://freefoam.sourceforge.net
411 - https://lists.sourceforge.net/lists/listinfo/freefoam-user
412 - http://www.OpenFOAM.org/discussion.html *please only ask questions related
413 to _OpenFOAM_ there*.
415 Reporting Bugs in FreeFOAM
416 --------------------------
417 http://freefoam.sourceforge.net
419 ////////////////////////////////////////////////////////
420 Process with: asciidoc README
422 Vim users, this is for you:
423 vim: ft=asciidoc sw=2 expandtab fenc=utf-8
424 ////////////////////////////////////////////////////////