Documentation of the main branch

These pages follow Mallard's main branch, which is ahead of release 0.8.0: some features they describe come with the next release.

Output and diagnostics

A run writes snapshots of the solution ([[write_data]]), restart files, and diagnostics: wall forces, domain integrals, running statistics and probes. The log on the terminal reports progress and timing.

Snapshots: [[write_data]]

[[write_data]]
prefix = "solut/flow"         # directories are created
format = "vtu"                # vtu, hdf5 or restart
time_interval = 0.01          # or interval = 100 (steps)
variables = ["RHO", "U", "P", "T", "VORTICITY"]

[[write_data]]                # several entries write independently
prefix = "solut/wall"
format = "vtu"
interval = 50
geometry = "cylinder"         # the faces of one boundary zone
variables = ["P", "T"]

Key	Default	Meaning
prefix	required	Output path prefix
format	required	vtu (ParaView, with a .pvd time series), hdf5 (with XDMF), or restart
interval / time_interval	one required	Every this many steps, or this much simulated time (the step is shortened to land on each output time)
variables	required (vtu, hdf5)	Variables to write, below; Y_* selects every variable with that prefix
geometry	"all"	vtu: a boundary zone name writes that zone's faces with the values of their cells (wall pressure, heat flux)
compression	"none"	"zlib": lossless compression of vtu, hdf5 and restart files (below)
relative_error	none (lossless)	vtu, hdf5 with compression = "zlib": lossy, each cell value within this relative error
chunk_cells	65536	Compressed restart files: cells per chunk

Variables:

Group	Names
Conservative	RHO, RHOU_X, RHOU_Y, RHOU_Z, RHOE, RHOU (vector)
Primitive	U_X, U_Y, U_Z, U (vector), P, T, H
Derived	CFL, VORTICITY, Q (Q-criterion)
TENO	TENO_SIGMA (troubled-cell indicator)
Mixtures	Y_<s>, X_<s>, RHOY_<s>; viscous: MU, LAMBDA, D_<s> (and DT_<s> with soret)
Chemistry, radiation	HRR, OMEGA_<s>, CHEM_COST, QRAD
LES	MU_T; TFLES: TF_F, TF_E, TF_OMEGA; PaSR: PASR_KAPPA
Detonations	P_MAX, the largest pressure each cell has seen (numerical soot foil)
Statistics	MEAN_<A>, COV_<A>_<B>, MEAN_*, COV_*

VTU or HDF5. VTU is the simple choice: one file per snapshot (and per rank in parallel, assembled by a .pvtu). format = "hdf5" (builds with -DMallard_ENABLE_HDF5=ON) writes one file per snapshot from all ranks with collective I/O, plus the mesh once, and XDMF indexes that ParaView opens. It pays off for large runs on parallel file systems; the files do not depend on the rank count. Read them in Python with tools/mallard_h5.py.

Asynchronous and compressed output. Writing large snapshots can take longer than many steps. By default ([output] async = true) each snapshot is copied out and written on a background thread while the run goes on, with the same files byte for byte as async = false; io_threads copies and compresses on several threads (GPU runs leave the host cores idle):

[output]
io_threads = 8              # async = true is the default

[[write_data]]
prefix = "solut/flow"
format = "vtu"
interval = 500
variables = ["RHO", "U", "P", "T"]
compression = "zlib"       # lossless; readable by any ParaView
relative_error = 1e-4       # optional: lossy, |x' - x| <= 1e-4 |x| per value

Compressed VTU uses VTK's own zlib compressor and compressed HDF5 the standard shuffle and deflate filters, so ParaView and h5py read them unchanged. VTU and restart compression needs a build with -DMallard_ENABLE_ZLIB=ON. relative_error rounds each value to the fewest mantissa bits within the bound (the mesh stays exact), which compresses smooth fields several times further; restart files are always lossless. On 4.2M quads on an A100, a VTU snapshot of RHO, U, P, T is 474 MB, 164 MB with zlib and 59 MB with relative_error = 1e-4.

Pitfalls: the run's summary reports the time spent writing; if each file takes longer to write than the steps between files, the run waits for the previous file anyway (write less often, or compress with more io_threads). Errors writing a file surface at the next file or at the end of the run, which waits for every file; a run killed outright (e.g. kill -9) can leave the file being written incomplete, while the files before it are complete. HDF5 output on several ranks stays synchronous (parallel HDF5 calls MPI only from the main thread).

Restart files (format = "restart") are described in Initialization and restarts.

The log

Rank 0 prints a header (version, build, device), the setup time of each stage, summaries of mesh, physics, numerics, boundaries and output, then one progress row every [output] check_interval steps (default 1):

Column	Meaning
step, t, dt	Step, time and time step
done	Fraction of the run, by whichever stop condition comes first
wall/step, cells/s, ETA	Time-stepping wall time per step, cell updates per second, time remaining
min rho, min p, max Ma	Positivity and Mach number at a glance
troubled	TENO: share of cells selecting stencils (shocks)

Chemistry adds the share of cells advanced and the largest sub-step count. Written files appear as rows with their step and time. The run ends with a summary of wall time (setup, time stepping, diagnostics, output) and throughput. Errors go to stderr from any rank. Colors are off when the output is not a terminal or NO_COLOR is set (CLICOLOR_FORCE=1 forces them, e.g. under mpirun).

Wall forces: [[forces]]

[[forces]]
zone = "cylinder"
interval = 10        # default 1
# file = "forces_cylinder.csv"

Writes step, t and the pressure and viscous force components of the fluid on the zone, per unit depth in 2D (per radian in axisymmetric runs). Divide by the dynamic pressure and a reference length (or area) for drag and lift coefficients.

Domain integrals: [integrals]

[integrals]
interval = 1
budget = true        # kinetic-energy budget (LES), default false

Writes integrals.csv with the volume integrals of the kinetic energy, enstrophy, squared dilatation and pressure dilatation, and of |u|^2, |omega|^2, rho^2, T and T^2 (from which mean squares and variances follow). For decaying turbulence (the Taylor–Green vortex) the dissipation rate is -dE/dt. With TENO, velocity gradients come from the reconstruction polynomials (order-consistent: within 1% of spectral derivatives of the same field). budget = true adds the kinetic-energy budget: molecular, SGS and numerical dissipation.

Statistics

[statistics] keeps running time averages and covariances per cell, on the device, without communication: bitwise the same on any number of ranks, and carried across restarts.

[statistics]
fields = ["RHO", "U_X", "U_Y", "U_Z", "P", "T"]
products = ["U_X*U_X", "U_Y*U_Y", "U_Z*U_Z", "U_X*U_Y"]
t_start = 40.0
interval = 10

Key	Default	Meaning
fields	none	RHO, U_X, U_Y, U_Z, P, T, H, Y_<s>
products	none	Pairs "A*B" whose covariance to keep
t_start	0	Start averaging after this time
interval	1	Sample every this many steps (weighted by the time since the last sample)
reset	false	Start afresh on a restart

Write them with variables = ["MEAN_*", "COV_*"], and average further over homogeneous directions with tools/plane_average.py (e.g. over x and z of a channel, giving profiles in y; its CSV also feeds synthetic inflow).

Probes: [[probes]]

[[probes]]
name = "centerline"
variables = ["RHO", "P"]
start = [0.0, 0.01]
end = [1.0, 0.01]
n_points = 200
interval = 10

Point (point = [x, y]) or line (start, end, n_points) probes append step, t, point, x, y, <variables> to probe_<name>.csv, at full precision, from the cell containing each point. The Sod comparison on the Numerics page was read from such a line probe. Variables are those of [statistics].

Post-processing

The Python scripts in tools/ (numpy, matplotlib; see Tools) read Mallard's output directly:

Script	Use
mallard_vtu.py, mallard_h5.py	Readers for VTU and HDF5 output, for your own scripts
plot_vtu.py, compare_png.py	A field of one or several snapshots
animate.py	MP4/GIF animation of a 2D series with numerical schlieren
plane_average.py	Averages over homogeneous directions
plot_<case>.py	Each validation case against its reference

ParaView opens .pvd (VTU) and .xmf (HDF5) series directly.

See also

• Input reference: [[write_data]], [output], [[forces]], [integrals], [statistics], [[probes]]