Oms API POST run the model - openmpp/openmpp.github.io GitHub Wiki
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).