Scenario Generation Tools#

The five Scenario Generation tools form the baseline simulation pipeline: they take a geographic area, produce a SUMO road network, generate trip demand, assign routes, and execute the simulation.

        flowchart LR
  A[osm_extract<br/>Step 1/5] --> B[net_convert<br/>Step 2/5]
  B --> C[trip_generate<br/>Step 3/5]
  C --> D[route_generate<br/>Step 4/5]
  D --> E[sumo_runner<br/>Step 5/5]

The five tools are expected to be invoked in order for fresh scenarios.

osm_extract#

Step 1/5. Download or extract OpenStreetMap road-network data for a given area, producing a raw .osm file.

def osm_extract(
    city_en: str,
    bbox: list = None,
    city: str = None,
    radius: float = None,
    od_data_file: str = None,
    zone_shp_file: str = None,
    column_mapping: dict = None,
    output_dir: str = "output/networks",
) -> Dict[str, Any]

Parameters

  • city_en (str) — English city or area name used for file tagging (e.g., "Gangnam-Station").

  • bbox (list, optional) — [min_lon, min_lat, max_lon, max_lat]. If omitted, AgentSUMO computes a bounding box from city + radius or from the OD/zone files.

  • city, radius (optional) — Place name to geocode and radius (km).

  • od_data_file, zone_shp_file, column_mapping (optional) — Inputs for RealOD demand sourcing. Forwarded to subsequent steps.

Returns — {osm_file, bbox, tag}. Pass osm_file to net_convert.

net_convert#

Step 2/5. Convert the raw OSM data into a SUMO-compatible road network (.net.xml) via netconvert, with road-type filtering and UTM projection.

def net_convert(
    osm_file: str,
    city_en: str = None,
    bbox: list = None,
    output_dir: str = "output/networks",
) -> Dict[str, Any]

Parameters

  • osm_file (str) — Path returned by osm_extract.

  • city_en, bbox — Forwarded from the previous step; used for naming and boundary trimming.

Returns — {net_file}. Pass it to trip_generate and sumo_runner.

trip_generate#

Step 3/5. Generate trip demand (*.trips.xml) for the simulation. Two modes:

  • RandomOD — synthetic random trips with a traffic_condition knob (light / medium / heavy), driven by SUMO’s randomTrips.py.

  • RealOD — real origin-destination data from a user-provided file (CSV or shapefile), driven by SUMO’s od2trips.py.

This tool only generates trips — route assignment is done separately by route_generate.

def trip_generate(
    trip_type: str,
    net_file: str,
    od_type: str = None,
    od_data_file: str = None,
    zone_shp_file: str = None,
    traffic_condition: str = None,
    column_mapping: dict = None,
    output_dir: str = "output/trips",
) -> Dict[str, Any]

Parameters

  • trip_type (str) — "random" or "real".

  • net_file (str) — Path from net_convert.

  • od_type (str, optional) — When trip_type="real", controls how OD data is mapped (e.g., coordinate, zone).

  • od_data_file, zone_shp_file, column_mapping (optional) — RealOD inputs.

  • traffic_condition (str, optional) — "light", "medium", "heavy" for RandomOD.

Returns — {trip_file, trip_count}.

route_generate#

Step 4/5. Assign shortest-path routes to each trip via SUMO’s duarouter. Produces a .rou.xml file consumed by sumo_runner.

def route_generate(
    net_file: str,
    trip_file: str,
    output_dir: str = "output/trips",
) -> Dict[str, Any]

Parameters

  • net_file (str) — Path from net_convert.

  • trip_file (str) — Path from trip_generate.

Returns — {route_file}.

sumo_runner#

Step 5/5. Execute the SUMO traffic simulation via TraCI, capturing vehicle position frames for post-simulation replay in the web UI.

def sumo_runner(
    net_file: str,
    trip_file: str = None,
    route_file: str = None,
    duration: int = 3600,
    output_dir: str = "output/simulations",
    additional_files: list = None,
    policy_type: str = None,
)

Parameters

  • net_file (str) — Path from net_convert.

  • trip_file (str, optional) — Required if route_file is omitted.

  • route_file (str, optional) — Preferred when available.

  • duration (int) — Simulation duration in seconds. Default: 3600.

  • additional_files (list, optional) — Supplementary SUMO XML files (e.g., rerouters, variable-speed signs, traffic-light additions) generated by Policy Experimentation tools.

  • policy_type (str, optional) — Tagging metadata for this run.

Returns — {output_files, replay_file, simulation_time}. output_files lists the XML produced (tripinfo.xml, edgeData.xml, edgeData_emission.xml); replay_file is the JSON capture used by the web UI’s vehicle replay layer.