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.

Currently, Stateline runs on Linux-based operating systems only.

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

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)

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.

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.

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 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.

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

If you find a bug, please open an issue.

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