• Simulate mode, departure-time and route choice
• Agent-based
• Multi-modal
• Micro-founded
• Dynamic
• Adapted for small- and large-scale simulations
• Fast
• Extensible

• Row-oriented file format for tabular data
• Human readable
• Compatible with many tools and languages (including Excel!)
• Used in METROPOLIS2 for most input and output files (comma separator only)
• Recommended only for small-scale simulations, especially when using Excel

• Column-oriented file format for tabular data
• Binary file (= non human-readable)
• Built-in compression: smaller file size than CSV
• Very fast
• Compatible with Python (polars or pandas libraries) and R (arrow package)
• Used in METROPOLIS2 for most input and output files
• Recommended format for large-scale simulations and people working with R or Python

• One bottleneck at the entry and exit of each link
• Bottlenecks can be in two states: open or closed
• Bottlenecks are open by default and open bottlenecks can be crossed immediately
• When a vehicle cross a bottleneck, the bottleneck gets closed for a duration \[ \text{closing time} = \frac{\text{Vehicle PCE}}{\text{Bottleneck flow}} \]
• When a vehicle reaches a closed bottleneck, it is pushed to the back of the bottleneck queue
• When a closed bottleneck re-opens, the vehicle at the front of the queue can cross
• Question: bottleneck flow of 1200 PCE/h; a truck (3 PCEs) is crossing it; what is the closing time?
• Answer: 3 / (1/3) = 9

• The bottleneck flow of a link is multiplied by the number of lanes
• The space available on the link is multiplied by the number of lanes (relevant for spillback only)

• When spillback is enabled, the road network can reach a state where some vehicles are permanently stuck
• The maximum pending duration defines the maximum amount of time a vehicle can be in a pending state
• After the maximum pending duration elapses, pending vehicles are forced onto the next edge

• edge_id: Identifier of the edge (positive integer, unique)
• source: Identifier of the source node (positive integer)
• target: Identifier of the target node (positive integer)
• speed: Free-flow speed on the edge (m/s)
• length: Length of the edge (m)

• bottleneck_flow: Maximum inflow and outflow of the edge (PCE/s)
• When the variable is omitted, the inflow and outflow are not limited

• overtaking: If `True`, vehicles can overtake other vehicles in the bottleneck queues if they are going to different edges
• Default value is `True`

• lanes: number of lanes available to vehicles on the edge (in the current direction)
• If omitted, the number of lanes is set to 1
• Non-integer values can be used

• constant_travel_time: time penalty that is added to the edge's travel time, in seconds
• Travel-time on the edge is (excluding the waiting times): \[ \text{constant\_travel\_time} + \frac{\text{length}}{\text{speed}(\text{density})} \]
• This penalty can represent delays which happen even under free-flow conditions (e.g., waiting at traffic lights, stopping at a stop sign)
• The default value is zero

• The METROPOLIS2 Routing algorithm cannot handle edges with the same source and target (parallel edges)
  
• Possible workaround if required:
  

• vehicle_id: Identifier of the vehicle (positive integer, unique)
• headway: Head-to-head length between two vehicles (m, used to compute edge's density)

• pce: Passenger-car equivalent for the vehicle (non-negative number)
• Used to compute the closing time of bottlenecks
• Default value is 1

• The "Multiplicator" speed function type can be used to increase / decrease the speed of vehicles by a multiplicative coefficient
• The "UpperBound" speed function type can be used to specify a maximum speed that the vehicles cannot exceed (e.g., trucks limited to 90 km/h)

• Cars are allowed on all edges
• Motorcycles are only allowed on edges 1 and 2
• Trucks are allowed on all edges but edges 3 and 4
• Warning: lists are only supported for the Parquet format so the road restrictions do not work for CSV

• The parameters JSON input file contains configuration values for the simulation (e.g., path to the input files, simulated period, learning model)
• A part of the file is dedicated to road-network parameters
• The remaining parts will be covered in the next sections

• recording_interval: time, in seconds, between two breakpoints in the edge-level travel-time functions (Mandatory; Recommendation: 5, 10 or 15 minutes for large-scale networks)
• approximation_bound: for a given travel-time function, if the difference between the maximum and the minimum travel time is smaller than this value, the function is represented as a constant function for optimization (Default: 0; Recommendation: between 0 and 5 seconds)

							{
								[...]
								"road_network": {
									"recording_interval": 300.0,
									"approximation_bound": 1.0,
									"spillback": true,
									"backward_wave_speed": 4.0,
									"max_pending_duration": 60.0,
									"constrain_inflow": true,
									"algorithm_type": "Best",
								},
								[...]
							}
						

• spillback: whether spillback congestion (queue propagation) is enabled (Default: TRUE; Recommendation: TRUE for more realistic congestion modeling)
• backward_wave_speed: speed at which the space taken by vehicles propagates backward upon exit (Default: instantaneous propagation; Recommendation: default or 15 km/h = 4.17 m/s)
• max_pending_duration: maximum amount of time a vehicle can stay in a pending state (Mandatory; Recommendation: between 30s and 5m, larger values are more realistic but generate more congestion)

							{
								[...]
								"road_network": {
									"recording_interval": 300.0,
									"approximation_bound": 1.0,
									"spillback": true,
									"backward_wave_speed": 4.0,
									"max_pending_duration": 60.0,
									"constrain_inflow": true,
									"algorithm_type": "Best",
								},
								[...]
							}
						

• constrain_inflow: whether bottlenecks limit vehicle inflow in addition to vehicle outflow (Default: TRUE; Recommendation: TRUE, set to FALSE to replicate MATSim behavior)
• algorithm_type: routing algorithm to use for profile queries, "Best", "TCH", or "Intersect" (Default: "Best"; Recommendation: "Intersect" for a smaller running time, "TCH" for a smaller memory consumption)

							{
								[...]
								"road_network": {
									"recording_interval": 300.0,
									"approximation_bound": 1.0,
									"spillback": true,
									"backward_wave_speed": 4.0,
									"max_pending_duration": 60.0,
									"constrain_inflow": true,
									"algorithm_type": "Best",
								},
								[...]
							}
						

• Each alternative consists in 0, 1 or more trip(s), to be executed sequentially
• Two types of trips: road and virtual
• Road trip: origin, destination, vehicle type
• Virtual trip (or teleport trip): exogenous travel time (e.g., walking, cycling, public transit)

File agents.csv

Define agents and their choice model between alternatives

File alts.csv:

Define alternatives for each agent, with the constant utility and departure-time choice model (except for alternatives with no trip)

File trips.csv:

Define the trips of each alternative, with the type (road / virtual), characteristics (origin, destination, travel time), and travel and schedule utility parameters

File alts.csv:

File trips.csv:

stopping_time is the time that elapses before the next trip starts

File trips.csv:

Warning: travel_utility.one is expressed in utility / second; schedule_utility.beta and schedule_utility.gamma are expressed in "generalized cost" / second

• At the top level, agents choose among an arbitrary number of travel alternatives
• A travel alternative is defined as a sequence of trips and a utility function specification
• The alternative choice can represent:
  1. Mode choice: H→W by car | H→W by PT | H→W by walk
  2. Mode choice with trip chaining: H→W→S→H by car | H→W→S→H by bicycle
  3. To travel or not to travel: H→W by car | No trip (work-from-home)
  4. Inter-modality: H→P by car then P→W by PT | H→W by car
  5. Destination choice: H→S1 by walk | H→S2 by walk
  6. Vehicle choice: H→W with a fast but energy-consuming car | H→W with a fuel-efficient but slow car

• The network conditions consist in a travel-time function for each link and for each vehicle type
• The travel-time functions are represented as piecewise-linear functions with a fixed interval $\delta$ between two breakpoints
• Simulated network conditions: Network conditions observed, given some travel decisions (from the supply model).
• Expected network conditions: Network conditions anticipated by the agents when taking travel decisions (in the demand model). They are used to compute road trips' travel times.
• Both simulated and expected network conditions are common knowledge to all agents.

File running_times.json

						{
							"total": "49181.060006808",
							"total_skims_computation": "37804.951886765",
							"total_demand_model": "2943.497363545",
							"total_supply_model": "8150.961492634",
							"total_learning_model": "9.425217904",
							"total_aggregate_results_computation": "148.839589353",
							"total_stopping_rules_check": "0.000029886",
							"per_iteration": "245.905300034",
							"per_iteration_skims_computation": "189.024759433",
							"per_iteration_demand_model": "14.717486817",
							"per_iteration_supply_model": "40.754807463",
							"per_iteration_learning_model": "0.047126089",
							"per_iteration_aggregate_results_computation": "0.744197946",
							"per_iteration_stopping_rules_check": "0.000000149"
						}
						

skims_computation: computation of OD-level travel-time functions given the expected road-network conditions

• agent_results.{parquet,csv}: results at the agent-level
• trip_results.{parquet,csv}: results at the trip-level
• route_results.{parquet,csv}: detailed itineraries for the road trips

• Default: use free-flow conditions as expected network conditions for the first iteration
• Initial network conditions can be given as input
• Input file format is the same as network conditions output file format

						{
								"input_files": {
										"agents": "agents.csv",
										"alternatives": "alts.csv",
										"trips": "trips.csv",
										"edges": "edges.csv",
										"vehicle_types": "vehicles.csv",
										"road_network_conditions": "net_cond_next_exp_edge_ttfs.csv"
								},
								"output_directory": "output",
								"period": [
										25200.0,
										28800.0
								],
								"road_network": {
										"recording_interval": 60.0,
										"spillback": false,
										"max_pending_duration": 0.0
								},
								"max_iterations": 100,
								"init_iteration_counter": 100,
								"saving_format": "CSV",
								"learning_model": {
										"type": "Exponential",
										"value": 0.4
								}
						}