Config.md 10.3 KB
Newer Older
1
# OpenFOAM Configuration
2

3 4 5 6
The main OpenFOAM settings are located in the parent `etc/` directory
with both POSIX (bash, dash,...) and csh shells being supported.
To use OpenFOAM, source either the `etc/bashrc` or the
`etc/cshrc` file, as appropriate.
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27

These source the following files in the `config.sh/` or
`config.csh/` directories:

* `setup` : finalize setup of OpenFOAM environment (called by bashrc,cshrc)
* `settings` : core settings
* `aliases` : aliases for interactive shells
* `unset` : sourced to clear as many OpenFOAM environment settings as possible
* `mpi` : MPI communications library settings
* `paraview` : application settings for ParaView
* `scotch` : application settings for compiling against scotch
* `metis` : application settings for compiling against metis

The `config.*/example` directories contain additional example configuration
files for the corresponding shell:

* `compiler` : an example of fine tuning ThirdParty compiler settings
* `openmpi` : an example of fine tuning openmpi settings for OpenFOAM
* `paraview` : an example of chaining to the standard config/paraview
   with a different ParaView_VERSION
* `prefs`: an example of supplying alternative site-defined settings
28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274


## OpenFOAM configuration layers

Before launching into manually adjusting the configuration, it is
useful to first understand how OpenFOAM supports different
configuration *layers*. Similar to file-system permissions, we use the
notion of **user**, **group**, **other** categories when searching for
files. The output of `foamEtcFile` can be used to obtain a quick
overview:
```
$ foamEtcFile -list

$HOME/.OpenFOAM/1906
$HOME/.OpenFOAM
/path/OpenFOAM-v1906/site/1906/etc
/path/OpenFOAM-v1906/site/etc
/path/OpenFOAM-v1906/etc
```

Both the *user* paths (located as `$HOME/.OpenFOAM/`) and the *group*
paths (`/path/OpenFOAM-v1906/site/`) support additional API versioning
to allow different settings between releases. The **other**
corresponds to the settings shipped with a particular OpenFOAM release.

Making configuration changes under the *user* or *group* directories
allows you to preserve these across upgrades and makes it easier (if
necessary) to revert to the original values.

## Making changes to the configuration

The first encounter with the OpenFOAM configuration files can be
somewhat intimidating. There are indeed quite a few different bits of
software related to using OpenFOAM, each of which could be available
in different preferred versions, in different possible locations and
with different conventions for naming their library directories.
Additionally it should allow individual users to make their own
configuration choices. Supporting cshell variants for everything adds
yet more files to the mix. Fortunately, the user often only needs to
make a few simple changes and can ignore most of the details and we
also provide a `bin/tools/foamConfigurePaths` tool to make multiple
common changes directly from the command line. The configuration files
generally contain detailed information about which values they expect,
and the user editable part is also clearly marked as such. For
example,

```
#------------------------------------------------------------------------------
# USER EDITABLE PART: Changes made here may be lost with the next upgrade

ParaView_VERSION=5.6.0
ParaView_QT=qt-system
cmake_version=cmake-system

# END OF (NORMAL) USER EDITABLE PART
#------------------------------------------------------------------------------
```

Nonetheless, before making changes it can be useful to understand
where these changes should actually be made (and why). To simplify
things, we only discuss POSIX (bash), but most points apply to cshell
variants as well.

1. The main entry point for the OpenFOAM configuration is the
   `etc/bashrc` file. The initial portion of the file establishes the
   version and contains some script *magic* to help us determine where
   the OpenFOAM directory is located. The balance of the file contains
   some general OpenFOAM-specific settings, which you can use for
   guidance but in general you should note the following:

   * Changes made to this `bashrc` file will be lost with the next upgrade.
   * Should override via a `prefs.sh` file instead of editing this file.

2. The `etc/bashrc` file (our entry point) passes control to the
   `etc/config.sh/setup` file, which dispatches the rest of the
   configuration actions.

The setup of the OpenFOAM environment can be described in terms of a processing tree:
```
source etc/bashrc  [args]
       |
       |-- constants
       |-- directory discovery magic
       |-- defaults
       |-- define OpenFOAM directory
       |
       \-- setup
           |-- discovery of ThirdParty locations
           |-- admin overrides (prefs.sh file)
           |-- user overrides (prefs.sh file)
           |-- user overrides (arguments)
           |-- settings (compiler, os)
           |-- mpi
           |-- paraview
           |-- vtk / mesa (llvm)
           |-- CGAL / boost
           |-- scotch
           |-- FFTW
           \-- aliases
```
At most locations in this process it is possible for the user to
influence the values used by providing an alternative version of the
file. For example, simply creating the file
`$HOME/.OpenFOAM/config.sh/FFTW` will cause it to be found by the
`foamEtcFile` mechanism during sourcing (see `foamEtcFile -list` for a
reminder of which directories will be searched). Most fairly permanent
changes that affect the base configuration of OpenFOAM itself (choice
of compiler, mpi, data sizes, etc) should normally be defined in the
`prefs.sh` file. These type of changes are important enough that they
receive special treatment. Use the base or admin `prefs.sh` file if
available as `PROJECT/etc/prefs.sh`. This provides the system admin a
reliable location to define site-wide settings, such as for compiler
and vendor-specific MPI libraries. use the user or group prefs.sh if
it exists. For quick or temporary changes, the special interpretation
of arguments when sourcing the etc/bashrc are quite convenient. This
mechanism allows direct setting of variables without needing to edit
any files. For example, to source the OpenFOAM environment with a
different compiler:
```
source /path/to/OpenFOAM-v1906  WM_COMPILER=Clang
```
If the argument does not appear to be an assignment of a variable, it
will attempt to resolve it as a file and then source that. This
property lets the user bundle some favourite settings and temporarily
switch to them. For example, by creating a few predefined
configurations:
```
# file = $HOME/.OpenFOAM/gcc82
export WM_COMPILER_TYPE=ThirdParty
export WM_COMPILER=Gcc82
export WM_LABEL_SIZE=32
```
or
```
# file = $HOME/.OpenFOAM/clang50-int64
export WM_COMPILER_TYPE=ThirdParty
export WM_COMPILER=Clang50
export WM_LABEL_SIZE=64
```
It is then possible to easily switch between different configurations:
```
source /path/to/OpenFOAM-v1906  clang50-int64
source /path/to/OpenFOAM-v1906  gcc82
source /path/to/OpenFOAM-v1906  wingw
```
Armed with this information, the user should be able to make
adjustments to the OpenFOAM configuration with a good degree of
confidence. However, there are also times in which it can be expedient
and useful to simply change the entries directly within the OpenFOAM
directory as new permanent defaults for all users. This can also be
the case for cluster installations where the user will not require the
usual flexibility. For these cases, the `bin/tools/foamConfigurePaths`
tool can be helpful (and powerful). For example, when installing
without any OpenFOAM ThirdParty dependencies and additionally setting
the OpenFOAM directory to a fixed location (removing any bash
discovery magic):
```
bin/tools/foamConfigurePaths \
    -project-path "/opt/openfoam-1906" \
    -boost boost-system \
    -cgal  cgal-system \
    -fftw  fftw-system \
    -kahip kahip-none \
    -scotch scotch-system \
    -scotch-path /usr/lib64/mpi/gcc/openmpi \
    ;
```
Using this tool has some restrictions:

* It must be called from the OpenFOAM project directory
* It is not available in the PATH, since it we wish to avoid any
  inadvertent use
* Using this tool to change default gcc, gmp, mpfr versions is not
  very precise. It will change the gcc version without distinguishing
  between Gcc48, Gcc82 etc.


## Working in groups

When an OpenFOAM cluster installation is being used by several
different people or interest groups it can be highly interesting to
share common setups or custom libraries and applications. This is
where the OpenFOAM site (group) configuration can be quite helpful.
The directory location of OpenFOAM site settings is defined by the
`$WM_PROJECT_SITE` environment variable. If this is undefined, the
default is to use `PROJECT/site` (ie, a site directory located within
the OpenFOAM directory). Within this `$WM_PROJECT_SITE` directory, we
can use a directory structure that mirrors elements of the OpenFOAM
directory structure, but which also includes a degree of versioning as
well:
```
$WM_PROJECT_SITE
|
|-- API
|   |-- bin
|   \-- etc
|-- VERSION
|   \-- platforms
|       |-- bin
|       \-- lib
|-- bin
\-- etc
```

Useful OpenFOAM-related scripts can be placed in the bin directory. If
the script can only work with a particular OpenFOAM version, it then
makes sense to place it into the API/bin directory accordingly.
Similarly, if particular configurations or setups are useful for
several people, it makes sense to locate them centrally as a site (or
group) resource. For example,
```
$WM_PROJECT_SITE
|
\-- etc
    |-- caseDicts
    \-- config.sh
        |-- openmpi
        \-- paraview
```
for some jointly useful caseDicts and suitable configurations for openmpi, paraview.
The `foamEtcFile -list` option provides a good overview of which
locations will be searched for configuration files, which uses the
following precedence:

* user:
  * `$HOME/.OpenFOAM/API`
  * `$HOME/.OpenFOAM`
* group:
  * `$WM_PROJECT_SITE/API/etc`
  * `$WM_PROJECT_SITE`
* other:
  * `$WM_PROJECT_DIR/etc`

If applications and libraries are to be shared within a group, a
typical approach is that one person is in charge of administering the
the internal code releases. They would compile the code in their
normal user directories, which means that it would normally have the
user destinations:
```
$FOAM_USER_APPBIN
$FOAM_USER_LIBBIN
```
For distribution at the group level, these files would be synchronized to the corresponding group directories:
```
$FOAM_USER_APPBIN  ->  $FOAM_SITE_APPBIN
$FOAM_USER_LIBBIN  ->  $FOAM_SITE_LIBBIN
```