-
Notifications
You must be signed in to change notification settings - Fork 0
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).
- Windows: Quick Start for Model Users
- Windows: Quick Start for Model Developers
- Linux: Quick Start for Model Users
- Linux: Quick Start for Model Developers
- MacOS: Quick Start for Model Users
- MacOS: Quick Start for Model Developers
- Model Run: How to Run the Model
- MIT License, Copyright and Contribution
- Model Code: Programming a model
- Windows: Create and Debug Models
- Linux: Create and Debug Models
- MacOS: Create and Debug Models
- MacOS: Create and Debug Models using Xcode
- Modgen: Convert case-based model to openM++
- Modgen: Convert time-based model to openM++
- Modgen: Convert Modgen models and usage of C++ in openM++ code
- Model Localization: Translation of model messages
- How To: Set Model Parameters and Get Results
- Model Run: How model finds input parameters
- Model Output Expressions
- Model Run Options and ini-file
- OpenM++ Compiler (omc) Run Options
- OpenM++ ini-file format
- UI: How to start user interface
- UI: openM++ user interface
- UI: Create new or edit scenario
- UI: Upload input scenario or parameters
- UI: Run the Model
- UI: Use ini-files or CSV parameter files
- UI: Compare model run results
- UI: Aggregate and Compare Microdata
- UI: Filter run results by value
- UI: Disk space usage and cleanup
- UI Localization: Translation of openM++
-
Highlight: hook to self-scheduling or trigger attribute
-
Highlight: The End of Start
-
Highlight: Enumeration index validity and the
index_errors
option -
Highlight: Simplified iteration of range, classification, partition
-
Highlight: Parameter, table, and attribute groups can be populated by module declarations
- Oms: openM++ web-service
- Oms: openM++ web-service API
- Oms: How to prepare model input parameters
- Oms: Cloud and model runs queue
- Use R to save output table into CSV file
- Use R to save output table into Excel
- Run model from R: simple loop in cloud
- Run RiskPaths model from R: advanced run in cloud
- Run RiskPaths model in cloud from local PC
- Run model from R and save results in CSV file
- Run model from R: simple loop over model parameter
- Run RiskPaths model from R: advanced parameters scaling
- Run model from Python: simple loop over model parameter
- Run RiskPaths model from Python: advanced parameters scaling
- Windows: Use Docker to get latest version of OpenM++
- Linux: Use Docker to get latest version of OpenM++
- RedHat 8: Use Docker to get latest version of OpenM++
- Quick Start for OpenM++ Developers
- Setup Development Environment
- 2018, June: OpenM++ HPC cluster: Test Lab
- Development Notes: Defines, UTF-8, Databases, etc.
- 2012, December: OpenM++ Design
- 2012, December: OpenM++ Model Architecture, December 2012
- 2012, December: Roadmap, Phase 1
- 2013, May: Prototype version
- 2013, September: Alpha version
- 2014, March: Project Status, Phase 1 completed
- 2016, December: Task List
- 2017, January: Design Notes. Subsample As Parameter problem. Completed
GET Model Metadata
- GET model list
- GET model list including text (description and notes)
- GET model definition metadata
- GET model metadata including text (description and notes)
- GET model metadata including text in all languages
GET Model Extras
GET Model Run results metadata
- GET list of model runs
- GET list of model runs including text (description and notes)
- GET status of model run
- GET status of model run list
- GET status of first model run
- GET status of last model run
- GET status of last completed model run
- GET model run metadata and status
- GET model run including text (description and notes)
- GET model run including text in all languages
GET Model Workset metadata: set of input parameters
- GET list of model worksets
- GET list of model worksets including text (description and notes)
- GET workset status
- GET model default workset status
- GET workset including text (description and notes)
- GET workset including text in all languages
Read Parameters, Output Tables or Microdata values
- Read parameter values from workset
- Read parameter values from workset (enum id's)
- Read parameter values from model run
- Read parameter values from model run (enum id's)
- Read output table values from model run
- Read output table values from model run (enum id's)
- Read output table calculated values from model run
- Read output table calculated values from model run (enum id's)
- Read output table values and compare model runs
- Read output table values and compare model runs (enun id's)
- Read microdata values from model run
- Read microdata values from model run (enum id's)
- Read aggregated microdata from model run
- Read aggregated microdata from model run (enum id's)
- Read microdata run comparison
- Read microdata run comparison (enum id's)
GET Parameters, Output Tables or Microdata values
- GET parameter values from workset
- GET parameter values from model run
- GET output table expression(s) from model run
- GET output table calculated expression(s) from model run
- GET output table values and compare model runs
- GET output table accumulator(s) from model run
- GET output table all accumulators from model run
- GET microdata values from model run
- GET aggregated microdata from model run
- GET microdata run comparison
GET Parameters, Output Tables or Microdata as CSV
- GET csv parameter values from workset
- GET csv parameter values from workset (enum id's)
- GET csv parameter values from model run
- GET csv parameter values from model run (enum id's)
- GET csv output table expressions from model run
- GET csv output table expressions from model run (enum id's)
- GET csv output table accumulators from model run
- GET csv output table accumulators from model run (enum id's)
- GET csv output table all accumulators from model run
- GET csv output table all accumulators from model run (enum id's)
- GET csv calculated table expressions from model run
- GET csv calculated table expressions from model run (enum id's)
- GET csv model runs comparison table expressions
- GET csv model runs comparison table expressions (enum id's)
- GET csv microdata values from model run
- GET csv microdata values from model run (enum id's)
- GET csv aggregated microdata from model run
- GET csv aggregated microdata from model run (enum id's)
- GET csv microdata run comparison
- GET csv microdata run comparison (enum id's)
GET Modeling Task metadata and task run history
- GET list of modeling tasks
- GET list of modeling tasks including text (description and notes)
- GET modeling task input worksets
- GET modeling task run history
- GET status of modeling task run
- GET status of modeling task run list
- GET status of modeling task first run
- GET status of modeling task last run
- GET status of modeling task last completed run
- GET modeling task including text (description and notes)
- GET modeling task text in all languages
Update Model Profile: set of key-value options
- PATCH create or replace profile
- DELETE profile
- POST create or replace profile option
- DELETE profile option
Update Model Workset: set of input parameters
- POST update workset read-only status
- PUT create new workset
- PUT create or replace workset
- PATCH create or merge workset
- DELETE workset
- POST delete multiple worksets
- DELETE parameter from workset
- PATCH update workset parameter values
- PATCH update workset parameter values (enum id's)
- PATCH update workset parameter(s) value notes
- PUT copy parameter from model run into workset
- PATCH merge parameter from model run into workset
- PUT copy parameter from workset to another
- PATCH merge parameter from workset to another
Update Model Runs
- PATCH update model run text (description and notes)
- DELETE model run
- POST delete model runs
- PATCH update run parameter(s) value notes
Update Modeling Tasks
Run Models: run models and monitor progress
Download model, model run results or input parameters
- GET download log file
- GET model download log files
- GET all download log files
- GET download files tree
- POST initiate entire model download
- POST initiate model run download
- POST initiate model workset download
- DELETE download files
- DELETE all download files
Upload model runs or worksets (input scenarios)
- GET upload log file
- GET all upload log files for the model
- GET all upload log files
- GET upload files tree
- POST initiate model run upload
- POST initiate workset upload
- DELETE upload files
- DELETE all upload files
Download and upload user files
- GET user files tree
- POST upload to user files
- PUT create user files folder
- DELETE file or folder from user files
- DELETE all user files
User: manage user settings
Model run jobs and service state
- GET service configuration
- GET job service state
- GET disk usage state
- POST refresh disk space usage info
- GET state of active model run job
- GET state of model run job from queue
- GET state of model run job from history
- PUT model run job into other queue position
- DELETE state of model run job from history
Administrative: manage web-service state
- POST a request to refresh models catalog
- POST a request to close models catalog
- POST a request to close model database
- POST a request to delete the model
- POST a request to open database file
- POST a request to cleanup database file
- GET the list of database cleanup log(s)
- GET database cleanup log file(s)
- POST a request to pause model run queue
- POST a request to pause all model runs queue
- PUT a request to shutdown web-service