Add machine workshop, typed logic, mechanics and sensor-driven ECUs

verification/performance/2026-10-31/workshop-instruments.md

@@ -0,0 +1,99 @@
+# 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](instruments-playback-1.csv), [0.1x](instruments-playback-0.1.csv),
+[0.01x](instruments-playback-0.01.csv).
+
+## 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:
+
+```powershell
+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
+```