Skip to content

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.

Example Code
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
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.