| blob | f10978ba2738026d8facc73a9daa49205e6378bb |
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
80 Installation
81 ------------
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):
88 +
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:
95 +
96 ---------------
97 $ mkdir build
98 $ cd build
99 ---------------
100 - Start CMake-configuration:
101 +
102 ---------------
103 $ ccmake ..
104 ---------------
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.
112 +
113 [NOTE]
114 Currently only MPI and the dummy implementation are available.
115 +
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
147 +
148 ----------------
149 $ make
150 ----------------
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
156 +
157 ----------------
158 $ make -j3
159 ----------------
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
165 of your system!
166 +
167 ---------------
168 $ make install
169 ---------------
171 Using FreeFOAM
172 ~~~~~~~~~~~~~~
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:
176 +
177 ----------
178 $ export PATH=$PATH:$HOME/Source/FreeFOAM/build/bin
179 ----------
180 +
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.
184 +
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):
188 +
189 -------------
190 $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/Source/FreeFOAM/build/lib/FreeFOAM-1.5.0
191 -------------
192 +
193 Again, this is assuming that your build tree is in +$HOME/Source/FreeFOAM/build+.
194 +
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):
198 +
199 --
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'.
208 --
209 +
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:
213 +
214 --------------
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
219 --------------
220 +
221 Or, if you prefer setting the environment variable:
222 +
223 ---------------
224 $ export FREEFOAM_CONFIG_DIR=$HOME/Source/FreeFOAM/etc
225 ----------------
226 +
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):
241 +
242 --
243 1. If the environment variable +FREEFOAM_PSTREAM_LIBRARY+ is set,
244 FreeFOAM will try to load the library specified in the value of
245 the variable.
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
252 entry.
253 --
254 +
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:
259 +
260 --
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.
270 --
271 +
272 This means that you can create a global +controlDict+ file containing
273 (among other things) something like the following:
275 PstreamImplementation
276 {
277 //configName dummy;
278 configName mpi;
280 dummy
281 {
282 library libdummyPstream.so;
283 Pstream dummyPstreamImpl;
284 OPstream dummyOPstreamImpl;
285 IPstream dummyIPstreamImpl;
286 }
288 mpi
289 {
290 library libmpiPstream.so;
291 Pstream mpiPstreamImpl;
292 OPstream mpiOPstreamImpl;
293 IPstream mpiIPstreamImpl;
294 }
295 }
296 +
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:
310 +
311 ---------------
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
315 ---------------
316 +
317 And try to run e.g. the 'cavity' tutorial case:
318 +
319 ---------------
320 $ cd icoFoam
321 $ blockMesh -case cavity
322 $ checkMesh -case cavity
323 $ icoFoam -case cavity
324 ---------------
325 +
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 ~~~~~~~~~~~~~~~~~~~~~~~
341 +CMAKE_BUILD_TYPE+::
342 One of +<empty>+, +Debug+, +Release+, +RelWithDebInfo+ and +MinSizeRel+.
343 +CMAKE_INSTALL_PREFIX+::
344 Installation prefix
345 +FF_PRECISION+::
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_INSTALL_HEADER_PATH+::
355 Installation path of the header files. If not absolute, it is
356 relative to +CMAKE_INSTALL_PREFIX+. On Mac OS X, and if
357 +FF_BUILD_FRAMEWORK+ is enabled, this setting is ignored.
358 +FF_INSTALL_LIB_PATH+::
359 Installation path of the libraries. If not absolute, it is
360 relative to +CMAKE_INSTALL_PREFIX+. On Mac OS X, and if
361 +FF_BUILD_FRAMEWORK+ is enabled, this is the framework installation
362 path.
363 +FF_INSTALL_PV3FOAMREADER_PATH+::
364 Installation path of the ParaView3 plugins. If not absolute, it is
365 relative to +CMAKE_INSTALL_PREFIX+.
366 +FF_INSTALL_PVFOAMREADER_PATH+::
367 Installation path of the ParaView2 plugins. If not absolute, it is
368 relative to +CMAKE_INSTALL_PREFIX+.
369 +FF_INSTALL_USERDFOAM_PATH+::
370 Installation path of the Ensight plugin. If not absolute, it is
371 relative to +CMAKE_INSTALL_PREFIX+.
372 +FF_USE_GAMMA+::
373 If enabled, FreeFOAM will use the GAMMA parallel communications library.
374 +FF_USE_MPI+::
375 If enabled, FreeFOAM will use the MPI parallel communications library.
376 This is required in order to build some of the libraries and utilities.
377 +FF_USE_PVM+::
378 If enabled, FreeFOAM will use the PVM parallel communications library.
379 +FF_DEFAULT_PSTREAM+::
380 The default Pstream selection in the global controlDict file.
381 +FF_BUILD_PARAVIEW_PLUGINS+::
382 Whether to build the ParaView plugins. If enabled, FreeFOAM requires a
383 ParaView build tree and the +ParaView_DIR+ variable set to the path of it.
384 +FF_BUILD_PRIVATE_CCMIO+::
385 Automatically download and build libccmio. Unfortunately this process will
386 fail in the download step, since CMake currently does not support +https+
387 URLs. But you will get specific instructions from the build system on how to
388 get around this problem.
389 +FF_BUILD_PRIVATE_METIS+::
390 Automatically download and build METIS.
391 +FF_BUILD_PRIVATE_PARMETIS+::
392 Automatically download and build ParMetis.
393 +FF_BUILD_PRIVATE_PARMGRIDGEN+::
394 Automaticall download and build ParMGridGen/MGridgen.
396 Documentation
397 -------------
398 http://www.OpenFOAM.org/doc
400 Help
401 ----
402 - http://freefoam.sourceforge.net
403 - https://lists.sourceforge.net/lists/listinfo/freefoam-user
404 - http://www.OpenFOAM.org/discussion.html *please only ask questions related
405 to _OpenFOAM_ there*.
407 Reporting Bugs in FreeFOAM
408 --------------------------
409 http://freefoam.sourceforge.net
411 ////////////////////////////////////////////////////////
412 Process with: asciidoc README
414 Vim users, this is for you:
415 vim: ft=asciidoc sw=2 expandtab fenc=utf-8
416 ////////////////////////////////////////////////////////