FluidSimCpp/docs/COMPONENT_IMPLEMENTATION.md

Component implementation progress

Active goal started 2026-11-01: implement the full machine systems roadmap, in its integrated order. The scope includes the later components; they have not been dropped because they need additional physical models. Preserve existing working-tree changes and user-edited machine files.

First implementation: typed port foundation

Implemented:

• Shared descriptors for Gas, Rotational, Translational, Boolean, Number and legacy ECU assignment. Direction, cardinality, quantity, pressure reference, required/default values and numeric ranges are explicit.
• Typed Boolean/Number values with validity and simulation timestamps. Finite numeric checks and explicit type matching prevent implicit truth conversions.
• A shared compatibility function used by connection previews, edits and document validation. Runtime compilation validates the same document.
• Explicit gas-domain filtering in pipe geometry updates, fluid compilation and fuel-source searches, avoiding assumptions that every non-ECU link carries gas.
• Version 5 stable port/method names, custom physical-port identities and loading of versions 1 through 4. Zero-storage junctions expose one shared port; old numeric aliases migrate to it.
• Shared UI port colors and silhouettes: red Boolean, green Number, input rings, filled outputs, neutral bidirectional gas connectors; legacy assignments blue.

The foundational types are real APIs. Boolean/Number nodes remain subsequent work; the first mechanical parts are implemented below.

Mechanical parts milestone

Implemented Shaft / crankshaft, Flywheel, Drive motor and Brake / load with typed gold attachment ports, real runtime behavior, 3D meshes, Mech picker category, inspectors, live motor/load/friction tuning and named rotational instruments. Shaft inertia and initial states require Build. Effective flywheel inertia appears in the shaft inspector. Cylinders and pumps use their attached shaft; each ECU's cylinders must share one shaft. Moving a shaft leaves gas geometry unchanged.

The independent-shaft solver tracks kinetic energy, source/drive work and losses. Its drag integration splits stops and reversals without allowing brakes to create motion. Ideal speed drives report their supplied/absorbed work, including startup. Engine-connected shafts currently enforce forward-only timing. The legacy starter remains explicit shaft calibration until the dedicated starter milestone; new shafts default to zero starter torque.

Version 6 saves mechanical parameters/connections. Older documents migrate to visible shafts/drives/loads and keep legacy gauge definitions. Examples/imports, copy/paste, assembly references, live tuning and benchmark tools use explicit mechanics. Existing user files are not rewritten on load. The new machines/shaft-drive-bench.machine.toml is a ready-to-run mechanical example.

Validation: nine focused suites pass, including analytic acceleration and damping, work/energy accounting, brakes/static hold/reversal, two independent engines at 1200/2400 RPM, live tuning one to 3600 RPM, required attachments, mixed-shaft ECU rejection, migration, save/load, builder/menu interactions and prior physics cases. Rendered review covers every mechanical inspector and a running bench at 1920x1080 and 1280x720. This is not a global gas-plus-mechanics conservation study; the existing explicit component-coupling timestep limitations remain relevant.

Sensor attachment milestone

Implemented six ideal sensor assemblies: absolute pressure / MAP, differential pressure, gas temperature / IAT, signed total pipe mass flow, crank speed/position and throttle position. They attach to existing physical hosts without consuming gas ports, adding storage or changing the fluid mesh. Pipe taps use normalized arclength. Total mass flow is explicitly distinct from the future fresh-air MAF sensor; gas temperature is not a head/coolant temperature model.

Sensor outputs use the typed port descriptors, sample timestamps and validity. Sampling occurs initially and after each audio sample's physics, providing the next signal-graph boundary's readings. Crank speed, wrapped angle and Boolean ideal synchronized status share a sample; shaft identity and unwrapped angle are retained for future timing consumers. A stopped shaft supplies valid zero speed. Sensor channels are independent of the eight recorded instrument channels.

Version 7 saves stable sensor identities, named kinds, host labels, normalized locations and pickup offsets, and preserves deleted-ID counters. Versions 1..6 still load. Host deletion leaves a visible unresolved entity; copy/paste and assemblies remap internal hosts and retain unresolved external bindings.

The Sense inspector creates supported sensors, binds hosts/reference taps, adjusts tap positions and pickup offsets, focuses/removes attachments and shows live typed outputs. Right-click Add sensor here uses the clicked pipe location. 3D markers select their sensor; unresolved-binding checks navigate to it. Attachments are Build-only and remain inspectable while running/paused. The new machines/sensor-bench.machine.toml demonstrates all six assemblies.

Validation covers sampling/units/signs, coherent timing and reverse crossings, stopped pickups, remeshing/transforms, no fluid/audio perturbation, more than eight sensor channels, host deletion, incompatible bindings, copy/paste and save/load, plus UI placement, undo/redo, diagnostics and Test edit locks. Rendered review covers pressure, crank and differential-pressure screens at 1920x1080/1280x720. All ten focused regression suites pass, as does migration/round-trip validation of the saved machines found in the workspace. The desktop executable is rebuilt.

Logic runtime milestone

The document now owns a separate typed signal graph with stable node/pin keys, saved canvas coordinates, shared port compatibility and atomic connection edits. Version 8 saves that graph; versions 1..7 still load. Physical gas/mechanical links and legacy blue ECU assignments retain their separate meanings.

Implemented 35 runtime node kinds: Boolean constants, switches/buttons, numeric constants/sliders/inputs, six Boolean gates with configurable fan-in, comparisons, windows/hysteresis, arithmetic, clamp/gain/map, number selection, Bool-to-number, sensor references, command references, lamps/readouts, and Boolean/Number delays. Polymorphic numeric nodes currently use explicit configured quantities/references. Multiply/divide use a scalar second operand; pressure subtraction produces a differential, while absolute-pressure addition requires a differential offset.

Graph evaluation occurs before each physics sample, consuming the previous boundary's sensor sample and latching commands across gas CFL substeps. Evaluation uses a compiled order, rejects combinational cycles with a named cycle path and commits explicit memory next states together. Required unwired inputs block Test; commands have declared inactive defaults. Invalid math/sensors stay invalid with runtime diagnostics, and actuator consumers apply inactive fallbacks. Short button press/release sequences survive between boundaries; fresh Test resets transient controls and memory. Constants/thresholds can be tuned without restarting physics.

Commands own individual motor enable/speed/torque, brake enable, throttle opening or legacy shaft starter fields. Duplicate ownership and ECU/opening conflicts are rejected; dormant signal-owned fields start inactive. A shaft allows only one potentially enabled ideal speed drive. The physical inspector identifies signal ownership and the live drive HUD uses the effective enabled state.

Connected harnesses follow physical assembly copy/paste. Internal parts/sensors/ nodes remap independently; omitted physical bindings remain explicitly unresolved. The new machines/logic-compressor-bench.machine.toml runs actual pressure -> below-threshold hysteresis -> master-enable AND -> compressor motor enable, with a speed slider, targeted readouts and recorded pressure/RPM/drive-power channels.

Core acceptance covers gate truth tables, unit/reference rules, fan-out/cardinality, unknown keys/types, ordering/cycles, delayed feedback, math faults, manual event ordering/reset, live tuning, command ownership/fallbacks, automatic compressor shutdown, brake/starter commands, sample-vs-CFL timing, saved harnesses and independent copied compressors. Twelve focused regression suites pass, along with workspace save migration checks. Rendered review covers signal-owned drive controls and the running pressure bench at 1920x1080 and 1280x720. The desktop is rebuilt at this runtime milestone. Timers, edge nodes and latches remain later work.

Logic editor milestone

Implemented 3D / Logic / Split workspace tabs with one document, selection and Test runtime. Canvas pan/zoom and the 3D camera remain independent. Selecting a sensor/command reference selects its physical host; Focus in 3D opens the split workspace. Sense -> Show Logic and physical Command buttons create or reveal references to existing entities without duplicating physical parts.

The node library has search, categories, an Objects list and compatible-node filtering while a pin is pending. New compatible numeric nodes adopt that pin's quantity/reference. Nodes drag by their headers, Shift/box selection supports groups, Home/F fit the graph/selection, and wheel zoom preserves the point under the pointer. Saved node positions are independent of 3D geometry.

Connections support click/click, dragging, fan-out, input rewiring, right-click pin disconnection and undo/redo. Rejected edits keep the old wiring and redo history. Boolean pins/wires are red, Number green; inputs are rings and outputs filled circles. Live values include units, required/default metadata, ranges, pressure references and validity. Candidate combinational cycles highlight the actual cycle nodes and retain the compiler's named path diagnostic.

Inspectors edit names, quantities/references, sensor/command bindings and node parameters. Invalid numeric text remains editable. Topology, control ranges, initial states and physical bindings require Build; safe constants/thresholds and canvas layout can change during Test. Switches, momentary buttons, sliders and numeric controls operate at simulation boundaries. Paused controls show queued values separately from frozen pins; slider motion coalesces. Focus loss, leaving Logic and stopping Test release momentary buttons. Numeric readouts have compact UI-sampled trends; the recorded meter channels remain separate.

Graph copy/paste preserves internal wires. Same-document sensor references share their existing sensor; cross-document references detach while retaining labels. Pasted command nodes require a new explicit target, preventing competing owners. Physical assembly copy/paste continues to remap complete internal harnesses.

Validation: thirteen focused regression suites pass. Interaction cases cover placement/search, typed wiring/rewiring, failed-edit rollback/redo, one-entry drag undo, zoom anchoring, live tuning, paused controls, focus/view-close button release, shared physical selection, split-view bounds and uninterrupted simulation time. Rendered review covers 1920x1080/1280x720, including live graphs, split view and the threshold inspector. Pixel checks confirm red/green filled outputs and hollow input centers. Updated rendering libraries are linked into out/build/windows-gcc/fluidsim_desktop_preview.exe; the canonical executable is currently locked by the user's running workshop, which was left intact.

Further graph/UI work remains on the roadmap: pinned operator panels, richer binding pickers/property help, visual wire waypoints and graph-wide automatic type inference, in addition to DPI scaling and visibility groups. Basic stage 2 is usable; those refinements and the later component stages are not dropped.

Sensor ECU and fuel-delivery milestone

Implemented the runtime primitives for the next component stage:

• Physical crank outputs now carry pickup/shaft identity, original acquisition time, unwrapped angle and measured speed through the signal graph. Unchanged routing retains that evidence; arithmetic creates ordinary numeric values. Delays retain their original acquisition time, so retimestamping a delayed value cannot make it a current timing measurement.
• A crank-only wasted-spark clock validates matching current speed/angle channels, counts unwrapped crossings, accepts stopped pickups and rejects stale/mixed or reverse timing. Acquisition/recovery does not replay missed sparks. Changing advance cannot fire twice for one revolution.
• Separate sensor ECU core with ignition-only and Alpha-N strategies. Ignition uses measured RPM and an advance map; Alpha-N requires measured TPS and uses a calibrated two-dimensional RPM/TPS table in kg per cylinder per four-stroke cycle. It never receives trapped cylinder air mass or global pedal demand. Required sensor faults cut outputs; the RPM limiter has hysteresis.
• Explicit injector delivery core with capacity limiting, declared ideal or finite regulated rail supply, depletion and fail-closed command handling. Delivery adds conserved fuel species, fuel-origin tracer and sensible energy to an existing gas volume. This is continuous/batch-average delivery, not sequential pulse-width control or a liquid-pressure circuit.
• Four-stroke cylinders accept consumed external spark pulses and cut commands. This path requires transported fuel and does not fall back to hidden internal spark timing. Burn progression follows the received event.

The cores are now integrated into saved machines and the workshop. The ECU inspector selects labeled Legacy ideal, Crank ignition or Alpha-N EFI presets. Show ECU connector in Logic creates/reveals one grouped connector. Crank speed/position are required green Number inputs; Alpha-N additionally requires actual TPS. The connector selects its physical ECU and copied graph-only connectors detach ownership. Physical assembly copies remap the complete harness.

Blue assignments declare controlled cylinders. Sensor-driven ECUs do not own throttle opening or read the global pedal; manual or separately commanded throttles remain available. Each cylinder has an explicit Pickup TDC deg calibration in the crank sensor's coordinate system. Its physical 720-degree phase is not used as hidden ECU synchronization. Commands and spark events use the existing simulation-sample boundaries, not UI updates.

An explicit injector attachment can be added to a chamber, bound to an Alpha-N ECU and configured with capacity, cylinder-dose count, fuel mass/temperature and finite or ideal regulated supply. A nozzle appears on its host. Total injector cylinder doses must match assigned cylinders; fuel is added once per physics sample and then transported by the gas solver. Live inspectors show delivered flow, remaining fuel, depletion and ECU fault/limiter status. Ignition maps and RPM limits can be tuned live; strategy, fuel tables, attachments and pickup calibration require Build.

Version 9 saves ECU strategy/fuel maps, grouped input schemas, pickup calibration and injector bindings. Versions 1..8 retain their legacy controller behavior. Deleted/omitted ECU references stay unresolved with labels; IDs remap on assembly insertion. Existing user files are not rewritten. Ready-to-run examples are machines/sensor-ignition-bench.machine.toml and machines/sensor-alpha-n-bench.machine.toml, both driven at 3000 RPM.

The delivered EFI model is open-loop, continuous/batch-average intake delivery. It does not claim sequential pulse timing, modeled liquid rail pressure or evaporation/wall-film dynamics. Those abstractions remain explicitly labeled; advanced sensor strategies remain in later stages.

The new sensor-ECU acceptance target covers physical sensor -> graph timing, stale/mixed/arithmetic rejection, delayed acquisition evidence, spark crossings, RPM/TPS interpolation, fault/recovery and limiter behavior, ECU demand -> gas-host fuel delivery, finite-supply mass/energy accounting and external spark actuation. Acceptance also covers actual combustion in both sensor-driven examples, live loss/recovery of timing, foreign-shaft and constant-number rejection, depletion in the machine runtime, live ignition tuning without restarting time, save/load, partial/full assemblies and UI preset/connector/injector controls. All fourteen focused suites pass after rebuilding affected targets. Workspace machine migration/round trips pass from the repository root. Rendered review covers the new graph, ECU and injector screens at 1920x1080 and 1280x720. Wasted exhaust sparks retain the last trapped-charge AFR reading; valid timing still samples fresh charge when ignition is cut by the limiter.

The Alpha-N example was opened in Build mode with out/build/windows-gcc/fluidsim_desktop_preview.exe, leaving the original workshop intact. The final checked binary, including the last charge-instrument fix, is out/build/windows-gcc/fluidsim_desktop_ecu_preview.exe. Open sessions were not restarted to replace a locked executable; recheck live processes before linking or launching the next review build.

Speed-density ECU milestone (stage 4, first slice)

Added a third sensor-driven preset, Speed-density EFI. Its grouped connector requires four Number inputs from three physical sensor assemblies: crank speed, crank position, manifold absolute pressure and intake gas temperature. TPS is not required in this basic mode. Gauge/differential pressure cannot connect to MAP; invalid, zero or stale MAP/IAT values cut fuel and new ignition events.

Fuel demand uses a declared dry ideal-gas estimate: air_kg_per_cylinder_cycle = MAP * displacement * VE / (R_air * IAT), followed by target AFR and the four-stroke RPM/120 conversion. Displacement, air gas constant, target AFR and the RPM/MAP volumetric-efficiency table are calibration, not hidden cylinder measurements. VE interpolates both axes and clamps to table edges. The gas network still transports the explicitly injected fuel. This open-loop estimate does not measure fresh-air fraction in diluted intake gas or provide warm-up, acceleration enrichment, lambda trim or sequential timing.

The preset, required input schema, calibration fields and EFI injector target picker are integrated into the workshop. SD calibration fields display cc, kPa and VE percent and require Build. Ignition-map/RPM-limit tuning remains live. Shared strategy names/keys validate the document, graph, runtime and serializer; unknown strategies fail explicitly. Format 10 saves the new VE/displacement calibration and connector schema; versions 1..9 still load.

machines/sensor-speed-density-bench.machine.toml is a working 3000 RPM example with physical intake MAP/IAT taps, an explicit injector and actual combustion. Its calibration is set when constructing the example; runtime fuel estimation does not query cylinder air mass or geometry.

Validation: fifteen focused suites pass, including ideal-gas charge cases, pressure/temperature/displacement scaling, two-axis VE interpolation, required sensor faults, live MAP loss/recovery with combustion, missing IAT host, input reference types, save/load, assembly remapping and UI preset/connector controls. Workspace machine migration/round trips pass from the repository root. Rendered review at 1920x1080 and 1280x720 covers the four-input graph and ECU/injector inspectors. Pneumatic valves and the pressure-switch supply circuit remain the next stage-4 delivery; they are not implemented by this ECU milestone.

Checked desktop build: out/build/windows-gcc/fluidsim_desktop_speed_density_preview.exe. Existing workshop windows were left intact. Next session should start with the physical valve slice below; no valve implementation is currently in progress.

Next physical component slice

Implement needle, solenoid shutoff, differential relief and non-relieving pressure-regulator behavior through the existing conservative gas boundaries. Use explicit inlet/outlet paths and real body/downstream pressure; do not enforce a setpoint by assigning gas pressure. Needle opening and solenoid coils need typed signal command ownership; the regulator's pressure demand must declare an absolute/gauge reference. Relief needs cracking/reseat hysteresis, solenoids need normally-open/closed rest states and finite travel, and regulator response must remain bounded when supply falls below demand. Include a pressure-switch preset and a finite-tank circuit with flow, depletion and conservation acceptance cases. Integrate picker modes, inspectors, save/load and assemblies before further UI polishing. Keep this and all later roadmap stages in the active goal.

Delivery backlog

Stage	Scope	State
0	Typed ports, validation, stable identities and migration	Complete
1	Explicit shafts, flywheel, drive motor, brake/load, sensor attachments and shaft instruments	Complete; six basic sensor assemblies implemented
2	Logic canvas; buttons, switches, constants/sliders; gates, thresholds, arithmetic, mapping, sensors, commands and displays	Basic runtime and editor integrated/verified; advanced graph UX and operator panels remain
3	Crank sensing, ignition and Alpha-N ECU presets, explicit fuel delivery and ECU connector UI	Basic presets integrated/verified, including physical combustion, saved bindings and workshop controls
4	MAP/IAT sensing, speed-density ECU, needle/shutoff/regulator/relief valves and pressure-switch control	Speed-density preset integrated/verified; pneumatic valves and pressure-switch circuit remain
5	Gears, clutch, starter; directional valves, pneumatic cylinders, linear loads/springs/dampers and quick exhaust; latches/timers/memory	Planned
6	MAF/sequential ECU options; air motors, rotary compressors, filters, nozzles and resonator/silencer assemblies	Planned
Later	Belt/pulley drives, heated/cooled chambers, ejectors, turbines/turbochargers and general linkages	Planned

Each stage needs actual runtime behavior, save/load and assembly support, usable UI controls and focused acceptance checks. Keep this file current at milestones.

Stage 0 validation: six focused suites pass (machine ports, machine physics and serialization, builder interactions, menu navigation, native maximization and desktop UI). Tests cover all current part descriptors, signal types/references, invalid values/defaults, input direction/cardinality, custom-port reordering, legacy ECU fan-out, old junction aliases and all saved machines found locally. Unknown part kinds now fail explicitly instead of inheriting gas ports/storage. Source whitespace checks pass. Existing user machine files were read and copied to temporary test locations; they were not migrated in place.