Model Run Options

From OpenM++
Jump to: navigation, search

There are many options which control model run, i.e.: number of cases, random generator starting seed, etc. OpenM++ model gets run options in following order:

  • as command line arguments
  • from ini-file (similar to Modgen .sce file)
  • from database run_option and profile_option tables
  • use default values

Each option has unique key string associated with it, i.e. "Parameter.StartingSeed" is model input parameter "StartingSeed", which is most likely, random generator starting seed. You can use this key to specify model parameter on command line, in ini-file or database. For example:

modelOne.exe -Parameter.StartingSeed 123 -ini small.ini

would run "modelOne" model with starting seed = 123 cases and other options from small.ini file.

Note: We recommend to use normal Windows command line cmd.exe. If you are using Windows PowerShell then it may be necessary to put "quotes" around command line options, e.g:

modelOne.exe "-Parameter.StartingSeed" 123 "-ini" "small.ini"

OpenM++ database connection

If database connection string is not specified then model try to open SQLite database OM_MODEL_NAME.sqlite (i.e.: modelOne.sqlite) in current working directory. Default database connection string is:

Database=OM_MODEL_NAME.sqlite; Timeout=86400; OpenMode=ReadWrite;

Please notice, Linux file names are case sensitive and modelOne.sqlite is different from ModelOne.sqlite.

You can specify database connection string as command line argument, i.e.:

modelOne.exe -OpenM.Database "Database=C:\My Model\m1.sqlite; Timeout=86400; OpenMode=ReadWrite;"

Or, more convenient, by using ini-file

modelOne.exe -ini C:\MyModel\small.ini

Following parameters allowed for SQLite database connection:

  • Database - (required) database file name or URI, file name can be empty
  • Timeout - (optional) table lock "busy" timeout in seconds, default=0
  • OpenMode - (optional) database file open mode: ReadOnly, ReadWrite, Create, default=ReadOnly
  • DeleteExisting - (optional) if true then delete existing database file, default: false

Please notice: to run the model you need OpenMode=ReadWrite.

OpenM++ ini-file run options

To specify name of ini-file you can use -s or -ini or -OpenM.OptionsFile key. Please see OpenM++ ini-file format to find out more.

Example of model ini-file:

;
; model parameters
; any scalar model parameter can be specified in [Parameter] section
; or as command line argument or in profile_option table 
;
[Parameter]

;
; random seed value
;
StartingSeed = 16807

;
; base salary is classification parameter
; using enum code "Full" to specify parameter value
; if [OpenM]IdParameterValue=true (see below) then we must use baseSalary=22 instead
;
; baseSalary = Full

; sub-values for model parameters
; if [OpenM].SubValues > 1 then parameters can have sub-values
;
[SubValue]

;
; sub-values of parameter "Member"
; "iota" means create parameter "Member" sub-values as 0,1,...[OpenM].SubValues-1
;
; Member = iota

;
; sub-values of "baseSalary" parameter
; "db" means read sub-values from input working set (read from model database)
; modelOne default input working set has 4 sub-values for "baseSalary" and "salaryFull"
;
; baseSalary = db

;
; sub-values of "salaryFull" parameter
; "csv" means read all sub-values from parameter.csv file
; by default only one sub-value read from csv file
;
; salaryFull = csv

;
; openM++ run options
;
[OpenM]

;
; number of sub-values, default: 1
;
; SubValues = 8

;
; number of modeling processes:
;   default is 1 for desktop (non-MPI) version
;   example of model run on MPI cluster using 1024 modeling processes:
;     mpiexec -n 1024 modelOne -OpenM.TaskName taskOne
; if MPI is used then
;   number of modeling processes = MPI world size
;   number of sub-values per process = total number of sub-values / number of processes
;   if total number of sub-values % number of processes != 0 then remainder calculated at root process
;

;
; max number of modeling threads, default: 1
;
; if number of sub-values per process < number of modeling threads then sub-values run sequentially.
; if more threads specified then sub-values run in parallel.
;
; for example:
;   model.exe -OpenM.SubValues 8 
;   model.exe -OpenM.SubValues 8 -OpenM.Threads 4 
;   mpiexec -n 2 model.exe -OpenM.SubValues 31 -OpenM.Threads 7
;
; Threads = 4

;
; database connection string
;    default database name: model_name.sqlite
;
; Database = "Database=modelOne.sqlite; Timeout=86400; OpenMode=ReadWrite;"
;
Database = "Database=m1.sqlite; Timeout=86400; OpenMode=ReadWrite;"

;
; name of model run results
; if not specified then automatically generated
;
; RunName = my-default-scenario

;
; set id is working set id to get model input parameters
; if working set id specified as run option 
;    then use workset (set id) and workset base run (base run id) as source
;    else use min(set id) as default set of model parameters
;
; SetId = 4

;
; set name is name of working set to get model input parameters
; if working set name specified then it used to get set id
; if set id specified then set name is ignored
;
; SetName = modelOne_other

;
; run id to restart model run (i.e. after power failure)
;
; RestartRunId = 

;
; task id is an id of modeling task
; if modeling task id specified then
; model will run all working sets included into that modeling task
;
; TaskId = 1

;
; task name is name of modeling task
; if task name specified then it used to get task id
; if task id specified then set name is ignored
;
; TaskName = taskOne

;
; task "wait": 
; allow to dynamically append new input data into modeling task
; modeling task not completed automatically
; it is waiting until some external script signal: 
;   UPDATE task_run_lst SET status = 'p' WHERE task_run_id = 1234;
;
; TaskWait = false

;
; task run id to restart modeling task (i.e. after power failure)
;
; TaskRunId = 

;
; profile name to select run options from profile_option database table
; default value = model name
;
; OptionsProfile = modelOne

; convert to string format for float, double, long double, default: %.15g
;
; DoubleFormat = %.15g

;
; path to parameters csv file(s) directory
; if specified then for each parameter where exist param/dir/parameterName.csv
; values from csv file are used to run the model
;
; ParamDir = 

;
; if true then parameter(s) csv file(s) contain enum id's, default: enum code
;
; IdCsv = false

;
; value of scalar parameter(s) can be specified in [Parameter] section (see above)
; or as command line argument -Parameter.Name of model.exe
; if IdParameterValue is true 
; then scalar parameter(s) value is enum id's, default: enum code
;
; IdParameterValue = false

;
; if true then use sparse output to database
;
SparseOutput = true

; if use sparse and abs(value) <= nullValue then value not stored
;
; SparseNullValue       ; sparse null value, you want to keep default = FLT_MIN

; language to display output messages
; default: Windows Control Panel or Linux LANG 
;
; messageLang = en-CA

;
; log settings:
; log can be enabled/disabled for 3 independent streams:
;   console         - cout stream
;   "last run" file - log file with specified name, truncated on every model run
;   "stamped" file  - log file with unique name, created for every model run
;
; "stamped" name produced from "last run" name by adding time-stamp and pid-stamp, i.e.:
;   modelOne.log => modelOne_20120817_160459_0148.1234.log
;
LogToConsole     = true         ; log to console
LogToFile        = true         ; log to file
; LogToStampedFile = false      ; log to "stamped" file
; LogUseTimeStamp  = false      ; use time-stamp in log "stamped" file name
; LogUsePidStamp   = false      ; use pid-stamp in log "stamped" file name
; LogFilePath      = model.log  ; log file path, default = current/dir/modelExeName.log 
; LogNoMsgTime     = false      ; if true then do not prefix log messages with date-time
; LogSql           = false      ; debug only: log sql statements

;
; trace log settings:
; trace can be enabled/disabled for 3 independent streams:
;   console         - cout stream
;   "last run" file - trace file with specified name (default: working set name)
;   "stamped" file  - log file with unique name, created for every model run
;
; "stamped" name produced from "last run" name by adding time-stamp and pid-stamp, i.e.:
;   trace.txt => trace_20120817_160459_0148.1234.txt
;
; TraceToConsole     = true       ; log to console
; TraceToFile        = true       ; log to file
; TraceToStampedFile = true       ; log to "stamped" file
; TraceFilePath      = trace.txt  ; log file path, default: working_set_name.txt
; TraceUseTimeStamp  = true       ; use time-stamp in log "stamped" file name
; TraceUsePidStamp   = true       ; use pid-stamp in log "stamped" file name
; TraceNoMsgTime     = false      ; if true then do not prefix trace messages with date-time

Number of sub-values stored in run_lst.sub_count table:

run_id      model_id    run_name                           sub_count   sub_started  sub_completed  create_dt
----------  ----------  ---------------------------------  ----------  -----------  -------------  ------------------------
11           1           ModelOne 2013-05-30 22:50:29.0447  4           4            4              2013-05-30 22:50:29.0447

<metadesc>OpenM++: open source microsimulation platform</metadesc>