AutoForge/docs/simulation.md

15 KiB

Synthetic simulation definitions and state

Definition boundary

Vehicle-profile JSON remains the strict schema-v1 metadata contract. Endpoint addresses, implemented services, initial DTC state, static signals, response latency and deterministic faults live in a separate source-controlled SimulationDefinition, not in profile JSON.

The SyntheticDiagnosticExamples catalog contains two inventories:

  • autoforge.synthetic.test-truck revision 1: a synthetic engine controller, transmission controller and cabin/body controller.
  • autoforge.synthetic.orchard-cart revision 1: an alternate inventory with a custom experimental sensor-bridge role.

IDs, names, identities and declared configuration are intentionally synthetic. The truck has no-response configured for the transmission probe to demonstrate that expected inventory is not the same as actual discovery. The body module returns an explicit unsupported negative response to virtual DTC clear. The engine has one initial virtual DTC and supports virtual clear.

SimulationDefinition.ValidateAgainst requires the exact profile identifier and revision, one unique mapping for every profile module and matching role, name and supplied hardware/software/firmware/calibration identity. Endpoint addresses and module IDs are unique. Service identifiers must be known protocol v1 synthetic services; signal IDs, units, JSON values, DTC values and fault entries are validated. Profile capability/provenance declarations do not enable or prove a virtual service.

Definitions may advertise probe without read.identity. Discovery then retains the validated probe and its advertised services, marks identity as not attempted with an explicit reason, and does not synthesize identity from the matching profile entry. Expected endpoints, positive probes and identities verified against the selected profile are counted separately. Advertised read/clear services do not enable UI actions until runtime identity is verified.

Session state

Opening a new Simulation session creates independent DTC state for each virtual module from its configured initial values. A successful clear.dtcs response acknowledges the request but is not itself proof of a state change. The Application clear-and-verify use case issues a fresh read.dtcs request and reports success only for a valid empty readback. A nonempty readback remains visible and fails verification; timeout, cancellation, closed session, no-response or malformed/negative readback is explicit uncertainty, never verified success. An already-empty module can still verify successfully even when the acknowledgement count is zero. These semantics concern virtual in-memory state only; no physical write occurs.

An accepted clear changes only that module in that session. Opening a second session starts with the definition's original initial values. Reset explicitly closes the old session and opens a new one against the same exact profile revision/provider/configuration, thereby restoring initial state and starting a new trace. Closing releases the old transport and its trace/state. No profile metadata or another session is mutated.

Normal Application/UI consumers see state only through encoded diagnostic requests and typed responses. An internal simulation oracle is granted only to the IntegrationTests assembly so tests can independently assert clear/reset/ isolation behavior; it is not a public provider or application service.

Static signals

Signals are configured JSON values with a source module, identifier, unit and quality. In this example, engine speed is the fixed synthetic value 850 rpm, engine supply voltage is fixed at 12.6 V, transmission state is the string parked-static, and the body module reports a static synthetic door count. Replies carry the logical request tick and origin SYNTHETIC_STATIC.

These are reproducible fixture values, not dynamic model output, current sensor data, a vehicle capture, compatibility evidence or operational advice. Unknown values remain unknown. This static provider does not generate motion, fuel, road-load or scenario physics; those capabilities are isolated in the explicitly selected dynamics provider below.

Fixed-step dynamics configuration

The separate DynamicsConfiguration document is format version 1 and model version 1; it does not change profile schema v1. It binds an exact profile ID, revision, vehicle ID, engine/transmission module IDs and calibration references to explicit model parameters, initial conditions, and five ordered finite scenario phases. Configuration JSON uses exact camelCase member names, string scenario enums, and strict required/unknown/duplicate-member validation at every object level. Missing values are not defaulted. Input ranges include fixed steps from 0.01 to 0.5 s, mass 100-100,000 kg, wheel radius 0.05-2 m, drag area 0-20 m2, rolling coefficient 0-0.2, ambient density 0.1-2 kg/m3, gravity 1-20 m/s2, engine speed up to 12,000 rpm, 2-12 strictly descending positive forward gear ratios, and finite strictly increasing torque-curve points. Scenario speeds are bounded at 150 m/s and durations at 86,400 s; the cruise phase must be at least 300 s and return-idle at least 10 s. Initial conditions are copied and validated against the model and exact profile.

The sha256:v1:<lowercase hex> configuration identifier is SHA-256 over stable camelCase JSON serialization of the immutable configuration (the derived identifier itself is omitted). The catalog is in-memory. Import validates exact profile/module/calibration references before registration; export followed by import preserves the identifier. A diagnostic run ID is separate from this stable configuration fingerprint and is bound into its session identity. Reset closes the existing session and opens a new one with the exact original immutable configuration object, regardless of later catalog selections.

The explicit warmed example uses SI units internally:

Input Value
Fixed virtual step 0.1 s
Vehicle mass 1,800 kg
Wheel radius 0.34 m
Aerodynamic drag area (CdA) 0.68 m2
Rolling resistance coefficient 0.012
Air density / gravity 1.2 kg/m3 / 9.80665 m/s2
Drivetrain efficiency / final drive 0.9 / 3.6
Maximum brake force 10,000 N
Idle / warm target / maximum engine speed 650 / 650 / 5,000 rpm
Launch slip end speed 2.5 m/s
Idle fuel flow / fuel mass per joule 0.00045 kg/s / 1.2e-7 kg/J
Ambient / initial / equilibrium engine temperature 20 / 88 / 90 degC
Thermal response rate 0.015 per second
Forward gear ratios 3.5, 2.2, 1.4, 0.9
Upshift / downshift schedules 4,000 / 1,450 rpm per gear

Torque curve points are (rpm, N*m): (650,240), (1000,300), (2000,360), (3200,350), (4200,300), (5000,180). Torque is linearly interpolated between points and held at endpoint values outside the curve. Automatic shifts use the configured schedule and hysteresis; launch coupling slip is limited to first gear below the configured launch speed. When locked, reported engine speed follows

engineRPM = speed_mps / (2*pi*wheelRadius_m) * 60 * gearRatio * finalDrive.

The launch torque-transfer factor is speed-based and is not the reported slip fraction. Reported slip is the normalized engine/wheel RPM discrepancy, so it cannot claim zero slip when those speeds differ. Wheel force is engineTorque * gearRatio * finalDrive * efficiency / wheelRadius * couplingFactor. Rolling and aerodynamic loads are m*g*Crr and 0.5*rho*CdA*v^2; brake force is configured maximum force times brake ratio. Longitudinal acceleration is (wheelForce - roadLoad - brakeForce)/mass. Each fixed step updates speed using forward Euler with a zero lower bound; distance uses trapezoidal integration of the old/new nonnegative speed. Scenario controllers adjust bounded throttle/brake commands but never assign vehicle speed.

An initial running in-gear condition is supported only when engine RPM equals the wheel/gear-derived RPM within 1e-8 rpm and remains within the engine limits. The initial-condition contract does not invent an unprovided clutch-slip input. Scenario targets and initial speed must also fit the top-gear redline envelope:

maximumEngineRPM * (2*pi*wheelRadius) / (60*topGearRatio*finalDrive).

The engine does not independently clamp RPM while keeping an unchanged, contradictory wheel speed. The phase throttle is instead bounded to the target speed/redline envelope for each fixed step. Inputs outside the documented envelope fail validation rather than producing healthy contradictory telemetry.

Fuel power is torque * engineAngularVelocity; fuel rate is idle flow plus nonnegative power times the configured mass-per-joule coefficient. Fuel and distance integrate from the fixed step. Engine-off RPM/fuel are zero. The thermal approximation is a first-order response toward the greater of ambient and configured equilibrium temperature, with a bounded additional target increase from modeled power; it is not coolant-flow or component simulation. All model state is checked for finiteness/domain violations and a failed run is explicitly marked Faulted. An arithmetic/domain failure rolls state and samples back to the last valid fixed-step snapshot before publishing the terminal reason.

Configuration import converts unavailable profile/revision, missing module and calibration-conflict references to the typed configuration-validation error contract. Validation precedes catalog registration; a rejected import preserves the selected configuration and any active run binding.

The ordered baseline scenario has 10 s warm idle, acceleration to 20.1168 m/s (45 MPH) with a 60 s maximum, a full 300 s target-speed hold, braking to 0.1 m/s with a 60 s maximum, and at least 10 s stationary return-idle. Headless stepping uses virtual steps only. RunScenarioAsync has an optional real-time pacer; 0.25x-1000x changes delay scheduling only, not the numerical step. Start, pause, resume, stop, reset, and explicit stopped/paused stepping are serialized. Diagnostic reads never advance model state. The numerical test independently checks the 650 +/- 5 rpm idle gate, 45 MPH <=60 s with shift activity, all 3,000 cruise samples with >=95% inside +/-0.44704 m/s, coupled cruise RPM relation, braking/return-idle limits, finite/nonnegative monotonic fuel, and exact same-input sampled-state reproducibility. Exact run outputs are recorded in the Step-04 worker report.

Overall scenario progress is cumulative elapsed scenario time divided by total configured phase duration; completed phase duration is retained across phase transitions. Current-phase progress is elapsed time divided by that phase's configured duration and is displayed separately. Both are bounded to [0,1]; reset starts both at zero and successful completion sets both to one. A missed phase target by its deadline ends in Faulted with the phase and reason preserved. Faulted dynamic signal reads return protocol-v2 negative response DYNAMICS_RUN_FAULTED, not a positive Good snapshot. The UI preserves the failure notice and clears previously good telemetry rows so they are not mistaken for a current healthy sample.

Each running controller owns one cancellable advancement task. Start/resume performs the first fixed step and then waits on the configured pacer; pacing changes delay only. Pause, stop, reset and dispose cancel and await that owner before returning, so a pending delay cannot advance a stale session. The simulation project exposes a narrow IDynamicsPacer seam for deterministic controlled-scheduler tests; it is not a general clock framework. UI operations also guard session/run generations after awaits. A stale open/reset/run result is discarded and disposed rather than published into a later session.

Start and resume validate that no prior advancement owner remains active or is settling before changing lifecycle state. If pause, stop or reset has cancelled an owner but its cleanup has not completed, a concurrent start/resume is rejected immediately with an explicit error and leaves lifecycle, model time, step, progress, configuration and ownership unchanged. The caller can retry after the cancelling operation completes. The command gate is not held while waiting for runner cleanup, so the owner can finish its cleanup path.

Static versus dynamic diagnostic providers

The existing autoforge.simulation.synthetic provider remains the static protocol-v1 baseline, including its fixed 850 rpm engine signal, original fault behavior and original tests. Dynamics is a separate autoforge.simulation.dynamics factory requiring OpenDynamicsAsync and an exact selected configuration; the static-open path cannot acquire dynamics controls. It exposes only the configured engine and transmission endpoint map. The engine and transmission telemetry are both snapshots from the same thread-safe engine state. While paused/stopped, reads across modules preserve the step/time; while the runner is active, each response advertises its actual sample step/time rather than pretending multiple requests are simultaneous. Each dynamic signal carries source module, unit, quality, SYNTHETIC_DYNAMIC origin and model/config/run metadata. Diagnostic capture ticks remain separate from the model clock. See protocol v2 for wire fields and strict validation.

The /simulation route requires explicit profile revision, dynamics provider and configuration selection. User-triggered example creation/import does not open or start a run. Controls and JSON interchange coordinate through Application; the telemetry table calls the actual protocol client, not the engine API. Values are synthetic behavior, not firmware, calibration, safe tuning guidance, validated manufacturer prediction or physical vehicle data. The route also hosts the shared configurable dashboard. It reads the same session-bound v2 source and reports per-response model step/time separately from diagnostic request ticks; polling and rendering do not advance the fixed-step model. Scenario target speeds and decoded numeric telemetry use the shared Imperial (US)/Metric display preference; each decoded row retains its exact source value and unit beside the display projection. Scenario definitions, configuration JSON, SI model state and fingerprints are unchanged. Static trace payloads and configuration interchange are source data, not converted output. See the live dashboard guide for mappings, preference persistence/error handling, editor range policy and freshness contract.

Reproducible faults and lifecycle

VirtualModuleDefinition accepts a validated fault map keyed by a defined synthetic service, plus non-negative logical response latency. Fault modes are:

  • NoResponse: no response payload arrives.
  • Latency above the protocol deadline: explicit Timeout, no response payload.
  • MalformedResponse: response bytes are retained but protocol decoding fails.
  • WrongCorrelation: response does not match request correlation.
  • WrongIdentity: identity reply names an unexpected module.
  • HoldUntilCancelled: pending transport work completes only on request cancellation or session close.

Fault maps are data, not random scheduling. The default truck definition reproducibly demonstrates a missing transmission probe response; tests construct other explicit vectors and assert their exact outcomes and trace records.

There is no physical/replay provider in this implementation. The Simulation provider will reject unknown or incompatible profile revisions and target selection does not automatically open an operational session. No simulation state is persisted beyond the current process/session.