Simulation foundations ---------------------- As an agent-based simulator, ``METS-R SIM`` consists of mainly two types of classes: the agent named by the component (e.g., Vehicle, Lane, Junction) and the container of a group of agents, named by ``[agent_class]Context`` as shown in the following figure. The simulation starts by initializing a ``ContextCreator``, in which the ``subContexts`` are built. For the components (e.g., Zone, Road, Signal) that need to be updated over time, a ``step`` function is provided. .. figure:: res/source_files.png :alt: Simulation source files Simulation source files EV charging module ~~~~~~~~~~~~~~~~~~ In ``mets_r.facility.ChargingStation``, we implemented the charging station class for the first come first serve charging services, which contains the queue structure: both the Level 2 (L2) and Level 3 (L3) charging queues are considered. In general, L3 charging is faster than L2 charging, and they are both adopted in current electric vehicle operation. Each charging station receives the electric vehicles and joins these vehicles into the corresponding charging queues based on the calculated utility. For electric vehicles inherited from ``mets_r.mobility.ElectricVehicle``, their searching strategy of the charging station is defined in the ``goCharging`` function. For EV taxis and EV buses, they would reroute to the closest charging station to charge themselves. After finishing the charging, ``finishCharging`` will be called to load the latest trip schedule. Ride-hailing operation module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A zonal-level ride-hailing service is implemented in ``mets_r.facility.Zone`` and ``mets_r.mobility.ElectricTaxi``. Within each zone, the passengers/vehicles matched using a first-come-first-serve queue. Ridesharing can be toggled on (``RH_DEMAND_SHARABLE=true``) so requests with the same origin/destination zones to be served in one trip. In addition, bus-taxi integration (``COLLABORATIVE_EV=true``) can be turned on so that one trip can be divided into bus and taxi subtrips. Vehicle repositioning is implemented in ``mets_r.facility.Zone`` to balance the trip demand and vehicle supply. Zones with deficient vehicle supply will ask for vehicles from the surrounding zones. While not repositioning, empty vehicles will perform random walks within the neighboring link of the current zones, if a vehicle has been cruising for more than a specific period (e.g., 10 minutes), it will be routed to the closest zone with available parking space. Bus operation module ~~~~~~~~~~~~~~~~~~~~ Each bus defined in ``mets_r.mobility.ElectricBus`` travels on the loop route with one terminal station (the first element in the station sequence) and several intermediate bus stops. If loaded beforehand, the bus schedules are stored in ``mets_r.input.BusSchedule``. One can alter the entire bus schedules in the synchronized mode by sending messages to trigger the ``scheduleBus`` function in ``mets_r.commnication.ControlMessageHandler``. Passenger module ~~~~~~~~~~~~~~~~ The passenger module describes the decision-making process of requests while traveling to and from the transportation hubs. The module consists of five components: trip generation, time/cost-based split model, queuing structure, passenger departure as well as bus/taxi departure. This process is defined in ``mets_r.facility.Zone`` using the concept of trip requests (``mets_r.mobility.Request``) and activity plans (``mets_r.mobility.Plan``). The implemented passenger activity module in our simulator is described in the figure below. .. figure:: res/passenger_module.png :alt: Passenger module Passenger module Car following and lane-changing module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The car following and lane-changing module is based on the previous A-RESCUE simulator. A-RESCUE is an agent-based road traffic simulator designed for simulating hurricane evacuation (https://github.com/umnilab/A_RESCUE). It adopts a three-regime car following model originally seen in MITSIM. We added modifications based on the intelligent driver model (IDM). The lane-changing model comes from an `early study `__, which consists of a probabilistic model for lane-changing decisions and a heuristic model for forced lane-changing behaviors. These are implemented in the ``mets_r.facility.Road`` and ``mets_r.mobility.Vehicle``. Energy calculation module ~~~~~~~~~~~~~~~~~~~~~~~~~ For gasoline vehicles, there were several well-developed and documented methods such as MOVES proposed by the Energy and Environmental Protection Agency. This method described vehicle gas consumption and emissions based on VSP (vehicle-specific power), velocity, and acceleration. For the case of EVs, there was no unified process that describes the energy consumption as a function of their VSP and velocity. We decided to focus on a 2016 `physics-based model `__ developed by Fiori et al., which can capture the impact of different vehicle characteristics, acting forces, and vehicle dynamics. The default parameters, defined in ``mets_r.mobility.ElectricVehicle``, are extracted from Nissan Leaf, which is one of the most used vehicle types in the literature at that time. Vehicle routing module ~~~~~~~~~~~~~~~~~~~~~~ Vehicle routing is implemented in ``mets_r.routing``, which is a very important element in a traffic simulator. In ``METS-R SIM``, we adopt a model close to modern routing engines. Specifically, each ``mets_r.facility.Road`` instance will record the vehicles’ time spent on each link to regularly update the estimations of link travel time. The estimated travel time will be used to calculate the shortest path between two nodes in the network. Besides this, one can override this routing mechanism by sending messages to trigger function ``routingTaxi`` or ``routingBus`` in ``mets_r.commnication.ControlMessageHandler``.