Simulation inputs/outputs
-------------------------

Input data
~~~~~~~~~~

All the required inputs for running the simulation are listed and
described in the configuration file ``METS_R/data/Data.properties``. The
paths of the input data are provided in the first section of the file.
Below are the details of each input:

1. ``Zone centroid (Shapefile)``: the locations of origins/destinations
   of all demand. One can specify a) the parking space available in each
   zone by setting the ``Capacity`` attribute to a nonnegative value; b)
   which zones correspond to the hubs by setting the ``Type`` as ``1``
   in the corresponding ``CSV`` file. In ``METS-R``, hubs behave
   differently from normal zones in terms of trip origin/destination
   sampling and vehicle repositioning criteria.

2. ``Charging station centroid (Shapefile)``: similar to the zone
   shapefile, this is the shapefile for charging stations. For a given
   scenario, one can specify the number of (L1/L2/DC) chargers in each
   charging station in the corresponding ``CSV`` file.

3. ``Network file (SUMO XML)`` or ``Road and lane (Shapefile)``:
   ``METS-R`` supports two types of network inputs. One can directly use
   the SUMO network as the input for ``METS-R``, or use the Shapefiles
   with the following format which can be generated by
   ``util\NYC_map_preparation``. The Road Shapefile should contain the
   information on which lane belongs to which road and the Shapefile of
   lanes should contain lane connection information.

4. Optional inputs: besides the above inputs, one can also provide
   ``RH_DEMAND_FILE (CSV/JSON)`` for public transit’s (including
   ride-hailing and buses) zonal-level demand arrival rate;
   ``EV/GV_DEMAND_FILE (CSV)`` for private EV/GV trips;
   ``Background traffic speed (CSV)`` for a user-specified target speed
   in different hours of the day, this is needed when the simulation
   considers only partial traffic.

Output data
~~~~~~~~~~~

1. The aggregated output data generated in the folder ``agg_output/``
   records the number of served requests by taxis and EVs, the trip
   numbers, the passenger waiting time, and the energy consumption. Such
   output files are stored under the agg_output file folder, including
   ``Buslog.csv``,\ ``Chargerlog.csv``,\ ``EVlog.csv``, ``Linklog.csv``,
   ``Networklog.csv``, and ``Zonelog.csv``.

   a. ``Networklog.csv`` summarizes the overall operational information
      of the entire system, the fields of ``Networklog.csv`` file are:

   -  ``tick`` is the simulation time tick.
   -  ``vehOnRoad`` is the current number of on-road EV taxis.
   -  ``emptyTrip`` is the cumulative number of empty trips EV taxis
      perform.
   -  ``chargingTrip`` is the cumulative number of charging trips EV
      taxis perform.
   -  ``generatedTaxiPass`` is the total number of generated taxi
      requests.
   -  ``generatedBusPass`` is the total number of generated bus
      requests.
   -  ``generatedCombinedPass`` is the total number of generated
      bus-taxi integrated requests.
   -  ``taxiPickupPass`` is the total number of taxi requests got
      onboard.
   -  ``busPickupPass`` is the total number of bus requests got onboard.
   -  ``combinePickupPart1`` is the total number of combined requests
      that got onboard in the first trip.
   -  ``combinePickupPart2`` is the total number of combined requests
      that got onboard in the second trip.
   -  ``taxiServedPass`` is the total number of taxi requests served
      (arrived).
   -  ``busServedPass`` is the total number of bus requests served
      (arrived).
   -  ``taxiLeavedPass`` is the total number of taxi requests that left
      the system unserved.
   -  ``busLeavedPass`` is the total number of bus requests that left
      the system unserved.
   -  ``numWaitingTaxiPass`` shows the current number of requests who
      are waiting for EV taxis.
   -  ``numWaitingBusPass`` shows the current number of requests who are
      waiting for EV buses.
   -  ``timeStamp`` shows the time of the record (in milliseconds).

   b. The attributes of ``Zonelog.csv`` file are:

   -  ``tick`` is the simulation time tick.
   -  ``zoneID`` is the index of the corresponding pickup/drop-off zone.
   -  ``numTaxiPass`` is the current number of EV taxi requests.
   -  ``numBusPass`` is the current number of EV bus requests.
   -  ``vehStock`` is the cumulative number of charging trips performed
      by EV taxis.
   -  ``taxiGeneratedPass`` is the total number of generated taxi
      requests in the zone.
   -  ``taxiServedPass`` is the total number of taxi requests served in
      the zone.
   -  ``taxiLeavedPass`` is the total number of taxi requests that left
      the zone unserved.
   -  ``taxiPassWaitingTime`` shows the cumulative waiting time of
      served taxi requests.
   -  ``busGeneratedPass`` is the total number of generated bus requests
      in the zone.
   -  ``busPassWaitingTime`` is the total number of generated bus
      requests in the zone.
   -  ``busServedPass`` is the total number of bus requests served in
      the zone.
   -  ``busLeavedPass`` is the total number of bus requests that left
      the zone unserved.
   -  ``busPassWaitingTime`` shows the cumulative waiting time of served
      bus requests.
   -  ``taxiWaitingTime`` is the cumulative idling time of EV taxis in
      the zone.

   c. The attributes of ``Linklog.csv`` file are:

   -  ``tick`` is the simulation time tick.
   -  ``linkID`` is the index of the road.
   -  ``flow`` is the cumulative times of EV traveling across the link.
   -  ``consumption`` is the cumulative energy EV consumed on that link.

   d. The attributes of ``EVlog.csv`` file are:

   -  ``tick`` is the simulation time tick.
   -  ``vehicleID`` is the index of the EV taxi.
   -  ``tripType``, 1 stands for occupied trip, 2 for repositioning
      trip, 4 for charging trip.
   -  ``originID`` is the index of the original zone.
   -  ``destID`` is the index of the target zone.
   -  ``distance`` is the distance (m) traveled.
   -  ``departure time`` is the departure time of the trip.
   -  ``cost`` is the energy consumed by the trip
   -  ``choice`` is the choice of routes among the candidates if
      eco-routing is enabled.
   -  ``passNum`` is the number of requests.

   e. The attributes of ``Buslog.csv`` file are:

   -  ``tick`` is the simulation time tick.
   -  ``vehicleID`` is the index of the EV bus.
   -  ``routeID`` is the index of the transit route that the EV bus is
      following.
   -  ``tripType``, 3 for a regular trip, 4 for a charging trip.
   -  ``originID`` is the index of the original zone.
   -  ``destID`` is the index of the target zone.
   -  ``distance`` is the distance (m) traveled.
   -  ``departure time`` is the departure time of the trip.
   -  ``cost`` is the energy consumed by the trip
   -  ``choice`` is the choice of routes among the candidates if
      eco-routing is enabled.
   -  ``passOnBoard`` is the number of requests on the EV bus.

   f. The attributes of ``Chargerlog.csv`` file are:

   -  ``tick`` is the simulation time tick.
   -  ``chargerID`` is the index of the EV chargers.
   -  ``vehID`` is the index of the charging vehicles.
   -  ``chargerType`` shows the type of the chargers, can be L2, L3, or
      Bus.
   -  ``waitingTime`` is the time that the charging vehicles spent in
      the charging queue.
   -  ``chargingTime`` is the time between the start of charging and the
      time of full charge.
   -  ``initialBatteryLevel`` is the initial battery level (kWh) of the
      charging vehicles.

2. One can toggle the ``ENABLE_JSON_WRITE`` to enable the collection of
   vehicle trajectory files (and toggle it off to save storage space),
   which are stored in ``trajectory_output/``\ and are the necessary
   inputs for the visualization module. Each JSON object stores the
   following information:

   -  ``ev:`` trajectory of EV taxis, including its coordinates, speed,
      battery level, origin, destination, current link, and number of
      requests
   -  ``bus:`` trajectory of EV buses, including its coordinates, speed,
      battery level, current link, and number of onboard requests
   -  ``pass:`` number of newly served requests.
   -  ``link:`` linkID, cumulative flow, average speed, cumulative
      energy consumption aggregated by link