Oms API POST run the model

Start new model run.

This is a beta version and may change in the future.

Method:

POST /api/run

For example:

curl -v -X POST -H "Content-Type: application/json" http://localhost:4040/api/run -d @run_modelOne.json

JSON request body: Request body is JSON of following Go structure

{
  ModelName   string            // model name to run
  ModelDigest string            // model digest to run
  RunStamp    string            // run stamp, if empty then auto-generated as timestamp
  Dir         string            // working directory to run the model, if relative then must be relative to oms root directory
  Opts        map[string]string // model run options, e.g.: -OpenM.SubValues 16
  Env         map[string]string // environment variables to set
  Threads     int               // number of modelling threads
  IsMpi       bool              // if true then it use MPI to run the model
  Mpi         struct {
    Np          int    // if non-zero then number of MPI processes
    IsNotOnRoot bool   // if true then do no run modelling threads on MPI root process
    IsNotByJob  bool   // if true then do not allocate resources by job, use CPU, threads and memory as is
  }
  Template  string     // template file name to make run model command line
  Tables    []string   // if not empty then output tables or table groups to retain, by default retain all tables
  Microdata struct {
    IsToDb     bool       // if true then store entity microdata in database: -Microdata.ToDb true
    IsInternal bool       // if true then allow to use internal attributes: -Microdata.UseInternal true
    Entity     []struct { // list of entities and attributes: -Microdata.Person age,income -Microdata.Other All
      Name  string        // entity name
      Attr []string       // list of microdata attributes, it is also can be All
    }
  }
  RunNotes []struct {
    LangCode string   // model language code
    Note     string   // run notes
  }
}

Template is a name of template file inside of etc sub-directory to make model run command line. Template file is required only if you want to run the model on MPI cluster, when Mpi.Np > 0. If template file name not specified then by default it is: etc/mpiModelRun.template.txt.

JSON response example:

{
  "ModelName":      "modelOne",
  "ModelDigest":    "_201208171604590148_",
  "RunStamp":       "2019_01_29_21_02_14_452",
  "SubmitStamp":    "2019_01_29_21_02_14_448",
  "IsFinal":        false,
  "UpdateDateTime": "2019-01-29 21:02:14.452",
  "RunName":        "",
  "TaskRunName":    ""
}

IsFinal: if true then model run failed to start.

RunStamp: model run stamp, use it to GET model run status and log or to PUT stop model run.

Model console output redirected to log file: models/log/modelName.RunStamp.console.log, for example: modelOne.2019_01_29_21_02_14_452.console.log.

INI file path

You can use OpenM.IniFile model run option to specify path to model run ini-file. By default ini file has a name: ModelName.ini and it is located in the same directory where model executable is.

If you wnat to use ini files from your server User Files Directory then please start your ini file path with OM_USER_FILES prefix. For example:

{
  "ModelName":       "modelOne",
  "ModelDigest":     "_201208171604590148_",
  "Opts": {
    "OpenM.IniFile": "OM_USER_FILES/my.ini"
  }
}

Example 1:

Run modelOne.exe with 2 sub-values (sub-value is similar to Modgen "sub-sample"):

{
  "ModelName": "modelOne",
  "Opts": {
    "OpenM.SubValues": "2"
  }
}

Important: Opts values must be a "quoted string". In above JSON number of sub-values is "2" and not 2.

curl -v -X POST -H "Content-Type: application/json" http://localhost:4040/api/run -d @run_modelOne.json

*   Trying ::1...
* TCP_NODELAY set
* Connected to localhost (::1) port 4040 (#0)
> POST /api/run HTTP/1.1
> Host: localhost:4040
> User-Agent: curl/7.54.1
> Accept: */*
> Content-Type: application/json
> Content-Length: 68
>
* upload completely sent off: 68 out of 68 bytes
< HTTP/1.1 200 OK
< Content-Location: /api/model/_201208171604590148_/run/2019_01_29_21_02_14_452
< Content-Type: application/json
< Date: Wed, 30 Jan 2019 02:02:14 GMT
< Content-Length: 188
<
{
  "ModelName":      "modelOne",
  "ModelDigest":    "_201208171604590148_",
  "RunStamp":       "2019_01_29_21_02_14_452",
  "SubmitStamp":    "2019_01_29_21_02_14_448",
  "IsFinal":        false,
  "UpdateDateTime": "2019-01-29 21:02:14.452",
  "RunName":        "",
  "TaskRunName":    ""
}
* Connection #0 to host localhost left intact

Oms web-service execute following command:

./modelOne -OpenM.RunStamp 2019_01_29_21_02_14_452 -OpenM.LogToConsole true -OpenM.SubValues 2

As result modelOne executable started on server with 2 sub-values. Model console output redirected to log file modelOne.2019_01_29_21_02_14_452.console.log:

2019-01-29 21:02:14.469 modelOne
2019-01-29 21:02:14.486 Run: 138
2019-01-29 21:02:14.486 Reading Parameters
2019-01-29 21:02:14.487 Running Simulation
2019-01-29 21:02:14.487 Writing Output Tables
2019-01-29 21:02:14.567 Running Simulation
2019-01-29 21:02:14.567 Writing Output Tables
2019-01-29 21:02:14.622 Done.

Example 2:

Run RiskPaths model in models/work directory:

{
  "ModelName": "RiskPaths",
  "Dir": "models/work",
  "Opts": {
    "OpenM.Database": "Database=../bin/RiskPaths.sqlite;OpenMode=ReadWrite;Timeout=86400;"
  },
  "RunNotes": [{
      "LangCode": "EN",
      "Note": "Model run notes.\n----------------\n\nThis is model run notes in English"
    }, {
      "LangCode": "FR",
      "Note": "(FR) Model run notes.\n---------------------\n\nJe suis désolé je ne parle pas français"
    }
  ]
}

Oms web-service execute following commands:

cd models/work
../bin/RiskPaths \
  -OpenM.RunStamp 2019_01_29_21_32_41_179 \
  -OpenM.LogToConsole true \
  -OpenM.Database Database=../bin/RiskPaths.sqlite;OpenMode=ReadWrite;Timeout=86400; \
  -EN.2019_01_29_21_32_41_179.run_notes.EN.md \
  -FR.2019_01_29_21_32_41_179.run_notes.EN.md

Example 3:

Run RiskPaths_mpi model executable on two nodes of small MPI cluster, 4 threads on each node, to calculate 16 sub-values:

{
  "ModelName": "RiskPaths",
  "Opts": {
    "OpenM.SubValues": "16"
  },
  "Threads": 4,
  "Mpi": {
    "Np": 2
  },
  "Template": "mpiSmallCluster.template.txt"
}

Oms web-service execute following commands:

mpirun -n 2 -wdir models/bin ./RiskPaths_mpi -OpenM.RunStamp 2019_01_29_21_32_10_577 -OpenM.LogToConsole true -OpenM.Threads 4 -OpenM.SubValues 16

Because Mpi.Np = 2 model is executed on MPI cluster. If we do not specify template file name mpiSmallCluster.template.txt then by default etc/mpiModelRun.template.txt will be used.

Example 4:

Run OzProj model, which may required OM_OzProj environment variable:

{
  "ModelName": "OzProj",
  "RunStamp": "My-uniqueStamp-of-OzProj-run",
  "Env": {
    "OM_OzProj": "../../OzProj"
  },
  "Opts": {
    "OpenM.ProgressPercent": "25"
  }
}

Oms web-service execute following commands:

OM_OzProj=../../OzProj ./OzProj -OpenM.RunStamp My-uniqueStamp-of-OzProj-run -OpenM.LogToConsole true -OpenM.ProgressPercent 25

Because RunStamp explicitly specified model console output log file name is: OzProj.My-uniqueStamp-of-OzProj-run.console.log. It is strongly recommended to use unique run stamps for each model run (modeling task run, if you running modeling task).