Improve physical geometry, fluid solvers, audio, and profiling

improvements.md

@@ -0,0 +1,273 @@
+# Sound realism improvement plan
+
+## Goal
+
+Make engine sound emerge from the simulated engine and its surroundings. The 1D
+fluid model should provide the coherent pressure and flow behavior; separate
+acoustic source and propagation models should represent phenomena the 1D model
+cannot resolve. The real-time path should remain affordable, deterministic when
+requested, and diagnosable by source.
+
+## Current sound path and limitations
+
+The four-stroke and two-stroke scenarios currently pass intake and exhaust
+open-end volume flow to `OutdoorAudio`. It derives a compact monopole pressure
+signal from the time derivative of that flow, applies distance and ear delays,
+simple image-source reflections, and an approximate late reverb. The engine's
+3D scene supplies source/listener positions, but visible geometry does not yet
+control detailed acoustic propagation.
+
+This captures coherent engine pulses, but has no direct model for turbulent
+noise at valves, throttle plates, sharp area changes, bends, collectors, or pipe
+exits. A nonzero flow or a large opening alone is not evidence that an audible
+turbulent source should be active. The 1D pipe state is cross-section averaged;
+it cannot resolve vortices, transverse velocity, or separated shear layers.
+The first-order pipe update also adds numerical damping, which can soften pulses
+before they reach the acoustic renderer.
+
+## 1. Separate acoustic sources
+
+Represent and capture each major sound contribution independently before
+mixing them:
+
+- **Coherent intake and exhaust pulses:** derive from simulated pressure and
+  volume-flow waves at ports and mouths.
+- **Intake aerodynamic noise:** generate at the throttle, valves, filter,
+  bends, contractions, and other restrictions when their local operating
+  conditions and geometry support turbulent flow or separation.
+- **Exhaust aerodynamic noise:** generate at exhaust valves, collectors, abrupt
+  expansions/contractions, and outlets where jets or separated flow are
+  expected.
+- **Combustion events:** retain cycle timing and add afterfire or misfire
+  sounds only when the combustion/fuel model predicts those events.
+- **Mechanical sources:** add valve train, injector, gear, belt, and rotating
+  imbalance sources as their physical models become available.
+
+Each source should have an independent output/capture channel and enable
+control. This makes level and spectral calibration possible without masking
+errors by changing unrelated sources.
+
+### Flow-noise source model
+
+Use local flow and feature data to estimate source strength, rather than mapping
+area or mass flow directly to noise. Useful inputs include:
+
+- mass or volume flow, density, local velocity, and flow direction;
+- upstream/downstream pressure and pressure drop;
+- effective opening area and area ratio;
+- hydraulic diameter, edge radius/sharpness, bend angle, and expansion ratio;
+- gas temperature and viscosity, for Reynolds-number estimates;
+- opening motion and rate of change for valves and throttle plates.
+
+Use these inputs to estimate whether the feature creates a jet, separation, or
+vortex shedding, and how strongly it is excited. Reynolds number is a useful
+regime indicator, not an audible-noise switch. Mean flow alone should not force
+a noise source to be audible. A smooth, well-matched passage and an abrupt,
+partly closed restriction should produce different results at comparable flow.
+
+For an initial real-time model, use a seeded, band-limited stochastic source
+with a smooth operating-point envelope and a short stateful correlation time.
+Shape its spectrum and level from local flow power/jet speed, pressure drop,
+feature geometry, and a calibrated source model. Avoid unfiltered white noise,
+hard on/off thresholds, and arbitrary random pops. Keep stochastic source
+generation out of the conserved pipe state in the first implementation; this
+avoids changing mass, momentum, or energy merely to create audio.
+
+Treat unsteady separated flow as a modeled source, not a directly measured
+quantity in the current 1D cells. Proxies such as rapid changes in flow or
+pressure, reversals, and valve motion may modulate the source, but they do not
+resolve turbulent fluctuations. For higher-fidelity source data, use transient
+3D CFD/LES or measurements at selected features and reduce those results to a
+real-time source model.
+
+## 2. Improve pipe and component acoustic coupling
+
+### Diagnose wave loss before changing the model
+
+Build small repeatable interface cases and record pressure on both sides of an
+interface:
+
+1. Send a pressure pulse through an equal-area straight connection.
+2. Measure reflection and transmission at T/Y junctions.
+3. Connect a pipe to a known volume and vary the volume and opening geometry.
+4. Repeat at several cell sizes, CFL/time-step settings, and flux schemes.
+5. Track incident, reflected, and transmitted wave energy, mass/energy
+   balance, `limited_fluxes`, and positivity repairs.
+
+If pulse loss decreases with mesh refinement, spatial numerical diffusion is a
+major contributor. If loss is concentrated at an interface and does not
+converge with refinement, improve the boundary/junction model. Compare with
+analytic acoustic impedance/scattering results where applicable and with
+measured junction data for realistic geometries.
+
+### Zero-volume pipe junctions
+
+The current ideal N-way junction uses a zero-storage Rusanov star state. Improve
+this with a characteristic junction solve that enforces mass and energy
+conservation while accounting for each branch's area, orientation, flow
+direction, and pressure-wave impedance. Add calibrated geometry-dependent
+losses where the junction is not ideal. Validate frequency-dependent reflection
+and transmission, not just steady flow or conservation.
+
+### Pipe-to-volume transitions
+
+The current pipe-to-component connection uses an orifice/nozzle boundary and a
+shared component pressure/state. Represent the actual entry geometry where it
+matters: opening area, contraction/expansion, short profiled transitions, and
+calibrated discharge/loss coefficients. A shared volume pressure is appropriate
+for a well-mixed compact reservoir, but may be too simple for a collector or
+plenum with strong spatial pressure differences. Use resolved pipe sections or
+a richer multi-port model where those differences materially affect pulse
+transfer.
+
+### Pipe wave resolution
+
+Compare the current first-order Rusanov update with higher-order limited
+finite-volume schemes that preserve shocks without excessive damping. Measure
+waveform, phase, and spectrum convergence with mesh and timestep refinement.
+Retain robust positivity handling and conservation checks. Do not select a
+scheme on shock-tube error alone; validate acoustic pulse propagation and
+engine-relevant frequencies as well.
+
+## 3. Add acoustic networks between flow ports and listener
+
+Separate the simulated fluid flow network from the acoustic radiation network.
+For each source, represent how its sound travels through connected ducts,
+plenums, filters, resonators, and mufflers before it radiates. Options include:
+
+- **Transfer matrices / frequency-domain network models:** efficient for
+  linear acoustic behavior and useful for calibrating duct and chamber
+  resonances.
+- **Digital waveguides / delay-line networks:** suitable for real-time,
+  time-domain wave travel, reflections, and frequency-dependent losses.
+- **Reduced-order component models:** compact state-space filters derived from
+  measured or higher-detail simulations for complex elements.
+
+Model acoustic reflection, transmission, resonance, and attenuation at
+junctions and openings. Include frequency-dependent losses from wall friction,
+viscothermal effects, and porous/absorptive parts where data supports them.
+Use separate paths for intake and exhaust so changes to one system do not
+unintentionally alter the other.
+
+## 4. Use the 3D environment for propagation and radiation
+
+The engine's 3D placement can improve more than stereo panning, provided the
+scene contains usable acoustic geometry and materials. Give each source a
+position, orientation, size, and frequency-dependent directivity. Relevant
+sources include intake mouth, individual or grouped exhaust outlets, engine
+surfaces, valve train, and drivetrain.
+
+Use scene geometry for:
+
+- **Directivity:** tailpipe and intake radiation vary with direction and
+  frequency; source orientation should affect the listener signal.
+- **Occlusion and diffraction:** engine parts, chassis, bodywork, and nearby
+  obstacles can block or bend sound. A simple visibility test is useful only
+  for the frequencies where geometric acoustics applies.
+- **Early reflections:** compute paths from actual ground, walls, vehicle body,
+  and nearby surfaces, with material-dependent reflection and absorption.
+- **Late reverberation:** derive or tune the diffuse tail from the environment
+  rather than relying only on fixed scene presets.
+- **Listener motion:** update source/listener distance, direction, delay, and
+  Doppler shift consistently; smooth changes without breaking phase/history.
+
+Use a **hybrid propagation model**. Ray tracing is relatively efficient for
+high-frequency reflections and occlusion. Low frequencies require wave or modal
+methods because they diffract and form strong cavity/vehicle resonances. A
+boundary-element, finite-element, or finite-difference time-domain (FDTD) solve
+can be run offline for representative geometry, then reduced to filters or
+modal data for real-time playback. The visible engine mesh alone is not enough:
+acoustic propagation also needs appropriate geometry detail and surface
+impedance/absorption data.
+
+## 5. Calibration and validation
+
+Record real intake and exhaust audio at fixed engine speed, load, throttle, and
+microphone position. Keep recordings unnormalized and disable automatic gain
+for comparisons. Add transient throttle sweeps and lift-off cases after the
+steady points.
+
+Compare:
+
+- engine-order peak frequencies, amplitudes, and phase/timing;
+- broadband noise level and spectral shape;
+- intake/exhaust level balance;
+- transient envelope and throttle response;
+- changes with listener position and direction;
+- reflection/decay behavior in each environment.
+
+Use separate source captures and bypassable acoustic stages to identify where
+an error enters. Calibrate source strength first, then duct/network filtering,
+then 3D radiation and environment. Avoid compensating for a weak physical
+source by boosting reverb or global gain.
+
+## Implementation status and scope
+
+- Every scenario TOML now supplies `[simulation] cells_per_meter`. The desktop
+  exposes a per-scenario resolution stepper with background mesh rebuild and
+  engine restart, retaining each selection during the app session. The desktop
+  calibration/geometry editor has been removed. Uniform and profiled pipe
+  resolution is controlled by the shared density, preserving geometry/volume.
+
+- Source-separated captures are implemented for intake, both exhaust emitters,
+  and valve contact, with a separate shared diffuse-tail capture, per-source
+  metrics, and capture-tool solo controls. Desktop UI controls remain future work.
+- Rusanov, HLLE, and HLLC are already selectable for comparison. The V8 uses
+  finite-volume port-coupled fittings; zero-storage junctions remain a comparison path.
+- 3D CFD/LES work is out of scope. Use the 1D model, reduced acoustic source
+  models, and measurements for this improvement effort.
+- Pulse benchmarks are implemented: 408 straight/split, zero-storage junction,
+  and finite-volume fitting cases across meshes, timesteps, and flux solvers.
+  See `docs/ACOUSTIC_BENCHMARK.md` for methodology, limitations, and findings.
+- Findings: straight-pipe numerical attenuation converges with refinement;
+  zero-storage junction scattering has additional mesh-independent error;
+  small finite-volume fittings can require tighter component timesteps.
+- A production-selectable `muscl` pipe solver now compares limited second-order
+  MUSCL-Hancock/HLLC against the original solvers via F3 or `--solver muscl`.
+  Automatic desktop gain defaults off. Pulse attenuation improves, with original
+  conservation/robustness checks retained. The sweep now covers 408 cases.
+- A nonlinear characteristic zero-storage exhaust junction is available with
+  `--junctions characteristic`, alongside volume and legacy comparison modes.
+  It supports unequal areas, branch orientation, automatic flow reversal,
+  enthalpy/species mixing, and configurable direction-dependent turning losses.
+  Equal/unequal-area acoustic scattering and 500/1000 Hz phase/gain checks are
+  included; see `docs/JUNCTION_SOLVER.md` for scope and limitations.
+- Next: listen at fixed operating points, check spectra and performance across
+  engine families, and investigate component coupling timestep stability before
+  changing acoustic source strength. The new mode remains opt-in for evaluation.
+
+## Suggested implementation order
+
+1. Add source-separated captures and per-source diagnostics.
+2. Build pulse reflection/transmission tests for straight connections,
+   junctions, and pipe-volume boundaries.
+3. Determine whether junction loss or first-order pipe diffusion dominates;
+   improve the responsible model and validate convergence.
+4. Add a flow/geometry-driven intake restriction-noise source with deterministic
+   seeded, band-limited output and a separate capture channel.
+5. Add corresponding exhaust valve/collector/outlet sources; model afterfire
+   only when supported by combustion state.
+6. Add an acoustic network (waveguide or reduced-order transfer model) for
+   intake and exhaust ducts and volumes.
+7. Use 3D geometry for source directivity, occlusion, early reflections, and
+   listener motion; add offline wave-based/acoustic calculations for important
+   low-frequency resonances as needed.
+8. Calibrate against controlled microphone recordings and retain objective
+   regression measurements alongside listening tests.
+
+## References and further reading
+
+- Li et al., *LES-FEM coupled analysis and experimental research on aerodynamic
+  noise of the vehicle intake system* (2017):
+  https://doi.org/10.1016/j.apacoust.2016.09.009
+- Ih et al., *Prediction of intake noise of an automotive engine in run-up
+  condition* (2009): https://doi.org/10.1016/j.apacoust.2008.03.007
+- Morel et al., *Modeling of Engine Exhaust Acoustics* (1999):
+  https://doi.org/10.4271/1999-01-1665
+- Parrondo et al., *Noise transmission through duct divisions in air circuits*
+  (2006), experimental scattering coefficients for duct junctions:
+  https://www.sciencedirect.com/science/article/abs/pii/S0022460X06002239
+- Lang and Mindt, *Entropy-Preserving Coupling Conditions for One-dimensional
+  Euler Systems at Junctions* (2017): https://arxiv.org/abs/1704.04035
+- Hu, Morfey and Sandham, *Sound radiation in turbulent channel flows* (2003):
+  https://doi.org/10.1017/S002211200200277X