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-truckrevision 1: a synthetic engine controller, transmission controller and cabin/body controller.autoforge.synthetic.orchard-cartrevision 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. See the live dashboard guide for its editor 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.