OpenFOAM 14 Part 4: controlDict and Simulation Control

Every OpenFOAM application builds a Time object at start-up (usually called runTime in the code). It is at once the clock of the calculation and the root registry of every object that can be read or written: mesh, fields, dictionaries. When a field is “written”, it is really runTime that decides whether the current instant is a write time and asks every registered object with automatic writing enabled to save itself in the current time directory.

This is why controlDict is read before any other case file: without it there is no database for the other objects to attach to. Even a utility that does not advance in time, such as blockMesh, needs a readable controlDict (as seen in Part 2). The numerically named directories (0, 0.01, …) are the “snapshots” of the database; after a solver write, each also contains a uniform/ subdirectory with a time file that records the time value, the step index and the current time step (see section 6).

The installation-wide settings (units, OptimisationSwitches, DebugSwitches) are not in the case controlDict but in $FOAM_ETC/configDict; they can be overridden for a single case by copying the sample with foamGet configDict into the system directory (User Guide §4.3).

foamRun is a generic application: it reads the solver keyword, loads the shared library of the module with that name, and then runs a common time loop that calls the module’s functions at each step (momentum predictor, pressure corrector, transport and thermophysical models). Physics and algorithm live in the module; time control, writing and function objects remain in foamRun and in the time database. Multi-region cases (for example fluid + solid) use foamMultiRun, with the modules given per region in regionSolvers.

The table is an orientation, not an exhaustive list: the authoritative list for your installation comes from the commands below. Steady versus transient is no longer chosen by changing application: with incompressibleFluid it is decided by the ddtSchemes entry in fvSchemes (steadyState or, for example, Euler), the subject of Part 5.

foamToC -solvers                 # solver modules known to this installation
foamInfo incompressibleFluid     # description and example tutorials
foamDictionary -entry solver -value system/controlDict

Typical error: a controlDict copied from an old tutorial with application simpleFoam; and no solver makes foamRun fail with a FOAM FATAL IO ERROR of the form “keyword solver is undefined in dictionary …/system/controlDict”. A misspelt module name instead produces a selection error that names the unknown type. Some Foundation tutorials also contain an application foamRun; line: tutorial scripts use it to know which executable to launch, but the entry that decides the physics remains solver.

The v14 User Guide (§4.4) lists the time-control entries and the writeControl/writeInterval pair as mandatory; the others have defaults. Writing them explicitly anyway makes the file self-documenting and protects against future changes of defaults.

To see the file as OpenFOAM reads it, with macros expanded and effective values, use foamDictionary -expand system/controlDict. The guide also lists less common entries: libs (additional libraries to load), functions (section 9), graphFormat (graph data format: raw by default, gnuplot, csv, vtk, ensight) and beginTime (section 4).

In a steady calculation the time derivative is removed from the equations (ddtSchemes { default steadyState; }) and the module uses a SIMPLE-type algorithm. The time database still advances, however: every “step” is one under-relaxed iteration towards the steady solution. By convention deltaT 1; is used, so time equals the iteration count.

The backward-facing step tutorial of the v14 User Guide (§2.1.7 and §2.1.9) shows this well: endTime 2000, deltaT 1, writeControl timeStep, writeInterval 100. The run stops earlier, when the initial residuals drop below the residualControl tolerances in fvSolution: the log reports SIMPLE convergence in 285 iterations and the directories 100, 200 and 285 are written. The last is not a multiple of 100: when stopping on convergence the module writes the final state.

Practical consequence: in a steady case a directory name such as 285 does not mean “285 seconds”, and a deltaT other than 1 does not change the converged solution; it only changes the names. Before interpreting a time directory, therefore, check ddtSchemes with foamDictionary -entry ddtSchemes system/fvSchemes.

The planned number of fixed steps is N = (endTime − startTime)/Δt; in the example 0.020/0.002 = 10. The comparison is not done in exact arithmetic, though: 0.002 is not exactly representable in binary floating point and ten successive sums do not give exactly 0.02. To avoid an extra or missing step caused by round-off, the Foundation time database keeps running while the current time is less than endTime − ½Δt, and the directory name is generated with timePrecision digits.

Numerical example: with endTime 0.021 and Δt = 0.002 the criterion is t < 0.020. After the tenth step t = 0.020, so the run stops at 0.020, not 0.021: with a fixed step there is no “shortened” final step. If endTime is not a multiple of Δt, the actual final time is the nearest multiple according to this criterion. Always predict it and compare with the last Time = line of the log.

With stopAt writeNow and noWriteNow the time database, at the first re-read of the file, effectively sets the end at the current step; with nextWrite it waits until the current step is also a write time. With firstTime and latestTime the value of startTime does not matter; with startTime a directory with that time, containing the required fields, must exist.

With incompressibleFluid in transient mode the algorithm is PIMPLE. One time step contains nOuterCorrectors outer loops; each has an (optional) momentum predictor, i.e. one linear-system solve per velocity component, followed by nCorrectors pressure corrections, each solving a Poisson equation for p (plus any non-orthogonal corrections). With 1 outer loop and 2 correctors, up to 3 velocity systems and 2 pressure systems are solved per step, and each system needs several linear-solver iterations of its own.

In the log this appears as one block per step: a Time = … line, then lines of the form “solver: Solving for Ux, Initial residual = …, Final residual = …, No Iterations …” for each solve, the continuity errors and finally ExecutionTime and ClockTime. Counting Time = lines counts steps; counting “Solving for p” lines counts pressure solves. PIMPLE settings and tolerances belong to fvSolution and are covered in Part 6.

timeStep. The current step is a write time when its index is an integer multiple of writeInterval (which must therefore be read as a whole number of steps). The index is the one held by the time database: after a restart it continues from the value saved in uniform/time; it does not restart from zero.

runTime / adjustableRunTime. At each step a write index is computed as the integer part of (t − t_ref + ½Δt)/writeInterval; when this index increases relative to the last write, the current step becomes a write time. The half step makes the comparison robust to round-off: with Δt = 0.002 and interval 0.006, at t = 0.006 one gets (0.006 + 0.001)/0.006 ≈ 1.17 → index 1 → write. If the interval is not a multiple of Δt, the write lands on the step nearest to the requested instant (within half a step), not on the exact instant, and the written times are not evenly spaced.

The reference t_ref matters after a restart. The v14 Guide documents the optional beginTime entry, which anchors write times to multiples of writeInterval from that time, for cases with an awkward start time. After a restart from a time that is not a multiple of the interval, check where the first write falls with foamListTimes instead of assuming it.

clockTime / cpuTime. The interval is in seconds of real or CPU time; the simulated times written depend on the machine load and change from one execution to the next. They are useful as safety checkpoints on long runs (for example writeInterval 3600 with clockTime), never for a reproducible comparison.

With adjustableRunTime the time database, whenever the step is set, computes the time remaining to the next write and divides it into a whole number of equal steps, rounding the ratio of remaining time to current step upwards. The new step is the remaining time divided by that number; the change relative to the previous step is bounded so as not to introduce abrupt jumps. The result is that writes land exactly on multiples of writeInterval.

Example: current step 0.004 s, next write due in 0.006 s. The ratio is 1.5 → 2 steps → Δt = 0.003 s. Without adjustment, with runTime, the steps would fall at 0.004 and 0.008 and the write “at 0.006” would end up at 0.008 (the nearest step within half a step, according to the rule in the previous note).

The v14 Guide recommends adjustableRunTime together with automatic stepping (adjustTimeStep yes): that is where it really matters, because the step changes continuously and without adjustment the written times would be arbitrary, as the dam-break tutorial (§2.2) notes. With a fixed step already aligned with the interval, as in the table example, runTime and adjustableRunTime give the same times.

In memory OpenFOAM works in double precision (about 15–17 significant digits). In ASCII each value is written with writePrecision significant digits: with 6 (the default) a value such as 0.0123456789 becomes 0.0123457. The solver loses no accuracy during the run, but a restart from an ASCII directory starts from rounded values: for small variations or for bit-wise comparisons between a continuous and a resumed run, this is enough to make the histories diverge slightly. That is why the reference uses 8, and for rigorous restarts binary, which keeps every bit, is preferable.

With writeFormat binary the FoamFile header stays textual (with format binary;) but non-uniform value lists become raw bytes; less shows unreadable characters. With writeCompression on the files become U.gz, p.gz, etc.; OpenFOAM reads them transparently and zcat 0.01/U.gz | head -n 30 shows their beginning if they are ASCII.

Order-of-magnitude estimate for the Part 2 channel (40 × 10 × 5 = 2,000 cells; 5,350 internal faces): U holds 2,000 vectors, i.e. 6,000 numbers; in binary 8 bytes each ≈ 48 kB, in ASCII with 8 digits about 12–15 characters per number ≈ 70–90 kB. phi (one value per internal face) and p add similar amounts. Multiply by the number of writes: 1,000 writes of a 10-million-cell mesh are already hundreds of gigabytes. Always measure with du -sh instead of guessing.

timeFormat accepts fixed, scientific and general (default). According to the v14 Guide, general uses scientific notation when the exponent is below −4 or at least timePrecision, otherwise decimal notation without trailing zeros. timePrecision (default 6) is the number of digits used.

A collision is serious: two different instants would write into the same directory, overwriting each other, or a positive time would be confused with 0. The Foundation time database detects the situation when the step is too small for the available digits, automatically increases timePrecision and reports it with a warning in the log (“Increased the timePrecision …”). Do not rely on this mechanism: choose the precision according to the smallest expected step (with adaptive stepping, according to what appears in the log) and look for the warning in the log.

The v14 Guide describes purgeWrite as a limit on the number of retained time directories: once the limit is exceeded, older directories are overwritten cyclically, i.e. deleted at every new write. With purgeWrite 2 and writes every 5 steps in the reference case extended to 0.040 s, only 0.035 and 0.04 would remain at the end; 0.01, 0.015, … would have been lost during the run.

In the Foundation implementation the queue of directories to delete holds the times written by the current execution: the initial 0/ directory and, after a restart, the directories produced by earlier executions do not enter it. Do not treat this as a guarantee, though: check on a copy with foamListTimes before and after.

Legitimate use: very long runs where only statistics collected by function objects (section 9) and a recent restart point matter. There is also the foamListTimes -rm tool, which deletes all listed time directories except 0: it too is irreversible and must only be used on copies, never as a diagnostic shortcut (section 13).

After a solver write, a directory such as 0.02/ contains the solved fields (U, p), the face flux phi (with incompressibleFluid; on restart it is read if present instead of being rebuilt from velocity) and any model fields (for example nut, k, omega with a turbulence model). The uniform/ subdirectory holds the time file with the time value, the name, the step index and the latest time steps (deltaT, deltaT0).

foamDictionary 0.02/uniform/time
# typical entries: value, name, index, deltaT, deltaT0
foamDictionary -entry index -value 0.02/uniform/time

Two consequences. First: with writeControl timeStep the index continues, so a restart from 0.02 (index 10) with writeInterval 5 writes at 0.03 and 0.04 (indices 15 and 20), consistently with the first run. Second: the time database uses the information in uniform/time to resume; if you changed deltaT in controlDict for the restart, check in the log the step actually used in the first steps (for example the interval between two Time = lines) rather than assuming it.

foamListTimes (Guide §4.7) lists the time directories excluding 0; with -latestTime it shows only the one that startFrom latestTime will select. foamDictionary -set edits entries repeatably and accepts several assignments in one call with comma-separated key=value syntax; after every change read the value back with -value.

# Predict what latestTime will select, without running anything
foamListTimes -latestTime

# Edit entries reproducibly instead of by hand
foamDictionary -set "startFrom=latestTime, endTime=0.040" system/controlDict
foamDictionary -entry startFrom -value system/controlDict
foamDictionary -entry endTime -value system/controlDict

The trap: foamCloneCase old new copies only 0, system and constant. It is perfect for a fresh start, but a clone does not contain the later time directories: a latestTime restart on the clone would silently start again from 0/. For a restart use cp -a, which copies everything while preserving dates and permissions, as in the safe sequence above.

If the mesh has changed (for example after refinement), the saved fields no longer have the right number of cells and reading fails. That is no longer a restart but a new calculation initialised from another: the v14 Guide (§5.8) describes mapFields for mapping fields between different geometries.

In finite volumes velocity is not carried by a single |U| but by the volumetric face fluxes φ_f = U_f·S_f (m³/s). For each cell P OpenFOAM computes Co_P = ½ Δt Σ_f |φ_f| / V_P: the sum of all incoming and outgoing fluxes, halved (what enters equals what leaves), relative to the volume. In words: the fraction of the cell volume swept by the fluid in one step. The log reports a “Courant Number mean: … max: …” line for each step, i.e. the cell average and the maximum.

For a uniform hexahedron with flow only along x the formula reduces to |U|Δt/Δx, i.e. the refresher’s estimate. Example on the Part 2 channel (Δx = 2.5 mm, Δy = Δz = 1 mm) with axial velocity 0.05 m/s and Δt = 0.002 s: Co = 0.05 × 0.002 / 0.0025 = 0.04. If the mesh is refined in x to Δx = 1.25 mm the Courant number doubles to 0.08 at the same step: refining the mesh without reducing the step increases Co. Use the peak velocity, not the mean: in a duct the centreline maximum is noticeably higher than the mean velocity.

Stability and accuracy are different questions. OpenFOAM’s implicit time schemes can remain stable even with Co > 1, but the temporal discretisation error grows with Δt and pressure-velocity coupling algorithms with few correctors lose accuracy. For problems with interfaces (VoF) there is a separate limit, maxAlphaCo, used by the dam-break tutorial together with maxCo 1.

In the Foundation implementation of the fluid modules the new step is obtained from the ratio r = maxCo/Co_max between the target and the current maximum Courant number. When r < 1 (Courant too high) the step is reduced immediately in proportion; when r > 1 growth is damped (factor no larger than 1 + 0.1·r) and capped at a 20% increase per step. Finally the step never exceeds maxDeltaT. At start-up the controlDict deltaT is the initial value, reduced at once if it already violates maxCo.

Example with this section’s excerpt: initial Δt 0.002 s, Co_max = 0.10, maxCo 0.5 → r = 5, but growth is capped at ×1.2 per step: 0.0024, 0.00288, 0.003456, 0.004147, 0.004977; the next step (0.00597) is then cut by maxDeltaT 0.005. With the step at 0.005 the expected Courant number is 0.10 × 0.005/0.002 = 0.25, still below 0.5: here the active limit is maxDeltaT, not maxCo. At the same time adjustableRunTime shortens the steps near 0.010 and 0.020 so that the writes land there.

Check in the log: with adaptive stepping a deltaT = … line appears at each step next to the Courant line. Extract the history with grep '^deltaT' log.foamRun and grep 'Courant Number' log.foamRun; if deltaT never changes despite adjustTimeStep yes, the module or the case is not using adaptation (for example because the case is steady).

At each step the dictionaries registered as “re-read if modified” are compared with the file on disk. The checking method is the fileModificationChecking option of the OptimisationSwitches in $FOAM_ETC/configDict (default timeStampMaster: modification-date check performed by the master process in parallel; alternatives timeStamp, inotify, inotifyMaster). On network file systems fileModificationSkew also matters: the seconds subtracted from the file date to compensate for delays and unsynchronised clocks (Guide §4.3). When a file is re-read, the log reports a message naming the re-read object (for example controlDict): that is the confirmation to record.

What responds reliably: the time and write controls of controlDict (endTime, stopAt, writeInterval, …) and, in general, the numerical parameters of fvSchemes and fvSolution. What must not be taken for granted: the mesh, the solver module (already loaded), the boundary conditions in the fields of the time directory in use, and many physical properties.

An editor that saves in several stages can make the solver read a half-written file, with a syntax error that stops the run. Safer: a single complete write with foamDictionary -set, preceded by a dated copy.

# 1. keep a dated copy of the file you are about to change
cp -p system/controlDict system/controlDict.$(date +%Y%m%d-%H%M%S)
# 2. change one entry in a single, complete write
foamDictionary -entry stopAt -set nextWrite system/controlDict
# 3. look for the confirmation in the log
grep -n 'controlDict' log.foamRun | tail -n 3

Ctrl-C (SIGINT) or kill terminate the process without writing: everything computed after the last write is lost and the restart point is the last complete directory. An interruption during a write can leave an incomplete time directory (some fields missing or truncated): before a latestTime restart check that the last directory contains all fields and, if not, move it out of the case rather than deleting it.

Comparing the orderly routes: stopAt writeNow writes immediately at the step after the re-read (no computation lost, but the written time is off the planned grid); stopAt nextWrite keeps the write grid (at the cost of waiting until the next event); stopAt noWriteNow stops without writing and is useful only when the data after the last write are not needed. There are also the OptimisationSwitches writeNowSignal and stopAtWriteNowSignal (Guide §4.3), which associate an operating-system signal with “write now” or “write and stop”; check their value in $FOAM_ETC/configDict with foamDictionary -entry OptimisationSwitches/writeNowSignal $FOAM_ETC/configDict before relying on them.

Template entry for the lab record: “2026-10-16 14:32 — case channel_B — endTime 0.020 → 0.040 — requested at t ≈ 0.014 — confirmed in the log at line N (controlDict re-read) — reason: extending the transient”.

The v14 Guide (§7.2) states that since v12 function objects preferably go in a separate system/functions file, rather than in the functions sub-dictionary of controlDict: applications that do not use function objects then do not need to read them. The older location in controlDict, shown above, still works. Pre-configured functions are included with the #includeFunc directive, passing arguments in brackets; those with many parameters (for example forces) are copied into the case with foamGet and edited: a local copy in system takes precedence over the defaults in $FOAM_ETC/caseDicts/postProcessing.

# v12 and later: a separate system/functions file is preferred
foamGet functions                       # copies a template into system/
# inside system/functions, for example:
#includeFunc patchFlowRate(patch=outlet)

foamPostProcess -list                   # configured functions available
foamToC -functionObjects                # underlying function-object types
# after the run, with the models of the solver module constructed:
foamPostProcess -solver incompressibleFluid -func "patchFlowRate(patch=outlet)"

foamInfo gives a description and examples for models, modules and functions; foamPostProcess -list lists the configured functions available; foamToC -functionObjects lists the compiled function-object types. Results normally go in postProcessing/<name>/<start time>/. For the channel, an outlet flow rate (patchFlowRate) is the natural first check: it must equal the inlet flow rate imposed in Part 3.

The table above separates “when to evaluate” from “when to write”. In Foundation function objects these two questions correspond to the executeControl/executeInterval and writeControl/writeInterval pairs, which accept the same modes seen in section 4 (timeStep, runTime, adjustableRunTime, clockTime, cpuTime) plus writeTime, which ties the event to the case field writes. A probe can thus be evaluated and written at every step (for a fine time history) while the full fields are saved only every 5 steps: this is precisely how to obtain a lot of data without filling the disk.

Watch consistency with purgeWrite: function-object data are not deleted by purgeWrite, but a function object run “after the fact” with foamPostProcess can only process the time directories that remain. Decide before the run which quantities are needed during execution and which can be derived afterwards.

Prediction: 0.020/0.002 = 10 steps; writes at steps 5 and 10 → directories 0.01 and 0.02. Before the run ls shows 0, constant, system (plus any case scripts); afterwards 0.01, 0.02 and log.foamRun appear. 0/ remains unchanged: the solver does not overwrite it.

A normal end has three concordant signs: the last line of the log is End; no FOAM FATAL ERROR or FOAM FATAL IO ERROR appears in the log; the process exit code is 0 (echo $? right after foamRun). If | tee is used instead of redirection, the exit code is that of tee unless set -o pipefail is set first. A log file exists even after an error at the first step: that is why its mere presence proves nothing.

tail -n 3 log.foamRun              # a normal termination ends with the line "End"
grep -c '^Time = ' log.foamRun     # number of completed time steps (10 here)
grep -n 'FOAM FATAL' log.foamRun   # empty output = no fatal error recorded
foamListTimes                      # written times, 0 excluded

The two sources named are an already working native v14 tutorial or the complete validated case of the series: the first worked case, the laminar Poiseuille channel, contains all the files needed (mesh, fields, physicalProperties, momentumTransport, fvSchemes, fvSolution) for incompressibleFluid. Among the tutorials, look for those that select the same module and copy one into your working directory before touching it.

# Native v14 cases that select the incompressibleFluid module
grep -rl --include=controlDict 'incompressibleFluid' "$FOAM_TUTORIALS" | head
# Copy one to your own run directory before touching it
mkdir -p ~/run && cp -a "$FOAM_TUTORIALS/incompressibleFluid/cavity" ~/run/cavityBaseline
ls ~/run/cavityBaseline

The cavity path is the usual one in recent Foundation versions; if it differs in your installation, use the result of the grep search. Many tutorials need a mesh step (blockMesh) first or have an Allrun script: read it before running it and, for this laboratory, replace only the controlDict values of Stage B. A cavity is closed: its patches are not called inlet/outlet, but the time logic is identical.

Two remarks to write on the sheet. In B the final state computed at 0.020 is not saved: the run performs 10 steps, but the last two (0.018 → 0.020) leave no trace on disk; a restart from B starts from 0.018. To avoid this, choose a writeInterval that divides the total interval. In C the size reduction depends on the mesh and the values (nearly uniform fields compress very well); on a 2,000-cell mesh the run time is dominated by start-up and the solver, so time differences of a few tenths of a second are noise: repeat the measurement before drawing conclusions.

# three independent copies of the same validated baseline
for c in A B C; do cp -a channelBaseline channel_$c; done

foamDictionary -set "writeControl=runTime, writeInterval=0.006" channel_B/system/controlDict
foamDictionary -set "writeFormat=binary, writeCompression=on" channel_C/system/controlDict

for c in A B C; do (cd channel_$c && foamRun > log.foamRun 2>&1); done

# measurements for the lab sheet
for c in A B C; do
  echo "== $c"
  (cd channel_$c && foamListTimes && du -sh $(foamListTimes) \
     && grep 'ExecutionTime' log.foamRun | tail -n 1)
done

OpenFOAM fatal errors have a fixed structure: a --> FOAM FATAL ERROR header (logic or selection error) or --> FOAM FATAL IO ERROR (file reading error), a message, then the file and line involved and the code function that detected the problem. Look for the first such block with grep -n -A 12 'FOAM FATAL' log.foamRun | head -n 30: later errors are often consequences.

Exact wording changes between versions: use the table to recognise the category, not as text to search for word by word. Fix one cause at a time and rerun the same command, keeping the previous log under a different name (mv log.foamRun log.foamRun.1).