OpenFOAM guide/Input and Output operations using dictionaries and the IOobject class

Many input/output operations are performed in OpenFOAM using the IOobject class, which is described in its header file as follows:

IOobject defines the attributes of an object for which implicit objectRegistry management is supported, and provides the infrastructure for performing stream I/O. An IOobject is constructed with an object name, a class name, an instance path, a reference to a objectRegistry, and parameters determining its storage status.

1 IOobject constructors

The constructor of an IOobject may have two forms:

1. Construct from name, instance, registry and IO options:

 
IOobject  	
(  
    const word &   	 	name,
    const word &  		instance,
    const objectRegistry &  	registry,
    readOption  		r = NO_READ,
    writeOption  		w = NO_WRITE,
    bool  			registerObject = true
)

2. Construct from name, instance, local, registry and IO options:

 
IOobject  	
(
    const word &   	 	name,
    const word &  		instance,
    const fileName &  		local,
    const objectRegistry &  	registry,
    readOption  		r = NO_READ,
    writeOption  		w = NO_WRITE,
    bool  			registerObject = true
)

While reading the two previous code snippets, remember that word inherits string, from which fileName is also derived. Moreover, both Time and polyMesh inherit objectRegistry. As a consequence fvMesh, inheriting polyMesh, indirectly inherits objectRegistry too. For further information, see the IOobject class reference.

2 Read options

Read options, which define what is done on object construction and explicit reads, are:

• MUST_READ – The object must be read from Istream on construction. An error message is produced if Istream does not exist or can't be read.
• READ_IF_PRESENT – It reads the object from Istream if Istream exists, otherwise doesn't. An error message is produced only if Istream exists but can't be read.
• NO_READ – Don't read the object.

3 Write options

Write options, which define what is done on object destruction and explicit writes, are:

• AUTO_WRITE – The object is written automatically when requested to by the objectRegistry.
• NO_WRITE – The object is not written automatically on destruction, but it can be written explicitly.

4 IOobject and dictionaries

Dictionaries can be read using the IOobject class when they are declared. Usually the readOption for a dictionary is MUST_READ, while the writeOption is NO_WRITE not to overwrite the settings contained in the dictionary. For example, the code required to read the usual transportProperties dictionary is:

 
IOdictionary transportProperties
(
     IOobject
     (
          "transportProperties",
          runTime.constant(),
          mesh,
          IOobject::MUST_READ,
          IOobject::NO_WRITE
     )
);

The first constructor form is adopted in this case, where:

• transportProperties is the name of the file containing the dictionary.
• runTime.constant(), the instance, gives the position of the dictionary, which is, in this case, contained in the constant directory of the considered case.
• The objectRegistry is represented by the mesh.

5 IOobject and fields

Similarly to dictionaries, read and write options for a field can be set using the IOobject class. The syntax is almost the same for all kind of field and it is clarified by the following example. If we would like to define a volScalarField called T, saving it at user-defined intervals of time in a file called T, the code is:

 
volScalarField T
(
    IOobject
    (
        "T",
        runTime.timeName(),
        mesh,
        IOobject::MUST_READ,
        IOobject::AUTO_WRITE
    ),
    mesh
);

where:

• T is the name of the file.
• runTime.timeName() tells OpenFOAM to save the file in a directory called as the current run time.
• mesh is the objectRegistry.
• Read and write options are set to MUST_READ and AUTO_WRITE in order to make OpenFOAM read the field and to automatically save it. If reading the field is not required, the MUST_READ option has to be changed into NO_READ.