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

verification/performance/2026-10-30/workshop-report.md

@@ -0,0 +1,95 @@
+# Workshop performance, 2026-10-30
+
+The flat-six workshop now runs within the real-time audio budget. The measured
+simulation cost fell from 104.44 to 8.79 microseconds per sample (11.9 times faster).
+At 44,100 Hz the available budget is 22.68 microseconds per sample.
+
+## Cause and changes
+
+The workshop used a different assembly path from the native scenarios. It split
+fluid sections at every visual pipe knot, inserted 5 mm inlet stubs, required at
+least four fluid substeps per sample, and repeated mechanical/control work in
+each substep. Flat6 consequently had a 1.78 mm cell and averaged 12.35 substeps
+per sample. Its native scenario had a 34.20 mm minimum cell and about one substep.
+
+- Mesh each pipe by total arclength and its diameter profile. Visual knots remain
+  in the editor and renderer; exact frustum averages preserve gas volume.
+- Advance shaft, ECU, cams, combustion, carburetors and pump displacement at the
+  audio sample rate, matching native engine scheduling. Keep CFL stepping for
+  fluid transport and pressure-operated check valves. Compile active part/gate
+  lists and cache fixed restriction areas.
+- Place the importer's metering assembly farther upstream within its existing
+  inlet segment, allowing a sensible outlet stub. The inlet endpoints, route
+  length, diameter and total gas volume stay the same. Existing custom pipes are
+  never lengthened automatically; actual short pipes still constrain CFL steps.
+- Cache local pipe vertices, normals and indices, shared primitive meshes, and
+  the part-picker icon atlas. Transforms and pressure updates reuse geometry;
+  route/diameter edits rebuild the affected pipe.
+
+Untouched stock imports in `machines/` were compared against the previous
+importer's canonical output before replacement. User files, including
+`paralell-twin.machine.toml`, were preserved.
+
+## Simulation results
+
+Windows GCC RelWithDebInfo, Rusanov, preset density 20 cells/m, 44,100 Hz,
+512 warm-up samples and 32,768 measured samples, motor-driven at 3,000 RPM,
+35% pedal. Timings include audio synthesis but exclude editor rendering and
+snapshot collection. Paired native/workshop measurements use the same process;
+before/after runs have normal timing variation.
+
+| Preset | Workshop before, us/sample | Workshop after | Native after | Workshop cells before / after | Substeps before / after |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Single 450 | 12.61 | 3.55 | 2.89 | 56 / 44 | 4.00 / 1.00 |
+| Twin | 16.96 | 6.89 | 6.11 | 67 / 58 | 4.00 / 1.72 |
+| Flat6 | 104.44 | 8.79 | 8.43 | 161 / 98 | 12.35 / 1.03 |
+| V8 H-pipe | 67.51 | 16.01 | 16.56 | 318 / 175 | 4.09 / 1.00 |
+
+At 6,000 RPM and 70% pedal, flat6 measured 9.31 us/sample and V8 16.11.
+All benchmark cases reported zero positivity repairs and finite audio.
+See [baseline](workshop-before.txt), [after](workshop-after.csv) and
+[higher-load results](workshop-high-load.csv).
+
+These are performance comparisons, not claims of identical combustion or sound.
+The workshop has explicit metering-body storage, connections and editable
+calibration; the native scenarios assemble that hardware differently. Arbitrary
+large or finely meshed custom machines can still exceed the audio budget.
+
+## Rendering and playback
+
+Hidden 1440 x 900 OpenGL window, 120 static frames, `glFinish`, no vsync or
+simulation: flat6 fell from 1.40 to 0.70 ms/frame; V8 from 1.77 to 0.96 ms/frame.
+This measures CPU/GPU render cost, not the displayed frame rate.
+See [before](workshop-render-before.csv) and [after](workshop-render-after.csv).
+
+The combined workshop/audio check ran at 60 display frames/s with a held
+3,000 RPM shaft, 16 warm-up frames and 120 measured frames per machine:
+
+| Preset | Wall seconds | Simulated seconds | Audio underruns | Buffered samples |
+| --- | ---: | ---: | ---: | ---: |
+| Flat6 | 2.006 | 2.020 | 0 | 4,096 |
+| V8 H-pipe | 2.071 | 2.082 | 0 | 4,096 |
+
+Simulation time includes producer buffering and snapshot timing, so a small
+offset from wall time is expected. This is a short playback check, not a long
+session guarantee. Raw output: [playback](workshop-playback.csv).
+
+## Validation and reproduction
+
+All 22 CTest cases passed. Machine tests cover import length/volume preservation,
+route-knot-independent meshes, a real 5 mm pipe retaining its CFL constraint,
+explicit fuel sources, cold starting and ECU cutoff. Pump pressure agreed within
+1% between 44.1 and 88.2 kHz. Builder checks cover geometry-cache reuse and
+invalidation, pressure coloring, transforms, deletion/ID reuse and the icon atlas.
+Editor preview images were visually inspected.
+
+From the repository root after `cmake --build --preset windows`:
+
+```powershell
+ctest --preset windows -j 8 --output-on-failure
+.\out\build\windows-gcc\fluidsim_machine_benchmark.exe 32768 3000 0.35
+.\out\build\windows-gcc\fluidsim_machine_benchmark.exe 32768 6000 0.7
+.\out\build\windows-gcc\fluidsim_machine_render_benchmark.exe 120
+.\out\build\windows-gcc\fluidsim_machine_render_benchmark.exe 120 --play
+.\out\build\windows-gcc\fluidsim_machine_builder_tests.exe --preview out/workshop-performance-preview
+```