4.2 Basic input/output file format

Advanced Search

Send us a comment/query

Back to main web site

OpenFOAM guides

- User guide

- Programmer’s guide

Index

Changes from OpenFOAM 2.2 to 2.3

Trademarks in the guides

[next] [prev] [prev-tail] [tail] [up]

4.2 Basic input/output file format

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.

4.2.1 General syntax rules

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.

4.2.2 Dictionaries

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>;

Most entries are single data entries of the form:

<keyword> <dataEntry>;

Most OpenFOAM data files are themselves dictionaries containing a set of keyword entries. Dictionaries provide the means for organising entries into logical categories and can be specified hierarchically so that any dictionary can itself contain one or more dictionary entries. The format for a dictionary is to specify the dictionary name followed the the entries enclosed in curly braces {} as follows

    <dictionaryName>
    {
        ... keyword entries ...
    }

4.2.3 The data file header

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.

Keyword

Description

Entry

version

I/O format version

2.3

format

Data format

ascii / binary

root

Root path to case directory, in "..."

e.g. "~/foam/chris2.3/run"

case

Case directory name, in "..."

e.g. "cavity"

instance

Subdirectory within case, in "..."

"<timeDirectory>" /

"system" / "constant"

local

Any subdirectory within instance, in "..." (optional entry)

e.g. "polyMesh"

class

OpenFOAM class constructed from the data file concerned

typically dictionary or a field, e.g. volVectorField

object

Filename

e.g. controlDict

Table 4.1:

Header keywords entries for data files.

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.

31  // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
32
33  solvers
34  {
35      p               ICCG 1e-06 0;
36      U               BICCG 1e-05 0;
37  }
38
39  PISO
40  {
41      nCorrectors     2;
42      nNonOrthogonalCorrectors 0;
43  }
44
45
46  // ************************************************************************* //

4.2.4 Lists

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:

simple: the keyword is followed immediately by round braces

        <listName>
        (
            ... entries ...
        );
numbered: the keyword is followed by the number of elements <n> in the list

        <listName>
        <n>
        (
            ... 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 is

        <listName>
        List<scalar>
        <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.

4.2.5 Scalars, vectors and tensors

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 $(1.0, 1.1,1.2) \special {t4ht=$ is written:

(1.0 1.1 1.2)

In OpenFOAM, a tensor is a VectorSpace of rank 2 and dimension 3 and therefore the data entries are always fixed to 9 real numbers. Therefore the identity tensor, described in 1.3.7 of the Programmer’s Guide, can be written:

    (
        1 0 0
        0 1 0
        0 0 1
    )

This example demonstrates the way in which OpenFOAM ignores the line return is so that the entry can be written over multiple lines. It is treated no differently to listing the numbers on a single line:

( 1 0 0 0 1 0 0 0 1 )

4.2.6 Dimensioned types

Physical properties are typically specified with their associated dimensions, to be created by the dimensioned<Type> class in OpenFOAM as described in 1.5 of the Programmer’s Guide. These entries have the format that the following example of a dimensionedScalar demonstrates:

nu nu [0 2 -1 0 0 0 0] 1;

The first nu is the keyword; the second nu is the word name stored in class word, usually chosen to be the same as the keyword; the next entry is the dimensionSet and the final entry is the scalar value.

4.2.7 Fields

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. More precisely, the fields are objects of the geometricField<Type> class, as described in 2.3.2 of the Programmer’s Guide. OpenFOAM writes geometricField<Type> data using keyword entries as described in Table 4.2.

Keyword	Description	Example

dimensions	Dimensions of field	[1 1 -2 0 0 0 0]
referenceLevel	Reference level for the internal field	(0 0 0)
internalField	Value of internal field	uniform (1 0 0)
boundaryField	Boundary field	see file listing in subsection 4.2.7

Table 4.2:

Main keywords used in field dictionaries.

The data begins with an entry for its dimensions. It is followed by a referenceLevel value; the field variables are stored as values relative to the reference level entry, which is usually set to zero but can be set to other values to improve solution accuracy. 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. The patch field conditions available in OpenFOAM are listed in Table 6.2 and Table 6.3 with a description and the data that must be specified with it. Example field dictionary entries for velocity U are shown below:

31  // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
32
33
34  dimensions      [0 1 -1 0 0 0 0];
35
36  internalField   uniform (0 0 0);
37
38  boundaryField
39  {
40      movingWall
41      {
42          type            fixedValue;
43          value           uniform (1 0 0);
44      }
45
46      fixedWalls
47      {
48          type            fixedValue;
49          value           uniform (0 0 0);
50      }
51
52      frontAndBack
53      {
54          type            empty;
55      }
56  }
57
58
59  // ************************************************************************* //

[next] [prev] [prev-tail] [front] [up]