Repository navigation
Mallard 0.7.0
Mallard 0.7.0 adds large-eddy simulation with explicit subgrid-scale and combustion models and a kinetic-energy-preserving hybrid flux, which also brings the Re_τ = 180 channel DNS within 2% of Moser, Kim & Mansour. It adds synthetic turbulent inflow, makes 3D TENO 2.2× faster and stable next to walls, and is the first release under Apache-2.0.
Changes that affect results
- Example CFLs raised toward the measured stability limits (#210): most examples now run at
cfl = 1.0(from 0.25–0.4;detonation_1d0.35), 1.4–5× fewer steps. Their results are not bitwise equal to 0.6.0 but each stated result was re-checked: e.g. Sod density L1 2.554e-3 → 2.587e-3, cylinder St/Cd identical to 4 digits, premixed flame speeds identical to 5 digits.noh_axisymmetric,detonation_2d,mallard, the Mach 3 and Re 300 spheres and the multi-hour reacting examples keep their values. channel_retau180uses the hybrid flux (#216): Re_τ 180.8 instead of 172.9 and C_f +2.0% instead of −6.8% against MKM (see below).- 3D TENO stencils are bounded by a Lebesgue constant of 4 (#232, fixes #126 and #229; was 10): this changes 3D TENO results on tetrahedra and pyramids at orders 4–6 (all cells), mixed meshes, prisms at orders 5–6, Kuhn tetrahedra at order 3 and hexahedra at order 6 next to walls. Hexahedra at orders 3–5 and prisms at orders 3–4 are unchanged. Existing TENO cache files are rebuilt (format
MALLARD-TENO-8). 2D is unchanged. - SSPRK3's last stage is computed as
U + 2/3 (U2′ − U)(#237), so a steady state stays exact: in single precision the rounded weights summed to 1 + 3e-8 and drifted by O(1e-4) over 1e4 steps. SSPRK3 results change at round-off in double precision too. Unstretched generated 3D Cartesian meshes now end exactly atL. - NSCBC transverse terms (#238, #221): in 3D the fit uses faces sharing an edge instead of a node, faces on an edge with a wall or other non-characteristic boundary get no transverse terms, reversed outlet faces get
beta = 0, and fits continue across periodic seams, so 3D NSCBC results change; in 2D only faces next to non-characteristic boundaries, with reversed flow or at periodic seams change. - NSCBC runs restart exactly (#219): restart files of runs with
nscbc_inlet/nscbc_outlet(format version 4) now store the per-face boundary state, so a restarted run is bitwise equal to an uninterrupted one on any rank count. Such files cannot be read by 0.6.0; files without characteristic faces are written in the older formats as before. - MallardReactor's ignition criterion (#220): ignition is the peak of dT/dt once dT/dt has fallen below half of it, instead of a 400 K rise. Lean mixtures that used to report "none" now report their delay (H2/air, φ = 0.1: 3.650 ms, as Cantera).
- LES and the hybrid flux are opt-in: without
[les]and with the defaultconvective_flux = "riemann", the LES work changes nothing (#203, #205). The faster 3D TENO kernel (#212) and the TENO setup's streaming (#227) are bitwise identical to what they replace. eps_numericalis redefined (#222): the kinetic-energy budget now takes the numerical dissipation from the scheme's discrete pressure work (new columnpressure_work) instead ofp div ufrom cell gradients, which in flames is 1e3–1e4 times the dissipation and measured the gradients' error. Non-reacting values change little (CBC 64³: −0.9% instead of +0.7% numerical share).
Large-eddy simulation
Design and validation: docs/design/les.md (#200).
- Eddy-viscosity models (#203):
[les] model = "sigma"(Nicoud et al. 2011, 3D default),"wale"(2D default),"vreman"and"smagorinsky", with filter widthV^(1/d)on every cell type (in 3D corrected for anisotropy by default, below). The SGS stress, heat flux (Pr_t, 0.9) and species fluxes (Sc_t, 0.9, Hirschfelder–Curtiss with correction velocity) are added at faces, none on walls;ν_tenters the time step. New outputMU_T. Single gases and mixtures, MPI-bitwise against serial. - Hybrid KEP + Ducros flux (#205):
[numerics] convective_flux = "hybrid"uses the kinetic-energy- and entropy-preserving central flux of Kuya, Totani & Kawai (2018) and switches to the Riemann solver only where a compression-only Ducros sensor fires ([numerics.hybrid] sensor_threshold, 0.65). Perfect gases, mixtures and double flux. - Kinetic-energy budget (#203):
[integrals] budget = truewrites the convective, viscous and SGS kinetic-energy rates and the numerical dissipationeps_numerical, so each run shows whether the model or the scheme dissipates; explicit LES needseps_numerical ≤ 0.5 eps_sgs. The budget does not change the solution. - Dynamically thickened flame (TFLES) (#215):
[les.combustion] model = "tfles", thickeningF = max(1, n_res Δ / δ_L)inside the flame only, Charlette efficiency (β = 0.5) with Colin's u′, chemistry scaled per cell through each Strang reactor's time. New outputsTF_F,TF_E,TF_OMEGA. A 1D stoichiometric H2/air flame keeps its consumption speed within 0.2% of Cantera at 2 and at 0.5 cells per δ_L (F = 7.9 and 31.6), displacement speed −1.8% / −3.5%. - Scotti filter width, the 3D default (#223):
[les] filter_width = "scotti"(Scotti, Meneveau & Lilly 1993) scalesV^(1/3)by each cell's anisotropy factor (1 on cubes;"volume"restoresV^(1/3), the 2D default). In the channel it brings Re_τ to +0.7% at 395 (64³) and +1.6% at 590 (96³), against +2.6% / +4.1% withV^(1/3), and C_f to +0.9% / +2.9%. - Dynamic constant (#223, opt-in):
[les] dynamic = true, a global Germano–Lilly procedure (Favre-weighted, rank-count independent; columnles_C). It gives the best CBC spectra at 128³ (0.060 / 0.054 decades) but C = 1.6 / 1.4 rather than the 1.8 that fits 64³, and Re_τ +4.0% in the 395 channel, worse than the static constant. - Partially stirred reactor (PaSR), experimental (#224):
[les.combustion] model = "pasr"scales the filtered reaction rates byκ = τ_c / (τ_c + τ_mix)(outputPASR_KAPPA), for non-premixed flames. Against a DNS of an H2/N2–air diffusion flame in decaying turbulence it brings the heat release from +16.6% (quasi-laminar) to −10.7% at Δ = 0.27 mm, but overcorrects at 0.53 mm (−50%, near extinction), so it is opt-in and experimental.
Validation:
- Decaying isotropic turbulence, Comte-Bellot & Corrsin (
examples/cbc_les,tools/cbc_les.py, #213): Sigma + hybrid flux at 128³ matches the measured spectra to 0.063 / 0.085 decades RMS at stations 2 / 3, with numerical dissipation 2% of the total (64³ with C = 1.8: 0.058 / 0.063). Without a model energy piles up (0.18–0.38 decades). With HLLC the scheme dissipates instead: 84% without a model and still 46% with Sigma, so upwind fluxes do not give explicit LES. - Channel, Re_τ = 395 (
examples/channel_les, #214, #223): 64³ wall-resolved LES (Δx⁺ 39, Δz⁺ 19) with Sigma and the hybrid flux, against MKM: Re_τ +0.7% and C_f +0.9% with the default Scotti filter width (+2.6% and +4.8% withV^(1/3), where U⁺ is within 3% for y⁺ 30–300, u_rms, w_rms and −u′v′ within 10%, and numerical dissipation 3.5% against 12.6% SGS). Without a model Re_τ is +7.1%; with HLLC −19%. - Channel, Re_τ = 590 (
examples/channel_les/input_590.toml, #230): 96³ (Δx⁺ 38, Δz⁺ 19) with Sigma, Scotti width and the hybrid flux: Re_τ +1.6%, C_f +2.9%, U⁺ within 1.5% at y⁺ 30 and 100, numerical dissipation 0.20 of the SGS dissipation. WithV^(1/3)Re_τ is +4.1%, without a model +7.8%. - Premixed H2/air flame in decaying turbulence (
examples/flame_turbulence,tools/flame_turbulence.py, #222): TFLES + Sigma at Δ = 0.4, 0.8 and 1.6 δ_L (F = 2, 4, 8) against a DNS at δ_L/10 (u′ = 2.1 S_L, Ka = 2). With the default Colin estimate of u′ the turbulent flame speed is within 7% of the DNS for Δ ≤ 0.8 δ_L (S_T/S_L 1.056 and 1.053 against 1.132), with numerical dissipation at most 0.20 of the SGS dissipation; quasi-laminar and no-model runs are erratic in time and 15–21% numerically dissipated at F = 8. New opt-in[les.combustion] subgrid_velocity = "eddy_viscosity"(u′ = C_u ν_t/Δ) for coarser meshes; its C_u = 28 comes from this case and is not validated.
Channel flow at Re_τ = 180 within 2% of DNS
examples/channel_retau180 (#216) now runs with the hybrid flux: Re_τ 180.8 against MKM's 178.1, C_f +2.0%, u_rms, v_rms, w_rms and −u′v′ peaks within 1.8%, numerical dissipation 0.9% of the total. The 7% C_f deficit of 0.6.0 was HLLC's upwind dissipation (6.8% of the total at Δx⁺ 12, Δz⁺ 6), not a bug: halving Δx and Δz recovers it with HLLC too (−0.8%) at about 5× the GPU time.
Numerics
- 3D TENO stable next to walls and on jittered meshes (#232, #126, #229): large stencils must have a Lebesgue constant of at most 4. Near-degenerate stencils at walls, symmetry seams and on jittered meshes put up to 73% of a face value's weight on the cell across the face, which was anti-dissipative. The largest growth rate of the linearized operator drops from up to 3.5 c/L to ≤ 1e-7 c/L on stretched prisms and Kuhn tetrahedra with walls and on jittered periodic prisms; jittered prisms with walls keep ≤ 1.4e-3 and AR-25 tetrahedra at order 6 with side walls 0.022. Accuracy keeps its order of convergence (errors −66% to +22% depending on cell type and order). Cost: larger stencils on tetrahedra and pyramids (step time +9–29% on CPU) and 5–9× slower order-6 setup on tetrahedra, pyramids and mixed meshes (cached by
cache_file).
Boundaries
- Synthetic turbulent inflow (#221):
nscbc_inletcan inject turbulence from a digital filter (Klein, Sadiki & Janicka 2003, Lund et al.'s Cholesky factor) with a prescribed mean profile, Reynolds stresses (reynolds_stress, or aprofileCSV fromtools/plane_average.py) and length scales, through[boundaries.turbulence]; inletuaccepts expressions. The field depends only on time, so runs are bitwise identical on any rank count and across restarts. At the inlet the Reynolds stresses are within 1% of their targets, and inexamples/turbulent_inflow_ductzero_net_flux(default) keeps the downstream pressure fluctuations at about ρu′², 6–8× below those without it. In a spatially developing channel at Re_τ = 180 (examples/channel_inflow_retau180, 8πh) C_f is within 5% of the periodic DNS from 1.1h (up to 6.5% high near 0.7h) and every statistic within 5% from about 17h (Keating et al. report about 20h). Design:docs/design/synthetic_inflow.md. - Fix: NSCBC transverse terms now continue across periodic seams (#221); before, a turbulent outflow could make the outlet pressure drift until the run diverged.
nscbc_outletsurvives eddies that reverse the flow (#238, fixes #234): the transverse terms grew any mode for which their fit had the wrong sign — grid-scale checkerboards through corner neighbors, one-sided fits at edges, and the reversed jets at outlet faces — until the run diverged. The 3D fit now uses faces sharing an edge, faces on an edge with a wall or other non-characteristic boundary get no transverse terms, andbeta = 0on outlet faces with inflow. Eddies of 2–6× the mean flow now leave a 3D box without diverging (main diverged at t = 0.7–18.5); the pulse-reflection and vortex results of 0.6.0 are kept. No input or restart-format change.- Exact NSCBC restarts (#219, above).
Performance and testing
- 3D TENO 2.2× faster (#212): the TENO smooth pass runs as a team kernel on GPUs (3D, degree ≥ 4), bitwise identical to 0.6.0. On one A100, TENO5 Taylor–Green at 96³: 335 → 151 ms per step (5.85M cells/s); TENO6 at 32³ 47.3 → 20.5 ms; TENO5 on 48k tetrahedra 17.5 → 10.9 ms. 2D and CPU backends are unchanged.
docs/design/performance.mdhas the baseline. - TENO setup host memory 6× lower on CUDA (#227, #58): the stencil tables go to the device chunk by chunk as the setup builds them, so the host peak of 3D TENO5 on 64³ hexahedra drops from 32.6 to 5.5 KB per cell (8.55 → 1.44 GB on one A100); device memory, speed and results are unchanged (bitwise). Other backends are unchanged.
- 3D single-precision builds pass every test and CI now runs them (
float-3d, on every pull request) (#237).
Examples
- Stratified autoignition (
examples/autoignition_2d, #174): 2D DNS of lean H2/air (φ = 0.1, 1070 K, 41 atm) with temperature fluctuations T′ = 3.75–30 K, after Chen, Hawkes and Sankaran et al. Larger T′ ignites earlier (heat-release peak at 0.99 → 0.82 τ_0) and burns longer, with the deflagrative share of heat release rising from 0 to 25%; the multizone model overpredicts the burn duration 2–4×. The comparison with the papers is qualitative. Tools to initialize, compute Cantera references and analyze. - 3D cellular detonation (
examples/detonation_3d, #183): 2H2–O2–7Ar in a 3 cm duct, 10 cells per induction length, in a window that follows the front; front speed within 0.2% of D_CJ over 17 cm, rectangular in-phase cells as in Deiterding's and Tsuboi et al.'s 3D runs, with soot foils. - 3D shock–helium bubble (
examples/shock_bubble_3d, #183): Mach 1.25 on a helium bubble at Re 1.5e3 (Haas & Sturtevant 1987 at reduced Reynolds number), 11.4M hexahedra. Refracted and transmitted shocks, vortex ring and late downstream interface within 0–8% of the measurements; the upstream interface and air jet differ at this Re. Newmechanisms/he_air.yaml. cbc_les,channel_les,channel_inflow_retau180andturbulent_inflow_duct(above);tools/plot_channel.py --retau 180|395|590.
License
- Mallard is now licensed under Apache-2.0 (#231), with a
NOTICEfile that redistributions and derivative works must keep. Versions 0.1.0–0.6.0 remain under AGPL-3.0-only. Cantera's BSD-3-Clause license, which covers the ported transport fitting and the bundled mechanisms, is now shipped inlicenses/.
Known limitations
- The best Sigma constant depends on resolution (C = 1.8 matches the CBC spectra better at 64³, the default 1.35 at 128³); the dynamic procedure (#223) does not find 1.8 at 64³ and does worse than the static constant in the 395 channel (Re_τ +4.0%). The CBC spectra meet 15% per shell in the mean but not at the lowest shells and near 2/3 k_c (31–47%).
- The v_rms⁺ peak is 8–12% low in the channels (11–12% at 395 on 64³, 8–9% at 590), nearly independent of the model: it is the x/z resolution of the near-wall cycle (8% at 395 with Δx⁺ 26, Δz⁺ 13).
- TENO-E with the hybrid flux is anti-dissipative (−22% numerical dissipation at 32³); use unlimited MUSCL with
convective_flux = "hybrid". - Upwind fluxes (HLLC) with an SGS model are not explicit LES: numerical dissipation stays comparable to or above the model's (46% in CBC, 13.5% vs 5.4% in the channel). Check
eps_numericalwith[integrals] budget = true. - With the default Colin estimate of u′, TFLES overpredicts the turbulent flame speed about 2× at Δ = 1.6 δ_L (efficiency 1.8–2.1 in both flame cases of #222): Colin's u′ is 5–8× the DNS subfilter velocity on coarse meshes. Keep Δ ≤ 0.8 δ_L, or try the opt-in
subgrid_velocity = "eddy_viscosity", whose constant is calibrated on one case only. - Sigma is refused in 2D builds (it vanishes for every 2D flow; use WALE or Vreman), and LES is refused with
axisymmetric = true. TFLES needss_Landδ_Las inputs and is a premixed closure. PaSR is experimental: it overcorrects the heat release on coarse meshes (−50% at Δ = 0.53 mm in #224's diffusion flame). - On pure pyramid lattices, 3D TENO order 4 grows modes (#236; it already did on 6³ and with walls in 0.6.0, and grows faster now), and order 6 now grows weakly on periodic ones. Order 6 on AR-25 tetrahedra with side walls keeps a weak growing mode. Prefer orders 3 or 5, or MUSCL, on such meshes.
- Large 3D TENO runs are limited by GPU memory (#58).
- With the default low-Mach correction,
extrapolationoutlets reflect 15% (MUSCL) to 34% (TENO5) of a normal acoustic pulse; usenscbc_outletwhere reflections matter. - With gas mixtures, RHLL + TENO5 can leave mass fractions slightly negative (N2 = −2e-10 in three cells of a shock tube).
- HLL and RHLL can grow a carbuncle at a normal shock at rest exactly on cell faces: the Roe average there is exactly sonic, so the sign of Einfeldt's wave speed is decided by round-off (#245; sonic-point-robust wave speeds are tracked in #244). A shock drifting across the faces stays stable.
- The Mach 3 sphere develops a carbuncle on the axis where two symmetry planes meet with RHLL and TENO5 (#80).
Full list of changes: v0.6.0...v0.7.0