/api/simulations/model-sampler

Last updated on 16th July 2024

POST

Creates and runs a model sampler simulation and returns the object with its various attributes.

Request

Example request body

curl -X POST \
  http://localhost:8080/api/simulations/model-sampler \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "modelName": "Simple Credit Card",
  "outputPath":"/tmp/sampler",
  "modelSampler": {
      "dimensions": {
        "interest":[0.01,0.02,0.03],
        "spending":{
          "min":100,
          "max":500
          }
      },
      "seeds":[123456, 987645],
      "nbSamples":3,
      "nbTicks":5
  }
}'

Windows user File

Characters need to be escaped when using model sampler 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 model sampler for
outputPath	String	true	Where to output the model sampler data.
modelSampler	object	true	Parameters of the model sampler
>dimensions	object	true	The dimensions that will be used for parameters sampling. The name should correspond the model inner parameters.
>seeds	array		The seeds used for the runs. The size of the array determine the number of runs.
>mcCount	Integer		The number of Monte-Carlo run per sample.
>nbTicks	Integer	true	How long to run each simulation of the model sampler for
>nbSamples	Long	true	The number of samples to create from the dimensions values.

The parameters mcCount and seeds both represents the number of run per sample. However, mcCount 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 mcCount does not match seeds' size, an error will be thrown.

Example request body with inline definition for the model sampler

{
  "modelName": "Simple Credit Card",
  "outputPath":"/tmp/sampler",
  "modelSampler": {
      "dimensions": {
        "interest":[0.01,0.02,0.03],
        "spending":{
          "min":100,
          "max":500
        }
      },
      "seeds":[123456, 987645],
      "nbSamples":3,
      "nbTicks":5
  }
}

Example of a request body with model sampler definition from input

{
  "modelName": "Simple Credit Card",
  "outputPath":"/tmp/sampler",
  "modelSampler": "path/to/input.json"
}

The content of input.json should be the same as the one given in the inline definition.

Dimensions input format

The input for a dimension can either be:

An array of values
A range which the model sampler tool will sample from

When using bounded range, the current method for parameters sampling will be a Latin Hypercube Sampler.

When using arrays of values as inputs, the parameters sets will be built in an iterative manner. As an example, with the following inputs:

{
    "interest":[0.01,0.02,0.03],
    "spending":[100,200,300]
}

The resulting parameters sets for the model would be:

{
    "1": {
      "interest": 0.1,
      "spending": 100
    },
    "2": {
      "interest": 0.2,
      "spending": 200
    },
    "3": {
      "interest": 0.3,
      "spending": 300
    }
}

When working with Spark multi-run, the model sampler file should be on HDFS. Consequentely the path should start with: "hdfs://[...]".

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."
}

Model Sampler Rest API /api/simulations/model-sampler/{id}