OpenFOAM v14 User Guide - 4.3 Global controls

4.3 Global controls

OpenFOAM includes global control parameters that are configured in a file named configDict, located in the OpenFOAM installation within the etc directory. That directory is represented by the environment variable $FOAM_ETC, so the file can be printed to a terminal by typing the following command. The file contents are also reproduced below for reference.

9{

10    format      ascii;

11    class       dictionary;

12    object      configDict;

13}

14// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //

15

16documentation

17{

18    docBrowser      "firefox";

19    doxyDocDirs

20    (

21        "$WM_PROJECT_USER_DIR/html"

22        "~OpenFOAM/html"

23        "$WM_PROJECT_DIR/doc/Doxygen/html"

24        "http://cpp.openfoam.org/dev"

25    );

26    doxySourceFileExt "_8C.html";

27}

28

29InfoSwitches

30{

31    writePrecision          6;

32    writeJobControl         0;

33    writeJobInfo            0;

34    writeDictionaries       0;

35

36    // Allow case-supplied C++ code (#codeStream, codedFixedValue)

37    allowSystemOperations   1;

38}

39

40OptimisationSwitches

41{

42    // On NFS mounted file system: maximum wait for files to appear/get

43    // updated. Set to 0 on distributed case.

44    fileModificationSkew 10;

45

46    //- Modification checking:

47    //  - timeStamp         : use modification time on file

48    //  - inotify           : use inotify framework

49    //  - timeStampMaster   : do time stamp (and file reading) only on master.

50    //  - inotifyMaster     : do inotify (and file reading) only on master.

51    fileModificationChecking timeStampMaster;

52

53    //- Parallel IO file handler

54    //  uncollated (default), collated or masterUncollated

55    fileHandler uncollated;

56

57    //- collated: thread buffer size for queued file writes.

58    //  If set to 0 or not sufficient for the file size threading is not used.

59    //  Default: 2e9

60    maxThreadFileBufferSize 2e9;

61

62    //- masterUncollated: non-blocking buffer size.

63    //  If the file exceeds this buffer size scheduled transfer is used.

64    //  Default: 2e9

65    maxMasterFileBufferSize 2e9;

66

67    commsType       nonBlocking; // scheduled; // blocking;

68    floatTransfer   0;

69    nProcsSimpleSum 0;

70

71    // Force dumping (at next timestep) upon signal (-1 to disable)

72    writeNowSignal              -1; // 10; // SIGUSR1

73

74    // Force dumping and exit (at next timestep) upon signal (-1 to disable)

75    stopAtWriteNowSignal        -1; // 12; // SIGUSR2

76}

77

78DebugSwitches

79{

80    dimensionSet        1;

81    fileName            2;

82    GAMGAgglomeration   1;

83    level               2;

84    lduMatrix           1;

85    SolverPerformance   1;

86    vtkUnstructuredReader 1;

87}

88

89units

90{

91    set     SI;

92

93    SI

94    {

95        kg      [1 0 0 0 0 0 0];

96        m       [0 1 0 0 0 0 0];

97        s       [0 0 1 0 0 0 0];

98        K       [0 0 0 1 0 0 0];

99        kmol    [0 0 0 0 1 0 0];

100        A       [0 0 0 0 0 1 0];

101        Cd      [0 0 0 0 0 0 1];

102    }

103

104    CGS

105    {

106        g       [1 0 0 0 0 0 0];

107        cm      [0 1 0 0 0 0 0];

108        s       [0 0 1 0 0 0 0];

109        K       [0 0 0 1 0 0 0];

110        mol     [0 0 0 0 1 0 0];

111        A       [0 0 0 0 0 1 0];

112        Cd      [0 0 0 0 0 0 1];

113    }

114

115    USCS

116    {

117        lb      [1 0 0 0 0 0 0];

118        ft      [0 1 0 0 0 0 0];

119        s       [0 0 1 0 0 0 0];

120        R       [0 0 0 1 0 0 0];

121        lbmol   [0 0 0 0 1 0 0];

122        A       [0 0 0 0 0 1 0];

123        Cd      [0 0 0 0 0 0 1];

124    }

125

126    // Conversions between fundamental units

127    g       1e-3                [kg];

128    lb      0.45359237          [kg];

129    cm      1e-2                [m];

130    ft      0.3048              [m];

131    K       1.8                 [R];

132    kmol    1000                [mol];

133    lbmol   453.59237           [mol];

134

135    // Derived units

136    Hz      1                   [s^-1];

137    N       1                   [kg m s^-2];

138    pdl     1                   [lb ft s^-2];

139    Pa      1                   [N m^-2];

140    J       1                   [N m];

141    W       1                   [J s^-1];

142    V       1                   [W/A];

143

144    // Scaled units

145    um      1e-6                [m];

146    mm      1e-3                [m];

147    km      1e3                 [m];

148    in      25.4                [mm];

149    yd      3                   [ft];

150    mi      1760                [yd];

151    us      1e-6                [s];

152    ms      1e-3                [s];

153    min     60                  [s];

154    hr      3600                [s];

155    lbf     32.174049           [pdl];

156

157    // Derived scaled units

158    l       1e-3                [m^3];

159    ml      1e-6                [m^3];

160    rpm     1                   [rot/min];

161    bar     1e5                 [Pa];

162    atm     101325              [Pa];

163    kPa     1e3                 [Pa];

164    MPa     1e6                 [Pa];

165    psi     1                   [lbf/in^2];

166    cal     4.184               [J];

167    kcal    4184                [J];

168    cSt     1e-6                [m^2/s];

169    cP      1e-3                [kg/m/s];

170}

171

172constants

173{

174    pStd    1e5                 [kg m^-1 s^-2];

175    Tstd    298.15              [K];

176}

177

178// ************************************************************************* //
   

The file contains sub-dictionaries for the following categories of control parameter.

• documentation: for opening OpenFOAM documentation in a web browser.

• InfoSwitches: controls information printed to standard output, i.e. the terminal.

• OptimisationSwitches: for parallel communication and I/O, see section 3.4.2 .

• DebugSwitches: messaging switches designed to help debug code failures.

• units: defines units and conversion factors, e.g. cal for calorie, described in section 4.2.7 .

• constants: defines engineering constants.

While some of these categories are described elsewhere, the remaining categories will be described below, beginning with DebugSwitches. It relates to the system of messaging, in OpenFOAM, that is written to the terminal when an application runs. In the DebugSwitches category is a vast number of switches that control the printing of messages to help debug faults. The complete set of switches, including the InfoSwitches and OptimisationSwitches, can be printed by running foamToC (see section 4.7.6 ) with the -switches option, i.e.

This shows the extent of the number of switches and that, with a value of 0, almost all of them are deactivated by default. Any switch can be activated by setting its value to 1. A small number of DebugSwitches control messaging at three levels, 0, 1 and 2, most notably the overall level switch and lduMatrix which provides messaging for solver convergence during a run.

In the OptimisationSwitches category, there are some switches that control certain operational and optimisation issues. The fileModificationSkew switch is particularly important when running over a network file system (NFS). OpenFOAM scans the write time of data files to check for modification. On an NFS there can be some disparity in the clock settings on different machines, so field data files may appear to be modified ahead of time. This can cause a problem if OpenFOAM views the files as newly modified and attempts to re-read the data. The fileModificationSkew keyword is the time in seconds that OpenFOAM will subtract from the file write time when assessing whether the file has been newly modified. This and other switches are listed below:

• fileModificationSkew: a time in seconds that should be set higher than the maximum delay in NFS updates and clock difference for running OpenFOAM over a NFS.

• fileModificationChecking: method of checking whether files have been modified during a simulation, either reading the timeStamp or using inotify; versions that read only master-node data also exist, termed timeStampMaster and inotifyMaster.

• commsType: parallel communications type, nonBlocking, scheduled or blocking.

• floatTransfer: if 1, will compact numbers to float precision before transfer; default is 0.

• nProcsSimpleSum: optimises the global sum for parallel processing, by setting the number of processors above which a hierarchical sum is performed rather than a linear sum.

There are also some remaining switches in OptimisationSwitches that relate to file input/output when running in parallel, discussed in section 3.4.2 .

From the InfoSwitches, the most important switch is allowSystemOperations which is enabled in the configDict file. Turning this switch off disables run-time compilation of code used for inline calculations and other inline code, described in section 4.2.15 and subsequent sections.

4.3.1 Overriding global controls

A user may wish to override one or more settings in the configDict file, either for all simulations or for a specific simulation. For example, they may wish to change the base set of units from the default (SI) to the US Customary system (USCS). This requires the set entry to be changed to USCS in the units sub-dictionary, as shown below.

To make this change for all simulations, the user could modify this setting in the etc/configDict file in the OpenFOAM installation. However, it is more flexible to configure changes in a file in their user directory. OpenFOAM provides a set of directory locations, where a local configDict file can be added, which it looks up in an order of precedence. To list the locations, run the following command.

The listed locations include a local $HOME/.OpenFOAM directory and follow a descending order of precedence, i.e. the last location listed (etc) is lowest precedence.

Therefore, if a user wished to work permanently in USCS units, they can maintain a configDict file in their $HOME/.OpenFOAM directory that includes the entry shown above. OpenFOAM would read the keyword entries from the global configDict file but override the set entry from the local file.

Alternatively, if a user wished to work on a single case in USCS units, they can add the same entry into a configDict file in the system directory for their case. There is a sample configDict file that can be copied into their system directory by running the foamGet script (see section 4.7.4 ) as follows.

Once the file is copied into their case, they can edit it accordingly. The file is annotated with example settings that are most commonly overridden.