Read, modify, and write OpenFOAM dictionaries

This tutorial covers how to:

• read an OpenFOAM dictionary file from disk into a Python object,

• pull typed values out of it (Word, float, sub-dictionaries),

• change a value, and

• write the dictionary back to disk in OpenFOAM format.

Prerequisites

• OpenFOAM v2312+ sourced (source /path/to/OpenFOAM/etc/bashrc).

• pybFoam installed (pip install pybFoam[all]).

Set up a working case

pybFoam.clone_example() copies a baseline case from the repo’s examples/ folder into a tmp directory and restores 0.orig/ → 0/. The original on-disk case is never touched.

from pybFoam import clone_example

case = clone_example("cavity")
print(f"case = {case}")

case = /tmp/pybfoam_47qxo1jm/cavity

Read a dictionary

pybFoam.dictionary.read() parses an OpenFOAM dictionary into a Python object. get[T] is templated on the expected return type — the same accessor handles scalars, words, vectors, and field entries; a wrong type raises immediately at the call site.

from pybFoam import Word, dictionary

control_dict_path = case / "system" / "controlDict"
d = dictionary.read(str(control_dict_path))

print("application :", d.get[Word]("application"))
print("startTime   :", d.get[float]("startTime"))
print("endTime     :", d.get[float]("endTime"))
print("deltaT      :", d.get[float]("deltaT"))

application : icoFoam
startTime   : 0.0
endTime     : 0.5
deltaT      : 0.0005

Enumerate the top-level keys with dictionary.toc. Use this to introspect any dictionary you didn’t write yourself.

print("top-level keys:")
for key in d.toc():
    print(f"  - {key}")

top-level keys:
  - FoamFile
  - application
  - startFrom
  - startTime
  - stopAt
  - endTime
  - deltaT
  - writeControl
  - writeInterval
  - purgeWrite
  - writeFormat
  - writePrecision
  - writeCompression
  - timeFormat
  - timePrecision
  - runTimeModifiable

Modify and write it back

dictionary.set updates an entry in place. dictionary.write serialises the whole dictionary back to disk in OpenFOAM format. We write to a sibling path so we can compare before/after.

modified_path = case / "system" / "controlDict.modified"

d.set("endTime", 0.05)
d.set("deltaT", 0.005)
d.write(str(modified_path))

The round-trip via disk proves the values were actually written — not just held in the in-memory dictionary object.

d_modified = dictionary.read(str(modified_path))
print("endTime (modified) :", d_modified.get[float]("endTime"))
print("deltaT  (modified) :", d_modified.get[float]("deltaT"))

endTime (modified) : 0.05
deltaT  (modified) : 0.005

Skim the output file directly to see what an OpenFOAM dictionary looks like on disk (set preserves OpenFOAM’s syntax).

for line in modified_path.read_text().splitlines()[-20:]:
    print(line)

writeControl    adjustable;

writeInterval   0.1;

purgeWrite      0;

writeFormat     ascii;

writePrecision  6;

writeCompression off;

timeFormat      general;

timePrecision   6;

runTimeModifiable true;


// ************************************************************************* //