Skip to content

Builder Tools

The Builder provides three paths: create a custom scenario from OpenStreetMap data, create a scenario from a template, or upload a custom scenario from a SUMO zip archive. These are the same paths as in the Builder web interface.

Examples:

  • "Create a custom scenario for the area around Alexanderplatz in Berlin with a 30 minute duration."
  • "Create a custom scenario for Berlin, Dörpfeldstraße at Adlergestell, large enough that there are two parallel streets as alternatives in every direction, but not larger than 2 km²."
  • "Create a custom scenario for Adlershof with a lot of bicycle traffic and one flow of 200 trucks per hour from the motorway exit to the industrial area."
Tool What it does
builder__find_area Finds the rectangle around a street intersection, an address, a place or a coordinate, large enough for alternative routes.
builder__build_custom_scenario Creates a custom scenario for a geographic area, optionally with random traffic and traffic flows, and waits until it is ready.
builder__list_scenario_templates Lists templates with their description, location and maximum duration allowed by your plan.
builder__get_scenario_template Shows a template's location, attribution, duration and simulation settings.
builder__instantiate_scenario_template Creates a scenario from a template and waits until the independent copy is ready.
builder__upload_scenario Uploads a custom scenario from a SUMO zip archive at a public https link.

Create a scenario from a template

Ask the assistant to list templates, compare their descriptions and bounding boxes, inspect one by the returned template_id, and create a copy with a name. Optional settings are duration_seconds, project_id and comment. If duration is omitted, SESAM uses the lower of the plan and template duration. Each creation uses one creation of the shared rolling 24-hour scenario-creation quota (together with builds and uploads) and produces a new workspace scenario. Creating from templates requires a plan that includes scenario templates. The template area is fixed and exempt from the map Builder's area limit.

The assistant waits for creation to finish, then returns the new scenario_id. Use ordinary Workspace, Editor and Simulator operations on that scenario; templates cannot be simulated or edited directly. Later changes to the template do not affect existing copies.

Upload custom scenario from zip archive

builder__upload_scenario does not transfer files from your computer. SESAM downloads the zip archive from a public https link that you provide, for example from a file hosting service. Links to private or internal addresses, links with a username and password, and files larger than your plan allows are rejected.

Optional settings are the scenario name and comment, the project, the begin time and duration, and whether the floating car data (FCD) output is disabled. For the simulation options the following values are allowed:

Option Allowed values (in seconds / meters)
Time step length 0.1, 0.5, 1 (default: 0.5 and 1)
Lateral resolution -1, 0.1, 0.4, 0.8, 1.6 (default: -1 and 1.6)

A lateral resolution of -1 switches the sublane model off. See the Simulator for the meaning of these options.

Uploads share the rolling 24-hour scenario-creation quota with custom builds and template copies. The tool therefore checks your plan and the file size before it starts.

Finding an area

You rarely know coordinates. Name a location instead and the assistant finds the rectangle with builder__find_area before it builds. Finding an area changes nothing in your account and does not count against your quota.

You can name:

  • An intersection: two streets, for example Dörpfeldstraße and Adlergestell.
  • An address: a street and a house number. If the house number is not mapped, the area is centered between its neighbors or on the street, and the assistant says so.
  • A place: a square, a station or another named place, for example Alexanderplatz.
  • A coordinate: latitude and longitude, if you have them.

Because street names repeat, the assistant also needs the city, optionally with district and country, for example Berlin-Adlershof, Deutschland. Spelling variants are tolerated (Str. for Straße, oe for ö). If several places match, for example an intersection that exists in two districts, the assistant shows them and asks which one you mean.

You can choose the size of the area:

  • Alternatives (default): the area grows around the location until two other streets (or another number) cross each of its four sides, so that traffic has alternative routes in every direction. You can limit the area, for example to 2 km², and the least important road class that counts (by default residential streets; service roads, tracks, foot paths and cycle ways never count). If the limit is reached first, you get the largest allowed area and are told which sides lack alternatives.
  • Radius: a square that extends the given distance in every direction.
  • Area: a square of the given size.

The area never exceeds the limit of your plan. Without a limit of your own, at most 4 km² are searched. The result also shows which streets cross each side, so that you can check the area before you build it. The result also contains a link that opens the Builder with the area already selected, so that you can look at it, adjust it and configure and start the build yourself. The map data is © OpenStreetMap contributors (ODbL).

What you can describe

  • Area: a rectangle given by its western and eastern longitude and its southern and northern latitude, for example the one that builder__find_area returns. The size of the area is limited by your plan.
  • Random traffic: for each transport mode (cars, trucks, buses, motorcycles, bicycles, pedestrians, trams, urban trains, trains and ships) the number of trips per hour and lane-kilometer, and how much of it is through traffic.
  • Traffic flows: individual flows between two coordinates with a vehicle class and a number of vehicles per hour.
  • Settings: the duration, whether to import polygons and public transport, a network for cars only, left-hand traffic, a project for the new scenario and a comment.

Everything that you do not specify uses the defaults of the Builder.

Good to know

The assistant waits up to 10 minutes and shows the progress. If this time is exceeded, the build keeps running in SESAM and the scenario appears in your Workspace when it is finished.

A build only creates the scenario. To see traffic, run a simulation of it. Every build counts against the shared rolling 24-hour scenario-creation quota; SESAM names the limit if it is reached.