Skip to content

Latest commit

 

History

History
929 lines (842 loc) · 57.9 KB

architecture.md

File metadata and controls

929 lines (842 loc) · 57.9 KB

Architecture

EngineLab separates the physical models, their orchestration, real time and presentation. The computation libraries stay in standard C++; JUCE is confined to audio and the desktop application.

Modules and dependencies

foundation
  ├── calibration ───────────────┐
  ├── events                     ├──► ecu
  ├── physics                    │
  ├── exhaust ──► events         │
  ├── serialization              │
  ├── diagnostics                │
  └── render                     │
                                 ▼
events + physics + ecu + exhaust ──► simulation
                                        │
                                        ▼
                                     runtime ──► audio (JUCE/DSP)

foundation + serialization ──► scripting
catalog + diagnostics + serialization + scripting
       + calibration + render + runtime + audio ──► app (JUCE)
Target Responsibility
EngineLabFoundation Configuration and state types, validation, normalisation and a generic SPSC queue
EngineLabCalibration Typed axes/units, scalars/curves/tables, validation, immutable snapshots and ECU JSON
EngineLabEvents Firing events and intra-cycle pressure frames
EngineLabPhysics Conservative gas, kinematics, P·dV, injection, flame, knock, valvetrain and Helmholtz intake
EngineLabEcu Map interpolation, enrichments, corrections and rev limiter
EngineLabExhaust Topology compilation, routes, aggregated gas properties and acoustic metadata
EngineLabSimulation Deterministic orchestration of the models and state integration; a bit-identical worker pool for the gas networks
EngineLabRuntime Simulation thread, transmission/vehicle, dyno, snapshots and bridge to audio
EngineLabAudio SI exhaust characteristics, passive radiation, explicit convolution and non-exhaust layers
EngineLabSerialization JSON/YAML round-trip in the current engine schema (9) and migration of older files
EngineLabScripting Safe compilation of the .els DSL and a background dependency watcher
EngineLabCatalog Loading of the shipped engines and parts
EngineLabDiagnostics Explanatory diagnostics for the UI
EngineLabRender API-independent 3D scene, fixed snapshots and interpolation
EngineLabApp JUCE composition, files, main window panels, ECU tuner, exhaust designer, audio workshop

State ownership and threads

EngineSimulator owns the physical states and advances only when its caller invokes step. EngineRuntime is its application-level owner and runs the simulation on a std::jthread. It publishes a protected EngineState for the UI, slow telemetry through atomics and two SPSC streams: discrete events and continuous pressure frames.

Inside a step, EngineSimulator may borrow a small CylinderWorkerPool (on engines with three cylinders or more, and on a two-stroke twin: at most half the reported hardware threads, two workers, three from ten cylinders). Per-runner intakes advance their runners on it; the exhaust network and a joint intake manifold use it through ExhaustGasNetwork::setParallelFor for each duct's share of an RK stage, handed out as one contiguous run of ducts per thread: its update, cache, wall heat, interior residual and the face fluxes of its ports, outlets and the interfaces it owns (the upstream duct's). What couples ducts (junctions, restrictions, applying the fluxes, the shared plenum) stays serial in a fixed order, so the result is bit-identical whatever the worker count, including none (EngineLab.GasDynamics checks a reversed dispatch order). A two-stroke's exhaust is a PartitionedExhaustNetwork instead: its unconnected pipes are networks of their own, each with its own CFL step, and one dispatch per advance runs one pipe per claim (EngineLab.PartitionedExhaustNetwork checks each pipe against a network of that pipe alone). A four-stroke's stays one network. From eight cylinders up, where each sub-step reads a frozen copy of the shared plenum, the per-cylinder pass (processCylinder) and the end-of-sub-step publish of each cylinder's state also run on the pool, one cylinder per item: it writes only that cylinder's state, and its engine-wide events (spark and misfire counts) are applied in cylinder order afterwards (EngineLab.JointIntakeManifold checks 0 against 3 workers on the LS3 and the Merlin). Two-strokes keep it inline.

The JUCE callback consumes these streams. It compiles no script, reads no file and takes no mutex. Impulse-response decoding, allocations and DSP preparation happen before rendering.

EngineScriptHotReloader owns a separate worker. It watches the root script, its includes and its optional base, compiles off the UI thread, then publishes an immutable state. The UI replaces the runtime only after a complete compilation and validation.

The calibration watcher is lighter: the ECU window timer detects a file change, parses and validates the document, then calls CalibrationStore::publish. ECU readers obtain the snapshot with an atomic load at the start of an external frame and never see a partial draft. A per-reader epoch keeps replaced snapshots alive until they are acknowledged; their destruction therefore happens on the publishing thread, not on the simulation thread. This strategy avoids a reader mutex but does not assume that atomic<shared_ptr> is lock-free in hardware.

Main window

MainComponent owns the runtime, the audio device and the files. It no longer paints anything itself. Once per 30 Hz tick it copies everything the screen shows into a DashboardModel: the engine state, the render snapshot, the telemetry ring, dyno runs, faults, runtime counters and the audio mix. It then asks each panel to refresh. Panels read the model and never touch the runtime. User actions come back as callbacks that MainComponent wires in its constructor.

Panel Area
TopBar engine picker, run state, Exhaust / Fuel / Equipment / Pass-by / Vehicle / ECU / Audio windows, ⋯ menu
ControlPanel ignition, starter, dyno, throttle column and presets, Drive section (speedometer, trip computer, gears, brake, clutch, cruise control, each with its key, and the switch of each fitted option, anti-lag's included), trims; it scrolls in a juce::Viewport when taller than the window (preferredHeight())
EngineViewport the GPU 3-D engine view with its overlays, or the 2-D cutaway
ReadoutStrip tachometer and six live readouts
SidePanel Dyno, Telemetry, Audio and Diagnostics tabs; its VehiclePanel (the vehicle's figures typed in, taken live) is shown in the top bar's Vehicle window
StatusBar fault summary, real-time factor, simulation speed, counters

Theme holds the colour tokens, fonts and the ui::LookAndFeel installed for the whole application, so the tool windows and alerts share it. Widgets holds the buttons, segmented controls and slider rows the panels are built from.

EquipmentWindow gathers the optional parts, one section each: nitrous (NitrousConfig, through applyNitrousEdit), the active exhaust valve (ExhaustNetworkEditor::fitSilencerBypass puts a valved bypass around the muffler nearest a tailpipe; the actuator through applyEngineEdit), VTEC and launch control (their calibration scalars, published at once with EquipmentWindow::publishScalar). Each section's status line reads the engine state of the last tick (nitrousBlockers, exhaustValveOpening, vtecHighCylinderMask, the launch-control limit bit).

PassByWindow sets a pass-by run and its microphone: Start hands the settings to EngineRuntime::startPassByRun, where a PassByDriver (runtime, PassByRun.hpp) takes the pedals and the gears on the simulation thread and publishes its phase, place, time and fade in EngineState (passBy*) and RealtimeAudioState; MainComponent passes the microphone's place, ground and level to RealtimeEngineAudio:: setPassByGeometry, turns the camera's microphones off while a run is published, and, with Record WAV, WavRecorder writes what getNextAudioBlock plays (a background thread, 24-bit) until the end's sound has reached the microphone.

A box is inside its window when it shows whole there, so a screen recorder's window capture films it. Alert boxes go through ui::showMessage and ui::showOkCancel, the hand-built dialogs (save as, JSON editor, key bindings, the exhaust valve) through ui::placeInWindow, which moves a box in only when it fits whole inside the window and covers no native view: the 3-D view's OpenGL surface is a native child window on Windows, and nothing its window draws shows over it (ui::markNativeView, set while the 3-D view is attached). Otherwise the box stays a desktop window, centred over its window. Menus (combo box lists included) are always desktop windows: inside a window a list was cut to that window (three entries in the Fuel window) and the engine picker vanished under the 3-D view. Each tool window has its own tooltip window (one parented to the main window shows nothing over another). A component in no window on screen yet (an error while the app starts, a test) gets a desktop box, never a modal one out of sight. The file choosers stay the system's own dialogs. To film the menus and the boxes over the 3-D view, capture the screen rather than the window.

Display units. The simulation keeps one internal unit per quantity (m/s, kPa absolute, N m, kW, °C, mm, cm³, kg, g/s, L/100 km). units:: in foundation/Units.hpp lists the units offered for each quantity (exact definitions: international mile and pound, US and imperial gallons, standard gravity, mechanical hp, metric PS) and four presets: Metric (the default, the simulator's own readouts), Metric bar/PS, US and UK. ui::UnitFormat, held in the DashboardModel, formats the readouts the panels show; a pressure can be shown absolute or gauge (relative to the engine's ambient air), and a pressure that is already a difference (oil, rail, a duct against ambient) is never offset again. The choice is in ⋯ › Units and is saved in units.json next to keybindings.json. The physics debug list of the Telemetry tab stays in the internal units on purpose: it is the engineering view.

The main component keeps the keyboard: no button or slider takes focus, and a mouse wheel a child does not use goes up to the main component's mouse-wheel handler (mouseWheelMove).

Transactional boundaries

ECU calibration

An editor works on a CalibrationDraft, which may be temporarily invalid. publish validates the whole and optionally checks expectedRevision. On success, a new CalibrationSnapshot is swapped in atomically. On error or conflict, the active pointer and its revision do not change.

This operation recreates neither EngineRuntime nor EngineSimulator. It suits the parameters the ECU reads at every evaluation: AFR, advance and rev limiter in the current integration.

Structural configuration

JSON, YAML and .els all produce a complete EngineConfig. The decoders accept engine schemas 1 to 9 (currentEngineSchemaVersion); normalisation migrates an older file to schema 9 in memory, filling what each later schema added with its documented default, and every export writes schema 9. Normalisation makes explicit topologies authoritative, then validation checks identifiers, ranges, cylinder assignments, solver frequency and acyclic graphs. An accepted configuration is used to build a new runtime. The old one is stopped only after its replacement could be created.

The replacement is safe but is not a state migration: engine speed, temperatures, fuel films, combustion phases, transmission and audio queues restart from the initial state. For structural reloads of the same engine (live script, JSON editor, exhaust designer), the new runtime reuses the same CalibrationStore: maps, tuner and ECU watcher survive. Explicitly choosing or importing another engine creates its default set.

Saved engines and session edits

The engine menu lists the catalogue, then My engines: the files of %APPDATA%/EngineLab/engines (loadSavedEngines, SavedEngines.hpp). A saved engine is one file, <name>.json: the configuration as Export engine writes it, its ECU tables inside under ecu_calibration (the ECU window's JSON; encodeEngineFile). It is written to a temporary file renamed over the old one. A save made by 0.9.1 or earlier kept the tables beside it in <name>.ecu.json: that file is still read when the engine file holds none, and the next save folds it in and removes it. Damaged tables fail the whole read: the engine never runs on other tables than its own. The file (JSON or YAML) names the voicing the engine speaks with (audio_voicing: family and key); the voicing itself is read back from the catalogue's voicing files (restoreAudioVoicing).

Leaving an edited engine for another one keeps its edits for the session: MainComponent stores its configuration and its CalibrationStore, and choosing it again builds the runtime from them. Return reloads the engine from disk and drops them. "Edited" is measured against the engine as it was loaded (EngineBaseline): the configuration through its JSON encoding, the tables through the JSON of their entries, without the store's revision. A dot on the engine picker shows it; the menu marks the engines that hold edits.

Save engine writes a saved engine over its file; on a catalogue engine it asks for a name (Save engine as…). A catalogue name is refused, since the menu tells engines apart by name. Saving does not restart the engine: EngineRuntime::renameEngine gives the running engine its new name, which a dyno run reads when it starts. Delete saved engine… moves its file (and an older save's table file) to the recycle bin; the running engine carries on, unsaved. Export engine writes the same single file, in JSON or YAML (the same tables as a YAML map, numbers as JSON writes them, so they read back to the same doubles); Import engine reads either with its tables. An engine decoder alone ignores ecu_calibration, so an older EngineLab still reads the engine.

Dropping a file on the main window opens it (MainComponent::filesDropped, droppedFileKind): an engine file (.json, .yaml, .yml) as Import engine does, an engine script (.els, .engine) watched as the import watches it, or ECU tables alone (.ecu.json) published to the running engine, completed with the settings the file predates (addMissingDefaultSettings). When the replacement would lose edits not saved (the running engine's, or for tables its tables'), EngineLab asks first; the edits of an engine of the menu left for another one are kept for the session as usual, so it does not ask then. A drop during a dyno run is refused.

New engine

New engine… (the menu) designs an engine from nothing: no base engine. designEngine() (catalog/EngineDesign.hpp) takes an EngineSpec (cycle, fuel, use, layout, cylinder count, banks, bore and stroke or a displacement, induction and boost) and derives everything else by rules fitted to the catalogue engines, which were authored from their makers' figures: redline from the use's mean piston speed, rods, pistons, compression, cams, intake and exhaust sizes for the peak-power speed, plenum, throttles, injectors, ignition template, gearing for the top speed the estimated power reaches. Each value is returned as a DesignValue with its rule; any can be set by key (overrides), and what derives from it follows. A rule that would fall outside the simulator's limits (validateEngineConfig(): on a 10-250 cc engine the flywheel, final drive, plenum, piston and throttle) is held at the limit (minimumRotatingInertiaKgM2 and the others, EngineTypes.hpp), and its rule says so; a value set by hand outside them is refused by name. The closed-throttle leak follows the throttle bore (0.6 mm2 at 60 mm and over) and is saved with the engine (closed_throttle_leak_mm2; before 0.6.0 a reloaded design ran on the 0.6 mm2 default). The truck use is the only one that fits an engine brake (four-strokes only; Engine brake in simulation-model.md), with the truck_12_speed_automated gearbox and the truck_tractor vehicle, its final drive set for 85 km/h at 0.55 x redline in top gear rather than for a drag-limited top speed. The control panel shows the brake's switch (ControlPanel::engineBrake, key 0) only on such an engine.

The window has three pages. Engine: the spec, the speeds, the compression and the induction (natural, turbocharged, supercharged -- a Roots, a centrifugal one on an aircraft -- or a centrifugal supercharger). Intake & fuel: the fuel system (fuel_system: port or direct injection, or a carburettor, on either cycle; a diesel injects directly), the intake (intake_style: an airbox, a pod filter, or open velocity stacks with a bellmouth 1.5 times the throttle's combined bore), the throttles, runners, plenum and, as they apply, the injection window or the jets, the venturi, the accelerator pump and the starter jet. A petrol four injecting directly injects on its intake stroke (420-600 deg, for a homogeneous charge), a direct-injected two-stroke from its exhaust port's closing for 70 deg. Exhaust: the system (exhaust_system: the family's, single, dual, dual with an H-pipe or an X-pipe), the silencer (exhaust_silencer: none, a packed box, a straight-through one), the primaries, collector, mid pipe, split, crossover, balance pipe, silencer body, tailpipe and tip. A value left empty shows its derived one in grey; one typed is set by key, as the Advanced table does.

The crank: banks at the layout's angles (a W's as given), cylinders shared over them in id order, one row per pin position along the crank. A V's or a W's cylinders of a row share one pin, as on the real engines (crank_pins, rowPinCrank(), CrankBalance.hpp): a 90 deg twin fires 270-450, a V8, a 72 deg V10 and a 60 deg V12 fire evenly. Where a shared pin cannot fire six cylinders or more evenly (a 60 or 90 deg V6, a W16), automatic splits the pins of a row by the least angle that does (splitPinCrank(): 60 and 30 deg); shared keeps them (a 90 deg V6 fires 90-150), separate gives each cylinder its own pin, placed for the best balance (evenFiringOrders()), as inline and flat engines have. A firing order given is kept, on shared pins when they allow it; crank offsets give an uneven crank (a 270 deg twin), the cylinders they put on one pin sharing it. A radial fires from its single throw. The crank_pins value says which, and the firing intervals. A two-stroke gets one expansion chamber per cylinder, tuned to its peak-power speed. Silencers, gearboxes and vehicles come from the family parts (parts/); a designed engine has the default voicing only.

An engine file may hold design: (the spec, same keys) instead of engine:; the catalogue loads it through the same function, so every harness runs a designed engine. The window (EngineDesignerWindow) shows the derived values and their rules as the spec changes, and names it from its cycle, fuel, layout and cylinder count until a name is typed; Advanced adds firing order, crank pins, crank offsets, W bank angles and setting any value by hand. Build and run first runs the design off-screen for a few seconds with the live engine paused (measureRealtimeCapacity(), runtime/RealtimeCapacityProbe.hpp: the physics-only factor at the realtime harness's speed; the engine is cranked with the throttle shut until it runs, at most 5 s simulated, then held on the dyno, since a carburetted two-stroke never catches at full throttle) and asks before building below realtimeCapacityMargin (1.14: the sound and the 3-D view cost 3-12 % on top). Cost grows with cylinders and speed: a 12-cylinder sport car is at the limit on the reference machine, a quad-turbo W16 at half. Then it saves the engine under My engines. EngineLab.EngineDesign checks it.

Live exhaust changes

An edit of exhaust and exhaustPaths only (the inspector's steppers, the Exhaust editor) that keeps the network's topology (same ducts, junctions, ports and outlets) is taken by the running engine:

  1. EngineRuntime::applyLiveExhaust, on the caller's thread, builds the new graph and gas network (EngineSimulator::buildLiveExhaustNetwork), which is the costly part, and leaves them in a mutex-guarded mailbox.
  2. The simulation thread takes it between two frames: the new network adopts the running one's state (ExhaustGasNetwork::adoptStateFrom), the simulator swaps it in, the runtime swaps its graph (the simulator holds a reference to it) and republishes the exhaust's static telemetry.
  3. The app hands the audio its own graph built from the same configuration. RealtimeEngineAudio::replaceExhaustGraph builds and prepares the new acoustic network off the audio thread; the audio thread feeds it silently for 150 ms while its pipes fill, then crossfades over 30 ms. The retired network is freed by the app's timer, never on the audio thread.

adoptStateFrom keeps the intensive state where it was: equal meshes copy cell for cell, different meshes take overlap-weighted means of densities, momentum, energy and wall temperature. A resized pipe therefore holds more or less gas at the same pressure and temperature. The wall temperature is the state that matters: its time constant is tens of seconds, while the gas refills in milliseconds (an exhaust swapped with a fresh network shows no engine-speed step, but a cold wall). Anything else (another topology, the dyno running, an audio network that fails to prepare) restarts the runtime as above.

The same path remeshes the running exhaust: the view settings' Exhaust waves choice (ViewSettings::fineExhaustWaves) passes 180 mm instead of the production 360 mm as the target cell length, and every later restart of the runtime keeps it. It never coarsens a mesh: a two-stroke's production cells are already 100 mm (EngineSimulator::productionExhaustCellLengthM) and stay so. 360 mm cells show 29 to 61 % less pressure swing than a 45 mm reference, 180 mm within 5 % on most engines; the simulation then has 13 to 20 % less headroom. The audio does not depend on it.

Live bore, stroke and rod changes

resizeCylinders (foundation) gives every cylinder one bore and stroke and the crank journals half the stroke as throw. An engine authored by compression ratio keeps it; one authored by chamber geometry keeps its piston-to-deck clearance and its compression ratio follows. resizeConnectingRods gives every cylinder one rod length (at least 1.2 strokes; a radial's articulated rods are refused) and keeps the compression ratio: one authored by chamber geometry keeps its piston-to-deck clearance, its deck moving by the added length. setCompressionRatio gives every cylinder one compression ratio (5 to 20): an engine authored by ratio takes it as is; one authored by chamber geometry keeps its head chamber, gasket and piston and moves its deck (a decked or shimmed block), refused when the crown would have to rise past the gasket. EngineRuntime::applyLiveCylinderResize hands the sizes to the simulation thread, where EngineSimulator::beginCylinderResize applies them one crank journal at a time, at the gas-exchange TDC (phase 360) of the first of its cylinders to reach it: the chamber then holds its clearance volume and both valves are near their crossing. The gas keeps its mass through the volume step (setVolumeAdiabatic). With a ramp, each such TDC takes the size interpolated at that moment until the target. A stopped engine takes the target at once. Changed at once, the first cycle of each cylinder burns fuel metered for the old one (one lean cycle on a larger engine); a ramp spreads that over many small steps.

What was derived from the geometry follows it: the kinematics reference is rebuilt after each change; the runtime republishes displacement, bore and stroke to the audio, gives the driveline the new engine inertia and, outside a dyno run, re-sizes the dyno absorber. Everything else reads the configuration at every step. Not updated until a restart: the audio's structural modes (StructuralModalRadiator, built from the mean bore and stroke). Cylinder count, layout and fuel stay restart-only.

Live injector, turbo, limiter, afterfire, flywheel, air and gearbox changes

The simulator reads injection, forcedInduction, ignition, exhaustAfterfire, the crankshafts' inertia and the ambient pressure and temperature only inside step(), and caches nothing derived from them but the exhaust outlet's ambient reservoir, which it rebuilds, so EngineSimulator::replaceSettings swaps them between two frames (the crankshafts field by field: their layout stays). The pipes' outer walls keep the outside temperature they were built with until a restart. EngineRuntime::applyLiveSettings posts them the same way as an exhaust, then gives the driveline the new engine inertia, gearbox and vehicle (DrivelineModel::replaceVehicle, same gear count: the clutch, wheel and vehicle states carry on) and the audio the new ambient. Refused, for a restart: another injection mode, a forced induction added, removed or of another type, another blade or lobe count, another number of gears, another crankshaft count, ratio, phase or position (settingsReplaceable). The ECU tables (advance, AFR, rev limit) are live through the ECU tuner, and override ignition's curve and limit whenever the store holds them. The sound's turbo layer takes the new configuration at the start of an audio block (RealtimeEngineAudio::replaceForcedInduction, ForcedInductionAcoustics:: updateConfig); its rotor and filter states carry on.

Live camshaft changes

The valve train reads the camshafts (the engine's and each bank's) at every sub-step and keeps only its phaser state, so an edit of the camshafts that keeps the banks and continuous valve control switched on or off alike (camshaftsReplaceable), is taken live, VTEC cams fitted or taken off included. EngineRuntime::applyLiveCamshafts posts it like the other groups; EngineSimulator::beginCamshaftChange swaps in the lift profiles, flow curves and continuous control at once and glides durations, lifts, centrelines, flow coefficients and the profile switch from their running values over the ramp (advanceCamshaftChange, at every sub-step), or takes them at the next sub-step without one. A valve open at that moment changes its lift on the spot; the ramp spreads that.

Live intake changes

An edit of the intake's sizes (runner length and diameter, per path or per cylinder, plenum volume, throttle bore) that keeps its topology (same paths and cylinders, throttle count, airbox or none: intakeReplaceable) is taken like an exhaust. EngineRuntime::applyLiveIntake builds the new runner networks (EngineSimulator::buildLiveIntake) off the simulation thread; replaceIntake has them adopt the running state, swaps them in, and resizes each plenum keeping its pressure, temperature and velocity (GasCell::resizeKeepingState); the throttle area is read at every step. The sound's intake network is rebuilt from the configuration and handed over like the exhaust's (RealtimeEngineAudio::replaceIntake: 150 ms filling silently, 30 ms crossfade).

Which edits are live

engineEditScope (serialization) compares a running and an edited configuration, both normalised, through their JSON, and sorts the difference into the groups above: exhaust, cylinder sizes, settings, intake, camshafts, or other. MainComponent::applyEngineEdit takes each group live in turn and restarts only for other or a group the running engine refuses; cylinder sizes and camshafts take its ramp (the inspector's choice, 3 s from the JSON editor). The JSON editor and the 3-D view's inspector go through it.

The top bar's A/B button (MainComponent::switchAbVersion, key 7) keeps the version not running in abVersions_ and hands the other one to applyEngineEdit with no ramp, so the switch is heard at once. Each version also keeps its ECU tables (a calibration snapshot), published back into the running store when it is switched to; the ECU tuner reloads on the new revision. Switching engine or reloading the engine file clears both versions.

Physical contracts

  • GasCell conserves species, internal energy, volume and 2D momentum. ConservativeGasSystem is the only transfer point between cells.
  • MechanicalKinematics provides positions, velocities, accelerations and lever arms, including master/articulated-rod geometry; simulation and render scene thus share the same reference.
  • FlamePhysicsModel computes delay, speed and progress without depending on the UI or audio. Its current geometric closure is a cylindrical effective volume πr²h, not a resolved 3D flame geometry.
  • IndicatedWorkModel integrates the signed P·dV loops as telemetry. The crankshaft receives the instantaneous torque from the pressure, not a reinjected mean torque.
  • ExhaustGraph turns a configuration into a bounded DAG, then ExhaustNetworkLayout discretises each component into quasi-1D ducts and finite junctions. ExhaustGasNetwork conserves species, momentum and energy, including at valves and outlets. The renderer receives a signed SI boundary and propagates its high band through passive characteristics, separately for each path.

3-D engine view

The engine view is drawn by the GPU through OpenGL 3.2 (juce_opengl). Three pieces split the work:

Piece Module Role
render::EngineModel3D render, no JUCE meshes built from EngineConfig (mm, +Y up, +Z along the crank) and a pose per crank angle
render::layoutExhaust / layoutIntake render, no JUCE ducts laid out from the configured exhaust graphs and intake paths
render::relaxRoutes / checkRoutes render, no JUCE pipes bent clear of each other and of the engine; what a real system could not do, counted
render::CrankClock render, no JUCE the crank angle to draw at any display time
render::GasFieldView / bindGasField render, no JUCE the solver's gas field mapped onto the drawn ducts, as wave colours and wall temperatures
ui::EngineSceneRenderer app shaders, buffers, multisampling and motion blur

Every moving part is placed with evaluateCylinderKinematics(), the function the simulator uses, so inline, V, flat, radial and articulated-rod engines are drawn as they are simulated. EngineLab.EngineModel3D checks every catalogue engine at 72 angles: rods keep their length, wrist pins stay on the cylinder axis, crowns stay below the deck. More than two banks (a W) are drawn bank by bank like a V, a head per bank, banks next in angle interleaved half a pitch along the crank as a VR's are; only a radial is drawn as one. On a designed W16 (EngineLabSceneExport --catalog-root) that took duct clashes from 58 to 15 and ducts through the engine from 70 to 8 (journal 2026-10-19). Rods on one crank journal are drawn on one pin; journals of their own pointing the same way share a pin within a row only (a V's banks sit 0.45 pitch apart, rows 0.55), so a V12's two middle throws stay two.

Threads:

  • the message thread copies the crank angle, engine speed, simulation rate (time scale × real-time factor, 0 when paused) and per-cylinder burn strength at 30 Hz into a mutex-protected block;
  • the OpenGL thread runs CrankClock: in real time it extrapolates the last sample with the engine speed and acceleration and pulls back onto each new sample (time constant 80 ms, jump beyond 90°), so the picture turns at the simulated speed between samples. In slow motion it integrates rpm × factor instead;
  • a pacing thread triggers frames at the chosen cap (30 to 240 fps). It also triggers the overlay repaints, so each tick renders one frame. "Unlimited" repaints continuously.

EngineSceneRenderer writes every part's transform and material into a buffer texture and draws each material group with one call. Each frame goes into a 4× multisampled buffer; with motion blur, the scene is drawn every 12° the crank sweeps during half a frame (12 sub-frames at most) and the sub-frames are averaged in a half-float buffer. Overlays are JUCE child components painted over the OpenGL frame. View settings live in view.json next to the key bindings. If the context cannot be created or a shader fails, the view falls back to the 2-D cutaway and says why.

The older RenderSnapshotBuilder / IEngineRenderer groundwork is not used by this view.

Ducts from the configuration

DuctLayout3D draws what the solver simulates, not a generic manifold:

  • Exhaust. Each path's component graph (or, without one, the graph the editor compiles from the scalar geometry) is drawn component by component, at its authored length and diameter; mufflers, catalysts, resonators and merges get the diameter of their authored volume. Pipes fed by a port, or feeding a junction with several inputs, are routed (below). Junctions and bodies sit on a trunk that runs along +Z (towards the flywheel), placed out from their ports and no higher than the crankshaft; a splitter spreads its branches, an X sends each bank back to its side. A collector's mouth is wide enough for its inputs side by side (they sit on a circle of radius (r + gap/2) / sin(π/N)). A collector fed by primaries sits behind the last port when every primary still reaches it (long tubes), else as far back as the shortest allows; the junctions of one path that would overlap (the two Y pieces of a 4-2-1) sit side by side across the trunk. A collector of three or more primaries with ports beyond its mouth turns the mouth across to face them, level with their middle, when every primary still reaches it (lead, entry and 1.2 times the straight distance within its length): the pipe after it bends onto the trunk in a quarter turn, or the gas goes straight on into the turbine of a turbo collector (the I5 and the TDI; the 2JZ's end primaries are too short). The straight runs of separate paths stand apart by their widest part, each moving away from the crankshaft (two-stroke chambers side by side). An outlet is the open end of the pipe before it: with no authored length it is only a short collar with a rolled lip, and the inside of an open opaque tube is shaded dark, so the opening reads as a hole.
  • Intake. Each runner has its length and taper, from the port to a plenum box of the authored volume (a drum round the crank axis on a radial). Upstream follow the throttle bores (on the plenum end, or on its face when there are several), the airbox volume, the inlet duct and its bellmouth, in the order the air crosses them. With neither a box nor a duct, each throttle's mouth carries a pod filter (pod_filter: a collar and a cone closed by its cap) or a velocity stack (its own lip, the authored combined lip over the root of the bore count).

Routing. relaxRoutes bends every routed pipe of the engine together. Each is a chain of equal segments with straight ends held fixed: 0.8 diameter out of its port, one diameter into its junction, along the trunk (the inputs of a collector arrive side by side, as on a real one). Contacts with the other pipes, with the intake ducts, and with the engine's solids (block, heads, crankcase, sump, liners, pulley, flywheel, plenum and airbox boxes) are projected out, then bends are held at 1.25 diameters or more and segments at their length, until nothing moves (200 contact passes at most). Each input of a collector takes the slot that makes the straight joins shortest in total. Intake runners are routed the same way, clear of their plenum. The shapes are invented; only their length, diameter and taper are the configuration's.

Round the engine (since 2026-11-18). The relaxation only moves a pipe locally: a primary laid through the crankcase stayed there (an X12's 12-into-1, its collector in the gearbox). So the engine's solids include the gearbox (engineSolidCount(): the engine and its gearbox, known before the ducts; a motorcycle's box also clears its two-stroke carburettors and its exhaust stubs), and three things follow the relaxation:

  • a pipe still through a solid (beyond a graze, two radii at each end left out) starts again from a way through the free room (FreeSpace: a grid of the solids and the fixed pipes, swollen by the pipe's radius and gap, a 26-neighbour shortest path) and is bent again with the others held, or with them all where they are in its way; a way longer than authored is drawn longer (stretched), never through the engine;
  • a path whose drawn pipes still sit in the engine, the gearbox, an intake box or another path's turbo, or whose turbo sits in the engine, is laid out a second time with its junctions free to move: each one whose trunk (body, straight run, turbo, the routed inputs' run into its mouth) is not clear moves to the free place its inputs reach with the least length left over, else to the one asking them the least extra length. That includes a junction further down fed by routed pipes (a V's Y on the crank axis behind the engine). Every other path keeps its layout exactly: the catalogue is unchanged but for the Big Twin's rear pipe, which crossed its gearbox by 71 mm. A first pass stops short where a pipe's axis is more than a diameter deep in a solid behind a blocked junction (beyond bending: its cost on an X12-2, 2.0 -> 2.9 s for the model, against 4.4 s with both passes whole);
  • an X or a W intake with ports on opposite sides gets two plenum boxes, the authored volume split by their runners and joined by a balance tube drawn between their faces; the simulation still has one plenum. A throttle, airbox or inlet duct goes where it clears the engine.

Bent first guesses (since 2026-11-18). The relaxation keeps a pipe near its guess, so the guess sets the look. Before it, spreadGuesses gives each pipe the clearest of 36 shapes bent as a tube bender would: straights and arcs of 1.5 diameters (bent), one or two tops pushed out at 12 angles round the chord, the height bisected to the pipe's length. Their cost counts overlap with the other pipes and the fixed tubes, depth in the solids, self overlap and bends under the minimum; up to three sweeps, a pipe already clear is kept. A collector whose ports lie behind its mouth now always turns to face them, even where its end primaries fall short and are drawn longer: along the trunk they had to turn back on themselves, and 25 of 26 that did were knotted.

A collector's place follows its primaries' length (since 2026-11-18). Back along the trunk it sits as far as every primary still reaches it (collectorZ: straight reach plus a fifth for the bends); turned, below the engine facing its ports, it moves out as far as they reach. It turns where ports lie behind its mouth, or where turning leaves its slackest primary clearly less to spend (+0.05 of its length) and the pipe after it can bend within its own length; a radial's stays on its axis. Turned trunks that come down onto another junction's draw back towards their heads a step at a time, alike. Kept just behind the last port, a 4 m primary spent its length in a 1.5 m hairpin.

Route check. checkRoutes measures what a physical system could not do: two ducts through each other, a duct through itself, a duct, a turbo or an intake box through the engine or its gearbox (since 2026-11-18), a centreline bent tighter than one diameter (circle through the points half a diameter either side), a pipe drawn more than 3 % longer than authored. Joints are not clashes: near an end that plugs into a port, a box or another duct, within two radii. Over the 16 catalogue engines, before the router: 107 clashes, 51 self-clashes, 0 through the engine, 259 tight bends, 6 stretched; with it: 7, 4, 0, 48, 7; over the 18 of 2026-11-14: 4, 4, 0, 46, 6; since 2026-11-17 (a plenum's face as far out as a runner's bend allows, a merge balanced between its routed inputs): 4, 4, 0, 21, 6. EngineLab.EngineModel3D keeps every count from growing, and designs 80 engines (inline, V, flat, X and W from 4 to 16 cylinders, with each of the designer's exhaust systems, a turbo on one pipe or the family's) of which none may have a pipe, collector or turbo through its engine or gearbox (29 did before 2026-11-18). A pipe that must span more than its length is drawn longer, and the inspector shows its drawn length beside the authored one: the two 140 mm pipes of the LS3's X (3.4 times), the two 1,070 mm pipes after it (6 %) and the two end primaries of the 2JZ, whose 430 mm cannot reach a collector they must enter along its axis. What remains is authored geometry the layout cannot fit without moving parts: the 2JZ's middle primaries coil to spend 430 mm over 230 (its 4 clashes), each 4-2-1's later secondary spends 256 mm over about 130 between Y pieces 100 mm apart (2 self-clashes), and the LS3's long primaries coil beside the head (2). EngineLabSceneExport writes the scene and the issues as JSON, to look at them outside the app.

Turbocharger. The gas solver's turbine is a restriction face on the outgoing face of the first junction where all of a path's cylinders have met (see simulation-model.md). The view draws one turbo per unit at the same place (TurboPlacement, turbos()): each unit on the collector of the first path that drives it, the path's own unit or its index modulo the count, as the simulator assigns them. A unit no path drives gets no gas and is not drawn; two units on a flat six's two banks are both drawn, each clickable with its own inspector (EngineLab.EngineModel3D checks it). Gas bends out of the collector, enters the volute tangentially and leaves the exducer along the trunk, where the path resumes; the shaft runs along the crankshaft, the compressor on the far side of the bearing housing, far enough out to clear the collector. Wheel sizes come from the inducer and exducer diameters (about 70 % and 85 % of the wheels), blade counts from the configuration (7 and 10 when unset). The wheels turn at the simulated shaft speed, slowed with the crank, motion-blurred over the same sub-frames. Housings are translucent in X-ray. The gas field shows the manifold at turbine inlet pressure and the downpipe at turbine outlet pressure. A turbo's charge piping is not drawn.

Supercharger. The solver has no compressor in its network either: the supercharger raises the intake pressure to the ratio its machine holds against the engine's draw (a Roots' displacement, leak and bypass, or a centrifugal wheel's map), geared to the crank (simulation-model.md, Forced induction). The view draws it (SuperchargerPlacement) between the airbox and the throttle of the first intake path with a single throttle mouth, beside the throttle on the side away from the engine: the airbox or the inlet duct feeds its eye along the throttle axis, a charge pipe runs from its volute back to the throttle. Wheel size from the inducer diameter (an eye 1.2 times the throttle when unset), blade count from the configuration. The impeller turns at the drive ratio times the displayed crank angle.

Engine views frame the engine with its ports, runners, plenum and primaries; the Exhaust view frames the whole system.

Gas field on the ducts

The exhaust and the intake runners and plenums are coloured by the gas solver's own state, not by an animation:

  • Capture. The view asks EngineRuntime::requestGasField() for the field at the crank angle on screen. The simulator tracks that angle and copies the state (GasFieldSnapshot: up to 16 cells per exhaust duct and junction, intake runner and plenum) between two sub-steps when its crank crosses it, so in slow motion or frozen the picture is the most recent cycle at the displayed angle. In real time the view takes the latest field instead. A request that waits 0.25 s of simulated time (a stopped engine) is served at the end of a frame. The copy reads conservative states only, so the simulation is unchanged (EngineLab.EngineModel3D compares two simulators bit for bit); the runtime publishes it through a try_lock mailbox and stops capturing a quarter of a second after the view stops asking (the 2-D cutaway never asks).
  • Mapping. bindGasField matches each drawn duct to its solver element by component id, or, on a path compiled from the scalar geometry, by node type and cylinder. Resonators with no outlet are acoustic side branches the gas solver does not carry; they keep their metal colour. Each duct vertex has a station (0 at the inlet, 1 at the outlet) and the shader interpolates between cell centres.
  • Resolution. The real-time mesh has cells of about 0.36 m on a four-stroke (0.10 m on a two-stroke), so a four-stroke primary shows one to three cells. The view shows what the solver resolves, not the audio band, which the characteristic network carries separately. Measured against a 45 mm mesh at full load: in a primary it shows 29 to 61 % less peak-to-peak; 180 mm closes most of it but costs 13 to 20 % of real-time capacity (the LS3 drops to about 1.0), so the production mesh stays.
  • Colours. The wave, not the pressure: each cell's departure from its own running mean (an exponential average over 0.5 s of simulated time, so a slowed or frozen view keeps it). Against ambient, a turbocharged manifold would read as one colour, at turbine inlet pressure. The prototype's scale: violet below the mean, grey at the mean, orange then pale yellow above, compressed with a 0.75 power. The scale is the strongest departure anywhere, decaying by 6 % per snapshot and never below 2 kPa; the legend prints it. Intake and exhaust share it, so their relative strength reads true: at idle and at full load (60 % of redline) the intake's peak is 0.6 to 4.8 times the exhaust's over the catalogue. The plenum is one lumped volume, so it shows one colour. A transient (a rev-limiter cut, a throttle step) shows as the whole exhaust above or below its mean until the mean catches up. The inspector gives the pressure against ambient.
  • Display mode. Pressure waves in the settings menu (saved in view.json) chooses what the All layer shows: Hidden (the default: plain metal, nothing flickers), Pulsation strength or Live pulses (the wave above). The strength is each cell's root-mean-square departure, its square averaged twice over 0.5 s (once leaves a 5 % ripple at an idle's cycle rate, a visible shimmer), on a scale that is the strongest anywhere, never below 1 kPa and decaying by 2 % per snapshot, from grey (still) to orange and pale yellow; it shows where the gas pulses hardest and holds still while the engine runs steadily. The Gas flow layer shows the strength when the mode is Hidden; the other layers show no waves.
  • Camera microphone. Microphone on the camera (settings menu, Sound, saved in view.json as microphoneOnCamera, on by default) hears the engine from where the camera is heading: EngineViewport::cameraMicrophones() maps the eye and its right vector through render::ListenerFrame, and MainComponent passes them to RealtimeEngineAudio::setMicrophones when they change or a new renderer plays. The drawn openings (EngineViewport::soundSources(), from render::ListenerFrame::sources, rebuilt with each 3-D model) go to RealtimeEngineAudio::setSoundSources in the same way, so the exhaust is heard from the drawn tailpipe and the intake from its drawn mouth (see realtime-audio.md, Camera microphone).
  • Trackside microphone. Trackside microphone (settings menu, Sound, EngineViewport::tracksideMicrophone(), off at every start, not saved) turns the camera's microphones off and has MainComponent call RealtimeEngineAudio::setPassByEnabled: the car loops past a microphone 7.5 m off its lane (realtime-audio.md, Trackside microphone); a pass-by run (top bar, Pass-by) drives it instead.
  • Heat. Each cell's wall temperature (the solver's finite-capacity wall) makes the steel glow from the Draper point, 798 K, to orange-yellow at 1,300 K, in every layer.
  • Afterfire. A flame at every outlet, lit by 1 − exp(−heat release / 10 kW) of the afterfire at the captured instant.

Clicking a part opens an inspector: the part's authored geometry and, for a duct, the solver's pressure range, gas and wall temperatures and cell count at the displayed angle. The pick is a ray cast on the CPU against the posed meshes of the visible layer; X-ray shells let the click through. A see-through duct (the intake runners) gives way to a solid part inside it: when the nearest hit is such a duct's wall and a solid part is hit between that duct's near and far walls, the solid part is picked (the injector in its runner).

For a duct the inspector also draws an oscilloscope: the pressure of the clicked cell (the cell nearest the click along the centreline) over one engine cycle, against ambient. The view asks EngineRuntime::requestGasProbe() for that cell; the simulator records it at every sub-step into 360 crank bins (2° on a four-stroke), each bin keeping the latest cycle that crossed it, and the runtime publishes the trace through a try_lock mailbox once per frame. It reads the same cell the gas field shows (runners reversed to gas-flow order) from conservative states only, so the simulation is unchanged; it stops 60 frames after the view stops asking. A marker shows the bin last written. Its sub-step resolution is what the snapshot cannot give: a capture is one instant per crank angle.

An exhaust component can be resized from the inspector: steppers for its length (10 mm, 1 mm with Shift) and diameter (1 mm, 0.1 mm), or a click on the value to type it. Enter applies the typed value at once (clamped to the stepper limits), Escape or a click elsewhere cancels it, and both hand the keyboard back to the engine controls. resizeExhaustComponent (exhaust library, no JUCE) writes the edit into the configuration: the component of the path's network or, on a path authored as scalar geometry, the scalar field behind it (the primaries share one size; a silencer is sized by its body). Every component's length can be edited: a merge, splitter, crossover or outlet takes 0 (no length) or 10 mm to 30 m, a pipe or silencer 10 mm to 30 m; a scalar path whose component has no scalar length is turned into its network first. The inspector warns that an element under about 50 mm sets a short time step for the whole network. It refuses an edit that would change which components the path has (a silencer no wider than its pipes stops being one) and, on the only path, mirrors the geometry into EngineConfig::exhaust, which normalisation copies back and the solver reads. A stepper press reaches the running engine 250 ms after the last one (a live exhaust change, see above); Reset goes back to the size the part had when it was selected. The camera stays and the part stays selected.

A cylinder liner or piston offers the engine's bore and stroke the same way (1 mm, 0.1 mm with Shift), and its compression ratio (0.5, 0.1 with Shift; only the values edited are applied, so a chamber-geometry engine's ratio still follows its bore and stroke), with a choice between a 3 s ramp (the default) and the next cycle (a live bore and stroke change, see above). The view shows the target size at once. A connecting rod offers the rods' length the same way (5 mm, 0.5 mm with Shift).

The other parts edit the same way, each through MainComponent::applyEngineEdit (see Which edits are live):

  • an intake runner (length and diameter, its own if the cylinder has one, else the path's, which every runner on it shares), a plenum (volume) and a throttle (bore): resizeIntakePart (foundation), which mirrors a single path into EngineConfig::intake and the legacy fields. On a path metered by a carburettor the throttle is drawn as one (the slide's tower above the bore, the float bowl under it) and named Carburettor: it also offers the main and pilot jets as stamped flow numbers, the needle clip (1 richest to 5), the air screw's turns out and the idle stop screw's turns in (tuneCarburettor, mirrored the same way), which the running engine takes as an intake edit;
  • the exhaust ports of a cylinder, and a junction, when the engine has another exhaust path that can join this one: a choice between Separate and Joined that restarts the engine with joinExhaustPaths (exhaust library). Each cylinder of the next path gets a copy of this path's first primary run (its components up to the first junction several pipes meet at), feeding that junction; the other path's pipes, silencers and outlet go, and banks that fed it feed this one. A boxer six's two 3-into-1 banks so become one 6-into-1; the collector keeps its size. Refused (not offered) when the primary meets no other pipe before its outlet, or when a turbocharger would be left without a path;
  • the injectors, on each drawn injector (PartRole::injector: in the runner out of the head for port injection, in the chamber's roof on the intake side for direct injection), and also on the intake ports: flow in g/min (the configuration keeps mg/s) and fuel pressure in bar, plus a diesel's start of injection in degrees before firing TDC (the window keeps its length and moves with it), with the window, live duty cycle, fuel per cycle and, for port injection, the wall film. The side panel's Telemetry tab has a Fuel injection section whose Show in 3-D button selects cylinder 1's injector (EngineViewport::showInjectors, back to the All layer if the current one hides it). The injector and the throttle body also offer the fuel system as a choice (port injection, direct injection, carburettor: withFuelSystem(), the designer's own sizing of the injectors, the carburettor's venturi and jets, and a two-stroke's direct window; a diesel refuses all but direct), and the airbox, the inlet duct and the throttle body (its secondChoice, on a row of its own) the intake style (airbox, pod filter, open trumpets: withIntakeStyle(), sized as the designer does). Both restart the engine; the view then selects the injector, or deselects when the intake's parts changed;
  • the fuel, on the combustion (PartRole::combustion): a choice among parts/fuels.yaml of the engine's kind (loadFuelPresets: properties, octane, latent heat) and the octane (cetane on a diesel), heating value, stoichiometric ratio (the oxygen a mole needs follows it, and so does the heating value unless it was edited too: followingHeatingValue() keeps the energy per kilogram of oxygen, about 13 MJ for any real fuel, which the Fuel window shows and marks past 14), latent heat and laminar flame speed; a restart, and an edited fuel is named "(edited)". The octane alone is the engine's, not the fuel's: it is a live setting (EngineEditScope::settings, the knock model reads it every step), keeps the fuel's name and changes no spark map or knock-limit curve -- the advance is the user's to tune. The same fields (app/FuelEditing.hpp, shared) are in the Fuel window (FuelWindow), opened by the top bar's Fuel button and by the Telemetry section's: its edits wait for Apply, and a field not edited keeps the fuel's exact value;
  • a turbo: the wastegate pressure ratio, the rated ratio keeping its distance to it, and the turbine flow area; a supercharger: its pressure and drive ratios. A turbo and every exhaust component also offer a choice between No turbo and Turbo: it fits sizedTurbocharger() or takes the turbo off, which restarts the engine; the view then selects the new turbo (Reselect::role), since the parts have changed;
  • the cylinder block: the air around the engine, as an altitude (the standard atmosphere's pressure there) and a temperature, the cooling airflow (coolingEfficiency, a restart), and a switch between regulated and realistic engine temperatures (thermal.regulated; the inspector's edit choice, taken at once; its rows show the coolant temperature and, realistic, when the radiator fan is on);
  • the gearbox (PartRole::gearbox, drawn on every engine with two gears or more): the clutch shift time and the quickshifter's ignition cut in ms, and the shift style as a choice (manual, quickshifter, quickshifter and blipper, dual clutch, CVT, automated manual; see Shift styles in simulation-model.md). Its rows show the engaged gear, its ratio, the input shaft speed, the clutch slip and the road speed. A car's box sits in line behind the flywheel and its clutch disc, the layshaft below; a motorcycle's (vehicle under 500 kg) behind the crank, driven against it by the primary gear, with its clutch pack and sprocket. Each pair has the teeth of its ratio (within 6 %) and turns at that tooth ratio of the input shaft, whose angle the view integrates from the engine speed less the clutch slip (the crank's in neutral), never wrapped; a blue collar slides against the engaged gear and turns the output shaft with it. Its parts sit out of the engine framing and out of the ducts' solids, so neither the camera views nor the routing change;
  • the crankshaft: the inertia of the crank and flywheel (every shaft scaled alike), with the total including the rods, and the bearing friction (frictionCoefficient, a restart);
  • an intake or exhaust valve: its cam's duration and lift; the cylinder heads: the intake and exhaust centrelines, with the lobe separation and the overlap. Every camshaft moves by the same amount, a variable profile's high cam too, over the 3 s ramp or at the next cycle.

Two controls at the bottom right slow things down, and they are different. 0.25x / 0.5x / 1x is the simulation's time scale (EngineRuntime::setTimeScale, also on the time keys and the wheel): the physics runs slower, and the sound with it. Live / Strobe 1:50 / Strobe 1:250 / Freeze is a stroboscope: only the picture slows down, showing the most recent cycle at the displayed angle, while the engine and its sound run on. A click in the 3-D view, like Enter or Escape in a text field (the dyno's run name, a typed size), gives the keyboard back to the engine controls.

Extension rule

A new engine cycle or fuel (as the two-stroke and the diesel did), a torsional crankshaft or an OpenGL backend must come in through an explicit model or interface. They must not bypass validation, the conservation invariants or the real-time boundaries.