Skip to content

Latest commit

 

History

History
1079 lines (976 loc) · 66.3 KB

simulation-model.md

File metadata and controls

1079 lines (976 loc) · 66.3 KB

Simulation model

EngineLab is a real-time control-volume simulator. Its equations are designed to stay consistent and observable within an interactive budget; they are neither a CFD model nor a performance certification.

Integration and angular resolution

The public EngineSimulator::step(dt, controls) call is split into sub-steps. The requested rate is the maximum of the minimum mechanical rate, including gasSubsteps, and the rate required to honour maximumCrankDegreesPerStep at the current engine speed. It stays bounded by maximumMechanicalFrequencyHz.

Validation rejects a configuration whose maximum rate could not hold the promised angular resolution at the rev limiter. The solver publishes the angular step actually reached and any overshoot; it does not hide an under-resolution behind a nominal rate.

Kinematics, pressure and torque

MechanicalKinematics solves the slider-crank geometry from the normalised crankshafts and journals. Conventional, master and articulated rods share the same API for position, velocity, acceleration and lever arm. Deck height, compression height, pin offset and articulated-journal radius take part in the TDC position when provided.

At every sub-step, each cylinder's pressure acts on the piston area and the exact lever arm. Gas, reciprocating, friction, starter, load and transmission forces form the net torque, then:

angular acceleration = net torque / equivalent inertia

Running torque comes from this resolved pressure. No empirical mean torque is mixed into the crankshaft dynamics.

In parallel, IndicatedWorkModel integrates the signed loop ∮(P_cylinder - P_ambient)dV with the trapezoidal rule. At each cycle change, it publishes indicated work, IMEP, indicated power and equivalent mean torque. This reading is for diagnostics and balances, without becoming a second torque source.

Piston/liner friction uses a Stribeck law per cylinder: breakaway force, Coulomb, low-speed transition and a viscous term. The direction is defined even near zero velocity, which avoids a friction that would artificially accelerate the piston.

Conservative gas network

The atmosphere, plenums, runners, cylinders, primaries and collectors are GasCells. A cell stores the amount of each species, the internal energy, the volume, an orientation, a characteristic area and a 2D momentum.

Restrictions use their real area and a discharge coefficient. The flow becomes choked when the pressure ratio reaches the sonic condition; otherwise it follows the subsonic isentropic relation. The directional dynamic pressure is signed: momentum directed towards the restriction raises its effective total pressure, opposing momentum lowers it.

A transfer simultaneously carries:

  • oxygen, inert gas, fuel vapour and burned products;
  • mass and momentum on both axes;
  • stagnation enthalpy and macroscopic kinetic energy.

An equilibrium search bounds the transfer before the non-physical reversal of the gradient. Dissipating momentum beyond the speed of sound converts the kinetic energy back into heat. The effective properties Cv, gamma, molar mass and speed of sound depend on the composition and the temperature: each species is thermally perfect, its Cv a straight line in temperature fitted to the JANAF tables over 300-2,600 K (O2 and N2 held at 5/2 R at 300 K; the products as 8 CO2 to 9 H2O; the fuel vapour constant), so the internal energy is a quadratic in T with an exact root and gamma is the local 1 + R/Cv(T): 1.40 for air at 300 K, ~1.27 for a burnt charge at 2,000 K. The cylinders and the 1-D ducts carry the same laws. A calorically perfect gas (N2 at 5/2 R, the products at gamma 1.26 at every temperature) expanded a burnt charge at ~1.35 and so extracted ~13 % too much work.

Temperature and pressure stay derived from all the conserved internal energy, including beyond the usual thermal range of the engine: no display ceiling can hide an energy reserve in a cell.

During valve overlap, intake and exhaust are evaluated from the same starting state and then applied together. This transaction prevents an arbitrary call order from changing the gradient seen by the second valve.

The cylinders and the plenum stay 0D volumes. Each intake runner, though, is a 1-D finite-volume duct (buildIntakeRunnerNetwork) in which a wave travels between plenum and valve; when the runners share a plenum the simulator joins them and it in one manifold network (EngineSimulator::jointIntakeManifold), so a pulse from one valve reaches the others.

A stopped crank (below 20 rpm, starter off) passes no gas through its valves, and the 1-D intake runners stand at their plenum's pressure instead of advancing (ExhaustGasNetwork::settleAtRest). Held at equilibrium, an open valve's quasi-steady law and the runners' explicit plenum coupling both grew roundoff into tens of kPa (see docs/journal.md, 2026-10-06).

Valvetrain and intake

ValveTrainModel evaluates the profile of the cylinder's bank. Lift profiles and lift/discharge-coefficient curves are sampled and interpolated. An RPM/load calibration can continuously drive intake advance, exhaust advance and the lift multiplier; the actuators follow their target at a configurable response rate. The switched high profile is VTEC: the ECU's vtec.* settings (docs/ecu-tuning.md) choose it per whole cycle, ValveProfileActuator applies it on a base circle, and the event generator, the physics' cam metrics and the 3-D view follow the cam each cylinder actually runs (EngineState::vtecHighCylinderMask).

The filling comes from those 1-D runners. HelmholtzRunnerModel still attaches a damped mode to each runner, its frequency set by the area, the length, the volume and the port's speed of sound from the runner network; it feeds the telemetry and the acoustic intake excitation, not the gas: it creates neither mass nor torque.

Two-stroke engines

cycle: two_stroke gives a piston-ported, crankcase-scavenged petrol engine (reed or piston-port intake, one firing per cylinder per revolution). The crank angle stays a 720-degree domain for every engine, so the render, the crank clock and the gas field are unchanged; each cylinder's thermodynamic phase runs on 360 degrees (EngineSimulator::cylinderCycleDegrees()), and spark, injection, the trapped-charge latch and the cycle telemetry follow it.

  • Ports, not valves (TwoStrokePorts.hpp): the exhaust and transfer ports open when the slider-crank piston uncovers their top edge (two_stroke.exhaust_port_open_deg, transfer_port_open_deg after top dead centre) and are fully open at bottom dead centre. The open area is width x uncovered height x port_discharge_coefficient; widths default to 0.65 and 1.30 x bore. No cam, no valve lift (published lifts are zero).

  • Crankcase pumping: each cylinder has its own intake path (validation enforces one cylinder per path). That path's plenum is the crankcase: its volume follows the piston's underside every substep, adiabatically, between crankcase_compression_ratio x its bottom-dead-centre volume and that volume. The throttle is the carburettor bore with a reed check valve (no flow out of the crankcase), and the runner is the transfer duct. The piston's underside sees the crankcase pressure, not the ambient.

  • Intake (two_stroke.intake): crankcase_reed, the default, feeds the crankcase through the reed whenever it is below the carburettor. A cylinder_port feeds it through a port in the barrel wall that the piston skirt uncovers intake_port_open_deg_btdc before top dead centre and covers again as far after (width intake_port_width_mm, 0: 0.70 x bore). Its open area is in series with the carburettor's, 1/sqrt(1/A_carb^2 + 1/A_port^2), and is zero while the skirt covers it; intake_port_reed keeps a reed behind the port (a check valve) or leaves it open, in which case the crankcase blows back through the carburettor when it is above it. Measured (EngineLab.TwoStroke): at 8,000 rpm a 110 deg port delivers 0.50 against the reed's 0.88; at 3,000 rpm a 190 deg port delivers 0.88 with a reed and 0.69 without. The designer gives a sport cylinder port 95 deg BTDC, a road one 72 deg.

  • Power valve (optional): a valve in the exhaust port's roof, Yamaha's YPVS and its kind. Shut, it lowers the roof, so the port opens power_valve_closed_exhaust_port_open_deg after top dead centre instead of exhaust_port_open_deg and is that much lower; a servo lifts it between power_valve_opening_start_rpm and power_valve_fully_open_rpm (a smooth schedule, 0.25 s of lag). The designer fits one to sport two-strokes, 12 deg later shut, lifting from 65 to 90 % of peak power speed: on a 500 cc twin it fills the 30 N.m trough at 4,000-4,750 rpm (+20-39 % from 3,250 to 5,750) and leaves the top end as it was. EngineState::powerValveOpening publishes it.

  • Trapping: the charge is trapped when the transfers close (symmetric about bottom dead centre); short-circuit losses come out of the same 1-D exhaust flow that scavenges the cylinder. There is no pumping loop in the cylinder: all of its work is gross work.

  • Scavenging (TwoStrokeScavenging.hpp): one well-mixed cylinder cell with two ports onto it is perfect mixing, so trapping came out a function of delivery ratio with no engine speed in it anywhere (0.448 at 2,000 rpm to 0.807 at 9,000, straight along that relation). A real loop-scavenged cylinder displaces first: the transfers aim the charge up the far wall, it loops over the head and pushes burned gas out ahead of it, and only once that front reaches the exhaust port does fresh charge start escaping. Those are the classical bounds -- displacement SE = min(DR, 1), mixing SE = 1 - exp(-DR) -- and the simulator sat on the lower one. What places an engine between them is a race between the front's travel and the port window. The front's progress is integrated every sub-step, frontProgress += jetVelocity x dt / loopLength, with the loop length scavenge_loop_length_ratio x bore and the jet velocity read from the crankcase-to-cylinder pressure difference; displacement lasts until the progress reaches 1 and mixing is established over one further loop length. The window lasts port_open_duration / (6 x rpm), so a faster engine's front covers less of the loop and the displacement phase owns more of the window -- which is why a two-stroke scavenges well near its tuned speed and is dirty when lugged. No pressure across the ports means no loop: the front stays where it is and the cylinder mixes as it used to. Integrating rather than predicting a transit time is not a refinement. An earlier version sampled the jet velocity once, at the instant the transfers cracked open, and in the 5,000-6,000 rpm band that instant is where the exhaust pipe's returning wave sits: the loop closed through it (strong jet, more trapped, more exhaust energy, stronger wave, different pressure at the next opening) and the RD350's brake torque stopped holding, 13.3 to 37.6 N.m around a 25.6 N.m mean at 5,999 rpm against 6 % spread with the model off (journal 2026-10-21). A front does not travel at one instant's orifice velocity in any case. The bias is applied to the composition the exhaust port offers the 1-D network, not to the port areas: the network reports back exactly the species masses it took and the cylinder is debited those same masses, so species, mass and energy conserve for any composition presented. Only the composition moves -- the energy density is passed through untouched, because pressure and temperature drive the flow and this model says what the gas leaving is, not how much of it leaves. A cylinder holding less burned gas than the fresh charge being held back (cranking, the first cycles) has nothing to displace with, and the bias reduces itself to what the residual can cover. A loop length of zero restores the perfectly mixed cylinder exactly, and a four-stroke never opens a window, so its exhaust boundary is bit-for-bit unchanged. Measured, one binary with only the loop length changed: the curve moves +2.2 % in the mean and +26 % at 5,752 rpm, where it fills an antiresonance (23.1 -> 29.1 N.m), and less than 1 % below 3,250 or above 7,000. The band is not a tuning. Below it the displacing share is a tenth of the window, so there is almost no bias; above it trapping is already 0.83 and the cap on what the residual can cover binds. It therefore does not address torque climbing to the rev limiter: that is trapping which never falls, and the displacing share is monotonic in engine speed by construction.

  • Carburettor: the fuel system a two-stroke actually has, what the designer fits to every two-stroke it builds, and a choice for a four-stroke (IntakeConfig::carburettor, CarburettorModel). Nothing is commanded: the jets are orifices into a float bowl at the pressure outside the engine, and the mixture is whatever depression the air draws through them. The fuel goes into the crankcase with the air that metered it, in the bore, so the lag to the cylinder is the crankcase's own residence time rather than an injector command's guess at it.

    Two circuits run in parallel and are never blended, because each is driven by a depression the other does not see. The main circuit has the throat's: the narrowest section the air crosses, which is the slide's own gap part-way open (with the idle passages and the leak beside it) and the venturi wide open. Its needle rides with the slide, cut so the needle jet's annulus follows the slide's open area over the venturi's: the main circuit then holds the full-throttle mixture from where the slide lifts to where the venturi takes over, and carries only the slide's share of the air. The clip scales that annulus by 8 % a notch (1 richest), and does not touch full throttle. With the slide down the needle shuts and the main passes nothing. Read off the whole venturi instead, the main drew a few tens of pascals at 10 % -- under the jet's lift -- and every designed two-stroke stalled lean at small openings (journal 2026-11-09). The pilot circuit has the whole drop from the bowl to the crankcase, largest with the slide shut and gone at full throttle, where the crankcase pumps at about ambient. Each fades out where the other takes over and no crossover term is written anywhere. A fixed venturi (a four-stroke's) keeps the venturi's depression and no needle.

    Jets carry the number stamped on them: cc/min of test fluid under one metre of head, so flow is the number times the root of the head available. The inspector shows them as the hole Dellorto and Keihin stamp, in hundredths of a millimetre (jetHoleHundredthsMm, through the jet's discharge coefficient, 0.80: a Mikuni 500 is a 173 hole), and a new carburettor bore scales the main jet with the throat's area, by the bore's square, when the venturi follows the bore (no venturi_diameter_mm): the mixture, jet area over throat area, holds. The designer sizes them from the engine and not from a table -- the fuel peak power needs at AFR 12.8 over the root of the venturi head there, and the fuel the idle air needs at AFR 13.5 over the root of the crankcase head. The idle air is what the idle path passes at that head (the slide's leak and the bypass at the idle governor's neutral opening). A carburettor has no idle governor: its idle stop screw (idle_screw_turns, 0-8 turns in) holds the slide on that path, 1.5 turns on the sizing opening and each turn alike, and the engine idles wherever that air takes it; only the after-start floor (the choke's stand-in) opens it further. As the path opens or shuts, the pilot follows it the way progression holes do: the idle mixture holds through cranking and idle. On an RD350-sized design the main comes out at 287 against the bike's 260-290. The main jet is very nearly its circuit's only restriction so its number is used directly; the pilot's is not, because the emulsion passage, the air screw's bleed and the outlet all throttle it further, and pilotCircuitFactor is that lumped restriction (0.026, the one value fitted to a real pair: an RD350's 35 pilot feeding its idle air at AFR 13.5 on about 20 kPa). A pilot sized for an idle delivery ratio of 0.35, about eight times what the model's RD350 idles on, flooded every designed twin.

    Two things a real carburettor has are deliberately absent, both of which act at the top of the range: there is no emulsion tube or air corrector, so the main circuit keeps the plain jet's richening with flow instead of being held flat, and the air density at the throat does not fall with the depression. Neither is stood in for by a factor, because the first is a two-phase effect in the passage that no single algebraic term represents honestly. They are measured gaps, not calibrations.

    A four-stroke's carburettor is a car's: a fixed venturi with a butterfly downstream and no needle (fixed_venturi), so the main jet meters at its whole area at any opening. The designer sizes its venturi for its signal, 5.1 kPa (Holley's 1.5 inHg rating) at peak power per bore, since a throttle-body-sized throat (2 kPa at peak) leaves the main jet under its lift at low speed; the pilot's head is a manifold idling about 65 kPa below ambient, its air choked across the plates. Two circuits a two-stroke's slide carburettor lacks come with it. The accelerator pump (accelerator_pump_stroke_cc, 0.25 cc per litre and bore for a full stroke, about a Weber DGV's; accelerator_pump_time_constant_s) squirts in proportion to the throttle's rise. The starter circuit (starter_jet_flow_number, a bike's enrichener or a car's choke) is a plain jet on the pilot's drop that opens with the start aid's air above the idle stop screw and closes as that air does; the designer sizes it to run that air at AFR 8. Without it the start aid's air only cracks the slide and feeds the pilot in proportion, which enriches nothing: a 750 cc four on four bores cranked at 75 kPa of manifold pressure and never fired. A choke's AFR 4 flooded a warm 2-litre once it ran with the aid still open. A sport four-stroke's cam (62 deg of overlap) idles too lean on the derived pilot and hunts; it holds with a pilot jet 1.4 times larger (journal 2026-10-29).

  • Fuelling (an engine configured without a carburettor): the ECU meters for the air that crossed the reed into the crankcase during its last fill (latched when the transfers close, just before the pulse), which is the same air a carburettor would have metered; not for the trapped oxygen (most of a two-stroke's trapped charge is retained from earlier cycles), nor for the air across the transfers, which lags the fill by an event on a tip-in and left the RD350 lean and stalling. There is no overrun fuel cut (a cut scavenges the cylinder clean, and each resume fires a full charge), and lambda learning is held through a closed-throttle overrun and for 2 s after it.

  • Idle: a shut throttle delivers a few percent of the swept volume, so the trapped charge is mostly the last cycle's burned gas, and the dilution misfire limit (Ignition, flame and knock) makes the engine fire about one revolution in three, with runs of up to a dozen misfires; the designed engines idle 1,240-1,340 rpm with dips to 800-1,150 rpm.

  • Load: a two-stroke's "manifold" is its crankcase, which pumps about ambient at any throttle (75-87 kPa at idle), so its load is the delivery ratio of its last cycle, not the manifold pressure; the ECU's load axis reads the same (an alpha-N calibration is the closest real input). Read as a four-stroke MAP, the crankcase made the ECU retard a full-load RD350 by about 2 deg, and read an idle as a 0.77 load.

  • Exhaust reconstruction: an expansion chamber is a chain of short cones, most of them two or three cells at the two-stroke mesh. A two-stroke's exhaust reconstructs across every open duct-to-duct interface (ExhaustGasNetworkConfig::reconstructAcrossInterfaces), so two components of one section are one pipe to the solver; a four-stroke keeps first-order duct ends.

  • Exhaust coupling: the exhaust network is coupled to the cylinders at intervals of up to 125 us (117 us, three mechanical substeps, for the RD350 at 8,000 rpm), and the exchange reaches the cylinder as one lump. From bottom dead centre to the transfers' closing, a two-stroke's cylinder pressure is a few-kPa balance between two open ports that sets the trapped charge, so while any cylinder is in that window the exhaust is coupled every substep (EngineSimulatorOptions::exhaustFineCouplingWhileScavenging). Coupled coarsely there, the RD350 lost 10-14 % of its torque above 6,000 rpm; coupling every substep over the whole cycle is not real time.

  • Compression ratio: the model takes the geometric ratio. A Japanese maker's figure (6.2:1 for the RD350LC) is usually the trapped one, counted from the exhaust port's closing.

  • Limits: petrol only, naturally aspirated, one cylinder per intake path, no individual throttles, injection angles inside the 360-degree cycle. There is no oil (premix) in the charge. An engine configured with an injector rather than a carburettor keeps the injector's own limit: the fuel reaches the cylinder about an event before the crankcase would deliver a carburettor's mixture, so a tip-in runs rich (AFR 9-10) for a few events. The expansion chamber's return wave needs fine exhaust cells: a two-stroke's production mesh is 100 mm (EngineSimulator::productionExhaustCellLengthM, 360 mm for a four-stroke; the view's fine mode never coarsens it). The catalogue RD350LC-like twin makes 29-33 N.m at 8,000 rpm (dyno sweep and held test) and 34 kW at 9,025 rpm in real time, against the maker's 37-40 N.m and 34.5 kW; 25 mm cells coupled every substep give 35.9 N.m. What is left of the mesh gap is mostly the first exhaust cell behind the port, which holds about a cylinder's volume and acts as a plenum. 75-80 mm make its idle hunt (journal 2026-10-15/16). The script language sets the cycle but not the port timings, which take their defaults (exhaust 92 deg, transfers 118 deg).

Rotary (Wankel) engines

cycle: rotary gives a Wankel engine of rotary.rotor_count rotors, each with its generating radius R, eccentricity e and width b. Each rotor's three faces are three of the engine's "cylinders" (cylinder_count = 3 x rotors, 32 at most). Each face runs its own cycle of 1,080 degrees of the eccentric shaft, with strokes of 270. The crank angle's domain is 1,080 for a rotary (crankDomainDegreesOf): spark, injection windows, valve events, the trapped-charge latch, the knock calibration's bins and the 3-D crank clock all follow it. Four-strokes and two-strokes are bit-identical to before.

  • Geometry (rotaryFacePosition):
    • A face sweeps Vd = 3 sqrt(3) R e b (a 13B: 654.7 cc).
    • Its volume is Vmin + Vd/2 (1 - cos(2a/3)), smallest at firing top dead centre and again at gas-exchange top dead centre (540).
    • The gas torque is p dV/da, so the lever is Vd/3 sin(2a/3).
    • A rotor's faces fire 360 degrees apart, and the rotors are spaced evenly round the shaft.
    • A face carries an equivalent bore of 2R/sqrt(3) (its two flames' path) and the stroke that gives its sweep (applyRotaryFaceGeometry). Bore and stroke cannot be set on their own.
    • Nothing reciprocates: there is no piston or rod inertia.
  • Heat: the chamber's wetted surface is the flank, the housing arc and the two side housings, 2 sqrt(3) R b + 2V/b. That is 0.031 m2 for a 13B face at top dead centre, against 0.023 m2 for a piston of the same bore. Woschni's velocity is the apex speed, omega R / 3. This long, thin chamber is the rotary's known heat-loss penalty, and it comes from the geometry, with no extra factor.
  • Ports as valves: a side port opens and shuts as the rotor's flank sweeps over it. It is written as a valve of the face's cycle: a trapezoid lift profile (open over a quarter of its duration) and a flow curve. The centrelines are measured from gas-exchange top dead centre, as on a four-stroke.
  • Shared ports:
    • Intake: the simulator builds one runner per rotor. Its three faces open in turn onto a passage junction (2.5 runner bores long) at the runner's end. Port fuel goes into the runner's inlet.
    • Exhaust: each rotor's faces open onto one passage, then the rotor's primary, both in the catalogue builder and in the designer's network.
    • A rotor's faces cannot be split across intake or exhaust paths.
    • Shared ducts run the cylinder pass serially (the parallel pass needs disjoint ducts).
  • Displacement:
    • engineDisplacementLitres sums every face (a 13B: 3.9 L).
    • The IMEP is per face.
    • What scales with the air an engine breathes takes breathingDisplacementLitres, the faces swept in 720 degrees (2.6 L for a 13B): the turbine, compressor and charge volume, the designer's rules, the bearing and accessory friction, the FMEP shown, and the dyno absorber's gains. The summed faces put 1.5 times a piston engine's friction on the shaft and made the absorber swing a 13B from 1,750 to 5,300 rpm about a 4,000 rpm point. Piston engines are bit-identical.
    • Mazda's figure, one face per rotor (1.3 L), is what the designer takes and what its status line shows.
  • Designer (cycle: rotary, rotors: or cylinders: = rotors, a displacement_l in Mazda's sense):
    • The rotor has the 13B's proportions (R/e = 7, b/R = 0.76), or the generating_radius_mm, eccentricity_mm and rotor_width_mm you set.
    • The redline follows the apex speed: 9,000 rpm (sport) or 7,500 at R = 105 mm, 1,000 less when boosted.
    • Compression is 10, less 1.25 per bar of boost.
    • The ports are the catalogue 13B's, scaled with the rotor.
    • Each face has two plugs. The ignition is the 13B's curve.
    • A diesel, a bore and stroke, a non-inline layout, a firing order, an H-pipe or an X-pipe (one bank), or more than 10 rotors is refused.
  • Catalogue: engines/18_mazda_13b_renesis_like.engine.yaml, a 13B-MSP high-power-class twin-rotor (Mazda: 184 kW at 8,500 rpm, 211 N.m at 5,500). Its port timing is Mazda's for the high-power primary port (service manual: intake 3 deg ATDC to 65 deg ABDC, exhaust 50 deg BBDC to 3 deg BTDC; Mazda Technical Review 21, 2003, gives the same exhaust and intake opening); its port areas are estimates, and its secondary and auxiliary ports are one equivalent port, not staged with speed. A rotary's cams take the switched profile (variable_profile_enabled, switch_rpm, high_*) on the face's 1,080 deg cycle, so a designed rotary can stage its ports; the catalogue's does not: Mazda's published port areas, staged, move 8,500 rpm by 0.4 % (journal 2026-11-01). Measured (DynoSweepHarness, WOT): 233 N.m at 5,500 (+10 %), 169 kW at 8,500 (-8 %), idle 801 rpm. Its torque is flat from 2,000 to 5,500 rpm and falls to 190 N.m at 8,500, where the real engine's variable intake keeps about 206. Its BSFC reads 245-278 g/kWh at lambda 0.9, 15-20 % above the catalogue K20's: the chamber's heat loss. A real rotary at full load is usually quoted above 300 (no measured map at a known speed was found): the petrol over-efficiency every engine shows, with no crevice or trailing-edge quench loss modelled.
  • 3-D view: each rotor is drawn in its epitrochoid housing, turning at a third of the shaft on the eccentric. Each face's flame rides its flank. Clicking a rotor shows its geometry and a face's live pressure; a rotor is resized by designing it again (the live bore and rod edits refuse it).

Injection and mixture

Injector flow depends on its nominal capacity and the square root of the pressure differential. For port injection, rail_pressure_bar is the differential pressure regulated against the manifold: flow therefore does not collapse under boost. For direct injection, it is an absolute rail pressure and the instantaneous cylinder back-pressure is subtracted.

  • With direct injection, fuel goes into the cylinder and its latent heat cools the charge according to the configured efficiency.
  • A diesel injects from the ECU's advance, which is its start of injection (deg BTDC, latched at the start of compression as a spark is), and never before the injection part's start_angle_deg. The ignition delay is Assanis et al.'s, tau = 2.4 phi^-0.2 p^-1.02 exp(2100/T) ms with a cetane correction, integrated (Livengood-Wu) from that start: the unburned fuel a cycle leaves in its residual is not integrated from mid-compression, which used to light every cycle before its own injection and needed a delay scale of 3 to land. The burn then has a premixed part and a mixing-controlled rest. The premixed part is the fuel that has mixed by autoignition: from the start of injection the injected fuel mixes at the diffusion burn's own rate (the mixing time below), so a long delay against a short injection premixes more. On the TDI it is ~26 % at idle and ~14 % at full load and 2,000 rpm, the direction of Watson's correlation (about half at light load, little at full load); it was a fixed 8 %. compression_ignition_mixed_premix: false restores a fixed compression_ignition_premixed_fraction of the fuel present at ignition.
  • On a diesel, the mixing-controlled burn (and the premixed burn, a fixed fraction of its time, and the premixing before ignition) is calibrated at the injector's rated pressure and scales with sqrt(rated / rail pressure): the jet's speed, which drives the mixing, goes as the square root of the pressure drop (Chmela and Orthaber). Halving the TDI's rail pressure at full load (3,000 rpm) lowers its firing peak from 136 to 123 bar with the injector capacity held.
  • With port injection, a fraction joins a persistent liquid film on the port. Its evaporation depends on temperature and a time constant: X 0.22 and about 0.6 s at a warm runner, the warmest tip-in of Curtis et al. (SAE 961186, lean x1.05 settling in ~1 s). The temperature is the runner gas's, not the port wall's that Curtis show sets the time constant; a cold port is therefore not slower here than a warm one at the same air temperature.

The commanded mass, the film, the vapour available at spark and the fuel actually consumed stay separate. A window that is too short, an undersized injector or a slow film therefore reduce the fuel actually burned.

With port injection, the pulse is sized once per cycle, at the first sub-step of the window: the charge's need, minus the film available before spark (X-tau) and the fuel of a chamber that misfired, divided by the share of the fresh pulse that is available. The port vapour is not credited: it is a stationary reservoir, not fuel for the next charge. During a fuel-cut resume the 60 mm footprint at the valve is balanced against its target both ways: a dry one adds to the pulse, a wet one (the film evaporating through the cut) comes off it.

Gas pushed back past the throttle is kept in the airbox (airbox_volume_l) and drawn back in first. Without an airbox, the fuel it carries is lost.

The reported AFR and lambda come from the trapped species. A per-cylinder corrector learns the transport losses of the previous cycle. Its bandwidth depends on the cycle duration and, with port injection, on the film's vaporisation constant; this avoids lambda hunting on big slow engines. The ECU tables set the AFR target and the advance as a function of engine speed and a normalised load; acceleration enrichment, cold start, temperature, knock and rev limiter apply after that.

Nitrous oxide

A kit (EngineConfig::nitrous, the nitrous section of an engine file, written only when fitted) is one nozzle behind the throttle: its liquid nitrous enters the plenum cells (split equally over the plenums) as the half mole of oxygen and the mole of nitrogen each mole decomposes into, so its mass and oxygen are exact, carrying its enthalpy less the latent heat of its evaporation (Watson, 376 kJ/kg at 184.7 K, (Tc - T)^0.38: 123 kJ/kg at 30 C, about 35 K off the charge). The 82 kJ per mole of its decomposition is released where it burns, in proportion to the share of the charge's oxygen that came from the kit (nitrousOxygenShare, the kit's oxygen rate over the kit's and the throttle air's, both smoothed over 0.15 s).

The jet passes nitrousMassFlowPerShotKw times the shot (2.27 kg/min per 100 hp) at the reference bottle pressure, 900 psi, as the root of the drop into the plenum. The bottle's pressure is nitrous's vapour pressure at its temperature (ln p[bar] = 10.552 - 1942/T); without the heater the vapour that replaces the liquid drawn cools it (its share rho_v / (rho_l - rho_v), the liquid's 2 kJ/kg K and the bottle's steel), and it warms back towards ambient at 1.5 W/K. It sprays armed (EngineControls::nitrousArmed), with the push button held when push_button (off on a new kit), past the minimum throttle and in the speed window, building over ramp_s. Each frame EngineState::nitrousBlockers holds one NitrousBlocker bit per condition not met (disarmed, button, ignition, throttle, below or above the speed window, empty bottle), so the Equipment window can say what it waits for.

The ECU sizes its pulse for the throttle air alone, the charge less the kit's share. A wet kit puts its own fuel into the plenum at its kit_lambda on the kit's oxygen and the fuel's stoichiometric ratio; a dry kit has the injectors add the same. The lambda loop holds its learning while the kit sprays, so a lean kit runs lean. The spark is retarded by spark_retard_deg_per_50hp per 50 hp of shot. Knock, peak pressure and breakage see the charge as it is. Not modelled: per-cylinder nozzles, the liquid's own transit in the plenum (it evaporates where it enters), the end of the liquid in the bottle (the vapour phase's lower flow).

Ignition, flame and knock

A spark is scheduled per cylinder. Before the kernel is born, an ignition delay depends on pressure, temperature, equivalence ratio and residuals. The laminar speed follows a Metghalchi-Keck type correlation; a closure based on mean piston speed adds turbulence, while dilution reduces speed and efficiency. The turbulence term grows with load up to a full cylinder and no further: the piston stirs the charge, not the intake pressure, so boost does not burn it faster.

A spark misfires at random, with a probability built from the mixture's distance to its lean and rich limits, cranking speed, and the charge's dilution: everything that is neither fresh air nor fuel at the spark (CylinderState::diluentFractionAtSpark). Dilution adds nothing below 0.60 and rises smoothly to the 0.92 cap by 0.70. This is what makes a two-stroke idle four-stroke: its idle traps 0.75-0.85 of burned gas, a misfire leaves a fresher charge behind, and a later cycle lights. The onset sits above the catalogue's most diluted four-stroke idle (CP4, 0.56), so four-stroke idles do not draw differently.

The current progression geometry is a cylindrical effective volume:

V_burned = π × radial_travel² × axial_travel

Both travels are bounded by the bore radius and the equivalent instantaneous chamber height. It is neither an ellipsoidal front nor a resolved 3D surface. The geometric fraction drives an absolute number of moles to react; the released energy uses the fuel's LHV and stoichiometry.

Knock follows the end gas, the charge the flame has not reached yet. From the seal it is its own zone, compressed isentropically by the cylinder pressure with real heat capacities (air, products and gasoline vapour, fitted to the ideal-gas tables). Its autoignition delay is Douaud and Eyzat's, fitted on primary reference fuels in a knocking engine, with their prefactor doubled:

tau = 35.4 ms x (ON/100)^3.402 x p[atm]^-1.7 x exp(3800 / T_unburned)

The prefactor is the constant users of this correlation recalibrate to their engine. With Douaud and Eyzat's 17.68 ms every catalogue engine with a knock limit, naturally aspirated ones included, held 4-13 deg of knock retard behind its own spark map, where a production map sits 0-3 deg from its limit; with 35.4 ms the maps hold 0-5 deg and 10 deg of advance over a map knocks.

A Livengood-Wu integral of dt/tau runs from the spark. When it reaches 1 while the flame burns, everything the flame has not reached autoignites at once and really raises the pressure in the cell. The pressure that gas adds burning at constant volume, (gamma - 1) x unburned share x charge energy / V, is the scale of the oscillation it starts; the knock intensity is that over 30 bar. The ECU's knock control retards in steps and gives the advance back slowly (ecu-tuning.md), so at full load an engine settles at its knock limit. Only knock above 0.45 (the diagnostics' "severe") adds damage, which lowers efficiency for good.

The correlation is global, not multi-species kinetics, and it over-predicts knock under boost: the Audi I5 knocks heavily at its maker's 2.5 bar even at the ECU's -10 deg floor, where the real engine (10:1, direct injection) holds it on 98 RON (journal 2026-10-22).

Each cylinder's firing peak is tracked at every physics sub-step and published once per cycle, when the cylinder opens into its gas exchange (EngineState::peakCylinderPressureBar, the highest over the cylinders). Above the engine's structural limit (peak_pressure_limit_bar; zero takes 120 bar naturally aspirated, 140 boosted, 200 for a diesel, the upper end of production designs) it adds damage as the square of the excess: 10 % over takes about 17 minutes to "damaged", 30 % about 2 minutes. The simulated full-load peaks of the Audi I5 ran above a real one (175 bar before the knock control held it), so it carries its own limit 10 % over that stock peak. The TDI fired 231 bar until its advance became its start of injection; it now peaks at 156-165 bar and runs under the diesel default.

Forced induction

The turbocharger follows a power balance: turbine minus compressor and bearing losses, integrated with the shaft inertia. The wastegate (or variable vanes) follows a proportional-integral boost controller that holds wastegate_pressure_ratio exactly: fully open 0.25 above it on the proportional term alone, integral time 0.5 s, frozen while the gate is saturated. Like an actuator spring set against the atmosphere, it holds a gauge boost: the ratio is the one at sea level (101.325 kPa), and in thinner air the ratio it allows rises so the gauge boost stays the same.

A supercharger is geared to the crank (supercharger_drive_ratio), and its boost is its machine's answer to the engine's draw. A Roots (supercharger_lobe_count > 0) carries supercharger_displacement_l per rotor turn; its clearances leak back, as orifices of fixed area, the displacement of 2,000 rotor rpm at a 50 kPa rise (about an Eaton M-series map: volumetric efficiency 0.80 at 10,000 rotor rpm, 0.50 at 4,000), and its bypass valve (supercharger_bypass_area_mm2, by default the throttle bores' area) opens with manifold vacuum, fully at 34 kPa. Its ratio is the one at which what it delivers, less leak and bypass, is what the engine draws (the draw taken in proportion to the outlet pressure), and its work is the displaced volume times the rise (no internal compression), which also heats the charge. Its boost therefore rises with speed as the leak's share falls, and at part throttle the bypass carries its air: a designed 1.6 four at 3,000 rpm holds 1.01 at 33-71 kPa of manifold pressure and absorbs under 0.1 kW, 4.2 kW at full throttle. The designer sizes it for its ratio at the redline (volumetric efficiency 0.9), geared to 14,000 rotor rpm there; the boost an engine reaches is then its own breathing's. No bearing, gear or belt friction is modelled. A centrifugal supercharger reads the turbocharger's map below at its geared speed, its design speed the full-boost speed through the drive; above it a regulator holds pressure_ratio (the Merlin's boost control).

The turbocharger's compressor head comes from a generic map scaled to its design point (Moraal and Kolmanovsky, SAE 1999-01-0908): the head coefficient against the flow coefficient, both relative to the design point, flat towards surge and falling to zero head at 1.5 times the design flow coefficient (choke). The design point is the wastegate ratio at compressor_design_mass_flow_kg_s, by default 100 m/s through an authored inducer, else the engine's air flow at 70 % of the redline. Since the wastegate holds the boost, the map only shows while the turbo spools. The compressor efficiency stays the authored constant: an efficiency island was measured further from the makers' torque figures (journal 2026-10-15).

Past its top speed line (maximum_shaft_speed_rpm, by default 1.3 times the design speed; the catalogue peaks at 1.07) a wheel's tips go transonic: its efficiency falls as (N / N_max)^-8, half at 9 % past it, on the shaft's work and on the charge's heating alike, so the shaft is held near the line however much energy the turbine brings. Under the line the efficiency is the authored one, bit for bit. A wheel held past it is damaged (wheelDamage, 2 x^2 per second, x the share past the line); at 1 it bursts: the shaft stops and the engine runs without boost until it is reset. Both show as ActiveLimit::turboOverspeed, and the 3-D view's turbo inspector shows the line (editable) and the damage. The shape of the collapse is a choice, not a fitted map (journal 2026-11-11): a real compressor map's speed lines bunch up towards choke there.

turbocharger_count (1 to 4) fits identical turbochargers, each with the areas, inertia and design flow authored for one. Each exhaust path's turbine face drives the one its turbocharger index names (by default the path's index modulo the count), and the face's share of that turbine is its share of that turbocharger's cylinders. The shafts run independently; their compressors feed one charge and are solved together every 0.25 ms: the common pressure ratio at which the flows their maps pass at their own speeds add up to the engine's draw. A turbocharger fed by fewer cylinders spins slower and passes less of the air, without any special rule.

compressor_surge (off by default) resolves the compressor duct and the charge in time, Greitzer's model (ASME J. Eng. Power 98, 1976): the duct's flow accelerates on the wheels' head over the charge's pressure (the inducer's area over an equivalent length of 0.4 m), and the charge (charge_volume_l, by default 1.5 times the displacement) fills with that flow less what the throttles and the blow-off valve pass. Below the surge line the head follows Moore and Greitzer's cubic: zero slope at the surge line, a shut-off head of 70 % of it at no flow, rising again for reversed flow. Left of its peak the head rises with flow, and that branch surges: a throttle shut on boost with no blow-off valve blows the charge back through the wheel in bursts, the flutter (a 2JZ shut at 4,000 rpm: 18 reversals in 1.3 s, about 13 Hz); its sound is the inducer's jet noise from the flow through the wheel, both ways. The held boost is the map's with or without it (1.8909 / 1.8909 on the 2JZ).

intercooler_effectiveness (0 to 0.95, default 0) takes that share of the compressor's temperature rise back out of the charge. The 2JZ, EJ25 and I5 author 0.7, as their real engines have one. Before the end gas could knock it gave them 19-29 % more torque than their makers' figures (journal 2026-10-15); now the knock control spends that margin and they land 7-13 % over (journal 2026-10-22).

The turbine lives in the exhaust gas network, as a restriction face (the same primitive as an individual throttle) on the single outgoing face of the first junction where all of a path's cylinders have met. The face opens to the turbine plus open wastegate area, times the path's share of the cylinders. Every pulse crosses it as an isentropic orifice fed by the collector's stagnation state; the turbine's share of the flow (its area over the total) gives up eta * cp * T0 * (1 - (p_out/p0)^((gamma-1)/gamma)) per kilogram, taken from the downpipe's energy, so the downpipe receives cooled gas and the shaft the work. The receiving side gets no jet momentum: the turbine took it, and the wastegate jet is dissipated in the housing. EngineLab.RestrictionFace checks the choked flow, the work against its isentropic ceiling, the energy balance and the cooling. The manifold therefore sits at turbine inlet pressure and the downpipe at turbine outlet pressure, pulse by pulse.

If a path has no such junction (a custom graph without a collector), the older model applies: every outlet is narrowed by the turbine and wastegate areas, and the shaft is driven from the peak exhaust pressure with a quasi-steady expansion. That expansion overstated the work, so the catalogue turbine areas were re-fitted when the turbine moved (2026-10-12, see docs/journal.md).

Fitting a turbo to any engine

sizedTurbocharger() (foundation, TurboSizing.hpp) sizes a turbocharger for an engine that has none, from scaling laws fitted to the four catalogue turbochargers (turbine area 0.028 mm² per litre and per redline rpm, full boost at 45 % of the redline, inducer from the square root of the air flow, rotor inertia from the inducer, design shaft speed from the tip speed the boost's head needs: 337 m/s at 2.3, the TDI-like's 39 mm wheel at 165,000 rpm, as the square root of the head, so a 162 mm marine wheel runs 46,400 rpm). The engine designer sizes its turbochargers with the same laws. The boost follows the compression ratio, as on a street conversion: 0.5 bar from 10.5:1, 0.7 from 9.5:1, 0.9 below, 1.3 on a diesel. The engine keeps its own ignition map, so a high-compression engine may knock at boost. The 3-D view's inspector fits it (or takes it off) from any exhaust component or from the turbo, and the engine restarts. Every engine with a collector gets the turbine face described above, one per path. A path with no junction (a single, the Big Twin's two pipes) gets it on the face out of the one pipe its ports open into, and the view bolts the turbo there. An engine with neither (the LS3's X-pipe) falls back to the older outlet model, whose shaft work is overstated, and the view does not draw it. A turbine fed by one cylinder takes each blowdown whole, so its wastegate is sized at 3.0 times the turbine area instead of 1.5 (a designed 0.5 L single held its gate fully open and read 2.2 for 1.56 at 1.5 times).

Exhaust

Each ExhaustPathConfig can hold a custom DAG. The physical compiler keeps tubes, resonators, mufflers, catalysts and outlets component by component as quasi-1D ducts; merges and splitters become finite junction volumes. Interfaces, valves and outlets exchange a common bidirectional Riemann flux. Pressures, temperatures, composition, flow and back-pressure therefore come from the conservative network and not from an equivalent 0D throat or collector. Without a graph, the historical geometry is first expanded into a compatible physical DAG. See custom-exhaust.md.

Cylinders use Woschni's instantaneous convective correlation rather than a constant conductance. A diesel adds its combustion term, C2 = 3.24e-3 m/(s K) times Vd Tr / (pr Vr) times the pressure above the motored one, extrapolated from the state at intake closing (n = 1.35): without it the TDI turned 51 % of its fuel into indicated work at full load (171 g/kWh). A spark engine keeps the motored term only: with the combustion term the lugged and launched engines the tests hold stall (journal 2026-10-23), and it is not measured there since. Intake ducts and every cell of the exhaust network have a metal wall with finite heat capacity. Internal exchange is integrated analytically and conserves gas + wall energy; only the explicitly accounted external convection rejects energy to the ambient. The model therefore never clamps EGT to hide excess energy.

The thermodynamic network and the audio renderer deliberately use two scales: a non-linear low-band mesh for flow/back-pressure, and a linear characteristic network for audible propagation. The instantaneous SI flow links the two at every mechanical sub-step. The outlet load is a passive radiation model; an IR is used only if it is explicitly provided. See thermoacoustic-architecture.md.

Intake runners can also define runner_plenum_diameter_mm. The historical runner_diameter_mm then designates the valve side and the new field the plenum side; zero keeps a constant area. Intake and exhaust share the same conservative conical discretisation (exact volume, local areas, friction and heat exchange computed with the local hydraulic diameter). The audio network carries a tapered runner as one delay line, so both its ends present the admittance of the cylinder of the frustum's volume, as each exhaust taper section does: a valve end at the inlet area beside a plenum end at the outlet area made the runner an amplifier (a compact 30-60 mm cone radiated 16 dB above its equal-volume cylinder at 150 Hz; audit A2-05).

individual_throttles: true puts one plate in each runner instead of one ahead of the plenum (motorcycle and racing throttle bodies). The plenum is then the airbox the runner mouths draw from, fed through the bores held fully open. Each runner becomes two 1-D ducts meeting at a restriction face, placed throttle_distance_from_valve_mm from the valve (zero: 55 % of the runner, a default not measured on any engine). The face is an isentropic orifice fed by the approaching cell's stagnation state, choked when it must be; the jet re-expands into the receiving duct against the pressure-loaded rest of the face, so the plate costs nothing fully open and its loss is the Borda-Carnot expansion otherwise. Each plate takes its share of the throttle, leakage and idle bypass area. The manifold pressure the ECU reads is the mean over the valve-side ducts (all their cells, all runners) through a 30 ms first-order tapping manifold; the cell right behind the plate reads the jet's low pressure and costs 10-19 % torque through a false load reading. A small 0-D cell per cylinder was tried first and refuted (.claude/CLAUDE.md).

An active exhaust valve (inlet_valve on a pipe, exhaust_valve for its actuator; custom-exhaust.md) is a face, not a duct. exhaustValveInterfaces lists the faces whose downstream end is a valved pipe's inlet, for both the gas network and the audio one. EngineSimulator::updateExhaustValve moves the stroke once a frame (automatic, shut or open, from EngineControls::exhaustValveMode) and gives the opening to the gas network before the turbine faces; below 1 the face goes through the restriction orifice at that share of its area, at 1 it is the plain face. The audio reads RealtimeAudioState::exhaustValveOpening once a block. EngineState::exhaustValveCount, exhaustValveStroke and exhaustValveOpening report it; without a valve they read 0, 1 and 1.

Engine temperatures

By default the thermal model is regulated (thermal.regulated): coolant and oil sit at regulated_coolant_c (90 degC) and regulated_oil_c (100 degC) from the start and never move, as a dyno cell's conditioning unit holds them. Every run, A/B switch and harness measurement is then made on a warm engine at one temperature, the state the recording protocol asks for. Unregulated (realistic, EngineThermalModel), both start at the ambient temperature. The coolant capacity stands for what a closed thermostat circulates (the water jacket and the metal around it), the oil exchanges heat with it through the block, and they take shares of the heat released by combustion (24 % and 5 % by default; Heywood gives 17-26 % to the coolant at full load) while the oil takes all the friction heat. A liquid-cooled engine sheds heat through a radiator its thermostat opens from 82 to 94 degC, in the air of its speed (EngineControls::coolingAirSpeedMps: the vehicle's speed, or 12 m/s of dyno cell fan on the dyno) and of an electric fan, on at 100 and off at 95 degC. An air-cooled one (liquid_cooled: false) sheds it through its fins, in the air of its speed and of its blower if it is driven by the crank (engine_driven_fan): a tenth of their design cooling always, the rest through an oil thermostat opening from 85 to 100 degC (the 911's opens its front cooler near 83 degC); its temperature stands for the oil's, as its gauge reads it. Unauthored sizes (0) follow the displacement: 14 kJ/K per litre plus 3 for the coolant side, a radiator that rejects the heat of the estimated rated power (9 kW per litre per 1,000 rpm of redline, more with boost) and its friction at 30 m/s and 65 K above the air. These are sizes for a plausible engine, not measured ones. The ECU enriches and retards a cold or hot engine from the coolant temperature. The switch is a settings edit, taken live.

Transmission and vehicle

DrivelineModel owns the clutch, gearbox shaft, differential, driven wheel and vehicle. Reverse, neutral and forward gears share a state machine with declutching, shifting, re-engagement and torque reduction.

The clutch is a dry brake with a stick/slip law (Karnopp), not a viscous coupling. Outside the clutch_lock_speed_rpm lock window, it slips and transmits its full capacity opposing the slip (kinetic friction, independent of the magnitude): that is what launches the vehicle and heats the disc. Inside the window, it sticks: crankshaft and input shaft form a single body, and their common acceleration is solved from both inertias, the engine's own torque and the reflected road load; the exact torque that holds synchronism follows from it. Since this is the solution of the constraint and not a steep slope, the reaction cannot overshoot over one step, so an engaged clutch holds the engine torque with a few rpm of residual slip instead of slipping endlessly. The capacity — bounded, then degraded by heating and fade — always limits it: beyond it, the clutch breaks away and slips. The wheel stays a degree of freedom separate from vehicle speed. Its slip generates a longitudinal force bounded by grip. The normal load on the driven axle responds to traction and to the quasi-static transfer m*a*h/L; forward acceleration loads a rear-wheel drive, unloads a front-wheel drive and keeps the total weight available for all-wheel drive. Drag, rolling resistance and brakes then dissipate the energy. The runtime sub-samples this coupling at 1 ms.

Shift styles

transmission.shift_style says how a change between two forward gears is made; neutral and reverse are always selected the manual way. It is a settings edit, taken live.

  • manual (default): the driver lifts (shift_torque_cut_fraction of the throttle) and dips the clutch over shift_duration_s; after the timer the torque comes back with the clutch slip, not the clock.
  • sequential: a dog box, clutch left in. With quickshifter (default on), an upshift cuts the ignition for quickshifter_cut_s (default 65 ms); the ECU cuts as its rev limiter does (spark, and fuel too unless ignition.limiter_keeps_fuel, in which case the unburnt charge reaches the exhaust). The dogs change after 15 ms (drum travel, not measured) and the clutch pulls the engine down to the new gear's speed while it makes no torque; a cut too short leaves the engine firing into the slip. With auto_blipper (default on), a downshift frees the dogs and opens the throttle (wide open until the last 15 % of the climb) until the engine reaches 98 % of the new gear's speed, at most 0.3 s, then engages. Without either device, that shift is made the manual way.
  • dual_clutch: an upshift hands the drive to the oncoming clutch at once, with no torque gap. Its pressure carries the engine's torque plus what pulls the engine down to the new speed over shift_duration_s. Under drive, the ECU retards the spark by up to dual_clutch_upshift_retard_deg (default 20°, taken off the mapped advance within its -10° floor) while the clutch pulls the engine down, and gives it back with the same speed-matched release as a manual shift's torque cut. The engine, making less torque, reaches the new speed sooner; the clutch's torque does not drop where it is already at its capacity (the 2JZ at 70-85 % of redline), so the push keeps its peak and is only shorter (journal). Production calibrations are not published: the 20° is a choice. Past the retard's floor the ECU also cuts injection on a share of the firings, dual_clutch_upshift_cylinder_cut (default 0.76, released with the retard): that is the "DSG fart". A Bosch ME7 asks for about 24 % of the torque during the shift and suppresses injection where the latest spark still leaves too much (NefMoto forum, "Launch control and DSG farts", one tuner's log). The simulator spreads the cut pulses over the engine as an error-diffusion sequence in firing order, each cylinder counting its own injection starts, decided at a cylinder's injection start for the whole cycle. The spark still fires, on air. A port injector's wall film still feeds a cut cylinder about a quarter of its charge, so it misfires lean (I5, 2026-11-06). A downshift is blipped as above. The clutch pedal is not connected: the gearbox runs its own launch clutch. At idle, foot off, it holds a creep torque (25 Nm, or 5 % of the clutch's capacity if lower), released on the brake. With the throttle open it closes with the engine's speed, fully at a launch speed that rises with the throttle to 38 % of the redline. It opens before the engine stalls, stays shut once in sync above 1.2 × idle, and opens again below 1.1 × idle. It fills in 0.10 s and dumps in 0.03 s (not measured). A downshift that would land the engine above the active rev limit goes only as far as the lowest gear that does not; a manual or sequential box lets the driver over-rev.
  • automated_manual: one clutch the gearbox works itself (an AMT: a Selespeed, an SMG, a truck's). It has the dual clutch's own launch clutch, creep and over-rev protection, and no pedal, but its upshift is the manual way, with the controller cutting for the driver: fuel and spark are cut at the start with the clutch still shut (whatever shift_torque_cut_fraction says: the driver's foot stays down, and a part cut flared the engine onto its limiter while the clutch was open), the clutch opens once the cycle's torque is gone (at most 0.15 s), the cut holds while it is open, a gap in the drive, then the torque comes back with the clutch's slip as it pulls the engine down to the new gear's speed. The controller changes up at the shift point itself (journal 2026-11-14). A downshift is blipped as above. The shift time is the gearbox's; the truck part's 0.8 s is an estimate, not a unit's figure.

Whatever the style, a shift started with the driver's clutch held out (pedal below half) is the driver's own: the gear changes at once and no device (torque cut, quickshifter, blipper) acts. Pulling the clutch during a blip ends the blip.

There is no dog-box engagement noise and no torque converter.

Engine brake (compression release)

engine_brake (EngineBrakeConfig), which the designer fits to a truck's four-stroke only, is a Jacobs-type brake. With its switch on (stage k of stage_count brakes the first round(k x N / stage_count) cylinders), the pedal under 2 % (engineBrakeMaximumThrottle), the ignition on and the starter off, it holds above minimum_rpm and takes hold again 100 rpm above it. A braking cylinder takes no fuel, and its exhaust valve gets an extra lift, a cos^2 bump of valve_lift_mm peaking peak_after_tdc_deg from firing TDC over duration_deg, added to the cam's in the gas solver (engineBrakeLiftMm). Real brakes open one valve: the lift is divided by the valve count so the curtain area is one valve's. The compressed charge blows down into the exhaust near TDC instead of returning its work on the expansion stroke. That drag and its sound are the solver's own: nothing is added to the torque or the audio. The runtime passes the switch through only in a gear (forward or reverse, not neutral), with the clutch at 0.9 or more and no shift under way (a real brake's clutch switch, and an AMT's release for the shift); in neutral a blip at rest would end in the brake's bark. The 3-D view draws the braking cylinders' extra exhaust lift (ScenePoseInput::engineBrakeCylinders). The dyno ignores it.

The designer's brake has a 2.0 mm lift (production brakes: about 1-2 mm), peaks at TDC (published: maximum lift near TDC), lasts 80 deg (estimated), lets go at max(1,000 rpm, idle + 400), and has three stages (Jacobs' switch: a six's 2, 4, 6). EngineLab.EngineBrake checks a designed 13 L six's brake at 2,100 rpm against a production brake's ~32 kW/L (416 kW on a 13 L, Jacobs) within 0.5-1.5 x (journal 2026-11-09). Not modelled: the valve train's compliance, the brake's oil-pressure delay on engagement, and an exhaust brake (a throttle in the exhaust).

Automatic shifting

With transmission.automatic_shifting (switched live with the Auto button or 8), ShiftSchedule chooses the gear from the driver's pedal, not the engine's throttle, so a blip or a torque cut does not move the points. The upshift point runs from max(2.2 × idle, 0.3 × limit) foot-light to 0.94 × the active rev limit flat out (automatic_upshift_rpm replaces the latter when set; a designed truck sets it at 1.05 x its peak power speed, at most 0.90 x redline), along pedal^1.5; the downshift point from 1.3 × idle (automatic_downshift_rpm) to 0.55 × the full-throttle upshift, which is the kickdown. An upshift must land above 1.15 × the downshift point and a downshift under 0.9 × the upshift point, so a gear it lands in is kept; a kickdown goes down several gears while the gear reached still lugs. It waits 0.8 s after any shift and never acts while the driver holds the clutch. The shape is a choice, not a fit to a production schedule. A change between two forward gears asked by the driver switches the gearbox back to manual; selecting first from neutral does not.

Continuously variable transmission

shift_style: cvt makes the gearbox a belt variator whose ratio runs anywhere between the first gear ratio (lowest) and the last (tallest); the selector has drive, neutral and reverse only (the UI shows D). VariatorControl holds the engine at a speed scheduled from the driver's pedal: max(1.5 × idle, 0.25 × limit) foot-light, 0.85 × the active rev limit flat out, along pedal^1.5, never under a centrifugal clutch's lock speed. The ratio moves toward the one that gives that speed at the current road speed, at most the whole range in 1.5 s (not measured), and goes back to its lowest whenever the start clutch is not holding. A car's or a scooter's mechanical balance (hydraulics; roller weights, spring and torque cam) is not modelled, only the engine speed it holds.

The moving ratio lives inside the clutch model: through a frame the ratio is interpolated over the 1 ms mechanical steps, and the stick constraint makes the crank follow the ratio's change (rate × wheel speed) and takes any slip out over 20 ms, so the clutch stays locked as the ratio moves. Gearboxes with fixed ratios are bit-for-bit unchanged.

It starts on its own clutch; the pedal does not reach it. A wet start clutch (default) is the dual clutch's launch clutch: it creeps at idle and stops on the brake. With centrifugal_clutch: true (a scooter's), the clutch is open at idle, bites at centrifugal_clutch_engage_rpm (0: 1.7 × idle) and is shut at 1.35 × that, a smooth step between. There is no torque converter. The parts car_cvt (2.5-0.4, final 5.0) and scooter_cvt (2.6-0.85, final 9.4) are typical ranges, not a specific unit's. Any gearbox can be switched to a CVT live from the gearbox inspector; the variator takes the gear's ratio.

Driver commands

DriverCommandArbiter (src/runtime) is the one place where the driver's pedals and the driveline's own devices become engine commands. Each public frame, advanceVehicle() gives the driveline the clutch the arbiter chooses (the driver's pedal; a dual clutch ignores it), advances it on the previous frame's engine state, then sets the engine throttle to max(driver x torque cut, blip) and passes a quickshifter's ignition cut through, and the engine brake's switch while a gear is engaged, the clutch is in and no shift is under way. It also records who held the throttle (driver, shiftTorqueCut or blipper). EngineRuntime, EngineLab.ShiftStyle and the shift, loaded-acceleration, afterfire and drive-scenario harnesses all step the vehicle through it, so they cannot drift from the product. The dyno bypasses it: the bench, not a driver, holds the engine.

The cruise control (CruiseControl) is a driver-side device: a PI on road speed (0.08 per m/s, integral 0.03) whose throttle joins the driver's pedal, the higher one winning, before the arbiter. It engages from 30 km/h at the throttle in use (no surge). Set while accelerating (or slowing), the integral then moves against the acceleration (0.6 per m/s2, filtered over 0.3 s) until the vehicle stops gaining or the driver's pedal overtakes: a set pressed during a hard pull peaks about 3 km/h over. Afterwards the integral holds while the speed is already returning faster than 0.1 m/s2, so a release of the pedal does not carry it past the set speed. (It once corrected at a fixed 0.5/s whenever 0.3 km/h off: the firing ripple made it hunt, journal 2026-11-05.) The brake, the clutch, neutral or falling under 0.6 × the set speed cancel it. The runtime merges it once per frame, so the driveline and the arbiter see the same inputs.

In vehicle mode, the runtime's external load (EngineRuntime::setLoad; the application keeps it at zero since it no longer has a Manual load control) is a longitudinal resisting force; it reaches the crankshaft only through the wheel, gearbox and clutch. In dyno mode, the brake acts directly on the crankshaft and the vehicle is decoupled. The two paths are never applied at the same time.

The balances publish stored energy, dissipated energy and residual. The model includes no suspension/pitch dynamics, no ABS, no detailed synchronisers and no full Pacejka; load transfer is a quasi-static longitudinal equilibrium.

Limitations and interpretation

  • two-stroke engines lose about a tenth of their full-load torque at the 100 mm real-time exhaust mesh against 25 mm cells (see Two-stroke engines);
  • 0D cylinders and plenums with 1-D finite-volume runners, without CFD or a 3-D flow at the port;
  • semi-empirical global reaction, turbulence, walls, blow-by, film and knock;
  • no spray, temperature field or 3D flame front;
  • multiple crankshafts linked by rigid ratios, without torsion of their own;
  • catalogue parameters not certified by a flow bench or an engine dyno;
  • power and torque useful for internal comparison, not for an engineering or tuning decision on a real vehicle.

The tests check invariants, finiteness, trends and regressions. They do not replace experimental calibration.