Simulator

Framework to run mobile network data micro-simulations

!!! Warning !!!

The latest developments of this project can be found at: https://github.com/bogdanoancea/simulator
Code revisions are expected to occur without notice and on a daily basis.
For any question about this software please write at: bogdan.oancea@gmail.com

The project implements a "development of a framework to run mobile network data micro-simulations. These simulations will provide us with synthetic data, useful to test the models. Being a micro-simulation, the estimations can be compared to the real data, unavailable in real life. While a simulation is (no matter how sophisticated) always different from real data, there is really no reason to expect that a model would perform worse for synthetic data than for real data. On the contrary, dealing with real data would be expected to be even more problematic, so a good performance for simulated data should be demanded anyway." (Salgado, D. et al. 2018)

The code is written in C++. To build the application you need a C++ compiler compliant with C++17.

How to build the application under Windows operating system

Building the simulator application on Unix-like systems (Linux, MacOS X, etc.) is straightforward but on Windows this is not a very easy task. That's why I provide here some information about the necessary steps to follow when one wants to build the application on Windows.

Prerequisites

1. MSYS2 environment. MSYS2 is a software distribution and building platform for Windows and it can be freely downloaded from https://www.msys2.org/. Installing MSYS2 is straightforward, detailed instructions are provided on the project's web page mentioned above.

After downloading the MSYS2 installer, run it and select to installation directory.

2. GNU C++ compiler on Windows with MSYS2 While there are a variety of toolchains to build C++ applications on Windows operating system and the most natural choice for Windows seems to be Visual Studio IDE we wanted to avoid proprietary software and use only open source software. This was the main reason why we chose GNU C++ compiler. Besides being open source, it is also available on most used platforms: Linux, MacOS X, Windows etc. The windows port of the GNU C/C++ compiler is called mingw. There are open source IDEs that contain a mingw compiler like CodeBocks or Qt Creator, but in this tutorial I will only show how to build the simulator application from the command line. After you installed MSYS2 use the pacman package manager to update all the packages. In an MSYS2 shell run the following command:
$pacman -Syu

After updating all packages, use pacman again to install the toolchain and C/C++ compiler. Run the command below:
$pacman -S base-devel gcc vim cmake

vim and cmake are optional but good to have them installed. Then, update the system PATH variable by adding the path to the C++ compiler and make utility.

In the following I assume the default location for MSYS2 which is C:\msys64 folder. You can update the PATH variable using the standard Control Panel application provided by Windows. If you intend to use the command prompt, your PATH could be updated using the following command: >setx path C:\msys64\mingw64\bin;C:\msys64\usr\bin;"%path%

Instead, you can use the shell provided by Mingw MSYS2 by running C:\msys64\mingw64.exe which has all required environment variables already set.

3. GEOS C++ library. GEOS is a C++ port of JTS - Java Topology Suite. JTS is an open-source library that provides an object model for Euclidean planar linear geometry and is intended to be used as a core component of vector-based geographical information systems. GEOS contains a subset of functions from JTS.

The current version of the micro-simulator is developed using GEOS ver. 3.7.1. The source code can be downloaded from https://trac.osgeo.org/geos. Instructions how to build the GEOS C++ library are provided here: https://trac.osgeo.org/geos/wiki/BuildingOnUnixWithAutotools Mainly, you have to open a shell by running C:\msys64\mingw64.exe, go to the folder where your source code is located and then type
$ ./configure
$ make
$ make install

Compilation of the GOES library could take several minutes, be patient!.

Build and run the simulation software

Download the source code of the micro-simulator from the github repository : https://github.com/bogdanoancea/simulator Assuming that you want to download the source code in D:\data-simulator folder, open a Git shell in this folder, and then type:
$git clone https://github.com/bogdanoancea/simulator.git
After the source code was downloaded, open makefile.inc with any text editor and change the values of the following 3 variables:
PROJ_HOME
GEOS_HOME
MSYS_HOME

PROJ_HOME should point to the folder where you downloaded the source code of the micro-simulator (for example D:\data-simulator\simulator), GEOS_HOME should point to the folder where you installed GEOS library (for example C:\msys64\mingw64\lib) and MSYS_HOME should indicate the folder where is your MSYS2 development environment. After changing these values, save the file, open an MSYS2 shell (run C:\msys64\mingw64.exe), go to the folder where is your micro-simulator source code and type:
$ make
$ make install

The executable is copied under the Release folder. To run a simulation type the following:
$Release/simulator.exe -m map.wkt -s simulation.xml -a antennas.xml -p persons.xml

We provide sample map.wkt, simulation.xml, antennas.xml and persons.xml configuration files in the root folder of the simulator source code. The output file is prob.csv.

How to build the application under Linux or Mac OS X operating systems

1. Download GEOS C++ library from https://trac.osgeo.org/geos. Build the library by typing:
$ ./configure
$ make
$ make install

If you don't have rights to install the GEOS library to the default location (/usr/local/lib) run the last command as:
$sudo make install

after you installed the library run:
$sudo ldconfig

2. Download the source code of the micro-simulator from the github repository : https://github.com/bogdanoancea/simulator :
$git clone https://github.com/bogdanoancea/simulator.git

After the source code was downloaded, open makefile.inc with any text editor and change the values of the following 2 variables:
PROJ_HOME
GEOS_HOME

PROJ_HOME should point to the folder where you downloaded the source code of the micro-simulator and GEOS_HOME should point to the folder where the GEOS library was installed (usually /usr/local/lib). After changing these values, go to the directory where your micro-simulator source code is located and type the following commands in a shell:
$ make
$ make install

How to run the simulator

In a terminal (command prompt) type:
$Release/simulator -m ./data/dataset1/map.wkt -s ./data/dataset1/simulation.xml -a ./data/dataset1/antennas.xml -p ./data/dataset1/persons.xml -pb ./data/dataset1/probabilities.xml -v

where the following files provide input parameters:
map.wkt is the map of the simulation
simulation.xml is a configuration file containing the parameters of a simulation
antennas.xml is the antennas configuration file
persons.xml is the population configuration file
probabilities.xml is the file containing the parameters need to compute the location probabilities

The location probabilities are computed only if -pb parameter is given in the command line. If -v is given in the command line the simulator will output on console the set of persons, mobile phone operators, antennas and mobile phones.