Repository navigation
Mallard 0.10.0 keeps the GPU fed and makes every run explain itself. Steps are decided on the device and enqueued ahead, and every kind of run, reacting and LES included, takes its steps in the CUDA graph. Inputs that choose no numerics now run the high_order preset. Every run writes a self-contained report.html, records what each file holds and where it came from, and diagnoses its own divergence. New mallard post, info, diff and pack commands and a Python package work on saved output, regions can be defined by the solution and move in time, and probes and statistics gain averages, spectra, conditional statistics, convergence monitoring and triggers. mallard check now sizes a run, reports its resolution, checks the environment and draws the case.
Changes that affect results
- Inputs that set neither
[numerics] presetnor[numerics.face_reconstruction]run thehigh_orderpreset (TENO-E 5, HLLC, SSPRK3,cfl = 1.0when[run]sets neithercflnordt) instead of first order.[numerics.face_reconstruction] type = "FO"restores first order;mallard input upgradenotes the inputs this concerns. - The
lespreset runsSSPRK54atcfl = 2.0instead ofSSPRK3at 0.8 (#774).[numerics] time_integrator = "SSPRK3"and[run] cfl = 0.8restore it. - TENO with
convective_flux = "hybrid"feeds the central flux the cells' values (central = "cell_averages"), which no longer adds kinetic energy (#689, #801).central = "reconstructed"restores the earlier flux; MUSCL and first order are unchanged. - Strang-split chemistry fuses each step's closing half step with the next step's opening one (
[chemistry] fuse_half_steps = true; #777). Results change within the chemistry's tolerances and no longer depend on the output schedule or on restarts.fuse_half_steps = falserestores the separate half steps. - Bound-preserving TENO no longer makes premixed flames 4-6% too fast (#707): the H2/air flame at 700 K runs within 1% of Cantera with TENO3 and TENO5.
- Probes no longer read samples outside the domain from the nearest cell (#673). A
pointorpointsprobe outside the domain is an input error; curves and resampled surfaces drop their outside samples withW-PROBE-OUTSIDEand record them asclipped. - Regions follow curved walls (#724): volume fractions, probe samples, clipped zones and extracted surfaces use the curved cells.
- TENO tables change at round-off (#776, #938). TENO caches become
MALLARD-TENO-14and older ones are recomputed. TENO also sets up on meshes one cell thick, where TENO3 results change slightly. - Runs whose
t_stopis a multiple of atime_intervalno longer take an extra round-off-length step and write a second final snapshot. - Last-bit changes: stage times of
SSPRK54,RDPK3Sp35andCK45with time-dependent boundaries, inflows, sources or sponges, which cannot be restored (#944); inputs that iterate a table, such as compositions, now read in key order (#509); sponges,wherefilters, mass-flowprofiles and boundary compositions evaluated by kexpr instead of exprtk; the exact sum of average-pressure outlets; and, on GPUs, synthetic-turbulence inflow weights and the dynamic TFLESbeta. GCC builds without a device backend use-ffp-contract=off, so arm64 matches x86-64.
Upgrading inputs
mallard input upgrade old.toml > new.toml rewrites inputs of earlier releases and notes the inputs affected by the new defaults above.
- Keys deprecated in 0.9.0 are removed and are now errors naming their replacement: the
[[boundaries]]typesupt,p_out,p_out_average,extrapolation,nscbc_inlet,nscbc_outletand characteristic parameters outside thenscbctable;[[mesh.curved]] shape;[[write_data]] geometry;[mesh] periodicand[initialize.mesh] periodic. [[write_data]] format = "hdf5"is removed: use"vtkhdf"(the default) or"xdmf"for the same XDMF and HDF5 files.[[probes]] format = "hdf5"is unchanged.- Renamed, with a warning until 0.11.0:
Qis renamedQ_CRITERION, with no alias (#511).- VTKHDF snapshots default to
series = true: onePREFIX.vtkhdfholds every snapshot (#768).series = falserestores one file per snapshot. - exprtk is no longer bundled. The syntax is unchanged; its vector, string and bitwise functions and case-insensitive names are errors that name the problem.
- Restart files are version 7, which 0.9 and earlier reject; every earlier version is still read (#667).
GPU performance
- Steps enqueued ahead: the device decides dt, the end of the run, retries, NaN checks, monitors, probes, statistics and
[[triggers]], and the host enqueues[run] step_queuesteps ahead (3 by default), stopping only at steps it must act on. Results are the same bit for bit at any depth (#730, #906, #914). - CUDA graphs everywhere: reacting mixtures (Strang and SIMPLER, TFLES, PaSR, chemistry load balancing), LES, mixtures without chemistry,
nscbcboundaries, synthetic inflow turbulence, average-pressure outlets and sources of domain averages take their steps in the graph. In NCCL builds, steps outside the graph also communicate with NCCL on the GPU's stream. - Cell ordering:
[mesh] cell_order = "auto"numbers cells along a Hilbert curve when it reads fewer cache lines, so a mesh file's numbering no longer sets the speed (a Gmsh sphere 28% faster on an A100; #478, #277). - Weak scaling: distributed TENO reconstructs only owned cells and overlaps the exchange, taking 3D TENO5 on 16 A100s from 91% to 96.5% (#305).
- Kernels: boundary dispatch per condition (teno5_3d +0.9%) and leaner mixture and chemistry kernels (flame_3d +3.3%) (#613).
- Setup and memory: 2D TENO setup on the device and up to 1.7 times faster on CPUs (#776, #916); analytical initialization of 1M hexahedra in 0.3 s instead of 3.2 s; faster mesh build and probe setup; setup-only data freed before the first step.
- Large runs: exchanges, gathers and writes of more than 2^31 values no longer fail or corrupt data (#775, #876, #894).
Checking a case
- Sizing:
mallard checkbreaks down memory by category at the setup's peak and in the steady state, and--memory 40GBor--memory a100-80gives the most cells per GPU and the fewest GPUs the mesh fits on (#550). - Resolution: cell sizes against Kolmogorov and Taylor lengths, first-cell y+, x+ and z+, wall-model exchange points and cells across TFLES's
delta_L, with warnings and the spacing to aim for (#548). - Environment:
mallard checkwithout an input checks the build, devices, placement, MPI, GPU-aware MPI and NCCL; run it undersrunormpirunto check a job's ranks (#508). - Case view:
mallard check --view DIRalso draws the case as light and dark SVGs, every zone, region, probe and periodic pair labeled (#546). - Mesh and stencil fields:
--mesh-fields PREFIXwrites mesh quality and TENO or MUSCL stencil fields, and--stencilsevery cell's stencils (#521). - Reports: sections and tables with statuses and units, stable codes (
W-CFL-LIMIT, ...) with a docs link for every warning and error, and--format json(#657, #659, #828).
Run records and reproducibility
report.html: every run writes one self-contained page with its outcome, configuration, health, plots, cost and output index (#515).- Divergence report: a diverging run names the invalid cells, ranks the likely causes with their evidence and what to try, and writes a snapshot of the neighborhood (#549, #659).
- What every file holds: a snapshot block with step, time,
run_id, why it was written, units, precision, value kinds and averaging windows (#667, #671, #672, #674); the run block records the resolved input and every file the run read with its SHA-256 (#509, #668). - Safe output: every file is written as
NAME.partialand renamed once complete;mallard info DIRchecks every recorded file (#669). Theendrecord gives theoutcomeandcause(#670). - Resuming:
--restart latestresumes from the newest complete restart file, as the job scripts and manifests now do (#510);t_wall_stopstops every rank after the same step (#670). - Reproducing:
mallard input resolvewrites the input as the run uses it (#509), andmallard pack RUN_DIRarchives everything needed to rerun (#519). - Monitoring:
--log-format jsonlstreams progress records on stdout (#827); the setup banner, progress table and summary are tables with units (#659, #675);physics.units = "nondimensional"labels no number with an SI unit (#659).
Working with output
mallard info FILE|RUN_DIRreports what any file holds, or a run's outcome, health and cost.mallard diff A Bcompares snapshots, restarts, probes or CSV files with norms, tolerances and exit statuses for CI, across meshes with--remap.mallard post:derive: derived fields of saved files, bit for bit what[[write_data]]writes (#511, #858);average: means, RMS, Reynolds and Favre covariances, homogeneous-direction profiles, solution-defined regions and conditional statistics (#512, #513, #799, #851);extract: probes and snapshots of saved output without rerunning;convergence: observed order, Richardson extrapolation and grid convergence index across resolutions, with or without an exact solution (#514, #769, #812).
- Derived fields:
MACH,Q_CRITERION,LAMBDA2,SCHLIEREN,P0,T0,H0,ENSTROPHY,CPand others, and for mixturesMIXTURE_FRACTION,PROGRESS_VARIABLE,FLAME_INDEXandSCALAR_DISSIPATION, from one catalog shared by[[write_data]],[statistics]andmallard post derive(#511, #512). - Python package
mallard:mallard.openreads every file Mallard writes into numpy arrays with units, through Mallard's own reader (#517). Containers, Spack and source builds install it (#791). - Discovery:
mallard list fields,list keys,list speciesandlist templates(#502, #786), andmallard completion bash|zsh|fish, which also completes keys and fields (#507, #770, #785).
Regions and probes
- Regions defined by the solution:
{type = "where", condition = "T > 1500"}and{type = "isosurface", ...}, followed on the device by sources, sponges, probes and snapshots (#543, #797, #800). - Moving and repeated regions: centers, sizes and transforms may depend on
t;repeatmakes arrays of copies; regions wrap across periodic boundaries (#501). - Exact sampling: curve probes with
n_points = "cells"and filled regions withsampling = "point"are exact for the reconstruction polynomials (#592). Filled region probes record their volume and area (#724), and every probe file records where each sample is read (#673). - Averages and spectra:
average = trueon probes and isosurfaces (#590, #798, #836), probes of the[statistics]averages (#590), and in-run time spectra with Strouhal numbers (#614). - Boundary probes: diffusive and total species and energy fluxes, the wall model's exchange-point state and a
momentreduction (#591); walls with awall_modeltake wall quantities from the model.
Statistics and triggers
[[triggers]]: conditions ont,step,walland monitored values that stop the run, write output or start the statistics, decided identically on every rank.- Convergence:
[statistics.convergence]detects the end of the transient and gives confidence intervals and effective sample sizes that triggers read (#337);[statistics] batchgives every cell confidence intervals (#337). - Conditional statistics:
[[statistics.conditional]]PDFs, joint PDFs and conditional means, the same bit for bit on any rank count;[statistics]samplesHRRandOMEGA_<species>(#513).
Boundary and initial conditions
- Time-dependent inflows:
directionexpressions ofx,y,z,t; synthetic turbulence on aninlet_statewhoseudepends ont(#600);inlet_mass_flowmdotandprofileoft(#601). - Turbulent initial states:
[initialize.turbulence]adds a divergence-free field of a prescribed spectrum, the same bit for bit on any rank count (#563). - LES:
[les] gradients = "reconstruction"(experimental, TENO only) takes the subgrid models' velocity gradient from TENO's central polynomial (#660).
Platforms
- Toolchains: GCC 15, Clang 22 or Apple Clang 21 and CMake 4.2 or newer are required; the Spack package with
+cudaneeds CUDA 13.4 or newer. - Containers are built on Ubuntu 26.04, the CUDA image with CUDA 13.5 (driver R580 or newer).
Known limitations
- Steps one at a time: runs with triggers that read a probe's value, and the progress rows, monitors, means and probes of reacting runs with fused half steps, are not enqueued ahead (#730, #777).
- Owner-computes overlap is reduced on meshes with rotational periodicity (#911) and in LES with
gradients = "reconstruction"(#912). - ParaView 6.0.1 fails to open a bare
.xmffile name; open./flow.xmfinstead (#682).
Installing
docker pull ghcr.io/matthewbonanni/mallard:0.10.0(CPU) orghcr.io/matthewbonanni/mallard:0.10.0-cuda(A100 to H100)- Spack:
spack repo add --path spack/spack_repo/mallard https://github.com/MatthewBonanni/mallard.git, thenspack install mallard %gcc@15(GCC 15 or newer; see the installation guide)
Full list of changes: CHANGELOG.md · v0.9.1...v0.10.0