Multicomponent Flow Code (MFC)

What's Changed

Feature release. Two new physics capabilities land here — a condensed-phase reactive burn with IBM burning surfaces, and a state-dependent equation-of-state family (Mie-Gruneisen, JWL, Vinet) evaluated per phase on the 5- and 6-equation models — alongside anchored dual-pass HLLD for hypoelasticity. Four unexercised capabilities were removed, so read the breaking changes below before upgrading a case file.

Breaking changes

• Remove the four-equation model (model_eqns = 4) — the Tait model was never exercised: no test, example, or benchmark set it, and no case anywhere set the rhoref/pref pair it required, so its paths were unverifiable in either direction while forcing a model_eqns branch through the pressure inversion, energy assembly, primitive recovery, HLLC, IBM, acoustic source, and both initialization paths. rhoref and pref are gone with it. A case setting model_eqns = 4 now fails validation. by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1713
• Remove the non-operational hyperelasticity capability — the exposed reference-map implementation was unreachable through a normal case (hyper_model was absent from the parameter registry and generated namelist), contained a 3D-only kernel exposed to lower-dimensional cases, computed the wrong Cauchy-Green contraction for rotated finite deformations, and left derived state fluxes unassigned. User-facing parameters, reference-map state, the constitutive module, solver hooks, and the documentation claims are removed; shared hypoelastic infrastructure stays. A corrected implementation is to be restored separately. by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1675
• Remove MHD from the Lax-Friedrichs solver — the MHD and RMHD branches in m_riemann_solver_lf.fpp were unreachable through the toolchain and the implementation had subtle defects (the Rusanov bound used only the acoustic sound speed). The branches are deleted and the missing Fortran-side check added. Closes #1661. by @ChrisZYJ in https://github.com/MFlowCode/MFC/pull/1722
• Remove integral output — integral_wrt, num_integrals, and the 30 integral(i)%{x,y,z}{min,max} parameters are gone. The region-integrated pressure output for Euler-Euler bubble runs had no coverage in the roughly nine years since it was added, and its author confirmed it has no users. No hot path is touched; the output was cold-guarded. by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1716
• Cases set only the parameters their equation of state reads — the validator now refuses pi_inf on an ideal gas outright rather than only a nonzero value. The solver already zeroed pi_infs for an ideal gas at init, so the value was a lie in the case file; 141 dead lines across 117 examples and 19 in test definitions are removed. No golden moves. by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1808
• pre_process must be requested explicitly on restart — restarting without naming a target no longer silently reruns pre-process and deletes the restart data in the directory. Passing -t pre_process still works if you intend to modify patches. by @danieljvickers in https://github.com/MFlowCode/MFC/pull/1761
• Phase change requires two fluids — the phase-change operator uses fixed liquid and vapor indices lp = 1, vp = 2 and writes both fields; with one carrier fluid the vapor index aliased x-momentum. Now rejected at validation. Fixes #1738. by @rj-scharff in https://github.com/MFlowCode/MFC/pull/1743

New features

• Combustion: condensed-phase reactive burn (5-/6-equation, Arrhenius kinetics) and IBM burning surfaces — a programmed, pressure-driven burn on the multi-fluid model that converts a reactant fluid to a product fluid and releases chemical energy, a lightweight route to detonation and deflagration without finite-rate kinetics. It runs on both the pressure-equilibrium 5-equation and the Saurel/Pelanti 6-equation model, with the formation energy threaded through phasic-pressure relaxation so phasic and mixture pressures stay qv-consistent (existing 6-equation goldens are bit-identical at qv = 0). An optional Arrhenius term gives temperature-driven ignition. Immersed boundaries can now act as burning or transpiring surfaces with wall-normal fuel injection and an optional Vieille's-law pressure-coupled burn rate for internal-ballistics feedback. Also fixes a hang when IBM and chemistry were enabled together, and adds a reactive shock-flame hardcoded IC (hcid 275). by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1670
• State-dependent equations of state: Mie-Gruneisen (linear and cubic Hugoniot), JWL and Vinet, with temperature — per-phase evaluation on the 5- and 6-equation models. Any Mie-Gruneisen form maps onto MFC's rho*e = Gamma*p + Pi, so the centralized operators need only those coefficients plus their density derivatives; stiffened gas is the degenerate member and stays bit-for-bit identical. Selected per fluid via fluid_pp(i)%eos, with each family owning its parameters and the validator refusing the rest. Evaluated in the mixture coefficients, the frozen mixture sound speed (Wood's law as an N-fluid loop), the characteristic-BC coefficient derivative, probes, post-process c, and through helpers in hypoelasticity, IBM, acoustic sources and the reactive burn. Verified against exact Hugoniot jump relations, analytic acoustic propagation and closed-form isentropic release, with a 27-case stiffened-gas gate confirming no existing path moved. by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1811
• Operator-split integration for the condensed-phase reactive burn — rburn%substeps freezes the flow and integrates the burn ODE across the step in equal sub-steps, re-evaluating the mixture pressure from the frozen internal energy each sub-step. Without it, a fast burn ties the reaction time scale to the acoustic CFL and forces a smaller step for the whole simulation, even where nothing is reacting. Defaults to 0, which leaves the source in the flow RHS exactly as before. by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1831
• Anchored dual-pass HLLD for hypoelasticity, plus HLLC and interface-consistent HLL — a newly developed anchored dual-pass HLLD form for the non-conservative hypoelastic terms, kept separate from the MHD HLLD because the inner-state equations follow a different eigenstructure. Hypoelasticity gains HLLC and an interface-consistent HLL option, and HLL gains the alpha div U treatment so its non-conservative handling aligns with HLLC. Riemann-consistent cross-derivative traces are now passed to the RHS, which finite differencing could not supply for HLLC/HLLD. Default behavior is preserved exactly; derivation notes for the source terms are added under misc/dev_notes. by @ChrisZYJ in https://github.com/MFlowCode/MFC/pull/1414
• Automatic IB neighborhood radius sizing — set ib_neighborhood_radius: 0 (the new default) and MFC computes the radius from the largest IB width and the largest processor width, with a 10% safety factor. This removes the need to recompute the radius by hand whenever the rank count changes, which previously made the same case awkward to move between CPU and GPU runs or through a strong-scaling sweep. Closes #1536. by @danieljvickers in https://github.com/MFlowCode/MFC/pull/1736
• Hemisphere shell particle cloud packing — particle_cloud(i)%packing_method = 3 places spherical or circular IBM particles inside a hemisphere-shell region, enforcing inner and outer shell-radius clearance, hemisphere-plane clearance, bounding-box clearance, and particle-particle non-overlap. Adds the shell_inner_radius and shell_outer_radius parameters. by @BCKim55 in https://github.com/MFlowCode/MFC/pull/1667
• File-per-process IB markers — removes an I/O bottleneck in large immersed-boundary runs. by @danieljvickers in https://github.com/MFlowCode/MFC/pull/1802
• Revised terminal output, with a limiting factor reported for adaptive stepping — narrower per-step lines and, under adaptive output, the factor currently limiting the step. by @wilfonba in https://github.com/MFlowCode/MFC/pull/1757
• Add a 3D reacting mixing-layer example (H2/N2-air, Mach 1.5) and hcid = 371 by @ecisneros8 in https://github.com/MFlowCode/MFC/pull/1758
• SCC26 practice problem preparation by @wilfonba in https://github.com/MFlowCode/MFC/pull/1731

Performance

• Large-scale startup optimizations — initialization changes needed to run at full Frontier scale, including optimizations specific to lattice packing. Collision detection reverts to linear-order prefiltering, which had been consuming three quarters of compute time at 810k IBs per neighborhood while costing about the same at low IB counts. Tested at 500 million immersed boundaries on 78k MPI ranks. by @danieljvickers in https://github.com/MFlowCode/MFC/pull/1686
• Base dependency and configure skips on real state rather than on CMakeCache.txt by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1696

Bug fixes

• Delete non-finite Lagrange bubbles in boundary enforcement — a bubble's ODE state can go non-finite under strong acoustic forcing, and the out-of-range comparisons in s_enforce_EL_bubbles_boundary_conditions are both false for NaN, so the bubble was never deleted. Its NaN position reached s_get_cell, where int(NaN) gave INT_MIN and the subsequent read ran roughly 17 GB out of bounds, crashing every bubbles_lagrange GPU run once a bubble went NaN. The check is inverted to test for inside, so NaN now fails it. by @aliencaocao in https://github.com/MFlowCode/MFC/pull/1772
• Fix two GPU kernels that share a scalar every thread writes — under OpenMP offload this is a data race; OpenACC hides it by predetermining scalars in a compute region as private, so the symptom was a different answer on every run under Cray OpenMP while every other backend looked fine. In HLLC the kernel is emitted twice through a fypp loop and the two hand-written private lists had drifted apart; the lists are now composed from a shared set and an elastic-only set so a variable cannot be left behind in one copy. Lax-Friedrichs had the same defect independently with Gamm_L/Gamm_R. by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1823
• Continuous damage model corrections — advances the conservative U_D = m_solid * D with flux U_D*u and source m_solid * D_dot instead of the scalar D, includes -p*I correctly in the maximum principal stress for 1D/2D/3D, tracks energy against the undamaged modulus G_0 so states stay finite and stable as D -> 1, and clips D to [0,1] with projection of U_D after each stage. Closes #1673. by @ChrisZYJ in https://github.com/MFlowCode/MFC/pull/1723
• Fix the missing qv term in the Lagrange bubble initial pressure — m_bubbles_EL.fpp open-coded the stiffened-gas pressure inversion and dropped the heat-of-formation term present in the canonical s_compute_pressure. Fixes #1706. by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1709
• Fill ptil so probe output stops writing undefined ptilde and ptot by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1742
• Fix hypoelastic probe output by @ChrisZYJ in https://github.com/MFlowCode/MFC/pull/1721
• Debug wall collisions and particle state writing by @danieljvickers in https://github.com/MFlowCode/MFC/pull/1745
• Do not require (xyz)_domain extents on restarts by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1734
• Make the OpenMP no_create clause a documented no-op instead of aborting fypp by @engineer-scientist in https://github.com/MFlowCode/MFC/pull/1724
• Keep multi-word values intact when loading toolchain modules by @Mohit-Ak in https://github.com/MFlowCode/MFC/pull/1702
• Fix Python 3.9 fastjsonschema compatibility by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1678
• Guard the rapidfuzz-dependent assertion in test_validate by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1705

Build and compiler support

• Avoid an NVHPC 25.5 fort2 ICE by expanding f_compute_multidim_cfl_terms by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1718
• Work around amdflang whole-image device codegen instability by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1759
• Move Frontier AMD builds to AFAR drop 23.2.1 by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1768
• Pin ffmt 0.4.5 by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1806

Refactoring and internals

• Centralize the equation-of-state expressions in the Riemann solvers — each EOS expression gets one definition (mixture coefficients, energy, sound speed, bulk modulus, pressure, phase internal energy, isentrope exponent and pressure), so adding a second equation of state became a change inside one module rather than an edit to every solver. This is the groundwork the state-dependent EOS family builds on. by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1762
• Refactor variable conversion into stage-independent common code — the first slice of making src/common genuinely stage-independent instead of selecting implementations with MFC_SIMULATION, MFC_PRE_PROCESS and MFC_POST_PROCESS. m_variables_conversion loses all stage-selection macros, uses one species-to-mixture kernel in every executable, and moves material-property arrays, viscosity-index metadata and direction mappings into common global parameters so they have a single declaration and GPU ownership point. Stage-dependent behavior becomes explicit initialization policy. by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1679
• Move input-only checks to case_validator, delete dead params_tests, and enforce the split — case_validator.py and m_checker.fpp had drifted into double entry, with the reactive burn adding nine constraints to both in the same PR. Net -1,363 lines. by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1717
• Refuse an array element passed to a device routine that runs a seq loop (lint) by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1816
• Check for integer(wp) and signed d-exponent literals in lint_source.py, addressing #1485 by @BakaOverflow in https://github.com/MFlowCode/MFC/pull/1725
• Tooling dedup: gen_case_constraints_docs.py, sched.py, user_guide.py by @AnaPcode in https://github.com/MFlowCode/MFC/pull/1720
• Make precheck pass under the pre-commit hook from a worktree by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1807
• Remove commented-out code by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1803
• Remove comments referencing invisible external context by @Moferanoluwa in https://github.com/MFlowCode/MFC/pull/1699
• Remove a junk separator comment tripping source lint by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1780
• Enable fortls navigation in VS Code by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1676

CI and testing

Most of this cycle's CI work went into making the Phoenix and Frontier lanes survive a shared, partly unhealthy cluster: bounding queue waits, resubmitting on preemption, backfilling onto whatever partition is free, and naming the node or kernel behind a failure instead of blaming a healthy one.

• Bound SLURM queue wait and combine build and test into one allocation on Phoenix by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1763
• Let Phoenix SLURM jobs wait for a node up to the job timeout (queue cap default 0) by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1770
• Resubmit SLURM jobs on preemption instead of failing (Phoenix embers) by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1771
• Fail fast on bad nodes and cluster outages by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1797
• Name the kernel behind a GPU memory fault, and stop CI condemning healthy nodes by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1800
• Identify the faulted node via sacct when the .out marker is missing by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1835
• Submit Phoenix GPU test jobs to a partition list for backfill by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1832
• Run Phoenix GPU benchmarks in one single-node job for backfill on matched hardware by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1833
• Request 1 GPU for case-optimization jobs, which only use one by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1836
• Skip the redundant rebuild in the case-optimization run job by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1766
• Run the post-build syscheck under mpirun on Phoenix by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1728
• Add --bind-to none to the Phoenix syscheck smoke test, fixing a GPU-node MPI bind failure by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1834
• Run the NVHPC container lanes without MPI by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1822
• Switch Frontier CI from the revoked hackathon QOS to normal by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1746
• Exclude bad Phoenix GPU node atl1-1-03-007-29-0 (uncorrectable ECC) by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1748
• Reclaim Phoenix V100 node atl1-1-03-002-29-0 (ECC verified clean) by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1749
• Exclude bad Phoenix L40S node atl1-1-03-007-31-0 (uncorrectable ECC) by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1750
• Take gpu-l40s out of rotation and seed frontier10202 as excluded by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1804
• Keep every column of probe output in golden packs by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1712
• Stop the coverage-map bot pushing a no-op commit on every refresh by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1683
• Stop the coverage unit tests committing into the developer's own repository by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1697
• Key coverage-map freshness on the refresh run, not on _meta.git_sha by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1732
• Post the LOC diff as a sticky pull request comment by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1753
• Resolve CodeQL code-scanning alerts in workflows by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1825
• Checkout with fetch-depth: 0 so the review bot works on fork PRs by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1671

Documentation and repository

• Fix the sign of the radial-velocity term in the documented mixture pressure by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1740
• Fix the broken star history chart in the README by @Dessalines39394 in https://github.com/MFlowCode/MFC/pull/1726
• Revise the pull request template for contribution guidelines by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1752
• Delete .github/ISSUE_TEMPLATE/bug_report.md by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1751
• Exclude stackoverflow.com from the lychee link check by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1701
• Exclude the VS Code Marketplace from lychee, it returns 503 to automated requests by @sbryngelson in https://github.com/MFlowCode/MFC/pull/1735

New Contributors

• @Moferanoluwa made their first contribution in https://github.com/MFlowCode/MFC/pull/1699
• @Dessalines39394 made their first contribution in https://github.com/MFlowCode/MFC/pull/1726
• @Mohit-Ak made their first contribution in https://github.com/MFlowCode/MFC/pull/1702
• @AnaPcode made their first contribution in https://github.com/MFlowCode/MFC/pull/1720
• @BakaOverflow made their first contribution in https://github.com/MFlowCode/MFC/pull/1725
• @rj-scharff made their first contribution in https://github.com/MFlowCode/MFC/pull/1743
• @BCKim55 made their first contribution in https://github.com/MFlowCode/MFC/pull/1667
• @aliencaocao made their first contribution in https://github.com/MFlowCode/MFC/pull/1772

Full Changelog: https://github.com/MFlowCode/MFC/compare/v5.6.1...v5.7.0