Configuration

The SimulationEngine accepts an options object to configure its behavior.


const sim = new SimulationEngine<Events, Store>({
  seed: 42,            // PRNG seed (default: Date.now())
  maxTime: 1000,       // stop at this simulation time (default: Infinity)
  maxEvents: 5000,     // stop after N events (default: Infinity)
  logLevel: 'info',    // 'debug' | 'info' | 'warn' | 'error' | 'silent'
  name: 'MySim',       // log prefix (default: 'Simulation')
  realTimeDelay: 100,  // ms delay between events in runAsync (default: 0)
  warmUpTime: 500,     // reset stats after this sim-time (default: undefined)
  stopWhen: (ctx) =>   // custom stop condition (default: undefined)
    ctx.stats.get('queue').mean > threshold,
  store: { ... },      // initial global store value (default: {})
});

Options Reference

Option	Type	Default	Description
`seed`	`number`	`Date.now()`	PRNG seed for reproducibility
`maxTime`	`number`	`Infinity`	Stop when simulation clock reaches this value
`maxEvents`	`number`	`Infinity`	Stop after processing this many events
`logLevel`	`LogLevel`	`'info'`	Minimum log level
`logger`	`SimLogger`	`ConsoleLogger`	Custom logger implementation
`name`	`string`	`'Simulation'`	Simulation name (used in log prefixes)
`realTimeDelay`	`number`	`0`	Delay in ms between events in `runAsync`
`warmUpTime`	`number`	`undefined`	Stats are reset when clock crosses this threshold
`stopWhen`	`(ctx) => boolean`	`undefined`	Custom stop condition evaluated after each event
`store`	`TStore`	`{}`	Initial value for the global simulation store

Warm-up Period

The warmUpTime option automatically resets statistics after a transient phase, useful for steady-state analysis. After the clock crosses warmUpTime, ctx.warmUpCompleted becomes true and all stats are reset.

Custom Stop Conditions

The stopWhen callback is evaluated after each processed event. When it returns true, the simulation ends with status 'stopConditionMet'. Useful for optimization, steady-state detection, and Monte Carlo convergence.

Simulation Result

run() returns a SimulationResult:


const result = sim.run();
 
result.totalEventsProcessed  // number of events handled
result.totalEventsCancelled  // number of cancelled events skipped
result.finalClock            // final simulation time
result.wallClockMs           // real-world execution time in ms
result.stats                 // Record<string, StatsSummary>
result.status                // 'finished' | 'stopped' | 'maxTimeReached' | ...
result.store                 // TStore — final state of the global store

Async Execution

For long simulations that shouldn’t block the Node.js event loop:


const result = await sim.runAsync();