CFD,  Education,  General,  OpenFOAM

P. 2. The structure of dictionaries (Ep. 1)

Dictionaries are what OpenFOAM® uses as input files, but the same name is used to indicate some of the structures inside such files.

I will distinguish between a dictionary file and a dictionary to avoid ambiguity, but this distinction is not systematic in the documentation found on the Internet. In this part we focus on the structure of dictionary files.

A dictionary files starts with the FoamFile subdictionary, which looks like

FoamFile
{
    version     2.0;
    format      ascii;
    class       dictionary;
    location    "system";
    object      controlDict;
}

The first entry, version, indicates the format version of the input file. The second, more interesting, indicates that the dictionary is in ASCII format. The alternative is binary, which may be found in dictionaries storing fields, if the output is set to be written in binary format.

The class entry indicates the type of object stored in the dictionary file. In this case the dictionary file stores a dictionary, but it could be a volScalarField, a volVectorField and so on.

The location indicates in what directory in the case structure the dictionary is stored. Typical values are 0 (the folder of initial conditions), constant or systems. Note this entry is a string, so it appears between double quotes.

Finally, the object indicates what object corresponds to the dictionary. In this case, a controlDict object. This is the name with which the dictionary object is identified in the internal database of OpenFOAM, so it may be important it is unique in case lookup operations on such database are performed to retrieve it (or you will spend hours figuring out why your code looks right and the object is not found: often the code is correct, but the input file is not! :-D).

The simple structure of FoamFile is that of a standard subdictionary, which is as follows:

name
{
entry 1;
entry 2;
}

where name is the name of the subdictionary, and entries are contained between a scope, represented by {}, and separated by semicolons.

A dictionary file may contain an arbitrary number of subdictionaries, but may also contain entries itself, not in a subdictionary. A very common example is controlDict, which has entries outside of a subdictionary, directly in the main body of the dictionary file:

FoamFile
{
    version     2.0;
    format      ascii;
    class       dictionary;
    location    "system";
    object      controlDict;
}

application     simpleFoam;
startFrom       startTime;
startTime       0;
stopAt          endTime;
endTime         500;
deltaT          1;
writeControl    timeStep;
writeInterval   500;
purgeWrite      0;
writeFormat     binary;
writePrecision  6;
writeCompression off;
timeFormat      general;
timePrecision   6;
runTimeModifiable true;

From this example, it appears that an entry has the following structure:

key    value;

where key is a string without spaces and value can be a string (in a very general sense, as we will see later) or a number.

The next post will focus on the type of entries and how they look like. Stay tuned!

This offering is not approved or endorsed by OpenCFD Limited, the producer of the OpenFOAM software and owner of the OPENFOAM® and OpenCFD® trade marks. Alberto Passalacqua is not associated to OpenCFD Ltd.

Leave a Reply

Your email address will not be published. Required fields are marked *

one × five =

I accept the Privacy Policy * for Click to select the duration you give consent until.