/api/simulations/scenario

Last updated on 16th July 2024

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
>format	string		Output data format. Options are parquet or json, defaults to json.
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, 
    "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."
}

Scenario Rest API /api/simulations/scenario/{id}