The execution model#
OSDL Core defines what an engine's execution must look like from the outside: event ordering, entity custody, state publication, run completion, recorded results, and portable events. It deliberately does not prescribe an architecture. Any calendar representation, callback layout, or programming language is conformant if the observable behavior matches.
One clock, one ordering#
Every run has one simulation clock. Scheduled work is ordered by time, with ties broken by insertion sequence, and there is no user-controlled event priority.
That single rule carries the whole system. Discrete events, agent transitions, and integration boundaries for continuous dynamics are all entries on the same calendar, which is why a hybrid model needs no co-simulation glue.
Timers have identity: a component schedules one at a relative delay or absolute time, and can cancel or reschedule it by identifier. Engines must reject non-finite times, negative delays, and times in the past.
Entities move under escrow#
When a component sends an entity, the engine takes the entity into escrow, assigns the transfer a persistent identity, and delivers it to the receiver at the current simulation time. The receiver decides:
accept: the entity moves atomically and the engine emitsentity.moved.block: the entity stays in engine escrow and custody remains with the sender. A full bounded queue is one reason to block.
When the receiver later reports readiness, blocked transfers are redelivered oldest first. Engines must not lose, duplicate, or substitute entities. The full protocol is in section 6 of the specification.
A run is a pure function#
A run is determined by five inputs: the document, the experiment, the parameter overrides, the seed, and any admitted external inputs. Within an engine version, replaying that tuple is bit-exact.
Randomness does not weaken this. Replication r of sweep scenario s draws from an RNG stream derived deterministically from the seed, and the sampler algorithm for each distribution is pinned by the specification, down to its draw count.
Every run ends with a report#
Each terminal execution path produces one run report: status, final time, recorded results, the available trace, and diagnostics. Status is one of:
| Status | Meaning |
|---|---|
| Completed | Normal completion, with a reason: the end time was reached, a stopWhen condition fired, a component requested completion, or the calendar went quiet. |
| Failed | A semantic model or component failure, carrying a structured diagnostic with a stable code. |
| Aborted | A host or policy outcome, such as cancellation or an exceeded budget. Not a semantic failure. |
Alongside the report, engines emit a typed event stream: lifecycle, entity, state, and library events in one envelope format. Telemetry events are excluded from cross-implementation comparison; the rest are the portable record of what the run did.
Read more#
- Execution semantics in the specification.
- The reference machine: the executable definition of these semantics.
- Paradigms on one calendar: how DES, ABM, and SD share this kernel.