OpenFOAM needs to read a range of data structures such as strings, scalars, vectors, tensors, lists and fields. The input/output (I/O) format of files is designed to be extremely flexible to enable the user to modify the I/O in OpenFOAM applications as easily as possible. The I/O follows a simple set of rules that make the files extremely easy to understand, in contrast to many software packages whose file format may not only be difficult to understand intuitively but also not be published anywhere. The description of the OpenFOAM file format is described in the following sections.
The format follows the following some general principles of C++ source code.
- Files have free form, with no particular meaning assigned to any column and no need to indicate continuation across lines.
- Lines have no particular meaning except to a // comment delimiter which makes OpenFOAM ignore any text that follows it until the end of line.
- A comment over multiple lines is done by enclosing the text between /* and */ delimiters.
OpenFOAM uses dictionaries as the most common means of specifying data. A dictionary is an entity that contains as set data entries that can be retrieved by the I/O by means of keywords. The keyword entries follow the general format
<keyword> <dataEntry1> … <dataEntryN>;
… keyword entries …
All data files that are read and written by OpenFOAM begin with a dictionary named FoamFile containing a standard set of keyword entries, listed in Table 4.1.
The table provides brief descriptions of each entry, which is probably sufficient for most entries with the notable exception of class. The class entry is the name of the C++ class in the OpenFOAM library that will be constructed from the data in the file. Without knowledge of the underlying code which calls the file to be read, and knowledge of the OpenFOAM classes, the user will probably be unable to surmise the class entry correctly. However, most data files with simple keyword entries are read into an internal dictionary class and therefore the class entry is dictionary in those cases.
The following example shows the use of keywords to provide data for a case using the types of entry described so far. The extract, from an fvSolution dictionary file, contains 2 dictionaries, solvers and PISO. The solvers dictionary contains multiple data entries for solver and tolerances for each of the pressure and velocity equations, represented by the p and U keywords respectively; the PISO dictionary contains algorithm controls.
22 solver PCG;
23 preconditioner DIC;
24 tolerance 1e-06;
25 relTol 0;
30 solver PBiCG;
31 preconditioner DILU;
32 tolerance 1e-05;
33 relTol 0;
39 nCorrectors 2;
40 nNonOrthogonalCorrectors 0;
41 pRefCell 0;
42 pRefValue 0;
46 // ************************************************************************* //
OpenFOAM applications contain lists, e.g. a list of vertex coordinates for a mesh description. Lists are commonly found in I/O and have a format of their own in which the entries are contained within round braces ( ). There is also a choice of format preceeding the round braces:
- the keyword is followed immediately by round braces <listName>
… entries …
- the keyword is followed by the number of elements <n> in the list
… entries …
- token identifier
- the keyword is followed by a class name identifier Label<Type>
where <Type> states what the list contains, e.g. for a list of scalar elements
<n> // optional
… entries …
Note that <scalar> in List<scalar> is not a generic name but the actual text that should be entered.
The simple format is a convenient way of writing a list. The other formats allow the code to read the data faster since the size of the list can be allocated to memory in advance of reading the data. The simple format is therefore preferred for short lists, where read time is minimal, and the other formats are preferred for long lists.
A scalar is a single number represented as such in a data file. A vector is a VectorSpace of rank 1 and dimension 3, and since the number of elements is always fixed to 3, the simple List format is used. Therefore a vector is written:
(1.0 1.1 1.2)
1 0 0
0 1 0
0 0 1
( 1 0 0 0 1 0 0 0 1 )
In continuum mechanics, properties are represented in some chosen units, e.g. mass in kilograms (), volume in cubic metres (), pressure in Pascals (). Algebraic operations must be performed on these properties using consistent units of measurement; in particular, addition, subtraction and equality are only physically meaningful for properties of the same dimensional units. As a safeguard against implementing a meaningless operation, OpenFOAM attaches dimensions to field data and physical properties and performs dimension checking on any tensor operation.
The I/O format for a dimensionSet is 7 scalars delimited by square brackets, e.g.
[0 2 -1 0 0 0 0]
where each of the values corresponds to the power of each of the base units of measurement listed in Table ??. The table gives the base units for the Système International (SI) and the United States Customary System (USCS) but OpenFOAM can be used with any system of units. All that is required is that the input data is correct for the chosen set of units. It is particularly important to recognise that OpenFOAM requires some dimensioned physical constants, e.g. the Universal Gas Constant , for certain calculations, e.g. thermophysical modelling. These dimensioned constants are specified in a DimensionedConstant sub-dictionary of main controlDict file of the OpenFOAM installation ($WM_PROJECT_DIR/etc/controlDict). By default these constants are set in SI units. Those wishing to use the USCS or any other system of units should modify these constants to their chosen set of units accordingly.
Physical properties are typically specified with their associated dimensions. These entries have the format that the following example of a dimensionedScalar demonstrates:
nu nu [0 2 -1 0 0 0 0] 1;
Much of the I/O data in OpenFOAM are tensor fields, e.g. velocity, pressure data, that are read from and written into the time directories. OpenFOAM writes field data using keyword entries as described in Table 4.3.
The data begins with an entry for its dimensions. Following that, is the internalField, described in one of the following ways.
- Uniform field
- a single value is assigned to all elements within the field, taking
the form: internalField uniform <entry>;
- Nonuniform field
- each field element is assigned a unique value from a list,
taking the following form where the token identifier form of list is
recommended: internalField nonuniform <List>;
The boundaryField is a dictionary containing a set of entries whose names correspond to each of the names of the boundary patches listed in the boundary file in the polyMesh directory. Each patch entry is itself a dictionary containing a list of keyword entries. The compulsory entry, type, describes the patch field condition specified for the field. The remaining entries correspond to the type of patch field condition selected and can typically include field data specifying initial conditions on patch faces. A selection of patch field conditions available in OpenFOAM are listed in Table 5.2 and Table 5.3 with a description and the data that must be specified with it. Example field dictionary entries for velocity U are shown below:
19 internalField uniform (0 0 0);
25 type fixedValue;
26 value uniform (1 0 0);
31 type fixedValue;
32 value uniform (0 0 0);
37 type empty;
41 // ************************************************************************* //
There is additional file syntax that offers great flexibility for the setting up of OpenFOAM case files, namely directives and macro substitutions. Directives are commands that can be contained within case files that begin with the hash (#) symbol. Macro substitutions begin with the dollar ($) symbol.
At present there are 2 directive commands available in OpenFOAM:
- #include "<fileName>"
- reads the file of name <fileName>;
- has two options: merge, which merges keyword entries in successive dictionaries, so that a keyword entry specified in one place will be overridden by a later specification of the same keyword entry; overwrite, which overwrites the contents of an entire dictionary; generally, use merge.
For example, let us say a user wishes to set an initial value of pressure once to be used as the internal field and initial value at a boundary. We could create a file, e.g. named initialConditions, which contains the following entries:
In order to use this pressure for both the internal and initial boundary fields, the user would simply include the following macro substitutions in the pressure field file p:
This is a fairly trivial example that simply demonstrates how this functionality works. However, the functionality can be used in many, more powerful ways particularly as a means of generalising case data to suit the user’s needs. For example, if a user has a set of cases that require the same RAS turbulence model settings, a single file can be created with those settings which is simply included in the RASProperties file of each case. Macro substitutions can extend well beyond a singe value so that, for example, sets of boundary conditions can be predefined and called by a single macro. The extent to which such functionality can be used is almost endless.