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:

  1. 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).

  2. 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.

  3. 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).

  4. 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.

  5. 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.

  6. 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.