4.2. Fluid Output

Many fluid quantities defined at the level of the lattice are available for output. The fluid quantities include the lattice Boltzmann distributions, density and velocity, and order parameters if relevant. Output for some quantities is optional, while output for quantities required for restart will always be enabled automatically.

4.2.1. I/O for all lattice quantities

There are a significant number of options related to the input and output of data. These concern the format of the data, the mechanism by which the data are produced, and reporting of input/output activity. The recommended options are:

default_io_mode           mpiio    # Use MPI-IO
default_io_format         binary   # ascii or binary
default_io_report         no       # produce a report on i/o

Here, the mode is the mechanism used to generate the output. The recommended mode is MPI-IO, which will always work and produce the same file irrespective of the number of MPI tasks. The format refers to the representation of data in files: either binary or ASCII is available. Binary format is recommended for reasons of speed and file size; for these reasons it is also the default.

4.2.1.1. Control for specific lattice quantities

Input and output for different quantities are controlled by specific key value pairs. For example, options for the density field rho may be selected explicitly - overriding any default - using:

rho_io_mode               mpiio    # overrides default_io_mode
rho_io_format             binary   # overrides default_io_format
rho_io_report             yes      # overrides default_io_report

rho_input_io_format       ascii    # overrides rho_io_mode
rho_output_io_format      binary   # overrides default

where``rho`` has replaced default in each case. Available lattice quantities include (using mode as an example):

lb_io_mode                          # LB distributions
rho_io_mode                         # density field (scalar)
vel_io_mode                         # velocity field (vector)
phi_io_mode                         # order parameters

Note that all order parameter fields are treated on the same basis including scalar order parameters phi, vector order parameters p, and tensor order parameter q. The format of these files for different numbers of scalar or vector components is discussed below.

4.2.1.2. Frequency of I/O

The following types of output may be requested at regular intervals

freq_rho         # fluid density
freq_vel         # fluid velocity
freq_phi         # order parameter
freq_config      # Full configuration output for restart

Full configuration output includes the lattice Boltzmann distributions, the density and velocity fields, and order parameters as required. The density and velocity fields are required in addition to the lattice Boltzmann distributions to ensure reproducibility at restarts.

If a full configuration is not required at the end of the run, one can set

config_at_end          no      # default is "yes"

The default is that configuration output should be produced at the end.

4.2.1.3. Meta data and data

Requests for file output will always create a relevant metadata file for the type of output requested. For example, a request for order parameter output will generate a single JSON file

phi-metadata.001-001

which contains information on the system size, order parameter fields and so on. The meta-data file provides a description of the corresponding data and is useful for post-processing.

Actual data appear in a separate file for each time step (at the frequency requested), e.g.,

phi-000000000.001-001
phi-000020000.001-001

would be expected for a simulation starting at time step zero, and producing output at each 20,000 steps. The file extension .001-001 indicates this is one file in a set of one.

4.2.1.4. Multiple file output

For the largest systems (probably larger than \(512^3\)) run on very large numbers of MPI tasks, it may be favourable to ask for output to be written to more than one file. This allows a larger overall bandwidth to disk to be obtained. The downside is that the separate files must be recombined if a complete view is required for visualisation etc.

Output (and input) to more than one file is requested by specifying an I/O grid. This decomposes the system in a similar way to the processor decomposition (with one or more MPI tasks per I/O grid group).

The I/O grid is set via

default_io_grid 2_2_1

which would result is four I/O groups writing to four separate files, e.g.,

phi-000020000.001-004
phi-000020000.002-004
phi-000020000.003-004
phi-000020000.004-004

with corresponding metadata files. The metadata files will detail which portions of the complete system are held by the respective data files.

4.2.2. File Data Formats

4.2.2.1. Data format

Output can be requested in either ASCII or (raw) binary format. While ASCII output can be appropriate for initial investigations, it is recommended that binary format is used. The data is always stored as 8-byte floating point in binary format. In ASCII there are usually 15 decimal places of precision.

4.2.2.2. Serial storage order

In serial (or with one MPI task with multiple threads), output occurs to a single file. Data for fluid quantities are written to file on a per-lattice site basis in the following order:

x_1 y_1 z_1   q_1 q_2 ...
x_1 y_1 z_2   q_1 q_2 ...
...
x_1 y_1 z_N   ...
x_1 y_2 z_1   ...
...

4.2.3. Older-style I/O mode

Users of versions older than v0.19.0 will have used an older I/O mode which can be retained by using

default_io_mode           ansi     # use "old" mode

There is no reason to prefer the old style I/O, except for the casae that older files are used for input. One can use

default_input_io_mode     ansi
default_output_io_mode    mpiio

which would enable reading of “old” style input data files and writing of “new” style outputs. Note that in serial, the organisation of the data in the files is actually the same in both cases.