Windows Create and Debug Model

Where is OpenM++

• Download desktop version: openmpp_win_YYYYMMDD.zip binary files and source code
• Documentation: Windows: Quick Start for Developers

Before you begin

Download and unzip openM++ Windows desktop binaries into any directory, for example: C:\openmpp_win_20210112\

Create New Model

• create new directory for your model under models subfolder i.e.: C:\openmpp_win_20210112\models\MyModel. It is not required, but recommended to have folder name same as your model name.
• copy one of the test model VC++ project files into your model subfolder, i.e.: from C:\openmpp_win_20210112\models\NewCaseBased\ompp\* into C:\openmpp_win_20210112\models\MyModel\ompp
• copy your model files *.ompp *.mpp and custom.h files into C:\openmpp_win_20210112\models\MyModel\code\ subfolder
• copy your data files *.odat *.dat files into C:\openmpp_win_20210112\models\MyModel\parameters\Default\ subfolder
• start Visual Studio and open C:\openmpp_win_20210112\models\MyModel\ompp\Model.vcxproj project
• save your new Model.sln solution
• build your model

You can set model name of your new model using Visual Studio menu: Project -> Properties -> Configuration Properties -> OpenM++ -> Name -> Model Name: MyModel

Create multiple input sets of parameters (multiple scenarios)

In example above we were creating only one "Default" scenario for our model from *.dat files in parameters/Default directory. It is also possible to create multiple input sets of parameters (multiple scenarios) when you are building the model:

• go to menu: Project -> Properties -> Configuration Properties -> OpenM++
• change: Names -> Scenario Names -> Default;CSV_Values
• Rebuild the project

As result you will create two input sets of parameters in the model.sqlite database:

• scenario "Default" from *.dat, *.odat, *.csv and *.tsv files in ..\parameters\Default directory
• scenario "CSV_Values" from *.csv and *.tsv files in ..\parameters\CSV_Values directory

Please notice: additional scenario directory can contain only CSV or TSV files and not .dat or .odat files.

To find out more about CSV and TSV parameter files please read: How to use CSV or TSV files for input parameters values

Debug your Model

• build your model as described above
• open any model.ompp or *.mpp file and put breakpoint in it
• start debugger
• to inspect model parameters go to Watch tab and do "Add item to watch"

Model run options

As described at Windows: Quick Start for Model Users you can run the model with different options. For example, you can calculate 8 sub-values (a.k.a. sub-samples, members, replicas), use 4 threads and simulate 8000 cases:

MyModel.exe -OpenM.SubValues 8 -OpenM.Threads 4 -Parameter.SimulationCases 8000

You can supply run options as model command line arguments or by using model.ini file:

[OpenM]
SubValues = 8
Threads = 4

[Parameter]
SimulationCases=8000

MyModel.exe -ini MyModel.ini

There are two possible ways to specify model ini-file using Visual Studio menu:

• Project -> Properties -> Configuration Properties -> OpenM++ -> Run Options
  • Model ini file = MyModel.ini
  • Run scenario after build = Yes
• Project -> Properties -> Configuration Properties -> Debugging -> Command Arguments = -ini MyModel.ini

Debug Model with microdata files

If your BestModel is using microdata file(s) then it is possible to start microdata path with environment variable:

  input_csv in_csv;
  in_csv.open("$OM_BestModel/microdata/OzProj22_5K.csv");
  ............

You may need to export that OM_BestModel variable in order to debug the model under Visual Studio. For example, if your model location is: C:\my-models\BestModel then add: OM_BestModel=C:\my-models\BestModel into the model Debugging Environment:

Debug model run-time errors

Model run-time errors cause a model to emit a log message and halt with a non-zero return code. Here's an example of a model run-time error message:

Simulation error: attempt to assign -1 to range REPORT_TIME which has limits [0,200] when current time is 0.000000000000000 in entity_id 1 in or after event TickEvent in simulation member 0 with combined seed 1

Model run-time errors are implemented in OpenM++ using C++ exceptions. C++ exceptions can be trapped by Visual Studio when running a Debug version of a model. If trapped, execution will halt when a run-time error occurs. This allows direct examination of entities, attributes, local variables, etc. in the Visual Studio Debugger to troubleshoot the cause of the error.

To tell Visual Studio to break if a model run-time exception occurs, ensure that <All C++ Exceptions not in this list> is checked in Debug > Windows > Exception Settings:

If a model run-time error occurs in a Visual Studio session with a Debug version of a model, display the call stack window in Visual Studio to identify the model code location which caused the error. In the following screenshot, the call stack entry NewTimeBasedD.exe]!Ticker::TickEvent() Line 79 is the topmost model code entry in the call stack when the run-time error occurred.

Double clicking that call stack entry causes Visual Studio to navigate to the model code line which caused the error. In this example, the line is in the module TickerCore.mpp of the NewCaseBased model which was modified to deliberately cause a run-time error:

void Ticker::TickEvent()
{
    // Increment report time
    report_time = COERCE(REPORT_TIME, report_time + 1);
    report_time = -1;

    // Age all Persons to the current time.
...

In a real situation, values of attributes could be examined in the Visual Studio Debugger, exactly like debugging after a Debug break point is hit.

Debug model c++ code

By default model compiled to debug only *.ompp and *.mpp source code, not a model C++ code. Normally it is enough to debug only *.ompp and *.mpp code but in some exceptional circumstances you may also want to debug model c++ code, generated by openM++ omc compiler.

C++ model files are located in ompp/src directory, for example, if you have openM++ installed in C:\openmpp_win_20210112 directory then model Chapter5 *.cpp and *.h source files are in C:\openmpp_win_20210112\models\Chapter5\ompp\src folder:

In order to debug model c++ code do following:

• go to menu: Project -> Properties -> Configuration Properties -> OpenM++ -> Disable generation of #line directives = Yes

• Rebuild the model project by going to menu Build -> Rebuild Solution
• put debug breakpoints at the om_developer.cpp RunSimulation() or other entry points of your choice, e.g.: om_definitions.cpp RunModel()
• start debugger

Use AddressSanitizer to catch memory violation bugs

Starting from version 16.9 Visual Studio include AddressSanitizer tool which allow to catch most of memory violation bugs. For example:

int x[10];
int main (int argc, char ** argv)
{
    x[20] = 20;  // error: global buffer overflow
    ........
}

If you want to add AddressSanitizer to your existing pre-version 16.9 Visual Studio installation start Visual Studio Installer, choose Modify and select "C++ AddressSanitizer":

To build your model with AddressSanitizer do following:

• exit from Visual Studio
• copy your existing model project to some backup location:

copy C:\openmpp_win_20210112\models\MyModel\ompp\Model.vcxproj* C:\my\safe\place\

• copy AddressSanitizer version of model project. For example if openM++ installed into C:\openmpp_win_20210112 directory and your model directory is MyModel then do:

copy C:\openmpp_win_20210112\props\ompp-asan\Model.vcxproj C:\openmpp_win_20210112\models\MyModel\ompp\
copy C:\openmpp_win_20210112\props\ompp-asan\Model.vcxproj.filters C:\openmpp_win_20210112\models\MyModel\ompp\

• start Visual Studio, open your model openM++ solution C:\openmpp_win_20210112\models\MyModel\MyModel-ompp.sln
• Important: clean existing model build. You can do it by Menu -> Build -> Clean Solution
• build your model

Now you can run your model from Visual Studio as usually, with or without debugger.

To run model.exe with AddressSanitizer from command line (outside of Visual Studio) use VS 2019 Native Tools command prompt:

• open command line prompt
• set 64 or 32 bit environment:
  • "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat"
  • "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars32.bat"
• run your model.exe:

cd \openmpp_win_20210112\models\MyModel\ompp\bin
MyModel64D.exe

Restore your original Model project from C:\my\safe\place\Model.vcxproj* after you done with AddressSanitizer.