Verifying determinism and replay in WareMax
How WareMax guarantees byte-identical trajectories: a ChaCha8 RNG, canonical id-based tie-breaking, and single-threaded runs. A tested property.
Reproducibility in WareMax is enforced, not asserted. This guide explains the mechanism and how to verify it yourself.
The three ingredients
- Seeded RNG. The core seeds a ChaCha8 RNG from a
u64. No wall-clock, no thread IDs, no address-dependent hashing enters the random stream. - Canonical tie-breaking. Everywhere two choices are otherwise equal — inventory placement, station and charging-station selection, every heuristic policy — WareMax breaks the tie by entity id, not by iteration order.
- Single-threaded per scenario. The simulator advances one event queue on one thread, so there is no cross-thread race to reorder events.
Why this matters
A “seeded” simulator that iterates over a HashMap silently reorders events between
runs. WareMax fixed several such latent bugs — for example in inventory placement and
heuristic tie-breaking — that had made prior “seeded” results, in fact, irreproducible.
Verify it
waremax run scenario.yaml --out run-a/
waremax run scenario.yaml --out run-b/
diff -r run-a/ run-b/ # identicalThe determinism tests live in waremax-rl/tests/determinism.rs. The RL control loop
adds a crossbeam ping-pong handshake so the property survives a worker thread.
Related: reading delay attribution · reproducible RL research. Built by Skelf Research.
Frequently Asked Questions
Is determinism actually guaranteed, or just usually true?
It is a tested property. Same seed plus same action sequence produces a byte-identical trajectory, enforced by tests in waremax-rl/tests/determinism.rs. The project fixed several latent HashMap-iteration-order bugs that had previously made seeded results silently irreproducible.
Does determinism survive the RL worker thread?
Yes. The RL control loop uses a strict crossbeam ping-pong handshake between the worker thread and the agent, so exactly one side runs at a time and the trajectory stays reproducible.