Skip to main content

Determinism

clockwright is built so that a result is reproducible: the same model document, the same seed (replication number) and the same replication count always produce the same answer, down to the event. This page states what that promise covers. The mechanisms behind it are held back until release.

note

This is an overview. The design behind the guarantee will be published when clockwright is released.

What is guaranteed​

  • The clock is an integer. Simulated time is an i64 tick, never a floating-point number; tick_scale_per_second in a model document says how many ticks make up a second. A float clock makes event ordering rounding-dependent, which makes determinism itself untestable.
  • Every event has a total order. Events are ordered by more than their time, so two events at the same instant cannot have their order decided by an implementation detail of the queue they happen to sit in.
  • A run is reproducible across machines and builds for the same engine version and toolchain. A run also reports a trace hash: two runs agreeing on it agree on everything, which turns "did this change anything?" into one comparison rather than a diff of every KPI.

What it does not cover​

⚠️ A different engine version, a different rustc, or a changed model document may legitimately produce a different answer — and will say so rather than pretend otherwise. A checkpoint records all three. ⚠️ It refuses on the model hash only — the engine version and toolchain are recorded for you to check, not enforced at resume time (#116). A result carried across a toolchain change is not comparable with one from before it, and the result document records what produced it for exactly that reason.

Why it matters for a verifier​

An optimiser is only as trustworthy as the difference between two runs. If a KPI moves, that has to mean the change moved it — not that the two runs happened to draw different numbers. clockwright makes two variants paired by construction, so comparing them measures the change rather than the noise, and cwright compare reports how much of the variance the pairing actually removed instead of assuming it helped.

Next​