/api/simulations/model-sampler

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