doc/man/manSource/freefoam.1.in.txt

   1 = FREEFOAM(1) =
   2 :mansource: @PROJECT_NAME@
   3 :manversion: @FOAM_VERSION_FULL@
   4 :manmanual: @PROJECT_NAME@ Manual
   5
   6 NAME
   7 ----
   8 @LOWER_PROJECT_NAME@ - The Cross-Platform CFD Toolkit
   9
  10 SYNOPSIS
  11 --------
  12 *@LOWER_PROJECT_NAME@* [-b '<baseDir>'] [-P] [-V | -version] [-h | -help] [--]
  13            '<application>' ['<args>']
  14
  15 DESCRIPTION
  16 -----------
  17 FreeFOAM is a cross-platform toolkit for computational fluid dynamics (CFD). It
  18 consists of a large collection of C++ libraries, allowing the user to write
  19 new solvers for partial differential equations using a notation very close to
  20 the mathematical one. FreeFOAM comes with a comprehensive set of solvers for a
  21 wide range of problems and accompanying pre-/and post-processing utilities.
  22
  23 FreeFOAM is based on the fantastic Open-Source OpenFOAM software. The goal
  24 of the FreeFOAM project is to remove the system-dependencies from OpenFOAM and
  25 make it generally more useable and easier to install.
  26
  27 The linkff:@LOWER_PROJECT_NAME@[1] command is used to invoke the actual FreeFOAM
  28 applications. It was mainly created to avoid putting a large number of
  29 binaries on the system +PATH+, cluttering the namespace unnecessarily. It also
  30 allows for the user to easily add her own applications to the search path,
  31 without having to extend the +PATH+ variable or being root.
  32
  33 linkff:@LOWER_PROJECT_NAME@[1] uses the following mechanism to find the
  34 application '<name>':
  35
  36 - It searches in the directory '<libexecDir>' for an executable with the name
  37   '@FOAM_EXE_PREFIX@<name>'. '<libexecDir>' defaults to '@FOAM_INSTALL_LIBEXEC_PATH@'.
  38   This can be overridden using the '-b' option.
  39 - If the +FREEFOAM_PATH+ variable is set, it is prepended to the above
  40   described search path. It is a colon-separated list of directories.
  41 - The '-P' option can be used to append the system +PATH+ to the search path.
  42
  43 OPTIONS
  44 -------
  45 *-b* '<baseDir>'::
  46   Specify a different directory to search for applications
  47   (default is @FOAM_INSTALL_LIBEXEC_PATH@)
  48 *-P*::
  49   Also search the system PATH variable first
  50 *--*::
  51   Separates options for this program from the application and its arguments
  52   (useful if the application name should start with a -)
  53 *-V | -version*::
  54   Display the version of FreeFOAM and exit
  55 *-h | -help*::
  56   Display an option summary
  57 '<application>'::
  58   The short name of the application to run (i.e. for the '@FOAM_EXE_PREFIX@ico'
  59   application the short name would be 'ico')
  60 '<args>'::
  61   Arguments and options to be passed to the application
  62
  63 environment variables:
  64   FREEFOAM_PATH specify an alternative path where to search for applications
  65
  66 FREEFOAM STANDARD APPLICATIONS
  67 ------------------------------
  68 The following sections give a short description for all the available standard
  69 solvers and utilities. More information is available from the individual manual
  70 pages.
  71
  72 include::brief_app_doc.txt[]
  73
  74 FreeFOAM Helper Scripts
  75 ~~~~~~~~~~~~~~~~~~~~~~~
  76 Below you find an overview of the small helper scripts provided by FreeFOAM.
  77
  78 *linkff:freefoam-clearPolyMesh[1]*::
  79   Remove the contents of the constant/polyMesh directory.
  80
  81 *linkff:freefoam-copySettings[1]*::
  82   Copy settings from one case directory to another, without copying the mesh or
  83   results.
  84
  85 *linkff:freefoam-graphExecTime[1]*::
  86   Computes the time used per iteration.
  87
  88 *linkff:freefoam-graphResKE[1]*::
  89   Extract the residuals of k and epsilon at each time step.
  90
  91 *linkff:freefoam-graphResUVWP[1]*::
  92   Extract the residuals of 'U', 'V', 'W' and 'p' at each time step.
  93
  94 *linkff:freefoam-job[1]*::
  95   Runs a @PROJECT_NAME@ job in the background.
  96
  97 *linkff:freefoam-log[1]*::
  98   Extracts xy files from Foam logs.
  99
 100 *linkff:freefoam-para[1]*::
 101   Start ParaView3 to visualize a case.
 102
 103 *linkff:freefoam-solverSweeps[1]*::
 104   Extract solver statistics from a log file.
 105
 106 CONFIGURATION MECHANISM
 107 -----------------------
 108 FreeFOAM offers a number of global configuration options. These include
 109
 110 - location of the API documentation and the method to display it
 111 - debug, info and optimisation switches
 112 - physical constants
 113 - plugin search paths
 114 - parallel communications method
 115 - starting of a parallel job
 116
 117 Global Configuration Files
 118 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 119 Unfortunately the OpenFOAM library (on which FreeFOAM builds) and some
 120 applications require the following files to be present for start-up:
 121
 122 - 'cellModels'
 123 - 'controlDict'
 124 - 'thermoData/BurcatCpData'
 125 - 'thermoData/therm.dat'
 126
 127 It finds them in the following places
 128 (in the specified order, picking the first hit):
 129
 130 1. Under the directory specified in the +$FREEFOAM_CONFIG_DIR+ environment
 131    variable
 132 2. In '$HOME/.FreeFOAM/{shortver}'
 133 3. In '$HOME/.FreeFOAM'
 134 4. In the installation directory of the configuration files,
 135    '@FOAM_INSTALL_CONFIG_PATH@'
 136
 137 where the versions in above directory names depend on the version of the
 138 FreeFOAM application to be run.
 139
 140 Locating the API documentation
 141 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 142 All FreeFOAM applications accept the options '-doc' and '-srcDoc'. The former
 143 locates and displays the API documentation of the application, the latter the
 144 source code. This, however, requires that FreeFOAM is able to locate the API
 145 documentation and knows which program to use for display.
 146
 147 By default FreeFOAM uses the API documentation provided on
 148 http://freefoam.sf.net/doc/API because most users will not want to
 149 install the sizeable documentation package. The method FreeFOAM uses to locate
 150 the documentation files is via index files which are conventional FreeFOAM
 151 dictionaries. Each of them contains an entry 'docDir' specifying the documentation
 152 root location (such as http://freefoam.sf.net/doc/API) and a
 153 dictionary called 'docFiles' mapping the application name to the names of the
 154 corresponding HTML documentation and source page.
 155
 156 These documentation indices are found by querying the list
 157 'Documentation::doxyDocIndices' in the global 'controlDict' file. If multiple
 158 documentation indices are specified, the first index that provides documentation
 159 for the given application is picked.
 160
 161 Displaying the API documentation
 162 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 163 FreeFOAM can automatically open a browser window displaying the HTML documentation
 164 for you. The entry 'Documentation::docBrowser' in the global 'controlDict' can be
 165 used to change which program is used for this. In this string the token '%f' gets
 166 replaced by the filename to open.
 167
 168 Debug, Info and Optimisation Switches
 169 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 170 The lists 'DebugSwitches', 'InfoSwitches' and 'OptimisationSwitches' in the
 171 global 'controlDict' file determine some global run-time behaviour of FreeFOAM.
 172 The entries in 'DebugSwitches' can be set to '1' for more verbose output in the
 173 specified class.
 174
 175 The 'InfoSwitches::writePrecision' setting determines the write precision in
 176 the output to the terminal (i.e. not the output written to files).  Whether a
 177 job-info file should be created can be specified by enabling
 178 'InfoSwitches::writeJobeInfo'.
 179
 180 For files that are modifieable during run-time (e.g. to change the interval at
 181 which the output is created), FreeFOAM compares the modification times of these
 182 files in order to determine whether they have to be re-read. The setting
 183 'OptimisationSwitches::fileModificationSkew' determines the minimum
 184 modification-time difference in seconds for a file to be considered changed.
 185
 186 The setting 'OptimisationSwitches::commsType' determines whether inter-process
 187 communications are either 'blocking', 'scheduled' or 'nonBlocking'.
 188
 189 'OptimisationSwitches::floatTransfer' causes to convert 'double' values to
 190 'float' before transferring them through the communications library. This saves
 191 some bandwidth at the loss of accuracy.
 192
 193 The sum operation across processors can be executed either in a linear or a
 194 tree fashion. Especially for a large number of processors, tree-summation is
 195 significantly faster. The threshold at which to switch from linear to
 196 tree-summation is determined by 'OptimisationSwitches::nProcsSimpleSum'.
 197
 198 Physical Constants
 199 ~~~~~~~~~~~~~~~~~~
 200 'DimensionedConstants::R'::
 201   Universal gas constant
 202
 203 'DimensionedConstants::Pstd'::
 204   Standard pressure
 205
 206 'DimensionedConstants::Tstd'::
 207   Standard temperature
 208
 209 'DimensionedConstants::sigmaSB'::
 210   Stefan-Boltzmann constant
 211
 212 Plugin Search Path
 213 ~~~~~~~~~~~~~~~~~~
 214 FreeFOAM very often relies on dynamically loading libraries (a.k.a plugins).
 215 If the library name is given as an absolute path, FreeFOAM tries to load it
 216 directly. To locate libraries specified just by their name or with a relative
 217 path, FreeFOAM first tries to find the library in one of the directories
 218 specified in the list 'LibrarySearchPaths' in the global 'controlDict' and, if
 219 the library was not found, falls back to the mechanism provided by your
 220 operating system (i.e. for Linux systems this would be the +LD_LIBRARY_PATH+
 221 and the default search path).
 222
 223 Selecting the Parallel Communications Library
 224 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 225 Both, FreeFOAM and OpenFOAM abstract the parallel operations into the 'Pstream'
 226 library, making it rather simple to firstly switch between parallel
 227 implementations and secondly port the software to a new communications library.
 228 However, FreeFOAM uses a much more flexible mechanism of determining which
 229 'Pstream' implementation library to use than OpenFOAM. The latter does this by
 230 adjusting the +LD_LIBRARY_PATH+ environment variable.  As FreeFOAM wants to be a
 231 well behaved Linux citizen, this is not an option. Instead, FreeFOAM dynamically
 232 loads the desired 'Pstream' library at startup (i.e. as a plug-in).  The
 233 following list details how FreeFOAM determines what library to load (if at all):
 234
 235 1. If the environment variable +FREEFOAM_PSTREAM_LIBRARY+ is set,
 236    FreeFOAM will try to load the library specified by it.
 237 2. If the sub-dictionary +PstreamImplementation+ exists in the global
 238    'controlDict' file (see above), it reads the value of the entry
 239    +PstreamImplementation::configName+ therein. This entry can be overridden by
 240    setting the +FREEFOAM_PSTREAM_CONFIG+ environment variable. It then expects
 241    that a sub-dictionary of +PstreamImplementation+ with the name specified in
 242    +FREEFOAM_PSTREAM_CONFIG+ or +PstreamImplementation::configName+ exists. If
 243    that sub-dictionary contains the entry +PstreamImplementation::library+, it
 244    will try to load a library specified by the value of that entry.
 245
 246 Please note that this library is also considered to be a plugin, and thus
 247 is located in the same way as described above.
 248
 249 After FreeFOAM (possibly) loaded the library, it will try to instantiate
 250 concrete implementations of the abstract base classes +PstreamImpl+,
 251 +IPstreamImpl+ and +OPstreamImpl+. Which classes are to be instantiated
 252 is determined as follows:
 253
 254 1. FreeFOAM queries the environment variables +FREEFOAM_PSTREAM_CLASS+,
 255    +FREEFOAM_IPSTREAM_CLASS+ and +FREEFOAM_OPSTREAM_CLASS+ for the class
 256    names to be instantiated.
 257 2. For any of the variables not set,  it requires the sub-dictionary
 258    +PstreamImplementation+ to be present in the global 'controlDict', reads the
 259    value of +FREEFOAM_PSTREAM_CONFIG+ or the entry
 260    +PstreamImplementation::configName+ and similarly to the library loading,
 261    loads the sub-dictionary specified by that value. It then expects to find
 262    the entries +PstreamImplementation::Pstream+,
 263    +PstreamImplementation::IPstream+ and +PstreamImplementation::OPstream+
 264    which specify the names of the classes to load.
 265
 266 This means that one can create a global 'controlDict' file containing
 267 (among other things) something like the following:
 268 =========
 269 ---------
 270 PstreamImplementation
 271 {
 272     //configName dummy;
 273     configName mpi;
 274
 275     dummy
 276     {
 277         library libdummyPstream.so;
 278         Pstream dummyPstreamImpl;
 279         OPstream dummyOPstreamImpl;
 280         IPstream dummyIPstreamImpl;
 281     }
 282
 283     mpi
 284     {
 285         library libmpiPstream.so;
 286         Pstream mpiPstreamImpl;
 287         OPstream mpiOPstreamImpl;
 288         IPstream mpiIPstreamImpl;
 289     }
 290 }
 291 ---------
 292 =========
 293
 294 This way the administrator can provide a global 'controlDict' in the FreeFOAM
 295 installation. Every user can then override that 'controlDict' by supplying her
 296 own file in her home directory as detailed above. In order to select a
 297 particular 'Pstream' implementation for a specific communications library, the
 298 user can then either adjust the +PstreamImplementation::configName+ entry in
 299 the global 'controlDict' file, set the +FREEFOAM_PSTREAM_CONFIG+ variable or,
 300 for full control, set the variables +FREEFOAM_PSTREAM_LIBRARY+,
 301 +FREEFOAM_PSTREAM_CLASS+, +FREEFOAM_IPSTREAM_CLASS+ and
 302 +FREEFOAM_OPSTREAM_CLASS+.
 303
 304 Starting of a Parallel Job
 305 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 306 Some of the tutorial scripts need to run FreeFOAM applications in parallel.
 307 However, how to do so differs strongly from system to system and between
 308 parallel communication libraries. This is why the command line to start an
 309 application in parallel is configureable in the +parRunTemplate+ setting.
 310 '$\{NPROCS\}', '$\{PAROPTS\}', '$\{APPLICATION\}' and '$\{ARGS\}' are
 311 placeholders for the number of processors to use, options for the parallel
 312 communications system, the application to run and its arguments, respectively.
 313 Note that the '-parallel' option is *NOT* included in '$\{ARGS\}'.
 314
 315 ENVIRONMENT VARIABLES
 316 ---------------------
 317 +FREEFOAM_CONFIG_DIR+::
 318   Directory containing the global configuration files
 319 +FREEFOAM_PATH+::
 320   Additional, colon separated paths in which to first search for FreeFOAM
 321   executables
 322 +FREEFOAM_PSTREAM_CONFIG+::
 323   Name of the 'Pstream' configuration in the global 'controlDict' file to use
 324 +FREEFOAM_PSTREAM_LIBRARY+::
 325   The 'Pstream' library to load
 326 +FREEFOAM_PSTREAM_CLASS+::
 327   Name of the concrete 'PstreamImpl' class to instantiate
 328 +FREEFOAM_IPSTREAM_CLASS+::
 329   Name of the concrete 'IPstreamImpl' class to instantiate
 330 +FREEFOAM_OPSTREAM_CLASS+::
 331   Name of the concrete 'OPstreamImpl' class to instantiate
 332
 333 SEE ALSO
 334 --------
 335 The user guide is available from http://freefoam.sourceforge.net/doc/UserGuide
 336 and the Doxygen-generated API documentation can be accessed at
 337 http://freefoam.sourceforge.net/doc/API.
 338
 339 AUTHOR
 340 ------
 341 Michael Wild <themiwi@users.sourceforge.net>
 342
 343 FREEFOAM
 344 --------
 345 Part of the linkff:freefoam[1] suite
 346
 347 COPYRIGHT
 348 ---------
 349 * Copyright (C) 1991-2010 OpenCFD Ltd.
 350 * Copyright (C) 2008-2012 Michael Wild.
 351
 352 ////////////////////////////////////////////////////////
 353 vim: ft=asciidoc sw=2 expandtab fenc=utf-8
 354 ////////////////////////////////////////////////////////