Simulator

Endpoint: simulator/simulate-scenario

To simulate an existing scenario in a user's workspace or a built-in scenario, you can use the simulator/simulate-scenario endpoint. Simply supply the scenario's id and include any additional simulation parameters, such as time step length, lateral resolution or number of simulation runs as json data in the POST request.

Note

Every scenario specifies the allowable range of values for time_step_length and lateral_resolution (see allowed_time_step_lengths and allowed_lateral_resolutions of a scenario). When specifying values for the simulator, it is important to ensure that they fall within the acceptable range for the selected scenario.

When the SESAM API receives a simulation request, it will initiate a background task to conduct the simulation. You'll receive a status url in response (see simulator/simulate_scenario-status/{result_id} endpoint), which you can use to track the status of the simulation workflow and retrieve the logs for each simulation run.

Note

It's important to understand that a simulation often comprises multiple runs with different seed values for the random number generator, forming what we refer to as a "simulation workflow". Through the status url, you can conveniently access the state and log output of each individual run within a workflow.

sequenceDiagram
    participant C as Client
    participant S as SESAM API
    Note over C,S: Login to retrieve token
    C->>+S: Login (username, password)
    S->>-C: Token

    Note over C,S: Simulate scenario
    C->>+S: POST simuator/simulate-scenario {...}
    S->>-C: OK, status_url
    loop until state == SUCCESS
        C->>+S: GET status_url
        S->>-C: workflow_state, logs, ...
    end

Here is an example python code to show the simulation of a scenario.

import time

import requests

with requests.Session() as session:
    # Login and update the http header with the access token (see above)

    # Simulate scenario with ID 13
    post_data = """{
        "simulation_name": "My first simulation",
        "scenario_id": 13,
        "user_comment": "SESAM is great!",
        "time_step_length": 1.000,
        "lateral_resolution": -1
    }"""
    response = session.post("https://sesam.co4e.com/api/v1/simulator/simulate-scenario", data=post_data)

    # Retrieve the polling endpoint
    status_url = response.json().get("status_url")

    simulation_workflow_complete = False

    # Periodically check the status of the build process
    while not simulation_workflow_complete:
        response = session.get(status_url)

        # Check if scenario has been built successfully
        if response.json().get("workflow_state", "") == "SUCCESS":
            simulation_workflow_complete = True

        else:
            # Delay the next polling
            time.sleep(0.5)

The outputs of each simulation run can be retrieved with the workspace/simulation-run-zip endpoint.

Endpoint: simulator/simulate-builtin-scenario

The simulator/simulate-builtin-scenario/{scenario_id} endpoint functions similarly to the simulator/simulate-scenario endpoint described earlier. The key difference is that the former allows users to simulate a built-in scenario by supplying its id, while the latter is limited to user-created scenarios only.

Traffic demand belongs to the scenario

Traffic demand is part of the scenario. Set per-vType scaling on the scenario with the editor vtype.scale.set operation before starting a simulation. The simulation endpoints no longer accept traffic_scale_factor or vtype_traffic_scale_factors. Requests containing either field return HTTP 400, including a former default value of 1.0. Remove those fields from integrations.

Configuring a simulation copies the scenario's effective vType values and active property-override provenance into independent relational simulation snapshots. SimulationVType.scale is copied directly from ScenarioVType.scale; there is no additional multiplier. The Analyzer reads these snapshots through the simulation run.

Only database metadata is snapshotted. SUMO runs against the scenario files in the scenario volume. SESAM neither copies those files into the simulation volume nor changes their scale during simulation startup. Scaling is read from the persisted vType definitions. A mismatch between the loaded vTypes/scales and the database snapshot fails explicitly before the first simulation step.

SESAM never adds a global --scale option itself and does not call setScale() after loading. A global scale declared in a scenario's own sumocfg is honored, however, and composes multiplicatively with the per-vType scales, so a scenario author can deliberately use both. Such a global scale is not part of the per-vType snapshot metadata: it is reflected in the actual simulation results but not in the reported SimulationVType.scale values.