Linux Quick Start User - openmpp/openmpp.github.io GitHub Wiki

Where is OpenM++

Download:
- desktop version: binary files and source code openmpp_debian_YYYYMMDD.tar.gz
- cluster version: binary files and source code openmpp_debian_mpi_YYYYMMDD.tar.gz
- Docker image to run openM++ models: openmpp/openmpp-run:debian
Documentation: this wiki

It is recommended to start from desktop version of openM++.

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.

You can use Docker containers to avoid installation of multiple additional components in your host computer. Because all necessary software will be installed in container your host system will be clean.

Run on Linux computer

download and unpack openM++, i.e.:

wget https://github.com/openmpp/main/releases/download/v1.2.0/openmpp_debian_20190508.tar.gz
tar xzf openmpp_debian_20190508.tar.gz

run modelOne model with single subsample on local machine:

cd openmpp_debian_20190508/models/bin/
./modelOne

2017-06-06 19:24:53.0747 modelOne
2017-06-06 19:24:53.0763 Run: 105
2017-06-06 19:24:53.0763 Reading Parameters
2017-06-06 19:24:53.0764 Running Simulation
2017-06-06 19:24:53.0765 Writing Output Tables
2017-06-06 19:24:53.0790 Done.

run modelOne model with 16 subsamples and 4 threads:

./modelOne -OpenM.Subvalues 16 -OpenM.Threads 4

2017-06-06 19:25:38.0721 modelOne
2017-06-06 19:25:38.0735 Run: 106
2017-06-06 19:25:38.0735 Reading Parameters
........................
2017-06-06 19:25:38.0906 Done.

run other models (i.e. NewCaseBased, NewTimeBased, RiskPaths):

./NewCaseBased -OpenM.Subvalues 32 -OpenM.Threads 4

run RiskPaths model with new parameter value CanDie = true and all other parameter values the same as in previous model run:

RiskPaths -Parameter.CanDie true -OpenM.BaseRunId 102

2020-08-14 17:27:48.574 RiskPaths
2020-08-14 17:27:48.610 Run: 103
2020-08-14 17:27:48.618 Sub-value: 0
2020-08-14 17:27:48.628 member=0 Simulation progress=0% cases=0
........................
2020-08-14 17:27:54.883 Done.

run modelOne to compute modeling task "taskOne":

./modelOne -OpenM.Subvalues 16 -OpenM.Threads 4 -OpenM.TaskName taskOne

2017-06-06 19:27:08.0401 modelOne
2017-06-06 19:27:08.0421 Run: 107
2017-06-06 19:27:08.0421 Reading Parameters
........................
2017-06-06 19:27:08.0593 Run: 108
2017-06-06 19:27:08.0593 Reading Parameters
........................
2017-06-06 19:27:08.0704 Writing Output Tables
2017-06-06 19:27:08.0812 Done.

in case if previous model run fail, for example, due to power outage, then it can be "restarted":

./modelOne -OpenM.RestartRunId 1234

output may vary depending on the stage where previous modelOne run failed, but still similar to above.

Run on multiple computers over network, in HPC cluster or cloud

make sure you have MPI run-time installed and ready to use. For example, on RedHat you may need to load it by following commands:

module load mpi/openmpi-x86_64

As an alternative to MPI installation you can pull Docker image docker pull openmpp/openmpp-run:debian to run models inside the container (see below).

download and unpack cluster version of openM++, i.e.:

wget https://github.com/openmpp/main/releases/download/v1.2.0/openmpp_debian_mpi_20190508.tar.gz
tar xzf openmpp_debian_mpi_20190508.tar.gz

please notice name of cluster version archive has mpi in it, i.e. openmpp_debian_mpi_20190508.tar.gz

run modelOne model with single subsample on local machine:

cd openmpp_debian_mpi_20190508/models/bin/
./modelOne_mpi

2017-06-06 19:30:52.0690 Run: 105
2017-06-06 19:30:52.0690 Reading Parameters
2017-06-06 19:30:52.0691 Running Simulation
2017-06-06 19:30:52.0691 Writing Output Tables
2017-06-06 19:30:52.0716 Done.

run two instances of modelOne to compute 16 subsamples and 4 threads:

mpiexec -n 2 modelOne_mpi -OpenM.Subvalues 16 -OpenM.Threads 4

2017-06-06 19:43:01.0486 modelOne
2017-06-06 19:43:01.0487 modelOne
2017-06-06 19:43:01.0742 Parallel run of 2 modeling processes, 4 thread(s) each
2017-06-06 19:43:01.0750 Run: 106
2017-06-06 19:43:01.0750 Reading Parameters
2017-06-06 19:43:01.0750 Run: 106
2017-06-06 19:43:01.0750 Reading Parameters
..........
2017-06-06 19:43:01.0800 Writing Output Tables
2017-06-06 19:43:01.0878 Done.
2017-06-06 19:43:01.0880 Done.

run other models (i.e. NewCaseBased, NewTimeBased, RiskPaths):

mpiexec -n 8 NewCaseBased_mpi -OpenM.Subvalues 64 -OpenM.Threads 4

It is recommended to install SLURM or Torque to simplify your computational resources management rather than using mpiexec as above. It is also possible to use Google Cloud, Amazon or even Microsoft Azure cloud where compute nodes available for you on demand.

Run models using Docker container

make sure you have Docker installed, for example, on Ubuntu: sudo apt-get install docker.
pull Docker image:

docker pull openmpp/openmpp-run:debian

image build for user ompp, UID=1999, GID=1999 and you may need to do one of:
- add same user ompp, UID=1999, GID=1999 to your host system and login as user ompp
- or as shown below use environment variables OMPP_* to map your current user name, UID, GID, HOME to container user
download and unpack cluster version of openM++, i.e.:

wget https://github.com/openmpp/main/releases/download/v1.2.0/openmpp_debian_mpi_20200621.tar.gz
tar xzf openmpp_debian_mpi_20200621.tar.gz

please notice name of cluster version archive has mpi in it, i.e. openmpp_debian_mpi_20200621.tar.gz

run modelOne model with single subsample on local machine:

docker run \
  -v $HOME/models/bin:/home/models \
  -e OMPP_USER=models -e OMPP_GROUP=models -e OMPP_UID=$UID -e OMPP_GID=`id -g` \
  openmpp/openmpp-run:debian \
  ./modelOne_mpi

2017-06-06 19:30:52.0690 Run: 105
2017-06-06 19:30:52.0690 Reading Parameters
2017-06-06 19:30:52.0691 Running Simulation
2017-06-06 19:30:52.0691 Writing Output Tables
2017-06-06 19:30:52.0716 Done.

For explanation of:

  -v $HOME/models/bin:/home/models \
  -e OMPP_USER=models -e OMPP_GROUP=models -e OMPP_UID=$UID -e OMPP_GID=`id -g` \

please take a look at User, group, home_directory topic.

run two instances of modelOne to compute 16 subsamples and 4 threads:

docker run \
  -v $HOME/models/bin:/home/models \
  -e OMPP_USER=models -e OMPP_GROUP=models -e OMPP_UID=$UID -e OMPP_GID=`id -g` \
  openmpp/openmpp-run:debian \
  mpiexec -n 2 modelOne_mpi -OpenM.Subvalues 16 -OpenM.Threads 4

2017-06-06 19:43:01.0486 modelOne
2017-06-06 19:43:01.0487 modelOne
2017-06-06 19:43:01.0742 Parallel run of 2 modeling processes, 4 thread(s) each
2017-06-06 19:43:01.0750 Run: 106
2017-06-06 19:43:01.0750 Reading Parameters
2017-06-06 19:43:01.0750 Run: 106
2017-06-06 19:43:01.0750 Reading Parameters
..........
2017-06-06 19:43:01.0800 Writing Output Tables
2017-06-06 19:43:01.0878 Done.
2017-06-06 19:43:01.0880 Done.

run other models (i.e. NewCaseBased, NewTimeBased, RiskPaths):

docker run \
  ....user, UID, GID, HOME.... \
  openmpp/openmpp-run:debian \
  mpiexec -n 8 NewCaseBased_mpi -OpenM.Subvalues 64 -OpenM.Threads 4