OpenMpp Quick Start OpenM Developer - openmpp/openmpp.github.io GitHub Wiki

Where is OpenM++

It is recommended to start from desktop version of openM++, not a cluster (MPI) version.

You need to use cluster version of openM++ to run the model on multiple computers in your network, in cloud or HPC cluster environment. OpenM++ is using MPI to run the models on multiple computers. Please check Model Run: How to Run the Model page for more details.

Build on Linux

Tested platforms:

  • Debian stable (12) 11 and 10, MX Linux 23, 21 and 19, Ubuntu 22.04, RedHat 9+
  • g++ >= 8.3
  • (optional) MPI, i.e.: OpenMPI >= 3.1 or MPICH (other MPI implementations expected to work but not tested)
  • (optional) OpenMPI >= 4.0 on RedHat >= 8.3 (OpenMPI was broken on RedHat 8.1)

Note: It does work on most of latest Linux distributions, we just not testing regularly on every Linux version.

It is also occasionally tested on openSUSE, Mint, Manjaro, Solus and others.

It is not supported, but may also work on older versions, for example Ubuntu 20.04, Ubuntu 18.04 and RedHat 8.

Check your g++ --version:

g++ (Debian 8.3.0-6) 8.3.0                 # Debian 10 and MX Linux 19
g++ (Debian 10.2.1-6) 10.2.1 20210110      # Debian 11 and MX Linux 21
g++ (Ubuntu 9.3.0-17ubuntu1~20.04) 9.3.0   # Ubuntu 20.04
g++ (GCC) 8.3.1 20191121 (Red Hat 8.3.1-5) # RedHat 8, Rocky Linux, AlmaLinux

Note: Above output does not include all possible Linux versions and may be outdated, openM++ supports almost any of modern Linux distribution.

To build debug version of openM++:

git clone https://github.com/openmpp/main.git master
cd master/openm/
make
cd ../models/
make

RedHat 8: If want to rebuild omc (OpenM++ compiler) then you will need bison version 3.3+ and flex 2.6+ installed, see details at: Setup Development Environment. It is optional and you can avoid it by rebuilding only openM++ run-time libararies:

git clone https://github.com/openmpp/main.git master
cd master/openm/
make libopenm
cd ../models/
make

To build release version of openM++: make RELEASE=1

To build MPI version of openM++: make OM_MSG_USE=MPI

Note: openM++ binary downloads build as: make RELEASE=1 OM_MSG_USE=MPI

RedHat 8: to build and run MPI version of openM++:

module load mpi/openmpi-x86_64

Of course, you can also use 32bit version of OpenMPI or MPICH.

Build on Windows

Tested platforms:

  • Windows 11, 10, it may also work on Windows 7 (64 and 32 bits), 2016 (64 bit)
  • expected to work on any Windows 7 and above or 2008R2 and above, 32 and 64 bits, not regulary tested
  • Visual Studio 2022 or 2019 (VS 2017 not supported, but may work), including Community Edition
  • (optional) Microsoft MPI SDK Redistributable Package

To build debug version of openM++:

  • checkout from openM++ git using your favorite Git client into C:\SomeDir\ or use command line:
git clone https://github.com/openmpp/main.git SomeDir

  • download and unzip Windows version of bison and flex into C:\SomeDir\bin\.

  • download and unzip sqlite3.exe into C:\SomeDir\bin\.

  • use Visual Studio or MSBuild to build C:\SomeDir\openm\openm.sln solution.

  • to build test model(s), i.e.: NewCaseBased, use Visual Studio or MSBuild: C:\SomeDir\models\NewCaseBased\NewCaseBased-ompp.sln.

To build MPI version of openM++:

<OM_MSG_USE>MPI</OM_MSG_USE>
  • build C:\SomeDir\openm\openm.sln solution.
  • rebuild the model and run it:
    • go to menu: Project -> Properties -> Configuration Properties -> OpenM++
    • change: Build Options -> Grid computing (MPI) -> MPI-enabled Executable (MPI)
    • change: Run Options -> Number of processes to launch -> ....2 or more (depends on your cluster configuration)...
    • change: Run Options -> Run the scenario after build -> Yes
    • Rebuild Model project

At bottom Output window of Visual Studio you will see something like:

1>Model.vcxproj -> C:\SomeDir\models\RiskPaths\ompp\bin\RiskPaths_mpi.exe
1>2021-06-01 20:57:28.146 RiskPaths
1>2021-06-01 20:57:28.146 RiskPaths
1>2021-06-01 20:57:28.146 RiskPaths
1>2021-06-01 20:57:28.163 RiskPaths
........
1>2021-06-01 20:57:28.366 OpenM++ build  : Windows 64 bit Release MPI
1>2021-06-01 20:57:28.367 Parallel run of 4 modeling processes, 1 thread(s) each
........
1>2021-06-01 20:57:28.859 member=3 Simulation progress=100% cases=2000
1>2021-06-01 20:57:28.867 member=3 Simulation summary: cases=2000, events/case=112.9, entities/case=1.0, elapsed=0.453989s
1>2021-06-01 20:57:28.868 member=3 Write output tables - start
1>2021-06-01 20:57:28.873 member=3 Write output tables - finish
1>2021-06-01 20:57:29.233 member=0 Write output tables - finish
1>2021-06-01 20:57:29.919 Writing into aggregated output tables, run: 102
1>2021-06-01 20:57:32.607 Done.
1>2021-06-01 20:57:32.607 Done.
1>2021-06-01 20:57:32.607 Done.
1>2021-06-01 20:57:32.607 Done.
1>Done building project "Model.vcxproj".
========== Rebuild All: 1 succeeded, 0 failed, 0 skipped ==========

Visual Studio MPI model run

Note: binary downloads build with Microsoft MPI SDK and MPI Redistributable.

Note: If you getting build error MSB8036:

C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\Common7\IDE\VC\VCTargets\Platforms\Win32\PlatformToolsets\v141\Toolset.targets(34,5):
error MSB8036: The Windows SDK version 10.0.14393.0 was not found.
Install the required version of Windows SDK or change the SDK version in the project property pages or by right-clicking the solution and selecting "Retarget solution".

then do one of the following:

  • "Retarget solution"
  • use Visual Studio 2019
  • start Visual Studio 2017 Installer (VS 2017 not supported but may work)
    • Modify
    • right column
    • check box Windows 8.1 SDK and UCRT SDK

Build on MacOS

  • Tested on MacOS latest, may work starting from Catalina 10.15 and 11.1+ Big Sur

Check your clang, make, bison, SQLite version:

clang --version
....
Apple clang version 11.0.0 (clang-1100.0.33.12)

make --version
....
GNU Make 3.81

bison --version
....
bison (GNU Bison) 3.8.2

sqlite3 --version
....
3.28.0 2019-04-15 14:49:49

To build debug version of openM++:

git clone https://github.com/openmpp/main.git ompp-main
cd ompp-main/openm/
make
cd ../models/
make

To build release version of openM++: make RELEASE=1

You can also use Xcode ~/ompp-main/openm/openm.xcworkspace.

In order to build omc complier you need to use menu and select Product -> Scheme -> omc

Known issue: Xcode UI does not update check mark on selected scheme To fix it go to Product -> Scheme -> Manage Schemes and use mouse to drag any scheme to move it up or down.

Release version of omc is required in order to build any model other than modelOne.

In order to build and debug modelOne using Xcode please open ~/ompp-main/models/modelOne/modelOne.xcworkspace

Build R package

  • clone from GitHub:
git clone https://github.com/openmpp/R.git ompp-r
  • Windows:
cd C:>C:\ompp-r
"C:\Program Files\R\R-3.4.0\bin\R.exe" CMD build openMpp
  • Linux and MacOS:
cd ompp-r
R CMD build openMpp

Expected output:

* checking for file ‘openMpp/DESCRIPTION’ ... OK
* preparing ‘openMpp’:
* checking DESCRIPTION meta-information ... OK
* checking for LF line-endings in source and make files and shell scripts
* checking for empty or unneeded directories
* building ‘openMpp_0.8.3.tar.gz’

Build Go utilities

mkdir $HOME/go-ompp
cd $HOME/go-ompp
export GOPATH=$HOME/go-ompp
git clone https://github.com/openmpp/go ompp-go
  • build Go utilities:
cd $HOME/go-ompp/ompp-go
go install -tags sqlite_math_functions,sqlite_omit_load_extension ./dbcopy
go install -tags sqlite_math_functions,sqlite_omit_load_extension ./oms

After initial checkout first go install command can take ~30 seconds because go needs to get all dependencies.

By default only SQLite model databases supported by dbcopy and oms. If you want to use other databases vendors please compile dbcopy with ODBC enabled:

go install -tags odbc,sqlite_math_functions,sqlite_omit_load_extension ./dbcopy

Currently supported database vendors are: SQLite (default), Microsoft SQL Server, MySql, PostgreSQL, IBM DB2, Oracle. You can use dbcopy utility to copy model data between any of vendors above, for example copy from MySQL to MSSQL or from PostgeSQL to SQLite.

Build UI

Instructions below assuming Windows environment and it is very much identical for Linux and MacOS, except of course, back slashes in directory paths.

cd my-openm-plus-plus-dir
git clone https://github.com/openmpp/UI.git ompp-ui
cd ompp-ui
npm install
  • make sure you have models\bin populated with *.sqlite db files and model executables.
  • it is recommended to have my-openm-plus-plus-dir\etc folder which can be found at openM++ release archive
  • start oms web-service by invoking:
    • ompp_ui.bat on Windows
    • ompp_ui.sh on Linux
    • ompp_ui.command on MacOS
    • or do it in command line:
cd my-openmn-plus-plus-dir
bin\oms -oms.HomeDir models -oms.LogRequest
  • start UI in debug mode:
cd my-openm-plus-plus-dir\ompp-ui
npm run dev
  • open your favorite browser at http://localhost:8080
  • to build UI for production:
cd my-openm-plus-plus-dir\ompp-ui
npm run build
  • copy HTML results folder my-openm-plus-plus-dir\dist\spa\* into my-openm-plus-plus-dir\html\
  • open your favorite browser at http://localhost:4040 and refresh (clear browser cache if required)

*Note: UI is beta version and you need to stop oms web-service in order to update, add or remove model .sqlite db files.

⚠️ **GitHub.com Fallback** ⚠️