Skip to content

Mallard 0.9.0

Choose a tag to compare

@MatthewBonanni MatthewBonanni released this 01 Nov 18:06
· 304 commits to main since this release
4bdd932

Mallard 0.9.0 makes regions a single concept used everywhere. Points, curves, surfaces and volumes, defined once and named, drive sources, sponges, initial states, probes, snapshots and curved boundaries. It adds probes of every dimension with exact fluxes, explicit boundary-condition types with composable options, and a run record and health diagnostics in every run. Jobs resume safely from restarts, on clusters, Kubernetes or prebuilt containers. Under the hood, everything typed is now one lowercase mallard command, every input error names its key and line, and old inputs are upgraded automatically.

Changes that affect results

  • The default TFLES efficiency is "dynamic" (#310). efficiency = "charlette" restores the 0.8.0 model.
  • TENO results change in troubled cells (#436): stencil selection no longer depends on axis orientation or cell numbering. TENO cache files are recomputed.
  • 2D TENO on straight-sided curved walls no longer settles into an odd-even wall-pressure mode (#382). 2D stencils on anisotropic or faceted-wall meshes change.
  • The stable time step includes the exterior states of boundary faces (#374). Runs whose inflow is faster than the adjacent cells take smaller steps.
  • Bound-preserving TENO keeps density and pressure positive in every cell at CFL ≤ 0.5 in planar single-gas runs (#603). Faces that need no limiting are unchanged.
  • Transmissive boundaries on unstructured meshes take the image cell's polynomial instead of its average (#607). A uniform subsonic inflow on triangles or tetrahedra was unstable with TENO.
  • [source] expressions of t are re-evaluated at every Runge-Kutta stage (#384). Before, they were evaluated once unless time_dependent = true.
  • Analytical initial states on quadrilaterals change by their quadrature error, up to 1e-8 relative (#436). They are integrated on the device.
  • The hybrid convective flux with SIMPLER coupling is rejected (#300). The combination was linearly unstable.

Upgrading inputs

mallard input upgrade old.toml > new.toml rewrites a 0.8.0 input, keeping comments and layout. Renamed keys still run in 0.9.0 with a warning naming the replacement, and are removed in 0.10.0.

  • Boundary types are explicit subtypes, kind first (#564): upt → inlet_state, p_out → outlet_pressure (average = true for p_out_average), extrapolation → outlet_extrapolation, nscbc_inlet / nscbc_outlet → inlet_state / outlet_pressure with an nscbc table.
  • Snapshots and geometry:
    • [[write_data]] geometry → region (#542);
    • [[write_data]] format = "hdf5" → "vtkhdf", now the default;
    • [[mesh.curved]] shape → type, with filled = false for surfaces (#407).
  • [mesh] periodic → [[periodic]] entries, one syntax for generated meshes and mesh files.
  • Unknown or unused keys are errors, with the line and the likely intended key (#362).
  • One lowercase mallard executable with subcommands replaces Mallard, MallardReactor, mallard-mesh-convert and MallardTest (#414). The 2D and 3D solvers install side by side behind it (#483).

Regions everywhere

  • Named regions: [regions] defines a region once; every region key takes its name (#500). The mesh's domain, boundary zones and cell zones are regions by name, without an entry (#580).
  • Every dimension: each region type has one dimension. {type = "boundary", of = ...}, {type = "interior", of = ...} and filled = false move between dimensions, and intersection/difference clip across them (#580, #582). Surfaces of primitives are exact, boundaries of booleans are extracted from the mesh, and surfaces and curves are oriented (#582).
  • Users:
    • sources, sponges (#500) and initial states ([[initialize.regions]], plus [[initialize.data]] from tables and point clouds; #497);
    • snapshots of any region (#578) and curved boundaries projected onto any surface region (#574).
  • mallard check lists every region with its dimension, measure and cells, and writes a ParaView case view (#584).

Probes and measurement

  • Probes of every dimension:
    • points and curves with high-order point values (#358);
    • boundary zones with wall shear, heat flux, C_f, C_p, y+ and fluxes (#570);
    • exact cut planes and resampled region surfaces with fluxes through them (#572, #586);
    • volume and surface region reductions: integral, mean, Favre, min, max, rms (#500, #586).
  • Variables: probes and statistics accept the conserved variables RHOU_*, RHOE and RHOY_* for instantaneous control-volume balances (#616).
  • Consistency: probe output is the same bit for bit on any rank count, tested against the GPU (#598, #605).
  • Statistics: [statistics.spectra] gives in-situ spectra and two-point correlations, and [statistics.phase] phase averages (#284, #311).

Boundary conditions

  • Options compose on each type: nscbc, average, turbulence, wall_model (#564). Unsupported combinations are errors that point to the plan (#565).
  • Values as expressions: temperatures, heat fluxes, pressures, velocities and mass fluxes may be expressions of x, y, z and t, evaluated on the GPU at each Runge-Kutta stage (#569). dirichlet states of t also run on the device inside CUDA graphs (#602).
  • New boundaries: inlet_mass_flow (#313), inlet_stagnation (#312), and isothermal and heat-flux walls for mixtures (#351).
  • Rotational periodicity (#315).

Output, run health and restarts

  • VTKHDF is the default snapshot format (#559).
  • Asynchronous and compressed output (#309).
  • Units and provenance: units and descriptions in every output file (#518), and provenance in every file (#376).
  • The run record mallard.jsonl holds start, progress and end records. A resumed run names its restart file and marks rewinds (#376, #619).
  • Run health:
    • extremes and activity per rank, a conservation ledger that closes at round-off, and an audit of numerical repairs (#571);
    • divergence detection that stops naming the bad cells (#355).
  • Safe restarts:
    • restart files are written under a temporary name and renamed once complete (#608);
    • resumed runs continue snapshot numbering instead of overwriting earlier snapshots (#611);
    • mallard ctl checkpoints, stops and changes a running job (#355).

Running anywhere

  • Prebuilt installs: container images on ghcr.io/matthewbonanni/mallard (CPU, and :cuda for A100 to H100) and a Spack package (#328).
  • Job scripts: for Slurm, PBS, Kubernetes and mpirun. They resume from the newest restart and resubmit themselves (#330, #386). Kubernetes Job and MPIJob manifests (#453).
  • Placement: each rank picks the GPU nearest its cores, and parallel runs report where every rank runs (#330, #386).
  • Mesh readers: CGNS, ANSYS Fluent and OpenFOAM (#354, #357, #361), plus [mesh.transform].
  • Solution remap between meshes (#353).

Setting up a case

  • Templates: mallard new <template> creates a ready-to-run case from 23 examples and tutorials (#368).
  • Pre-flight checks: mallard check finds unused keys, unconditioned zones, mesh quality issues and the stable time step, and estimates memory and cost (#321, #362).
  • Help: every command has a full --help page (#503).
  • Input conveniences: units in input files (p = "1 atm"; #389), numerics presets (#391), and one expression language with loops and conditionals, compiled for the GPU (#317).

Gallery and tutorials

  • New gallery cases: a pulsed jet launching vortex rings (#579), flow past an ellipsoid with flat against curved wall faces (#575), and the Mallard logo as an initial condition (#576). The Mach 8 mallard is rerun on a duck traced from the logo (#547).
  • New tutorials: running on a cluster (#558) and measuring a flow with regions, probes, fluxes and phase averages (#596). The user guide is reorganized by topic.

Known limitations

  • GPU performance: teno5_3d runs about 2–4% slower than early-October builds on A100, and the explicit boundary-type dispatch costs about 1.7% of that (#613). A possible GPU race in the 3D rotational-periodic path is under investigation (#612).
  • [[forces]] viscous forces on several ranks read stale halo values without a wall model, an O(dt) error (4e-7 in C_D in tutorial 8). It is fixed in #623 for the next release. Boundary probes are not affected.

Full list of changes: CHANGELOG.md · v0.8.0...v0.9.0