Simulation Engine

The POLARIS simulation engine is the core computational framework that orchestrates all agent-based models within the platform. It implements a parallel discrete-event simulation architecture that manages the creation, scheduling, updating, and destruction of all agents (persons, vehicles, traffic infrastructure, operators, etc.) throughout the simulation timeline.

Architecture Overview

The figure below illustrates the layered architecture of the POLARIS simulation engine, from the top-level simulation control through the central event dispatcher, to the two types of component managers and the parallel thread pool.

The simulation engine consists of several key components:

• Simulation Control: Manages the global simulation clock, start/end times, time-step configuration, thread management, and iteration control.

• Simulation Engine: The central event dispatcher that advances the simulation by processing scheduled events in temporal order.

• Scheduled-update objects: Agents that are updated at regular, scheduled time-steps (e.g., link traffic state updates, skim table refreshes). Each belongs to a scheduled-update manager that batches updates for parallelism.

• Discrete-event objects: Agents that respond to discrete events at irregular times (e.g., a vehicle arriving at a link endpoint, a person completing an activity). Each belongs to a discrete-event manager.

• Thread pool: The engine supports multi-threaded execution, distributing agent updates across available CPU cores for large-scale scenarios.

Discrete-Event Processing

At each simulation step, the engine performs the following:

1. Determine next revision: Identify the earliest scheduled event or execution update across all active component managers.

2. Step: Advance the simulation clock to that time and process all agents scheduled at that time.

3. Update: After processing, agents may schedule new events or update their next execution time, which feeds back into the revision schedule.

The engine uses a revision-based scheduling mechanism. Each agent maintains a revision marker (a combination of time-step and sub-step) indicating when it should next be processed. The engine selects the minimum revision across all active agents and advances to that point.

Locking and Thread Safety

Because multiple threads may attempt to update the global schedule simultaneously, the engine uses lightweight spin-locks to protect shared state. Any thread may propose an earlier revision, which the engine atomically accepts if it precedes the current next revision.

Component Managers

POLARIS distinguishes between two types of component managers:

Scheduled-Update Managers

These manage agents that are processed on a regular cadence (e.g., every simulation time-step). Examples include:

• Traffic link state updates

• Skim table updates

• Operator logging

Scheduled-update managers maintain a linked list of all agents of a given type and batch-process them in parallel.

Discrete-Event Managers

These manage agents that are triggered by discrete events at irregular times. Examples include:

• Vehicle entering/exiting a link

• Person starting/ending an activity

• TNC request arrival

Discrete-event managers allow agents to be activated and deactivated dynamically as events occur.

Multi-Threaded Execution

The number of parallel threads is configurable in the scenario file. Each thread processes a partition of agents independently. Thread-local storage is used where possible to minimize contention, and locks are used only for shared data structures (e.g., the global event queue).

The key scenario parameters controlling the engine are:

Parameter	Description
simulation_interval_length_in_second	Base time-step for traffic simulation
num_simulation_intervals_per_assignment_interval	Number of time-steps per reporting interval
simulation_start_time	Start of the simulation (seconds from midnight)
simulation_end_time	End of the simulation (seconds from midnight)
num_threads	Number of parallel simulation threads

Diagnostics

The engine can periodically dump core diagnostics (agent counts, event queue sizes, memory usage) for performance monitoring. The frequency of diagnostic output is configurable in the scenario file.

Important

Please refer to the the following paper for the foundational POLARIS framework:

Auld, J., Hope, M., Ley, H., Sokolov, V., Xu, B., Zhang, K. (2016). Polaris: Agent-based modeling framework development and implementation for integrated travel demand and network and operations simulations. Transportation Research Part C: Emerging Technologies 64, 101–116. https://doi.org/10.1016/j.trc.2015.07.017.