Simpact can be used in a number of ways. Besides the core C++ program, which can be run from the command line, there also exists a Python interface and an R interface. The basic Simpact program is a standalone command-line program. To be able to run a simulation, you need to prepare a configuration file, and provide the filename of this file as a command-line argument. However, preparing such a configuration file manually is time-consuming work.
So, to make it easier to prepare and run simulations, there’s a Python module that you can use to control Simpact from Python, or alternatively there’s a R library that you can install in R that provides a similar interface. The Python module is included when you install the Simpact binaries, but the R library must be installed separately from within an R session.

The source code for the core C++ program and the Python interface can be found here, while the source code for the R interface can be found here. Source code packages and pre-compiled versions can be found here.

For more detailed information on configurations, inner workings and more, please visit the documentation page.

 


Running Simpact from the command line

When Simpact has been installed on your system, the executable you will need to call is simpact-cyan-release. You will need to specify three command-line arguments:

  • The path to the configuration file: the configuration file is just a text file containing a list of key/value pairs (e.g. population.simtime = 100). All configuration variables that are needed by the simulation should be set in this file: no default values are assumed by the command line program.
  • Use single- of multicore version: if the single-core version should be used, this should be 0. If multiple cores are to be used, this should be 1.
  • Algorithm to be used: which mNRM algorithm to used. When you specify ‘simple’, the basic algorithm is used, which recalculates all event fire times each time an event is triggered. However, when you specify ‘opt’, an optimized algorithm is used, where only the event fire times of people affected by the firing of an event are recalculated.

So, assuming we’ve created a configuration file called myconfig.txt that resides in the current directory, we could run the corresponding simulation with the following command: simpact-cyan-release myconfig.txt 0 opt.

 


Running Simpact from R

Getting started

Quick getting started and troubleshooting instructions for R users can be found in the R package github repository. To use the R interface, the underlying C++ needs to be installed first. Note that if you’re using MS-Windows, you’ll also need to install the Visual Studio 2015 redistributable package (use the x86 version).
Furthermore, a working Python installation will need to be present on your system. On Linux or OS X, this is usually already available, but if you’re using MS-Windows, you may need to install this separately. In this case, it is best to install it in the default directory, e.g. C:\Python27 or C:\Python34, so that the R package will be able to locate it easily.
Before being able to use the RSimpactCyan module, the library which contains the R interface to the Simpact Cyan program, you need to make sure that other libraries are available. The most straightforward way is to run source(“https://raw.githubusercontent.com/j0r1/RSimpactCyanBootstrap/master/initsimpact.R”) from the command line, which runs a script from RSimpactCyanBootstrap that downloads the required packages.
You can also install the necessary dependencies manually from within R:

  • install.packages(“RJSONIO”)
  • install.packages(“findpython”)
  • install.packages(“rPithon”, repos=”http://research.edm.uhasselt.be/jori”)
  • install.packages(“RSimpactCyan”, repos=”http://research.edm.uhasselt.be/jori”)

After which, you can load the library with the command: library(“RSimpactCyan”).

Running a simulation

When running a simulation from the R interface, default values for all configuration parameters are specified. You will thus only need the specify those parameters for which you want to use a value different from the default value. You can do this using a list: cfg[“population.simtime”] <- 100.
Together with the defaults for other options, these settings will be combined into a configuration file that the underlying C++ program can understand. Taking a look at the full configuration file will show you what other values are in use; to see this configuration file, run simpact.showconfig(cfg). In case you’d want to use a simulation using all defaults, you can either use an empty list, or specify NULL for cfg.
To actually run the simulation, use the command simpact.run. Two parameters must be specified:

  • The configuration to be used
  • A directory where generated files and results are stored

There are also some optional parameters which can be specified here. For more information on these parameters, see the documentation pages.

Other functions

Other functions the R library provides are:

  • simpact.available: this function returns a boolean value, which indicates if the R library is able to find and use the Simpact simulation program.
  • simpact.getconfig: This takes a list with config values as input, similar to simpact.showconfig, merges it with default settings, and returns the extended configuration list. If the second parameter (show) is set to TRUE, then the full configuration file will be shown on-screen as well.
  • simpact.run.direct: This function allows you to start a simulation based on a previously created configuration file. This configuration file must be set as the first argument. Other arguments are optional.
  • simpact.set.datadir: The R library will try to figure out where the needed data files are located. If you want to specify another location, this function can be used to do so.

 


Running Simpact from Python

Getting started

The Python module to control Simpact from within Python is automatically available once you’ve installed the main program. Note that if you’re using MS-Windows, you’ll also need to install the Visual Studio 2015 redistributable package (use the x86 version). To load the Simpact module in a Python script or interactive Python session, just execute import pysimpactcyan.
This allows you to create an instance of the PySimpactCyan class that’s defined in this module: simpact = pysimpactcyan.PySimpactCyan().

Running a simulation

When running a simulation from the Python interface, default values for all configuration parameters are specified. You will thus only need the specify those parameters for which you want to use a value different from the default value. This is done using a dictionary (e.g. cfg[“population.simtime”] = 100).
Together with the defaults for other options, these settings will be combined into a configuration file that the underlying C++ program can understand. Taking a look at the full configuration file will show you what other values are in use; to see this configuration file, run simpact.showConfiguration(cfg). In case you want to use a simulation using all defaults, you can either use an empty dictionary, or specify ‘None’.
To actually run the simulation from within Python, you can use the ‘run’ method of the PySimpactCyan object you’re using. Two parameters must be specified:

  • The configuration to use
  • A directory where generated files and results can be stored

There are also some optional parameters which can be specified here. For more information on these parameters, see the documentation pages.
The return value of the run method contains the paths to generated files and output files.

Other functions

Other functions the Python module provides are:

  • getConfiguration: This takes a dictionary with config values as input, similar to showConfiguration, merges it with default settings, and returns the extended configuration dictionary. If the second parameter (show) is set to True, then the full configuration file will be shown on-screen as well.
  • runDirect: This function allows you to start a simulation based on a previously created configuration file. This config file must be set as the first argument, and is always required.
  • setSimpactDataDirectory: The Python module will try to figure out where the Simpact data files are located. If you want to specify another location, this function can be used to do so.
  • setSimpactDirectory: In case you want to specify that the Simpact C++ executables are located in a specific directory, you can use this function.