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.

Link Class

The Link class models road segments connecting nodes and handles traffic flow dynamics. Key attributes include:

• Connectivity: start_node and end_node defining the link’s direction.

• Physical Attributes:

  • length: Length of the link in meters.

  • number_of_lanes: Number of lanes on the link.

  • merge_priority: Priority level when merging at nodes.

• Traffic Flow Parameters:

  • free_flow_speed (u): Speed vehicles travel at under uncongested conditions.

  • jam_density (kappa): Maximum vehicle density under congested conditions.

  • Derived parameters like tau, w, capacity, delta, and k_star are calculated based on the fundamental diagram of traffic flow.

• Capacity Constraints:

  • capacity_in: Maximum rate vehicles can enter the link.

  • capacity_out: Maximum rate vehicles can leave the link.

• Signal Group: signal_group determines which signal phases affect the link.

• Vehicle List: vehicles stores vehicles currently on the link.

• Methods:

  • in_out_flow_constraint(): Updates inflow and outflow capacities.

  • set_traveltime_instant(): Calculates instantaneous travel time.

  • update(): Updates the link state each simulation step.

  • Getter methods for speed, density, flow, num_vehicles, and num_vehicles_queue provide real-time traffic information.

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.