Optimistic parallel discrete-event simulation on the BEAM.

The engine handles every Time Warp mechanic — speculative execution, rollback, anti-messages, GVT, fossil collection. A domain author implements only TimeWarp.Model.

ids = [:a, :b, :c, :d]

{:ok, sim} =
  TimeWarp.start_run(
    model: TimeWarp.Examples.PHOLD,
    lps: Map.new(ids, &{&1, %{ids: ids, max_delay: 10}}),   # lp_id => init_args
    seed: 42,
    until: {:vtime, 1_000},
    init_events: for(i <- 0..7, do: {Enum.at(ids, rem(i, 4)), i, :ping}),
    gvt_interval_ms: 50,
    # A binding window is the only bound on retained state — see the warning
    # below. PHOLD is all-to-all and does not bound on its own.
    time_window: {:vtime, 20},
    check_purity: false,         # the purity divergence detector
    thrash_guard: nil            # or {rollbacks_per_s, window_ms}
  )

{:done, _} = TimeWarp.await(sim)
report = TimeWarp.report(sim)

Options

• :model — a TimeWarp.Model implementation (required).
• :lps — %{lp_id => init_args} (required).
• :seed — integer seed for per-LP PRNGs (default 0).
• :until — {:vtime, t} run horizon, or :infinity (default).
• :init_events — [{target, at, payload}] genesis events kicking off the run.
• :gvt_interval_ms — wall-clock cadence of GVT cycles (default 50).
• :check_purity — run the double-call purity probe (the divergence detector, default false).
• :thrash_guard — {rollbacks_per_s, window_ms} thrash circuit breaker. Off by default. Note it brakes on rollback rate, which is not the same as retained state — see the retention warning below.
• :time_window — {:vtime, W} to bound optimism to [GVT, GVT+W], or :none (default). Deadlock-free (the effective bound is max(GVT+W, global_min_event)). W trades parallelism for conflict, not a free storm fix, and it is also the only bound on retained state — see both notes below.

• :cancellation — :aggressive (default) | :lazy. Lazy suppresses an anti-message when re-execution re-emits an identical event; it only pays on models whose straggler-path events are PRNG-free (see TimeWarp.Model — it is inert and can amplify the storm on random models like PHOLD).

• :placement — %{lp_id => node} pinning LPs to nodes. Static, no migration; an LP not listed runs on the local node. LPs are addressed by pid, so a remote LP is mechanically identical to a local one and the straggler protocol is unchanged.

• :gvt_mode — :mattern (default) | :freeze. Mattern's colored-message algorithm is authoritative. :freeze is the earlier stop-the-world computation, kept as the test oracle and as the single end-of-run termination confirmation; it is not a steady-state path.

• :lp_call_timeout — milliseconds, default 5_000. Timeout for the Coordinator's own calls into LPs (:dump behind report/1, :gvt, the freeze-confirm poll). These execute inside the Coordinator process and an LP may be remote, so exceeding this does not fail one call — it fails the run. Raise it for high-latency links or large per-LP state.
• :quiescence_timeout_ms — milliseconds, default 1_000. Ceiling on the freeze-confirm quiescence poll; exceeding it raises, meaning in-flight messages are not settling. The workable value scales with link latency, so a distributed run legitimately needs more than a local one.
• :net_delay — test-only. Artificial per-message delay in milliseconds, used by the suite to characterize behaviour under inter-node latency. Not a production knob.