[[sec_controlDict]]
=== Time and data input/output control
(((time,control))) (((control,of time)))

The {project} solvers begin all runs by setting up a database. The database
controls I/O and, since output of data is usually requested at intervals of
time during the run, time is an inextricable part of the database. The
filename:system/controlDict[] dictionary sets input parameters 'essential' for
the creation of the database. The keyword entries in
filename:system/controlDict[] are listed in <<tab_controlDictKeywords>>. Only
the time control and `writeInterval` entries are truly compulsory.

[[tab_controlDictKeywords]]
.Keyword entries in the filename:controlDict[] dictionary
[grid="none",frame="topbot",cols="1,3"]
|==============================================================================
2+h| Time control
|`startFrom`(((`startFrom` keyword)))(((keyword,`startFrom`))) a|Controls the
start time of the simulation.

`firstTime`(((`firstTime` keyword)))(((keyword,`firstTime`)))::
  Earliest time step from the set of time directories.
`startTime`(((`startTime`,keyword entry)))(((keyword entry,`startTime`)))::
  Time specified by the `startTime`(((`startTime` keyword)))
  (((keyword,`startTime`))) keyword entry.
`latestTime`(((`latestTime`,keyword entry))) (((keyword entry,`latestTime`)))::
  Most recent time step from the set of time directories.
| `startTime`(((`startTime` keyword)))(((keyword,`startTime`))) | Start time
for the simulation with `startFrom startTime;`
| `stopAt`(((`stopAt` keyword)))(((keyword,`stopAt`))) a|Controls the end time
of the simulation.

`endTime`(((`endTime` keyword)))(((keyword,`endTime`)))::
  Time specified by the `endTime`(((`endTime` keyword)))(((keyword,`endTime`)))
  keyword entry.
`writeNow`(((`writeNow`,keyword entry)))(((keyword entry,`writeNow`)))::
  Stops simulation on completion of current time step and writes data.
`noWriteNow`(((`noWriteNow`,keyword entry))) (((keyword entry,`noWriteNow`)))::
  Stops simulation on completion of current time step and does not write out
  data.
`nextWrite`(((`nextWrite`,keyword entry)))(((keyword entry,`nextWrite`)))::
  Stops simulation on completion of next scheduled write time, specified by
  `writeControl`.(((`writeControl`,keyword entry)))
  (((keyword entry,`writeControl`)))
| `endTime`(((`endTime` keyword)))(((keyword,`endTime`))) | End time for the
simulation when `stopAt endTime;` is specified.
| `deltaT`(((`deltaT` keyword)))(((keyword,`deltaT`))) | Time step of the
simulation.

2+h| Data writing
| `writeControl`(((`writeControl` keyword)))(((keyword,`writeControl`))) a|
Controls the timing of write output to file.

`timeStep` footnoteref:[ftn_default,default if associated keyword is ommited]::
  (((`timeStep`,keyword entry)))(((keyword entry,`timeStep`)))
  Writes data every `writeInterval` time steps.
`runTime`(((`runTime`,keyword entry)))(((keyword entry,`runTime`)))::
  Writes data every `writeInterval` seconds of simulated time.
`adjustableRunTime`::
  (((`adjustableRunTime`,keyword entry)))
  (((keyword entry,`adjustableRunTime`))) Writes data every `writeInterval`
  seconds of simulated time, adjusting the time steps to coincide with the
  `writeInterval` if necessary &mdash; used in cases with automatic time step
  adjustment.
`cpuTime`(((`cpuTime`,keyword entry)))(((keyword entry,`cpuTime`)))::
  Writes data every `writeInterval` seconds of CPU time.
`clockTime`(((`clockTime`,keyword entry)))(((keyword entry,`clockTime`)))::
  Writes data out every `writeInterval` seconds of real time.
| `writeInterval`(((`writeInterval` keyword)))(((keyword,`writeInterval`))) |
Scalar used in conjunction with `writeControl` described above.
| `purgeWrite`(((`purgeWrite` keyword)))(((keyword,`purgeWrite`))) | Integer
representing a limit on the number of time directories that are stored by
overwriting time directories on a cyclic basis. Example of
math:[t_0=\unit[5\]{s}], math:[\Delta t=\unit[1\]{s}] and `purgeWrite 2;`: data
written into 2 directories, filename:6[] and filename:7[], before returning to
write the data at math:[\unit[8\]{s}] in filename:6[], data at
math:[\unit[9\]{s}] into filename:7[], 'etc.' 'To disable the time directory
limit, specify' `purgeWrite 0;` footnoteref:[ftn_default]; For steady-state
solutions, results from previous iterations can be continuously overwritten by
specifying `purgeWrite 1;`
| `writeFormat`(((`writeFormat` keyword)))(((keyword,`writeFormat`))) a|
Specifies the format of the data files.

`ascii`footnoteref:[ftn_default]::
  (((`ascii`,keyword entry)))(((keyword entry,`ascii`)))
  ASCII format, written to `writePrecision`(((`writePrecision` keyword)))
  (((keyword,`writePrecision`))) significant figures.
`binary`(((`binary`,keyword entry)))(((keyword entry,`binary`)))::
  Binary format.
| `writePrecision`(((`writePrecision` keyword)))(((keyword,`writePrecision`)))
| Integer used in conjunction with `writeFormat` described above,
6 footnoteref:[ftn_default] by default
| `writeCompression`(((`writeCompression` keyword)))
(((keyword,`writeCompression`))) a|Specifies the compression of the data files.

`uncompressed` footnoteref:[ftn_default]::
  (((`uncompressed`,keyword entry)))(((keyword entry,`uncompressed`)))
  No compression.
`compressed`(((`compressed`,keyword entry)))(((keyword entry,`compressed`)))::
  `gzip` compression.
| `timeFormat`(((`timeFormat` keyword)))(((keyword,`timeFormat`))) a|Choice of
format of the naming of the time directories.

`fixed`(((`fixed`,keyword entry)))(((keyword entry,`fixed`)))::
  +&plusmn;m.dddddd+ where the number of ++d++s is set by `timePrecision`.
`scientific`(((`scientific`,keyword entry)))(((keyword entry,`scientific`)))::
  +&plusmn;m.dddddde&plusmn;xx+ where the number of ++d++s is set by
  `timePrecision`.
`general` footnoteref:[ftn_default]::
  (((`general`,keyword entry)))(((keyword entry,`general`)))
  Specifies `scientific`(((`scientific`,keyword entry)))
  (((keyword entry,`scientific`))) format if the exponent is less than -4 or
  greater than or equal to that specified by `timePrecision`.
| `timePrecision`(((`timePrecision` keyword)))(((keyword,`timePrecision`))) |
Integer used in conjunction with `timeFormat` described above,
6 footnoteref:[ftn_default] by default
| `graphFormat`(((`graphFormat` keyword)))(((keyword,`graphFormat`))) a|Format
for graph data written by an application.

`raw` footnoteref:[ftn_default]::
  (((`raw`,keyword entry)))(((keyword entry,`raw`))) Raw ASCII format in
  columns.
`gnuplot`(((`gnuplot`,keyword entry)))(((keyword entry,`gnuplot`)))::
  Data in `gnuplot` format.
`xmgr`(((`xmgr`,keyword entry)))(((keyword entry,`xmgr`)))::
  Data in `Grace/xmgr` format.
`jplot`(((`jplot`,keyword entry)))(((keyword entry,`jplot`)))::
  Data in `jPlot` format.

2+h| Data reading
| `runTimeModifiable`(((`runTimeModifiable` keyword)))
(((keyword,`runTimeModifiable`))) | `yes` footnoteref:[ftn_default] / `no`
switch for whether dictionaries, 'e.g.' filename:system/controlDict[], are
re-read by {project} at the beginning of each time step.

2+h| Run-time loadable functionality
| `libs`(((`libs` keyword)))(((keyword,`libs`))) | List of additional libraries
(on `$LD_LIBRARY_PATH`) to be loaded at run-time, 'e.g.'
`("libUser1.so" "libUser2.so")`
| `functions`(((`functions` keyword)))(((keyword,`functions`))) | List of
functions, 'e.g.' `probes` to be loaded at run-time; see examples in
filename:<tutorials>[]
|==============================================================================

Example entries from a filename:system/controlDict[] dictionary are given
below:

-------------------------------------------------------------------------------
application        icoFoam;

startFrom          startTime;

startTime          0;

stopAt             endTime;

endTime            0.5;

deltaT             0.005;

writeControl       timeStep;

writeInterval      20;

purgeWrite         0;

writeFormat        ascii;

writePrecision     6;

writeCompression   uncompressed;

timeFormat         general;

timePrecision      6;

runTimeModifiable  yes;
-------------------------------------------------------------------------------
