fix emit/surf: mass-flow inlet (mflow) and time-averaged subsonic BC

[stanmoore1]

Summary

Adds two boundary-condition capabilities to fix emit/surf, as keywords on the
existing fix (no new fix classes):

• mflow Mdot Tin [window N] — a mass-flow-rate inlet that injects to hit a target
  mass flow rate Mdot through the surface group.
• subsonic Psub Tsub [window N] — the existing subsonic pressure BC gains an
  optional moving-average window that damps the statistical noise of the
  instantaneous cell velocity (Sun & Boyd 2005).

This is a corrected, minimal-footprint alternative to the upstream proposal in
sparta#430 (issue sparta#429).

Background — issue sparta#429

sparta#429 (and PR sparta#430) added a mass-flow inlet and a time-averaged subsonic inlet, but
reported two unexplained errors: a steady ~2% deviation from the target mass flow on
a simple channel, and ~2x too much flow on complex geometries.

Root cause (PR sparta#430's subsonic_grid):
nsubsonic = mflow/(species[0].mass * v_n * inlet_area) back-solves a number density
from a convective-only flux model, applied per cell with a user-typed inlet_area,
the local normal velocity, and a single species mass — while particles are actually
inserted with SPARTA's full Maxwellian flux (mol_inflow, convective + thermal) over
the true clipped cell/surf area. The mismatch causes:

1. ~2x geometry error: realized flow scales by (true emit area)/(typed inlet_area);
2. ~2% bias: convective-only target vs convective+thermal insertion (grows as Mach drops);
3. mixture error: species[0].mass is wrong for any real mixture.

What this PR does

mflow chooses one global number density each step so the expected total inserted
mass rate equals the target:

nrho = Mdot / S,
S = sum over tasks,species of  mol_inflow(indot, vscale, fraction) * area * mass / cell_weight

S is built from the true clipped emit area, the actual mol_inflow flux, and
per-species masses, and is MPI_Allreduce'd across ranks. So the realized rate is
correct for any geometry/mesh/mixture/decomposition, with no user inlet-area input.
The optional window applies an EMA to the cell streaming velocity.

Implemented in src/fix_emit_surf.{h,cpp} (parser + mflow_grid() + the subsonic
window), reusing the existing mol_inflow(), subsonic sort/grid machinery, and the
emission tally. Docs in doc/fix_emit_surf.txt; examples in.emit.surf.mflow,
in.emit.surf.mflow.single, in.emit.surf.subsonic with mpi_1/mpi_4 reference logs.

How this differs from PR sparta#430

• Keyword on fix emit/surf, not new forked fix classes. Dev subsonic mflow boundary conditions sparta/sparta#430 copied ~1600 lines
  into fix_emit_surf_mflow.* / fix_emit_surf_timeavg.*; this is a ~75-line diff on
  the live fix. The fork was stale and re-introduced the double-emission bug fixed
  upstream in Do not emit particles in cells that are outside of the flow volume sparta/sparta#431 (the cinfo[icell].volume == 0.0 guard); the keyword inherits that
  guard (and twopass, custom, region, etc.) for free.
• Mdot/S rescale (true area + real flux + per-species mass, MPI-reduced) instead
  of Mdot/(species[0].mass*v_n*inlet_area).
• No inlet_area argument — computed internally (this is the 2x-geometry fix).
• No vmin — obsolete (it only existed to avoid div-by-zero in Dev subsonic mflow boundary conditions sparta/sparta#430's formula).
• compute momentum dropped — SPARTA already measures mass flux via
  compute surf ... mflux on a transparent surface.
• Fixes Dev subsonic mflow boundary conditions sparta/sparta#430's concrete bugs (uninitialized normal_vel_dot in the vmin clamp; a
  per-task std::cout debug line).

How this fixes sparta#429

• Mass-flow ~2% deviation: gone — realized rate uses the same mol_inflow flux as the
  insertion, so target and realization are consistent.
• Mass-flow ~2x on complex geometry: gone — true emit area is used (no hand-typed area).
• Subsonic pressure noise: the window EMA provides the requested smoothing.

Verification (serial + MPI via OpenMPI 4.1.6)

• Development of improved subsonic boundary condition and mass flow rate boundary condition sparta/sparta#429 microchannel (the tests/surf_mflow_test deck), target 4e-10 kg/s:
  realized inlet rate ratio 0.998–1.000 on 1 and 4 ranks (was ~2% off / 2x in Dev subsonic mflow boundary conditions sparta/sparta#430).
• Linearity: single-species, ratios 1.007/1.007/0.999/0.992 across an 8x range.
• Geometry/mesh independence: ratios 0.99–1.03 across grid 5→40; on the curved
  circle the true emit area is 3.14x a naive guess yet the rate is on target.
• Rank independence: ratios 1.007/1.016/0.995/0.986 on 1/2/4/8 ranks.
• Subsonic window: per-step insertion std 14.9 → 9.9 → 6.6 for window 0/20/200;
  window 0 is byte-identical to stock subsonic.
• Regression: all stock emit/surf examples reproduce reference logs bit-for-bit
  (serial and 4-rank MPI). valgrind clean.

Notes / limitations

• The target rate is met in an expected (statistical) sense; measure as a time-average.
• CPU-only here; under -k on these keywords safely error (the KOKKOS port is separate).

🤖 Generated with Claude Code

---

Generated by Claude Code