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.

Tools

Python scripts need numpy, scipy, matplotlib, imageio and imageio-ffmpeg; the 3D animations also need pyvista.

Script	Purpose
mallard_vtu.py	Minimal reader for Mallard's VTU files (cells, cell data, time), binary or ASCII (boundary-zone output); also reads HDF5 snapshots (.h5), so the scripts below accept them too
mallard_h5.py	Reader for format = "hdf5" output (needs h5py): mesh, cell fields of a snapshot, and the snapshots of a series PREFIX.xmf (animate.py takes --glob "PREFIX_[0-9]*.h5")
plot_vtu.py	Plot one cell field of a VTU file
compare_png.py	Side-by-side plots of a field from several VTU files
plot_sod.py	Density profiles against the exact Sod solution
plot_viscous_shock_tube.py	Viscous shock tube at t = 1 against the grid-converged reference of Zhou et al.: wall density, lambda-shock triple point
animate.py	MP4/GIF animation of a VTU series: density (or --var, including derived VORTICITY and MACH) with contours, plus numerical schlieren
animate_cartesian.py	Large runs on generated quad meshes (millions of cells): extract turns each (P)VTU snapshot into a float32 grid (.npy), optionally deleting the snapshot and following a running case so disk use stays bounded; render makes pixel-exact 4K frames (shaded density beside the numerical schlieren, area-averaged from the full grid, so nothing aliases) and the MP4; still writes the density and schlieren at one pixel per cell
animate_grid.py	Several cases side by side in one animation, synchronized in normalized time: field panels, wall profiles against reference data, 2D detonations with their soot foil, pre-rendered frame sequences (e.g. 3D views) and time series traced over a reference curve. hero_grid.json makes the README animation from the 4096² Riemann problem, 3D detonation, Taylor-Green (full box) and 2D autoignition examples, frames cropped from the case animations plus the TGV dissipation rate traced over the DNS (the config's _inputs lists where each input comes from); detonation panels show a 2D detonation run's pressure and numerical soot foil
make_import_meshes.py	The mesh-import test fixtures in test/data/meshes/: one channel-and-cylinder mesh (2D, extruded 3D, tetrahedral 3D, order 2) written by Gmsh as .msh and CGNS (also as two zones joined 1-to-1), and converted by OpenFOAM in a container (podman or docker, opencfd/openfoam-default) to polyMesh (gmshToFoam) and Fluent (foamMeshToFluent)
make_cylinder_mesh.py	Gmsh O-grid around a cylinder; --half gives the upper half with the axis cuts, the meridian plane of a sphere for axisymmetric runs
plot_poiseuille.py	Axisymmetric Hagen-Poiseuille flow: axial velocity against the exact r-weighted cell averages
plot_noh.py	Spherical Noh problem from an axisymmetric run: density against the exact solution, shock radius by direction
plot_sphere_axisymmetric.py	Steady axisymmetric flow past a sphere: drag, separation angle and wake length against the literature
make_mallard_mesh.py	Triangle mesh (via the gmsh Python module) around a flying mallard silhouette
plot_taylor_green.py	Taylor-Green vortex: kinetic energy and dissipation rate (-dE/dt and enstrophy-based) from [integrals] output against the spectral DNS reference
animate_taylor_green.py	Taylor-Green vortex animation: Q-criterion isosurfaces on the box mirrored from the computed octant, orbiting camera, and the dissipation rate tracing the reference
chemistry_reference.py	Reference data for the chemistry tests from Cantera (pip install cantera): writes the CSV files in test/data/chemistry/, which are committed so the tests need no Cantera
transport_reference.py	Transport reference data from Cantera: species viscosities, conductivities and binary diffusion coefficients, and mixture-averaged and unity-Lewis mixture properties, as CSV files in test/data/chemistry/
flame_reference.py	Freely propagating premixed flames (Cantera FreeFlame) of H2/air and CH4/air at 300 K and 1 atm, phi 0.6-1.4, mixture-averaged and unity Lewis: flame speeds, thermal thicknesses and profiles in examples/premixed_flame/reference/, and optionally each flame's full solution; --single FUEL PHI T_U DIR computes only one mixture's flames (both transport models, any fresh-gas temperature)
flame_restart.py	A premixed-flame run (input and restart file) in the flame's frame from a Cantera flame's full solution, at a given number of cells per thermal thickness: a 1D strip, or with --ny a periodic 2D channel whose front is wrinkled by random modes (--perturb); --ref-delta gives flames of different transport the same mesh
flame_speed.py	Consumption and displacement speeds of a premixed-flame run over time, against a reference flame speed
flame_sweep.py	Sweeps of 1D premixed-flame runs over equivalence ratio, transport model, resolution and CFL (setup, with flame_restart.py, a restart file every half flame time), and their report against Cantera (report): consumption speed over the last flame time and its drift, displacement speed, peak heat release and temperature profile errors, the change from CFL 1 at equal times, as a table, CSV and plot
plot_flame.py	Temperature and heat release profiles of a premixed-flame run against Cantera's, aligned at the maximum of dT/dx
counterflow_reference.py	Counterflow diffusion flames (V10) from Cantera's CounterflowDiffusionFlame: H2/N2 against air swept in strain rate up to extinction (peak temperature against the local strain rates ahead of the flame and the spread rate at the flame), and full solutions at given nozzle velocities (--profile) or local strain rates (--match), in examples/counterflow_diffusion/reference/
counterflow_setup.py	A 3D counterflow run from a Cantera solution: the quarter domain of two opposed round jets with N2 coflows, as a Gmsh file of hexahedra refined through the flame, the initial state (Cantera's solution with radial velocity r V(x)) and the input file
plot_counterflow.py	Counterflow runs against Cantera on the stagnation line: peak temperature against the local strain rate and against the spread rate at the flame, temperature, velocity and species profiles at matched strain rate, histories, and a still of the flame
isotropic_turbulence_restart.py	Initial state of examples/isotropic_turbulence as a restart file: random solenoidal velocity with E(k) ~ k^4 exp(-2 (k / k0)^2) at a given Mt, uniform density and pressure, as exact cell averages of the same band-limited field on any N^3 mesh; prints the derived viscosity and tau
isotropic_turbulence_stats.py	Statistics of isotropic turbulence snapshots (restart files of a uniform hexahedral box): kinetic energy, enstrophy, dilatation, temperature, density and pressure variances on the full mesh and filtered to 64^3 (sixth-order or spectral derivatives, the references' protocols), Mt, Re_lambda, k_max eta; shell spectra and fields for the animation
plot_isotropic_turbulence.py	Isotropic turbulence runs against the filtered DNS of Johnsen et al. (2010) and Subramaniam et al. (2019): filtered and unfiltered histories (grid convergence) and spectra
animate_isotropic_turbulence.py	Isotropic turbulence animation: Q-criterion isosurfaces colored by dilatation, orbiting camera, the dilatation on a plane (shocklets) and the enstrophy and dilatation variance tracing the reference
make_sphere_mesh.py	Gmsh tetrahedral mesh of the quarter domain around a sphere (symmetry planes y = 0 and z = 0), refined on the sphere and through the bow-shock layer
plot_sphere.py	Bow-shock standoff of supersonic flow over a sphere, from the meridian-plane output, against Billig's correlation
animate_sphere.py	Sphere animation: Mach number on the horizontal meridian plane, schlieren on the vertical one, the bow shock revolved into a 3D surface, and the standoff history against Billig
sedov.py	Exact 3D Sedov-Taylor blast (similarity ODEs): the constant xi0 of R = xi0 (E t^2 / rho0)^(1/5), and a run's shock radius and density profile against it
animate_sedov.py	Sedov-Taylor animation: density on the three symmetry planes (mirrored to full disks) with the exact shock sphere, orbiting camera, shock radius and density profile against the exact solution
make_sphere_re300_mesh.py	Gmsh mesh of the full domain around a sphere for viscous flow: prism boundary layer, tetrahedra refined through the near wake; --scale refines every size for mesh studies
plot_sphere_re300.py	Sphere at Re = 300: Strouhal number from the lift, mean drag and lift over whole shedding periods, against Johnson & Patel and other simulations
animate_sphere_re300.py	Sphere wake animation: Q-criterion isosurfaces colored by streamwise velocity, orbiting camera, and the drag and lift histories
plane_average.py	Average [statistics] output (MEAN_, COV_) of a quad or hex mesh over homogeneous directions as a function of the others (e.g. a channel's profiles in y), grouping equal cell-center coordinates (stretched meshes included) and adding the dispersive part to the covariances; reads VTU or PVTU
channel_init.py	Initial state of the turbulent channel (examples/channel_retau180) as a restart file: a turbulent-like mean profile at bulk velocity 1 plus a random, divergence-free perturbation (the curl of a random vector potential) that vanishes at the walls
plot_channel.py	Turbulent channel against Moser, Kim & Mansour (1999): mean velocity, RMS velocities and Reynolds shear stress in wall units from plane_average.py profiles, wall shear history, Re_tau and skin friction (downloads the MKM profiles on first use)
animate_channel.py	Turbulent channel animation from restart files: Q-criterion isosurfaces colored by streamwise velocity over the near-wall streaks
interpolate_restart.py	Interpolate a restart file onto another Gmsh mesh of the same domain (inverse-distance weighting of the nearest cells); [initialize] type = "remap" does this conservatively and to high order on any mesh
znd_restart.py	Initial state of a detonation run from a ZND profile (detonation_reference.py): 1D, 2D (--ny, --ly) or a 3D duct (--nz, --lz too) with disks or spheres of unreacted gas behind the front (--pocket, repeatable; --fresh-pocket for fresh gas at rest) to trigger cells
detonation_window.py	Moving window for detonation runs on generated boxes: alternates Mallard runs and shifts of the restart file that keep a fixed stretch of burnt gas behind the front, saving the soot foil (P_MAX) of the dropped columns and animation frames; also turns a 2D cellular detonation into a 3D initial state (extrude, --superpose for both transverse directions in phase)
soot_foil_3d.py	3D detonation in a duct: the four wall soot foils of a detonation_window.py run, mean front speed against D_CJ and the track spacings along and across each wall
animate_detonation_3d.py	3D detonation animation: the leading shock colored by the pressure behind it in a cut-away duct whose far walls carry the soot foil, and the four foils unrolled
shock_bubble.py	Shock / helium-bubble interaction: initial state (Rankine-Hugoniot shock, contaminated helium bubble with a tanh interface), frames reduced from restart files, and the axis x-t diagram's velocities against Haas & Sturtevant (1987)
animate_shock_bubble.py	Shock / helium-bubble animation: helium and vortex-ring isosurfaces, schlieren on the symmetry plane and the x-t diagram against the experiment's velocities
soot_foil.py	2D cellular detonation: mean front speed against D_CJ, triple points on the front and the cell width they imply, and the numerical soot foil (P_MAX) as an image
animate_detonation_2d.py	Cellular detonation animation: pressure and the soot foil building up in a window that follows the front, and the whole foil so far
animate_flame_2d.py	Side-by-side animation of 2D flame runs (flame_restart.py --ny): temperature over the adiabatic flame temperature with heat-release contours, and the consumption speeds against time
perf_suite.py	The performance set (benchmarks/perf/): runs it on 2D and 3D builds (best of several runs after a warm-up, with the spread), writes JSON/CSV, compares with the baselines for the hardware (fails when slower by more than the threshold and the spread) and updates them; standard library only
triple_flame.py	A triple-flame run: a planar premixed front (Cantera's flame at the stoichiometric mixture fraction) meeting a tanh mixing layer of fuel and air that enters through a upt inlet with a composition varying across it
triple_flame_analysis.py	Triple flames: leading-edge position, propagation speed U_F = u_in - dx_tip/dt, local mixing thickness D_TF through the strongest heat release, and U_F / S_L against D_TF beside Ruetsch, Vervisch & Linan (1995)
animate_triple_flame.py	Side-by-side triple-flame animation: heat release with the stoichiometric and equivalence-ratio lines, fresh-gas streamlines and the leading edge, and each run's U_F / S_L against the heat-release limit
flame_vortex.py	A premixed flame-vortex run in the half channel above the pair's axis: a counter-rotating Gaussian vortex pair of size r and velocity u' upstream of a planar flame (flame_restart.py)
flame_vortex_analysis.py	Flame-vortex runs: total heat release, flame length, weakest burning along the front and cut-off fresh-gas pockets over time; each run classified as Poinsot, Veynante & Candel (1991) do and placed on their spectral diagram
animate_flame_vortex.py	Flame-vortex animation: every run's temperature, heat release and vorticity on one clock (mirrored to the full pair), with the spectral diagram and the heat-release histories
autoignition_restart.py	Initial state of a stratified autoignition run (input and restart file): a periodic square of lean H2/air at uniform pressure with Passot-Pouquet random fields of temperature (--t-rms, --l-T) and solenoidal velocity (--u-rms, --l-e); the same --seed gives the same field shapes at every amplitude
autoignition_reference.py	0D references of the autoignition runs with Cantera: the homogeneous constant-volume reactor (tau_0), the ignition delay against temperature, and the multizone model of each run's initial temperatures (equal-mass zones at a common pressure, no transport)
autoignition_deflagration.py	1D Mallard runs of the deflagration speed S_L and thickness of an autoigniting mixture, with the fresh gas frozen ([chemistry] T_frozen) so that it cannot autoignite; measure gives the consumption speed over time
autoignition_analysis.py	Autoignition runs against their 0D references: mean heat release rate, its peak time and width, and the share of heat released by deflagrations (displacement speed of the H2O isolines against S_L) next to the a priori criterion of Sankaran et al. (2005); history CSVs and figures
animate_autoignition.py	Side-by-side animation of autoignition runs: temperature and heat release rate of each, and the mean heat release rate traced over the multizone and homogeneous predictions
flame_turbulence.py	Flame in decaying turbulence (examples/flame_turbulence): isotropic initial field (hit), premixed or diffusion flame placed in it, box-filtered and thickened for LES (init), laminar reference rates (laminar), snapshots to npz (extract), flame speed, consumption speed, flame surface and filtered temperature PDFs (analyze), comparison figure (figure)
render_flame_turbulence.py	3D render of the flame surface (colored by heat release) and the vortices of the fresh gas from extract snapshots; side-by-side stills and movies (needs pyvista)
make_volvo_mesh.py	Gmsh file of hexahedra for the Volvo bluff-body combustor (examples/volvo_bluff_body): four blocks around the triangular flameholder, mesh lines normal to its slanted faces, spanwise extrusion (periodic)
volvo.py	Volvo bluff-body LES analysis: probes (a mid-span plane of line probes for the input), profiles (span and time averages at the measurement stations and on the centerline, recirculation length), plot (against the experiment in examples/volvo_bluff_body/reference, with the mean errors), budget (dissipation shares and eps_num / eps_sgs over a window), slice / animate (mid-span vorticity or temperature movie), render (Q-criterion isosurface, needs pyvista)
tfles_apriori.py	A priori test of the TFLES efficiency on a filtered DNS: wrinkling factor at the scale F delta_L, Colin's and the eddy-viscosity subgrid velocities against the DNS's, and the implied C_u; on extracted .npz snapshots, the dynamic efficiency against the wrinkling factor
make_annulus_mesh.py	Gmsh O-grid of an annulus (quadrilaterals, or triangles with --triangles), optionally with high-order boundary lines (--order 2 or 3) on the circles and jittered nodes
curved_convergence.py	Convergence of the steady isentropic vortex between two circular walls, straight against curved boundaries, over orders and mesh levels (the curved-boundary validation)
tile_restart.py	Repeat the flow of a restart file of a generated 3D box along x: starts a spatially developing run from a developed periodic one
cbc_les.py	Comte-Bellot & Corrsin grid turbulence for LES (examples/cbc_les): initial field, rescaling, spectra of restart files, comparison with the measurements and the dissipation budget
mixture_riemann.py	Exact Riemann solution for thermally perfect mixtures of frozen composition: references of the multicomponent shock tube tests
plot_reactive_shock_tube.py	Reactive shock tube at several resolutions: reaction front, peak temperature and pressure at 170 and 230 us
plot_detonation.py	1D detonation runs: shock position, front speed, induction length and peak pressure, against the CJ speed and ZND induction length
cantera_mechanisms.py	Copy the mechanisms too large for the repository (n-hexane, 1268 species) from Cantera's data into mechanisms/external/
v3_reference.py, v3_check.py	Constant-volume ignition with large mechanisms: Cantera references, and MallardReactor against them
docs/make_figures.py	The figures of the user guide (docs/images/guide/) and of the theory manual (docs/images/theory/), light and dark, from the formulas, the example inputs and short Mallard runs (--mallard build/src/Mallard)