FluidSimCpp/docs/JUNCTION_SOLVER.md

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 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

.\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 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.