/api/simulations/scenario

Last updated on 12th October 2022

Note: if you wish to modify variables in Globals please make sure any inputs are prefaced with system. or are contained within a system object.

POST

Creates and runs a scenario simulation and returns an object with its various attributes.

Request

Example request body

curl -X POST \
  http://localhost:8080/api/simulations/scenario \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "modelName": "Simple Credit Card", 
  "output": {"uri": "scenarioFolder" },
  "scenarios":[{
    "name": "myScenario", 
    "runs": 3,
    "seeds": [1234, 2314, 4213]
    "scenarioData": {
        "0": {"spending": 200},
        "4": {"spending": 100, "interest": 0.04}
      }
  }]
}'

Windows user File

Characters need to be escaped when using scenarios in windows on cmd.

'{"name": "Game of Life"}' must become '{\"name\": \"Game of Life\"}'

Body Schema

Parameter Type Required Description
modelName string true Name of model to run a scenario for. This is the name that the model is registered with when starting the server.
scenarios [object] List of objects describing scenarios to run for this model
>name object A user specified name for the scenario. If not provided, scenario_{id} will be used as the name, where id is the index of this scenario in the array of scenarios
>runs integer Number of times to run this scenario.
>seeds [long] A list of seeds to set for the runs of this simulation.
>scenarioData object true Key value pairs of ticks to the inputs to set for those ticks. The tick `0` corrspond to the mode setup
input object

Details of input files to read the scenario data from. The name of the file will be used as the name of the scenarios.

Required if scenarios field isn't present. If scenarios' fields are present, input will be ignored.

>uri string true Path to the files containing the scenario data
output object true Details of the simulation's output
>uri string true This is the root directory that the files generated by the model will be output to. Within this directory, a folder will be created for the entire run named using the uuid of the run (which is returned in the POST response, and a folder will be created for each run of the scenario
customExportMetadata object An object containing custom fields that will be included in the metadata.json file as part of the data output.
config object Key value object of config keys to update with values to update to.

The parameters runs and seeds both controls the number of runs per defined scenarios. However, runs offer no control over the seeds generation. The seeds will be generated using an internal prng. If you wish to control the specific seeds used, then provide the SDK with the seeds parameter.

Only one should be provided. If both are provided but runs does not match seeds' size, an error will be thrown.

Example request body with inline scenario definition

{"modelName": "Simple Credit Card", 
  "output": {"uri": "scenarioFolder" },
  "scenarios":[{
    "name": "myScenario", 
    "runs": 10, 
    "ticks": 20,
    "scenarioData": {
      {
        "0": {"spending": 200},
        "4": {"spending": 100, "interest": 0.04}
      }
    }
  }]
}

Example request body with scenario from input

{"modelName": "Simple Credit Card", 
  "output": {"uri": "scenarioFolder" },
  "input":{"uri": "/path/to/inputFiles"}
}
If a request body has both inline scenario definition and and input path, the input path will be ignored.

Response

Status Meaning Description
200 OK Successfully created. The session ID is returned in a cookie named simudyneSessionID. You need to include this cookie in subsequent get requests.
404 Not Found Simulation not found.

Response Schema

Status Code 200

Name Type Required Description
id string(uuid) true
name string true
description string true
public boolean true
session string(uuid) true simudyneSessionID cookie
kind string true

Example 200 response body

{
  "id": "d7558ad9-3405-4a4c-972a-531a87fdcd27",
  "name": "Game of Life",
  "description":
    "The Game of Life, also known simply as Life, is a cellular automaton devised by the British mathematician John Horton Conway in 1970.",
  "public": false,
  "session": "760b2d3e-20b2-42e6-9655-58e662e79e73",
  "kind": "pojo"
}

Status Code 404

Name Type Required
message string true

Example 404 response body

{
    "message": "SimulationRegistry: Could not find requested simulation default."
}