README

About

This is the main repository for the Devs Ex Machina ('dxex') simulator, a PythonPDEVS inspired C++ PDEVS simulation engine supporting conservative and optimistic synchronization. Models written for dxex can be written agnostic of the runtime synchronization protocol. A quick overview of features:

High performance (P)DEVS simulation engine (see publications folder for results)
Extensible Tracing module, output to Json, XML, ... . Custom tracers supported. (compile time optional)
High performance logging framework (compile time optional)
Visualisation and internal tracing of a simulation (compile time optional)
Implemented in standard C++ (C++11, C++14 optional) for maximum portability.

For a more in depth review of the design and features we refer you the to publications.

Publications

If you want to cite this project, kindly use the following bibtex

#!tex
@inproceedings{Dxex,
    author                  = {Cardoen, Ben and
                               Manhaeve, Stijn and
                               Tuijn, Tim and
                               Van Tendeloo, Yentl and
                               Vanmechelen, Kurt and
                               Vangheluwe, Hans and
                               Broeckhove, Jan},
    title                   = {Performance Analysis of a {PDEVS} Simulator Supporting Multiple Synchronization Protocols},
    booktitle               = {Proceedings of the 2016 Symposium on Theory of Modeling and Simulation - DEVS},
    series                  = {TMS/DEVS '16, part of the Spring Simulation Multi-Conference},
    month                   = APR,
    pages                   = {614 -- 621},
    year                    = {2016},
    location                = {Pasadena, CA, USA},
    publisher               = {Society for Computer Simulation International},
}

All benchmark data used in the conference paper can be found in

Rscript/data
publications/Springsim2016/final_libreoffice_plots.ods

For the journal paper (under review), the relevant data can be found in

publications/Journal/fig/plots.ods

License

This project is licensed under the EUPL, see COPYING.txt Copyright 2014-2016 University of Antwerp This project uses GTest, GPerftools, TRNG and includes their sources, see their respective licenses for details.

Requirements

CMake >= 2.8.8
Boost >= 1.57
g++ >= 4.8 , clang++ >= 3.4 (versions of GCC up to 6.1 are supported)
*Nix environment (Linux, Cygwin, MacOS). The project is developed on Fedora 24, Linux Mint 17, these are guaranteed to work.

Optional:

Python 3.4 for the benchmark script.
R for the statistical analysis of the benchmarks
Perf (+kernel support) for the profiling/benchmark analysis.
libubsan (clang or g++ should provide this) for leak/race/undefined detection
Valgrind for memory profiling
adevs for comparison

Building & running

$ git clone git@bitbucket.org:bcardoen/devs-ex-machina.git
$ cd devs-ex-machina
$ ./setup.sh OPTIONS

To find all options of the setup script:

$ ./setup.sh -h
$ cd ./build/Release/
$ make TARGET OPTIONS

A list of targets:

dxexmachina
dxexmachina_devstone
dxexmachina_interconnect
dxexmachina_phold
dxexmachina_pholdtree

PDEVS can be activated using

./setup.sh -x "-DPDEVS=ON"

Extra configuration is possible using the macro "-DPDEVS_THREADS=x"

Note that at this point, only Clang and g++ are supported (with stringname : g++ , clang++)

The script makes a new directory build, next to directory main. This build directory will contain directories Debug, Release and Benchmark. Each with different compiler options and macros.

Hotswap

Dxex supports runtime switching of synchronization protocols. This is available in branch hotswap, see file main/src/test/hotswaptest.cpp for an example on how to use this feature

IDE Support

Eclipse

Optionally, you can open the project in Eclipse (provided you have the CDT plugin):

File > Import > General > Existing Projects into Workspace
Select the clone directory (containing main, build)
CMake has preconfigured all compile/link settings for you.

NetBeans (version >= 7.0 with C++ support)

File > New Project > C++ Project with existing sources
Select the devsexmachina/build/{Debug|Release|Benchmark|BenchmarkFrng} as root folder
The remainder of configuration can be left at default, NetBeans will use the make files generated by CMake
Optionally, select 'custom' for configuration mode and add "-j {nrcores*2}" in "Build Actions after "Build Command"
NetBeans will build the project and parse the source code, depending on which build you selected (default = dxexmachina kernel) you will have full IDE support for the project (Code completion, refactoring etc... .)

Benchmarking

All benchmark data used in the conference paper can be found in

Rscript/data
publications/Springsim2016/final_libreoffice_plots.ods

First, to be able to build our adevs models the source of adevs is required. Create a file in {project_root}/main named "localpreferences.txt" where you can inform CMake of adevs' path :
set(ADEVS_ROOT mypath)

If you wish to run different benchmarks and save the performance results in .csv files:

$ ./doBenchmark.py

To find all the options of the doBenchmark script:

$ ./doBenchmark.py -h

The memory benchmarks (only if you have at least 8GB RAM) requires a POSIX shell, and valgrind. Each benchmark that is profiled for memory can take up to a factor 100 longer to execute under valgrind, please take this into account. The actual memory usage changes little over time (except with optimistic), so you can manually adjust the runtime in the script should this be required.

$ ./membench.sh

For the 2nd paper, this memory profiling script avoids valgrind.

$ ./membenchvs.sh

The PDEVS comparison benchmarks were run using

$ ./pdevsbench.sh

Windows

Building on Windows is possible using Cygwin 64-bit.

The Cygwin installer will give you the opportunity to install all dependencies. From inside the Cygwin shell you can follow the build instructions above.

Note that the compiler will issue warnings about -fPic having no effect, this is a harmless side-effect.

Note that this project is developed on Linux, we cannot guarantee that the latest development version will build on Cygwin without issues.

Troubleshooting

CMake fails to find dependencies : if Boost is not located where cmake looks for them, make a local file in the root project directory named localpreferences.txt where you put set(BOOST_ROOT{my_path})
After any change to the CMakeLists.txt, remove your build directory to prevent stale CMake configuration files corrupting the build. The setup.sh script is capable of doing this for you.

bencardoen/devs-ex-machina