Linux Create and Debug Model

What do you need

• Download: latest binary files and source code
• Documentation: Linux Quick Start for Developers

Before you begin

• check your g++ --version:

g++ (Debian 12.2.0-14) 12.2.0
g++ (Ubuntu 13.3.0-6ubuntu2~24.04) 13.3.0
g++ (GCC) 11.5.0 20240719 (Red Hat 11.5.0-2)

Optional:

If you want to debug your model then you will need to rebuild openM++ runtime library first as described at Linux Quick Start for Developers

To build and run debug version of the model use desktop (non-MPI) version of openM++:

wget https://github.com/openmpp/main/releases/download/v1.8.3/openmpp_debian_20210304.tar.gz
tar xzf openmpp_debian_20210304.tar.gz
cd openmpp_debian_20210304/openm/
make libopenm

Create new Model

• create new directory for your model under models subfolder i.e.: models/MyModel
• copy other test model makefile into your model folder, copy your model files and data files:

cd openmpp_debian_20210304/models/
mkdir MyModel
cd MyModel
cp ../NewCaseBased/makefile .
mkdir code
cp ~/my_model_sources/*mpp code
cp ~/my_model_sources/*.cpp code
cp ~/my_model_sources/*.h code
mkdir -p parameters/Default
cp ~/my_model_data/*dat parameters/Default

• build your model and "publish" it:

make all publish

• run the model:

cd ompp-linux/bin
./MyModelD
cd ..

Please note: It is recommended (not required) to have directory name exactly the same as model name. Linux file and directory names are case-sensitive and myModel is not the same as 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:

make SCENARIO_NAME=Default,Other OMC_SCENARIO_PARAM_DIR=parameters/Default,parameters/SomeOther all publish

Above command will create two input sets of parameters:

• scenario "Default" from *.dat, *.odat, *.csv and *.tsv files in parameters/Default directory
• scenario "Other" from *.csv and *.tsv files in parameters/SomeOther 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

Use AddressSanitizer to catch memory violation bugs

There is an excellent 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
    ........
}

It is not recommended to use AddressSanitizer in production, it slows down model code execution approximately by 70% and double memory usage. For that reason openM++ binary release does not enable AddressSanitizer by default and you will need to re-build openM++ run-time libraries to use it for your models testing.

To enable AddressSanitizer for your developement do:

• unpack openM++ release in separate folder, for example: ~/openmpp-asan. It is not recommended to use it in your main development folder
• re-build openM++ run-time library:

cd ~/openmpp-asan
rm -rf lib
rm -rf build

cd openm
make USE_ASAN=1 libopenm
make USE_ASAN=1 RELEASE=1 libopenm

• rebuild your model with AddressSanitizer, for example if your model name is RiskPaths you can build Debug and Release model versions by:

cd ~/ompp-main/models/RiskPaths
make clean-all
make USE_ASAN=1 all publish
make USE_ASAN=1 RELEASE=1 all publish

• and now you can run Debug or Release version of your model:

cd ompp-linux/bin
./RiskPathsD
./RiskPaths

Please notice, Debug version of the model executable is always significantly slower than Release. It is recommended to prepare smaller version of your test scenario to run it with Debug model. Or, maybe adjust some parameters from default scenario, for example:

cd ompp-linux/bin
./RiskPathsD -Parameter.SimulationCases 1234

Debug your Model using Visual Studio Code

Prerequisites:

• install Visual Studio Code
• follow steps described above to create new model

Note: In example below we are using RiskPaths demo model, please replace "RiskPaths" with your actual model name.

Make sure you have GDB, g++, make and other build tools installed on your system. For example on Ubuntu:

sudo apt install sqlite
sudo apt install g++
sudo apt install make
sudo apt install curl
sudo apt install git

For example on RedHat (CentOS):

dnf install gcc-c++
dnf install make
dnf install sqlite
dnf install gdb
dnf install git

Start Visual Studio Code and go to: File -> Open Folder... -> ~/openmpp_debian_20210304/models/RiskPaths

Create build task for your model using menu: Terminal -> Configure Tasks...

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "build-RiskPaths",
            "type": "shell",
            "command": "make all publish",
            "problemMatcher": "$gcc",
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "dependsOrder": "sequence",
            "dependsOn": [
                "build-libopenm",
                "stop-ui-RiskPaths"
            ]
        },
        {
            "label": "build-RiskPaths-release",
            "type": "shell",
            "command": "make RELEASE=1 all publish",
            "problemMatcher": "$gcc",
            "group": "build",
            "dependsOrder": "sequence",
            "dependsOn": [
                "build-libopenm-release",
                "stop-ui-RiskPaths"
            ]
        },
        {
            "label": "start-ui-RiskPaths",
            "type": "shell",
            "command": "../start-model-ui-linux.sh",
            "problemMatcher": []
        },
        {
            "label": "start-ui-RiskPaths-release",
            "type": "shell",
            "command": "RELEASE=1 ../start-model-ui-linux.sh",
            "problemMatcher": []
        },
        {
            "label": "stop-ui-RiskPaths",
            "type": "shell",
            "command": "../stop-model-ui-linux.sh",
            "problemMatcher": []
        },
        {
            "label": "clean-RiskPaths",
            "type": "shell",
            "command": "make clean-all && make RELEASE=1 clean-all",
            "group": "build",
            "problemMatcher": []
        },
        {
            "label": "build-libopenm",
            "type": "shell",
            "command": "make libopenm",
            "options": {
                "cwd": "../../openm"
            },
            "problemMatcher": "$gcc",
            "group": "build"
        },
        {
            "label": "build-libopenm-release",
            "type": "shell",
            "command": "make RELEASE=1 libopenm",
            "options": {
                "cwd": "../../openm"
            },
            "problemMatcher": "$gcc",
            "group": "build"
        }
    ]
}

You also can find file above at ~/openmpp_debian_20210304/models/RiskPaths/.vscode-linux/tasks.json

Some models may require special settings in order to run, for example, you may need to increase ulimit resources for OncSimX model:

        {
            "label": "start-ui-OncoSimX",
            "type": "shell",
            "command": "ulimit -S -s 65536 && ../start-ompp-ui-linux.sh",
            "problemMatcher": []
        },
        {
            "label": "start-ui-OncoSimX-release",
            "type": "shell",
            "command": "ulimit -S -s 65536 && RELEASE=1 ../start-ompp-ui-linux.sh",
            "problemMatcher": []
        },

Create model debug configuration using menu: Debug -> Add Configuration...:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "debug RiskPaths",
            "type": "cppdbg",
            "request": "launch",
            "program": "${workspaceFolder}/ompp-linux/bin/RiskPathsD",
            "args": [],
            "stopAtEntry": false,
            "cwd": "${workspaceFolder}/ompp-linux/bin",
            "environment": [
              { "name": "OM_RiskPaths", "value": "${workspaceFolder}" }
            ],
            "externalConsole": false,
            "MIMode": "gdb",
            "setupCommands": [
                {
                    "description": "Enable pretty-printing for gdb",
                    "text": "-enable-pretty-printing",
                    "ignoreFailures": true
                }
            ]
        }
    ]
}

You also can find file above at ~/openmpp_debian_20210304/models/RiskPaths/.vscode-linux/launch.json

In order to debug *.mpp and *.ompp files as c++ go to menu File -> Preferences -> Settings -> Text Editor -> Files -> Associations -> click on "Edit in settings.json" and add into settings.json:

{
    "files.associations": {
      "*.mpp": "cpp",
      "*.ompp": "cpp"
    }
}

You also can find file above at `~/openmpp_debian_20210304/models/RiskPaths/.vscode-linux/settings.json

Build your model using Terminal -> Run Build Task...

Start model debugging by using Run -> Start Debugging

• open any model.ompp or *.mpp file and put breakpoint in it
• (optional) add breakpoint(s) at RunSimulation entry point using File -> Open File... -> use/case_based/case_based_common.ompp -> RunSimulation()
• (optional) you may also add breakpoint(s) at main entry point: File -> Open File... -> openm/libopenm/main.cpp
• open model with UI by using Terminal -> Run Task... -> start-ui-RiskPaths. You can see UI screenshots at UI: openM++ user interface page.

To inspect model parameters add Watch variable:

View Doxygen comments on hover your Model code in Visual Studio Code

It is a convenient to see Doxygen comments in your model code when you hover:

If such functionality does not work for you then it maybe a result of missing include path in your c++ model settings. To fix it find a missing (red underscored) include, in example below it is #include "omc/omSimulation.h" and select Quick Fix -> Edit includePath settings:

It should open Microsoft C/C++ extension settings page. Add "${workspaceFolder}/../../include/**" to your Include Path list. It is also a good idea to set C++ standard as c++20:

That can be done by adding .vscode/c_cpp_properties.json to your model folder, but such JSON maybe specific to the particular version of VSCode:

{
    "configurations": [
        {
            "name": "Linux",
            "includePath": [
                "${workspaceFolder}/**",
                "${workspaceFolder}/../../include/**"
            ],
            "defines": [],
            "compilerPath": "/usr/bin/gcc",
            "cStandard": "c17",
            "cppStandard": "c++20",
            "intelliSenseMode": "linux-gcc-x64"
        }
    ],
    "version": 4
}

You also can find file above at ~/openmpp_debian_20210304/models/RiskPaths/.vscode-linux/c_cpp_properties.json

Model run options

As described at Linux 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:

./RiskPathsD -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

./RiskPathsD -ini RiskPathsD.ini

There are two possible ways to use model ini-file with Visual Studio Code:

• by adding -ini RiskPaths.ini command line argument to model executable. Go to menu -> Run -> Open Configurations and edit launch.json at "program" line:

{
    // .... .... ....
    "program": "${workspaceFolder}/ompp-linux/bin/RiskPathsD -ini RiskPaths.ini",
    // .... .... ....
}

• by adding MODEL_INI=RiskPaths.ini command line argument to model make. Go to menu -> Terminal -> Configure Task -> build-RiskPaths and edit tasks.json at "command": "make .... line:

{
    "tasks": [
        {
            "label": "build-RiskPaths",
            "command": "make MODEL_INI=RiskPaths.ini all publish run",
        // .... .... ....
        }]
}

That MODEL_INI argument will be passed to model executable when make run the model as:

ompp-linux/bin/RiskPathsD -ini RiskPaths.ini