/api/simulations/scenario

Last updated on 16th July 2024

POST

Creates and run a scenario simulation and returns the 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": 10, 
    "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
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
input	object		Details of input files to read the scenario data from. Required if scenarios field isn't present.
>uri	string	true	Path to files containing scenario data
output	object	true	Details of the simulation's output
>uri	string	true	Path to output scenario data results
>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.

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}/ticks