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.
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).