HPC module

METS-R HPC is used to control multiple simulation instances that can run and exchange data through WebSocket connects. Apache Kafka is used to explicitly model the data stream. The overall HPC framework is shown in the figure below, note this framework allows us to separate the logics of modeling data processing, decision generation, traffic simulation, and potentially cyber attacks.

Code structure

Four types of classes are used:

Client for interfacing the data communication between simulators and other components.
Runner for defining different types of experiments.
Model for implementing operational algorithms.
Config for storing the configuration templates.

Besides these, we provide the example scripts: interactive_example.ipynb, cosim_example.py.

Interactive APIs

The following APIs are implemented to interact with the METS-R SIM, here sim_client is an instance of METSRClient.

STEP

Name	Description	Examples	Return
tick	Move the simulation one tick forward	`sim_client.tick()`

QUERY

If an agent ID is provided, a query would return the information of the specific agent, otherwise, it will return a list containing the ID of all agents.

Name	Description	Examples	Return
`query_vehicle(id=None, private_veh=False, transform_coords=False)`	Get the information of one or more vehicles. By default, queries public vehicles. Set `private_veh=True` for private vehicles and `transform_coords=True` to convert coordinates to SUMO format.	`sim_client.query_vehicle(1, True, True)`	x, y, speed, acceleration, bearing, origin zone, destination zone, vehicle state
`query_taxi(id=None)`	Get the information of one or more EV taxis.	`sim_client.query_taxi(36879)`	x, y, passenger number, vehicle state, origin zone, destination zone
`query_bus(id=None)`	Get the information of one or more EV buses.	`sim_client.query_bus(37732)`	battery state, route ID, current stop, passenger number
`query_road(id=None)`	Get the information of one or more roads.	`sim_client.query_road(100011)`	speed limit, number of on-road vehicles, average travel time, road length (m), energy consumed, road type
`query_centerline(id, lane_index=0, transform_coords=False)`	Get the centerline geometry of a specific lane on a road. Set `transform_coords=True` to return coordinates in SUMO format.	`sim_client.query_centerline(100011, 0)`	list of (x, y) coordinate pairs along the lane centerline
`query_zone(id=None)`	Get the information of one or more demand zones.	`sim_client.query_zone(0)`	vehicle stock, taxi demand, bus demand, x, y, zone type
`query_signal(id=None)`	Get the information of one or more traffic signals.	`sim_client.query_signal(14)`	current phase, next phase, next update time
`query_signal_group(id)`	Get the signal group information for a given signal controller ID, including all phases and their durations.	`sim_client.query_signal_group(14)`	signal group ID, phase list, phase durations
`query_signal_between_roads(upstream_road, downstream_road)`	Query the signal controlling the connection between two consecutive roads.	`sim_client.query_signal_between_roads("r1", "r2")`	signal ID, current phase, next update time
`query_chargingStation(id=None)`	Get the information of one or more EV charging stations.	`sim_client.query_chargingStation(-10)`	x, y, number of available chargers
`query_coSimVehicle()`	Get the vehicle IDs currently located on the co-simulation road.	`sim_client.query_coSimVehicle()`	list of vehicle IDs on the co-sim road
`query_route(orig_x, orig_y, dest_x, dest_y, transform_coords=False)`	Query the shortest route between two coordinate-specified locations. Set `transform_coords=True` if inputs are in SUMO coordinate format.	`sim_client.query_route(10.0, 20.0, 50.0, 80.0)`	ordered list of road IDs forming the route
`query_route_between_roads(orig_road, dest_road)`	Query the shortest route between two road IDs.	`sim_client.query_route_between_roads("r1", "r2")`	ordered list of road IDs forming the route
`query_road_weights(roadID=None)`	Query the current edge weights (travel time or energy cost) used for routing. Returns weights for all roads if no ID is specified.	`sim_client.query_road_weights(100011)`	road ID, current weight value
`query_bus_route(routeID)`	Get the stop sequence and road path for a named bus route.	`sim_client.query_bus_route("route_1")`	route name, stop zone IDs, road path
`query_route_bus(routeID)`	Get all active buses currently assigned to a specific route.	`sim_client.query_route_bus("route_1")`	list of bus IDs on the route

CONTROL

Name	Description	Examples	Inputs
`generate_trip(vehID, origin=-1, destination=-1)`	Generate a vehicle trip between origin and destination zones.	`sim_client.generate_trip("veh_1", 3, 5)`	vehID, origin zone ID, destination zone ID
`generate_trip_between_roads(vehID, origin, destination)`	Generate a vehicle trip between origin and destination roads.	`sim_client.generate_trip_between_roads("veh_1", "r1", "r2")`	vehID, origin road ID, destination road ID
`set_cosim_road(roadID)`	Set one or more roads for co-simulation. Vehicles on these roads will be controlled externally.	`sim_client.set_cosim_road("road_2")`	roadID
`release_cosim_road(roadID)`	Release one or more co-simulation roads, returning vehicle control to the simulator.	`sim_client.release_cosim_road("road_2")`	roadID
`teleport_cosim_vehicle(vehID, x, y, bearing, private_veh=False, transform_coords=False)`	Teleport a co-simulation vehicle to a specified coordinate with a given heading. Set `transform_coords=True` if coordinates are in SUMO format.	`sim_client.teleport_cosim_vehicle("veh_1", 10.5, 25.0, 90.0)`	vehID, x, y, bearing (degrees), private_veh, transform_coords
`teleport_trace_replay_vehicle(vehID, roadID, laneID, dist, private_veh=False)`	Teleport a vehicle to a position specified by road ID, lane index, and distance from the downstream junction.	`sim_client.teleport_trace_replay_vehicle("veh_1", "road_3", 1, 30.0)`	vehID, roadID, laneID, dist, private_veh
`enter_next_road(vehID, private_veh=False)`	Move a co-simulation vehicle onto the next road in its planned route.	`sim_client.enter_next_road("veh_1")`	vehID, private_veh
`reach_dest(vehID, private_veh=False)`	Signal that a co-simulation vehicle has reached its destination and should be removed from the network.	`sim_client.reach_dest("veh_1")`	vehID, private_veh
`control_vehicle(vehID, acc, private_veh=False)`	Directly override the acceleration of a vehicle for the current tick.	`sim_client.control_vehicle("veh_1", 2.5)`	vehID, acc (m/s²), private_veh
`update_vehicle_sensor_type(vehID, sensorType, private_veh=False)`	Change the sensor type of a vehicle (e.g., for V2X data stream configuration).	`sim_client.update_vehicle_sensor_type("veh_1", "LiDAR")`	vehID, sensorType, private_veh
`update_vehicle_route(vehID, route, private_veh=False)`	Override the planned route of a vehicle with a new ordered list of road IDs.	`sim_client.update_vehicle_route("veh_1", ["r1", "r2", "r3"])`	vehID, route (list of road IDs), private_veh
`dispatch_taxi(vehID, orig, dest, num)`	Dispatch a specific taxi to serve a passenger request between two zones.	`sim_client.dispatch_taxi("taxi_1", 0, 2, 1)`	vehID, origin zone ID, destination zone ID, num passengers
`dispatch_taxi_between_roads(vehID, orig, dest, num)`	Dispatch a specific taxi to serve a request between two road-specified locations.	`sim_client.dispatch_taxi_between_roads("taxi_1", "r1", "r2", 1)`	vehID, origin road ID, destination road ID, num passengers
`add_taxi_requests(zoneID, dest, num)`	Inject a taxi passenger request at a zone, to be fulfilled by the simulator’s dispatch logic.	`sim_client.add_taxi_requests(1, 3, 2)`	origin zone ID, destination zone ID, num passengers
`add_taxi_requests_between_roads(orig, dest, num)`	Inject a road-based taxi request from one road to another.	`sim_client.add_taxi_requests_between_roads("r1", "r2", 1)`	origin road ID, destination road ID, num passengers
`assign_request_to_bus(vehID, orig, dest, num)`	Assign a passenger request directly to a specific bus.	`sim_client.assign_request_to_bus("bus_1", 0, 5, 10)`	vehID, origin zone ID, destination zone ID, num passengers
`add_bus_requests(zoneID, dest, routeName, num)`	Inject a bus passenger request at a zone for a specific route.	`sim_client.add_bus_requests(2, 5, "route_1", 15)`	origin zone ID, destination zone ID, route name, num passengers
`add_bus_route(routeName, zone, road, paths=None)`	Define a new bus route by specifying its stop zones and road path. If `paths` is provided, explicit road paths between stops are used.	`sim_client.add_bus_route("route_new", [0,1,2], ["r_a","r_b","r_c"])`	route name, list of zone IDs, list of road IDs, optional paths
`add_bus_run(routeName, departTime)`	Schedule a new bus departure on an existing route at a specified simulation time (in ticks).	`sim_client.add_bus_run("route_1", 3600)`	route name, departure time (ticks)
`insert_bus_stop(busID, routeName, zoneID, roadName, stopIndex)`	Dynamically insert a new stop into an active bus route at a given index.	`sim_client.insert_bus_stop("bus_1", "route_1", 3, "r_c", 2)`	bus ID, route name, zone ID, road name, stop index
`remove_bus_stop(busID, routeName, stopIndex)`	Remove a stop from an active bus route at a given index.	`sim_client.remove_bus_stop("bus_1", "route_1", 2)`	bus ID, route name, stop index
`update_road_weights(roadID, weight)`	Update the routing weight (e.g., travel time or energy cost) for a road segment.	`sim_client.update_road_weights(100011, 45.0)`	roadID, new weight value
`update_charging_prices(stationID, stationType, price)`	Update the per-kWh charging price at a specific station. `stationType` specifies L2 or L3 charger.	`sim_client.update_charging_prices(-10, "L3", 0.25)`	station ID, charger type, price ($/kWh)
`update_signal(signalID, targetPhase, phaseTime)`	Force a traffic signal to switch to a target phase, lasting the specified duration (in ticks).	`sim_client.update_signal(14, 2, 30)`	signal ID, target phase index, phase duration (ticks)
`update_signal_timing(signalID, greenTime, yellowTime, redTime)`	Update the fixed-time cycle durations (in ticks) of a traffic signal.	`sim_client.update_signal_timing(14, 30, 5, 25)`	signal ID, green ticks, yellow ticks, red ticks
`set_signal_phase_plan(signalID, greenTime, yellowTime, redTime, startPhase, phaseOffset)`	Set a complete signal phase plan using durations in seconds.	`sim_client.set_signal_phase_plan(14, 30.0, 5.0, 25.0, 0, 0.0)`	signal ID, green time (s), yellow time (s), red time (s), start phase, phase offset (s)
`set_signal_phase_plan_ticks(signalID, greenTicks, yellowTicks, redTicks, startPhase, tickOffset)`	Set a complete signal phase plan using durations in simulation ticks.	`sim_client.set_signal_phase_plan_ticks(14, 60, 10, 50, 0, 0)`	signal ID, green ticks, yellow ticks, red ticks, start phase, tick offset
`save(filename)`	Save a full snapshot of the current simulation state to a file, enabling reproducible replay.	`sim_client.save("snapshot_t1000.bin")`	filename
`load(filename)`	Restore the simulation to a previously saved state.	`sim_client.load("snapshot_t1000.bin")`	filename
`reset()`	Reset the simulation to its initial state using the current configuration.	`sim_client.reset()`
`terminate()`	Fully terminate the simulation process.	`sim_client.terminate()`
`close()`	Close the client connection while leaving the simulation running.	`sim_client.close()`