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

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

All inputs are configured in ``METS_R/data/Data.properties``. The file
is divided into several sections described below.

**Simulation setup**

Key flags that control the overall simulation behavior:

-  ``STANDALONE`` — set to ``true`` to run without an external HPC
   controller (first-come-first-serve dispatch).
-  ``SYNCHRONIZED`` — set to ``true`` to wait for an HPC tick signal,
   enabling co-simulation and real-time algorithmic control.
-  ``V2X`` — set to ``true`` to activate the on-board unit (OBU) and
   road-side unit (RSU) Kafka data streams.
-  ``RANDOM_SEED`` — integer seed for reproducible simulation runs
   (default: ``42``).
-  ``SIMULATION_STEP_SIZE`` — duration of one simulation tick in seconds
   (default: ``0.2`` s/tick).
-  ``SIMULATION_STOP_TIME`` — total simulation duration in minutes.
-  ``DEMAND_DIFFUSION`` — if ``true``, trip origins/destinations are
   uniformly sampled within a zone; if ``false``, zone centroids are used.

**Network files**

-  ``NETWORK_FILE (SUMO .net.xml)`` *(primary)*: a SUMO network file
   that fully specifies roads, lanes, junctions, and signal plans.
   When set, this overrides the shapefile-based inputs below.
   Example: ``data/NYC/facility/road/nyc.net.xml``.

-  ``ROADS_SHAPEFILE / ROADS_CSV`` and ``LANES_SHAPEFILE / LANES_CSV``
   *(fallback)*: road and lane shapefiles. The road shapefile encodes
   which lanes belong to which road; the lane shapefile contains lane
   connection information. These can be generated from raw map data
   using ``util/NYC_map_preparation``.

-  ``INITIAL_X`` / ``INITIAL_Y``: the reference longitude/latitude used
   when writing trajectory JSON output (e.g., ``-73`` / ``40`` for NYC).

**Facility files**

-  ``ZONES_SHAPEFILE / ZONES_CSV``: zone centroid locations for
   origins/destinations. The ``CSV`` can specify:

   -  ``Capacity``: available parking spaces per zone (non-negative).
   -  ``Type = 1``: marks a zone as a *hub*, which affects trip sampling
      and vehicle repositioning behaviour.

-  ``CHARGER_SHAPEFILE / CHARGER_CSV``: charging station locations and
   charger counts. The CSV specifies the number of L2 and DCFC
   (DC Fast Charging) chargers at each station.

**Travel demand**

-  ``RH_DEMAND_FILE (CSV/JSON)``: zonal ride-hailing demand arrival rates.
-  ``RH_WAITING_TIME (CSV)``: maximum acceptable waiting times per zone.
-  ``RH_SHARE_PERCENTAGE (JSON)``: per-zone ridesharing acceptance rates.
-  ``RH_DEMAND_SHARABLE``: global toggle for ridesharing (``true``/``false``).
-  ``RH_DEMAND_FACTOR``: scalar multiplier applied to all ride-hailing
   demand (e.g., ``0.1`` for 10 % of the full demand).
-  ``EV_DEMAND_FILE (CSV)``: private EV trip chains.
-  ``GV_DEMAND_FILE (CSV)``: private gasoline vehicle trip chains.
-  ``EV_CHARGING_PREFERENCE (CSV)``: per-vehicle charging preference
   profiles for private EVs.
-  ``BUS_SCHEDULE (JSON)``: initial bus routes and departure schedules.
   Bus routes can also be created and modified at runtime via the
   Interactive APIs.

**Background traffic**

-  ``BT_EVENT_FILE (CSV)``: time-varying speed targets for background
   traffic events (e.g., incidents).
-  ``BT_STD_FILE (CSV)``: baseline hourly speed profile. Needed when
   simulating only a subset of total traffic.

**Fleet and battery**

-  ``NUM_OF_EV``: number of EV taxis deployed at simulation start.
-  ``NUM_OF_BUS``: number of EV buses deployed at simulation start.
-  ``EV_BATTERY`` / ``TAXI_BATTERY``: battery capacity of private EVs
   and EV taxis (kWh).
-  ``BUS_BATTERY``: battery capacity of EV buses (kWh).

**Events**

-  ``EVENT_FILE (CSV)``: time-stamped road closure or traffic regulation
   events. Checked every ``EVENT_CHECK_FREQUENCY`` seconds.

**Operation options**

-  ``K_SHORTEST_PATH``: if ``true``, uses *k*-shortest path routing with
   logit route choice; if ``false``, uses single shortest path.
-  ``PROACTIVE_RELOCATION``: if ``true``, idle taxis reposition proactively
   to high-demand zones.
-  ``PROACTIVE_CHARGING``: if ``true``, taxis charge proactively before
   the battery reaches the low threshold.
-  ``RECHARGE_LEVEL_LOW`` / ``RECHARGE_LEVEL_HIGH``: state-of-charge
   thresholds (0–1) that trigger and terminate charging for each vehicle
   type (``TAXI_`` and ``BUS_`` prefixed variants also available).

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

**Aggregated output** (``agg_output/``)

Six CSV log files are written at configurable intervals:

a. ``Networklog.csv`` — system-wide operational summary:

   -  ``tick``: simulation time tick.
   -  ``vehOnRoad``: current number of on-road EV taxis.
   -  ``emptyTrip``: cumulative empty trips by EV taxis.
   -  ``chargingTrip``: cumulative charging trips by EV taxis.
   -  ``generatedTaxiPass``: total generated taxi requests.
   -  ``generatedBusPass``: total generated bus requests.
   -  ``generatedCombinedPass``: total generated bus-taxi integrated requests.
   -  ``taxiPickupPass``: total taxi requests that boarded.
   -  ``busPickupPass``: total bus requests that boarded.
   -  ``combinePickupPart1`` / ``combinePickupPart2``: combined requests
      that boarded the first and second legs respectively.
   -  ``taxiServedPass``: total taxi requests fully served (arrived).
   -  ``busServedPass``: total bus requests fully served (arrived).
   -  ``taxiLeavedPass``: total taxi requests that left unserved.
   -  ``busLeavedPass``: total bus requests that left unserved.
   -  ``numWaitingTaxiPass``: current number of requests waiting for taxis.
   -  ``numWaitingBusPass``: current number of requests waiting for buses.
   -  ``timeStamp``: wall-clock time of the record (milliseconds).

b. ``Zonelog.csv`` — per-zone statistics:

   -  ``tick``, ``zoneID``.
   -  ``numTaxiPass`` / ``numBusPass``: current pending requests per mode.
   -  ``vehStock``: cumulative charging trips performed by EV taxis in the zone.
   -  ``taxiGeneratedPass`` / ``taxiServedPass`` / ``taxiLeavedPass``: taxi
      demand lifecycle counts.
   -  ``taxiPassWaitingTime``: cumulative waiting time of served taxi requests.
   -  ``busGeneratedPass`` / ``busServedPass`` / ``busLeavedPass``: bus
      demand lifecycle counts.
   -  ``busPassWaitingTime``: cumulative waiting time of served bus requests.
   -  ``taxiWaitingTime``: cumulative idle time of EV taxis in the zone.

c. ``Linklog.csv`` — per-road-segment statistics:

   -  ``tick``, ``linkID``.
   -  ``flow``: cumulative number of EV traversals on the link.
   -  ``consumption``: cumulative energy consumed on the link (kWh).

d. ``EVlog.csv`` — per-trip log for EV taxis and private EVs:

   -  ``tick``, ``vehicleID``.
   -  ``tripType``: ``1`` occupied trip, ``2`` repositioning trip,
      ``3`` private trip, ``4`` charging trip.
   -  ``originID`` / ``destID``: origin and destination zone indices.
   -  ``distance``: trip distance (m).
   -  ``departure time``: departure tick.
   -  ``cost``: energy consumed (kWh).
   -  ``passNum``: number of passengers carried.

e. ``Buslog.csv`` — per-trip log for EV buses:

   -  ``tick``, ``vehicleID``, ``routeID``.
   -  ``tripType``: ``3`` regular trip, ``4`` charging trip.
   -  ``originID`` / ``destID``, ``distance``, ``departure time``, ``cost``.
   -  ``passOnBoard``: number of passengers on board during the trip.

f. ``Chargerlog.csv`` — per-charging-session log:

   -  ``tick``, ``chargerID``, ``vehID``.
   -  ``chargerType``: ``L2``, ``DCFC``, or ``Bus``.
   -  ``waitingTime``: time spent in the charging queue (ticks).
   -  ``chargingTime``: time from charge start to full charge (ticks).
   -  ``initialBatteryLevel``: battery level at charge start (kWh).

**Trajectory output** (``trajectory_output/``)

Toggle ``ENABLE_JSON_WRITE = true`` to collect per-tick vehicle
trajectories required by the visualization module. Files are split by
``JSON_TICK_LIMIT_PER_FILE`` ticks and contain:

-  ``ev``: EV taxi trajectories — coordinates, speed, battery level,
   origin/destination zone, current link, and passenger count.
-  ``bus``: EV bus trajectories — coordinates, speed, battery level,
   current link, and onboard passenger count.
-  ``pass``: number of newly served requests per tick.
-  ``link``: per-link cumulative flow, average speed, and cumulative
   energy consumption.