stateline

Stateline is a framework for distributed Markov Chain Monte Carlo (MCMC) sampling written in C++11. It focuses on parallel tempering methods which are highly parallelisable.

System Support

Currently, Stateline runs on Linux-based operating systems only, though there is also a Dockerfile.

Compiler Support

Stateline has been compiled and tested under g++ 4.8.2.

Prerequisites

Stateline requires the following libraries as prerequisites:

• Boost 1.55
• Eigen 3.2.0
• google-log (glog) 0.3.3
• google-test (gtest) 1.7.0
• zeromq 4.0.3
• cppzeromq 2358037407 (commit hash)
• nlohmann json (commit 58d7342)

Building

The simplest way to get Stateline running is to run the fetch-all.sh script in the project root directory:

$ git clone https://github.com/NICTA/stateline.git
$ cd stateline && ./fetch-all.sh
$ cd build/debug && make

This will automatically download and build the necessary dependencies into a build folder. It will also create and configure separate folders for debug and release builds. If you want to do a release build, just run make in the release build folder instead. There are also more advanced build instructions.

Communications

By default, Stateline workers communicate with the sever on port 5555. Keep this port open or exposed on the Docker containers.

Running C++ Demo

To see Stateline in action, open two terminals and run the following commands in a build directory:

Run the Stateline server in Terminal 1:

$ ./stateline --config=cpp-demo-config.json

Run a Stateline worker in Terminal 2:

$ ./demo-worker

Now, in your build directory, you should see a folder called cpp-demo-chains. This folder contains samples from the demo MCMC. Running

$ python vis.py cpp-demo-output/0.csv

will launch a Python script that visualises the samples of the first chain. You'll need NumPy and the excellent triangle-plot module.

Running Python Demo

There is also a demo in Python, which shows how workers written in other languages can interact with the Stateline server. Again, open two terminals and run the following commands in a build directory:

Run the Stateline server in Terminal 1:

$ ./stateline --config=python-demo-config.json

Run a Stateline worker in Terminal 2:

$ python demo-worker.py

And again, running

$ python vis.py python-demo-output/0.csv

will launch a Python script that visualises the samples of the first chain.

Documentation

Documentation can be found in the wiki, and there is automatic doxygen documentation generated by running

$ make doc

in a build directory. Please ensure Doxygen is installed. Finally, there are demos for python and C++ in the src/bin folder.

Licence

Please see the LICENSE file, and COPYING and COPYING.LESSER.

Bug Reports

If you find a bug, please open an issue.

Contributing

Contributions and comments are welcome. Please read our style guide before submitting a pull request.