Improve physical geometry, fluid solvers, audio, and profiling

docs/JUNCTION_SOLVER.md

@@ -0,0 +1,98 @@
+# Direction-aware characteristic junctions
+
+## Model and scope
+
+The new `BoundarySystem` node solves a nonlinear common-pressure mass balance
+using each branch's outgoing Euler acoustic wave curve: an isentropic
+rarefaction or Rankine-Hugoniot shock curve. Branch area enters mass flow,
+and pipe-coordinate orientation is handled independently of physical direction.
+Incoming total enthalpy and species are mixed by incoming mass flux. Outgoing
+contact density follows the mixed total enthalpy and the local pressure/velocity.
+Outgoing fluxes share that enthalpy and composition, conserving total energy,
+air, and fuel at the zero-storage node. Fitting forces react momentum; axial
+momentum is not summed as a scalar across differently directed branches.
+
+Pressure is found by a bracketed Newton iteration. Setup allocates scratch
+arrays; node updates allocate no memory. Outgoing mass is normalized to incoming
+mass to remove root roundoff. A shared donor budget scales advective fluxes when
+necessary, preserving node conservation, and reports `junction_limited_fluxes`.
+
+This is a subsonic, common-pressure engineering closure. It has not been proven
+entropy stable for arbitrary mixtures, large thermal contrasts, and shocks.
+Endpoint Mach numbers at or above 0.95, predicted face Mach numbers at or above
+0.98, and unsuccessful pressure solves select the conservative legacy Rusanov
+fallback. `junction_fallbacks` reports these cases. It is not a choked/supersonic
+multi-port Riemann solver. Frequent fallback or limiting indicates a case needing
+further timestep/model investigation, not a validated acoustic measurement.
+
+The broader research on entropy-preserving Euler junctions uses common total
+enthalpy and entropy-based coupling; the implemented common-pressure/mixed-enthalpy
+closure is a distinct engineering choice. See
+[Lang and Mindt, 2018](https://www.aimsciences.org/article/doi/10.3934/nhm.2018008)
+for the stronger mathematical coupling conditions and their subsonic assumptions.
+
+## Direction and turning
+
+Each endpoint can specify a unit axis pointing out of the node. For a receiving
+branch, the loss coefficient is the incoming-mass-weighted average of
+`turning_loss * (1 + dot(outward_receiver, outward_donor)) / 2`.
+Opposite axes have zero turning loss; perpendicular axes have half the configured
+loss. A local signed pressure-drop relation uses `K * rho * u² / 2`, with three
+outer updates of the donor-weighted direction coefficients. Donors are recomputed
+as flow reverses. This is a quasi-steady uncalibrated turning-loss approximation.
+It does not resolve vortices, bend radii, separation, or transverse acoustic modes.
+
+At zero mean flow, ideal low-frequency compact-junction scattering depends on
+branch impedances, not a stereo direction or a branch-angle audio filter. Angles
+enter the mean-flow/turning model. Defaults use schematic route tangents, which
+can be overridden with actual branch axes in TOML. No 3D CFD is involved.
+
+## Production selection
+
+```powershell
+.\out\build\windows-gcc\fluidsim_desktop.exe --example v8-h --solver rusanov --junctions characteristic --junction-loss 0.5 --scene dry
+```
+
+Use `--junctions volume` for the original finite-volume fittings or
+`--junctions legacy` for the old zero-storage numerical node. The volume model
+remains the default. Pipe solvers and junction models are independent. Restart
+for model comparisons; auto gain remains off by default.
+
+The same options work in `fluidsim_audio_capture`. Captures report junction
+iterations, fallback, limiting, and pipe positivity repairs. On collector-topology
+engines, selecting characteristic/legacy explicitly replaces collector storage
+with a node. Changes there include removal of that physical compliance, so they
+cannot all be attributed to numerical accuracy. The V8 and staged exhaust paths
+also change from storage fittings to zero-storage nodes.
+
+See [the configuration guide](ENGINE_CONFIG.md#characteristic-exhaust-junctions)
+for branch direction overrides and endpoint indexing.
+
+## Validation
+
+`fluidsim_junction_tests` checks mass, total energy, air/fuel conservation,
+unequal areas and thermal states, opposite donor configurations, all-pipe
+coordinate reversal, world rotation, straight-versus-turning flow preference,
+invalid direction rejection, and explicit supersonic fallback reporting.
+
+The 408-case acoustic benchmark compares volume fittings, characteristic nodes,
+and legacy nodes across all four pipe schemes, meshes, and timesteps. Equal-area
+characteristic scattering approaches reflected energy 1/9 and transmitted energy
+8/9 after approximately removing common pipe attenuation. With outlet areas
+2A and 3A and inlet area A, the targets are 4/9 reflected and 5/9 transmitted.
+Characteristic pulse cases require no fallback. At the finest mesh, transmitted
+pressure gain and phase at 500 and 1000 Hz are compared against ideal equal-area
+gain 2/3 and zero extra phase, after straight-pipe de-embedding.
+
+For Rusanov, 160 cells per 2 m, Courant 0.4, corrected transmission is about
+0.889 with the characteristic node versus 0.222 with the legacy node. Seven
+small-volume cases remain flagged in the separate volume model. Full measured
+junction spectra, geometry calibration, high-Mach coupling, and entropy
+admissibility remain follow-up work.
+
+Listening captures are in `out/audio/junction-ab-single-{volume,characteristic}-rendered.wav`
+and `out/audio/junction-ab-v8-{volume,characteristic}-rendered.wav`. Their
+`-level-matched.wav` copies use RMS 0.08 with constant per-file gain. The single
+comparison is 3000 RPM / pedal 0.3; V8 is 3000 RPM / pedal 0.5 with turning-loss
+coefficient 0.5 in the characteristic case. Both use dry Rusanov rendering.
+These comparisons include the change in storage model described above.