Simulation Mechanism: Details

The below is further details on the mechanism and program structure with reference to the code elements.

Deepwiki is also available. I have checked its contents, and it looks mostly okey.

Overall Structure

UXsim is built upon several core classes that represent different elements of a traffic network:

  • Node: Represents intersections or junctions where vehicles can enter, exit, or transfer between links.

  • Link: Represents road segments connecting nodes, modeling traffic flow dynamics.

  • Vehicle: Represents individual vehicles or platoons moving through the network.

  • RouteChoice: Handles route choice computations, allowing vehicles to select routes based on current traffic conditions.

  • World: The simulation environment that contains all nodes, links, vehicles, and manages the simulation execution.

  • Route: Represents a specific path (sequence of links) through the network.

Node Class

The Node class models intersections or junctions in the network. Each node has:

  • Position: Coordinates x and y for visualization.

  • Signal Control: Nodes can have traffic signals, specified by the signal attribute, which is a list representing signal phases (e.g., [60, 10, 50, 5] for four phases with respective durations in seconds).

  • Flow Capacity: Optionally limits the number of vehicles that can pass through the node (flow_capacity).

  • Vehicle Management:

    • Generation Queue: A queue (generation_queue) for vehicles waiting to enter the network.

    • Incoming Vehicles: A list (incoming_vehicles) of vehicles requesting to move to another link via this node.

  • Methods:

    • signal_control(): Updates the signal phase based on elapsed time.

    • flow_capacity_update(): Updates the remaining flow capacity at the node.

    • generate(): Moves vehicles from the generation queue onto outgoing links if possible.

    • transfer(): Manages vehicle movements between incoming and outgoing links, considering signal phases and capacities.

    • update(): Calls necessary update methods each simulation step.

Vehicle Class

The Vehicle class represents individual vehicles or platoons. Key features include:

  • Trip Details:

    • orig and dest: Origin and destination nodes.

    • departure_time: Scheduled time for the vehicle to start its trip.

    • arrival_time and travel_time: Recorded upon trip completion.

  • State Management:

    • state: Current state, such as “home”, “wait”, “run”, or “end”.

    • flag_waiting_for_trip_end: Indicates if the vehicle is ready to end its trip.

  • Position and Movement:

    • link: Current link the vehicle is on.

    • x: Position along the link.

    • v: Current speed.

    • lane: Assigned lane on multi-lane links.

    • leader and follower: References to adjacent vehicles for car-following behavior.

  • Route Choice:

    • route_pref: Preferences for choosing links based on route choice principles.

    • route_next_link: Next link the vehicle intends to take.

    • route_choice_principle: Strategy used for route selection (e.g., “homogeneous_DUO”).

  • Methods:

    • update(): Updates the vehicle’s state and position each simulation step.

    • end_trip(): Handles trip completion procedures.

    • carfollow(): Implements car-following logic to update position and speed.

    • route_pref_update(): Updates route preferences based on traffic conditions.

    • route_next_link_choice(): Chooses the next link to traverse.

RouteChoice Class

The RouteChoice class manages the route selection process for vehicles:

  • Shortest Path Computation:

    • route_search_all(): Computes shortest paths between all node pairs using Dijkstra’s algorithm.

  • Route Preference Update:

    • homogeneous_DUO_update(): Updates link preferences based on the Dynamic User Optimum (DUO) principle, promoting routes that minimize travel times.

World Class

The World class represents the entire simulation environment:

  • Global Parameters:

    • DELTAT: Simulation time step width, calculated from reaction time and platoon size.

    • REACTION_TIME and DELTAN: Driver reaction time and platoon size.

    • Route choice parameters like DUO_UPDATE_TIME, DUO_UPDATE_WEIGHT, and DUO_NOISE.

  • Data Structures:

    • Lists of NODES and LINKS.

    • Dictionaries for VEHICLES, VEHICLES_LIVING, and VEHICLES_RUNNING.

  • Scenario Management:

    • Methods like addNode(), addLink(), and addVehicle() to build the network and populate it with vehicles.

    • finalize_scenario(): Prepares the simulation by setting time limits and initializing components.

  • Simulation Execution:

    • exec_simulation(): Runs the simulation loop, updating all components each time step.

    • simulation_terminated(): Handles post-simulation tasks like data analysis.

  • Utility Functions:

    • Methods to get nodes or links by name (get_node() and get_link()).

    • Functions to load and save scenarios.

    • Visualization tools like show_network().

Computation Procedure

The simulation in UXsim advances in discrete time steps, updating the state of vehicles, links, and nodes at each step based on predefined models and parameters.

  1. Initialization:

    • Define the simulation parameters and create a World instance.

    • Add nodes and links to build the network.

    • Populate the network with vehicles, specifying origins, destinations, and departure times.

    • Finalize the scenario with finalize_scenario().

  2. Main Simulation Loop (`exec_simulation()`):

    • Time Advancement: The simulation progresses one time step (DELTAT) at a time.

    • Link Updates: Each link updates its capacities and traffic state.

      • in_out_flow_constraint(): Manages inflow and outflow capacities.

      • set_traveltime_instant(): Updates instantaneous travel times.

    • Node Operations:

      • Nodes generate vehicles from their queues with generate().

      • Signals are updated via signal_control().

      • Vehicles are transferred between links using transfer().

    • Vehicle Updates:

      • Each vehicle updates its position and state with update().

      • Movement is calculated using carfollow() based on car-following models.

      • Route choices are made at nodes using route_next_link_choice().

    • Route Choice Updates:

      • At intervals defined by DUO_UPDATE_TIME, the route choice model updates vehicle preferences.

      • Shortest paths are recalculated with route_search_all().

      • Preferences are adjusted using homogeneous_DUO_update().

    • Data Logging:

      • Vehicles record their positions and states for analysis.

      • Traffic state data is collected for links and nodes.

  3. Termination:

    • The simulation ends when the maximum time is reached or all vehicles have completed their trips.

    • simulation_terminated() is called to perform any final calculations or data processing.

Traffic Flow Model Details

Fundamental Diagram Parameters

Each link uses a fundamental diagram to model traffic flow, characterized by:

  • Free Flow Speed (u): Speed under uncongested conditions.

  • Jam Density (kappa): Maximum density when the link is fully congested.

  • Reaction Time (REACTION_TIME): Affects the time step and driver response.

  • Derived Parameters:

    • Wave Speed (w): Speed at which congestion waves move backward.

    • Capacity (capacity): Maximum flow rate of the link.

    • Critical Density (k_star): Density at which flow reaches capacity.

    • Minimum Spacing (delta): Minimum distance between vehicles.

These parameters influence how vehicles accelerate, decelerate, and interact on the link.

Multi-Lane Modeling

  • Single-Pipe Approach: Even with multiple lanes, the link is treated as a single entity for flow calculations.

  • Lane Assignment:

    • Vehicles have a lane attribute to represent their lane.

    • No explicit lane-changing behavior is modeled.

  • Car-Following Behavior:

    • Vehicles adjust their speed based on the distance to the vehicle ahead in the same lane.

    • The carfollow() method implements this behavior.

Capacity and Bottlenecks

  • Inflow (`capacity_in`) and Outflow (`capacity_out`) Capacities:

    • Limit the number of vehicles entering or exiting a link.

    • Can model real-world bottlenecks like narrow bridges or toll booths.

  • Node Capacities:

    • Nodes can have a flow_capacity limiting throughput.

    • Signals at nodes further control vehicle movements.

Signal Control at Nodes

  • Signal Phases:

    • Nodes with traffic signals have defined phases, each with a duration.

    • Vehicles can only proceed if their link’s signal_group matches the current signal_phase.

  • Signal Timing:

    • The signal_control() method updates the current phase based on elapsed time and the signal schedule (signal attribute).

  • Impact on Vehicle Transfer:

    • Signals influence the transfer() method, determining whether vehicles can move between links.

Route Choice Modeling

Vehicles make route choices based on current traffic conditions, aiming to minimize travel times.

  • Dynamic User Optimum (DUO):

    • Vehicles periodically update their route preferences to follow the shortest paths.

    • The RouteChoice class computes these paths and updates preferences.

  • Stochasticity:

    • A small noise factor (DUO_NOISE) is added to travel times to prevent ties and promote variability.

  • Preference Updates:

    • Vehicles adjust their route_pref attributes based on updated shortest paths.

    • Gradual updates can be enabled to smooth transitions.

Key Inputs for Simulation

To set up a simulation in UXsim, the following inputs are essential:

  • Network Definition:

    • Nodes: Positions (x, y), signal settings, flow capacities.

    • Links: Start and end nodes, physical attributes (length, number_of_lanes), traffic flow parameters (free_flow_speed, jam_density), capacities, and signal groups.

  • Vehicle Demand:

    • Origin and destination nodes for each vehicle.

    • Departure times.

    • Route preferences or specific route choice principles if deviating from the default.

  • Global Simulation Parameters:

    • Time step settings (REACTION_TIME, DELTAN).

    • Route choice parameters (DUO_UPDATE_TIME, DUO_UPDATE_WEIGHT, DUO_NOISE).

    • Simulation duration (TMAX) if not automatically determined.

Program Structure and Workflow

  1. Initialize the World: - Create a World instance with desired global parameters.

  2. Define the Network:

    • Add nodes using addNode().

    • Add links using addLink().

  3. Specify Vehicle Demand:

    • Add vehicles individually using addVehicle().

    • Or use demand functions like adddemand() for bulk additions.

  4. Finalize the Scenario:

    • Call finalize_scenario() to prepare for simulation.

    • This sets up internal structures and calculates any derived parameters.

  5. Run the Simulation:

    • Execute exec_simulation() to start the simulation loop.

    • Can specify until_t or duration_t to control simulation length.

  6. Analyze Results:

    • Use built-in analysis tools in Analyzer or access logs from vehicles and links.

    • Visualization functions like show_network() help display results.