5.3 KiB
Workshop instruments, slow playback and live tuning
Implemented on 2026-10-31. The workshop now supports eight nonintrusive instrument channels, simulation-time traces, CSV export, slow playback down to 1%, paused 10 ms stepping, and live adjustment of safe component settings.
Measurement model
Pressure, temperature and mass-flow taps read the compiled simulation. Pipe taps sample the cell at a chosen fraction of arclength. Lumped-part flow is net into the part; pipe flow is signed Start-to-End. RPM is instantaneous shaft speed; torque and power use the shaft model's running averages.
Bulk AFR/lambda use a passive conserved fuel-origin tracer. Combustion does not erase that tracer, so downstream instruments include fuel that has already burned. It travels through pipe fluxes, component ports, storage volumes and junctions. The extra tracer does not feed back into gas pressure, energy or mass. Bulk AFR = (gas mass - fuel-origin mass) / fuel-origin mass; lambda divides that by the channel's stoichiometric AFR reference, default 14.7. Fresh-charge AFR on a cylinder instead reads its remaining unburned fresh-air/fuel mass ratio.
Undefined readings are gaps on the graph and empty cells in CSV. Sensor heating, response lag, oxygen chemistry and fuel-specific combustion chemistry are not added by this change. Initially clean exhaust pipes can read very lean until purged. A probe after a collector measures the gas mixture that actually reaches that collector's outlet, including dilution and backflow.
Channels sample every 16 physics samples: 2,756.25 Hz at a 44,100 Hz simulation rate. The bounded capture retains 32,768 records (about 11.9 simulated seconds). Graph compression preserves sampled min/max envelopes and leaves undefined intervals disconnected. Frequencies above 1,378.125 Hz cannot be resolved by this capture rate. This is not an audio-rate acquisition mode.
Playback and tuning
Slow playback resamples audio without changing the physics timestep. Producer batch size, prefill and target queue depth scale with playback speed. Pause stops both audio and physics; switching speed discards queued audio while both threads are stopped, preserving the machine's state. A paused step advances exactly 441 samples (10 ms). Graph timestamps remain simulated seconds.
Live edits are validated and applied under the simulation mutex between batches. Carb calibration, ECU settings, throttle opening, cracking pressure, combustion settings and shaft/load settings retain gas state, fuel film, controller state and simulation time. Geometry, initial conditions, mesh/solver settings, cam/valve mechanics and compiled boundary settings remain locked. The API rejects structural changes even if a caller bypasses the UI. Live edits support undo/redo and saving. Probes/taps can change live; changing the capture schema clears the trace.
Machine files now use version 4 for probe definitions. Versions 1 through 3 remain readable; recordings are exported separately. Existing user machine files were not rewritten.
Playback checks
Windows GCC RelWithDebInfo; hidden 1440 x 900 window at a 60 Hz display target; 16 warm-up display frames, 120 measured display frames; motor-driven at 3,000 RPM. All eight channels were active, including cylinder pressure, downpipe AFR/lambda, fresh-charge AFR, mass flow and shaft gauges, with the scope visible.
| Machine | Requested speed | Measured simulated / wall time | Audio underruns | Buffered input samples |
|---|---|---|---|---|
| Flat6 | 1.0 | 1.00875 | 0 | 4,096 |
| V8 H-pipe | 1.0 | 1.00160 | 0 | 3,872 |
| Flat6 | 0.1 | 0.101294 | 0 | 407 |
| V8 H-pipe | 0.1 | 0.100410 | 0 | 409 |
| Flat6 | 0.01 | 0.0100798 | 0 | 41 |
| V8 H-pipe | 0.01 | 0.0100857 | 0 | 41 |
The small offsets reflect queue depth, snapshot timing and short-run measurement variation. These are short playback checks, not a sustained-session guarantee. Raw results: 1x, 0.1x, 0.01x.
Verification
The full 22-test CTest suite passed. Targeted checks additionally cover conserved burned-fuel transport in all four solvers, characteristic/legacy junction mixing, finite exhaust AFR after combustion, lambda normalization, undefined dry readings, probe persistence, live tuning without state/time reset, rejected geometry edits, increased fuel delivery after live carb jet changes, pause/step/slow playback, live undo/redo, CSV units and independently selectable overlapping probe markers.
Builder preview mode verifies rendered UI pixels after OpenGL scene/icon rendering and captures pressure, downpipe lambda and live carb-tuning views. Those images were visually inspected. Extremely small passive tracer tails are flushed like the existing species tails to avoid subnormal arithmetic overhead; total gas mass and energy are unchanged.
Reproduce from the repository root:
cmake --build --preset windows
ctest --preset windows -j 8 --output-on-failure
.\out\build\windows-gcc\fluidsim_machine_builder_tests.exe --preview out/workshop-instruments-preview
.\out\build\windows-gcc\fluidsim_machine_render_benchmark.exe 120 --play 1
.\out\build\windows-gcc\fluidsim_machine_render_benchmark.exe 120 --play 0.1
.\out\build\windows-gcc\fluidsim_machine_render_benchmark.exe 120 --play 0.01