Revision 55ef78b5da2904eeed9088a0262a3f88750da489 authored by RJB Goudie on 08 October 2020, 08:43:51 UTC, committed by GitHub on 08 October 2020, 08:43:51 UTC
1 parent 5ab9dea
README.md
# MultiBUGS <a href="https://www.multibugs.org"><img src="https://www.multibugs.org/images/logo.svg" align="right" width = 130></a>
[MultiBUGS](https://www.multibugs.org) implements a simple, automatic algorithm for parallelising Markov chain Monte Carlo (MCMC) algorithms for posterior inference of Bayesian hierarchical models. It builds on the existing algorithms and tools in [OpenBUGS](http://www.openbugs.net/), and so is applicable to the broad range of statistical models that can be fitted using BUGS-language software, but automatically parallelises the MCMC algorithm to dramatically speed up computation. This makes modern multi-core computing accessible to applied statisticians, without requiring any experience of parallel programming.
See the [MultiBUGS website](https://www.multibugs.org) for further details.
## Contents
- [Citation](#citation)
- [Installation](#installation)
- [Pre-built unstable binaries](#pre-built-unstable-binaries)
- [Compiling from source](#compiling-from-source)
## Citation
If you use MultiBUGS in your published work, please cite
Goudie, R. J. B., Turner, R. M., De Angelis, D., Thomas, A. (2020) MultiBUGS: A parallel implementation of the BUGS modelling framework for faster Bayesian inference. Journal of Statistical Software, 95(7). [doi:10.18637/jss.v095.i07](https://doi.org/10.18637/jss.v095.i07)
## Installation
See the main [MultiBUGS website](https://www.multibugs.org) for installation instructions of the current released version.
The current released version of MultiBUGS works on Windows (with [Microsoft MPI (MSI-MPI)](https://msdn.microsoft.com/en-us/library/bb524831(v=vs.85).aspx), version >=8.1) or Linux.
## Pre-built unstable development versions
[![Build status](https://ci.appveyor.com/api/projects/status/9ewgftojuttkn9jg/branch/master?svg=true)](https://ci.appveyor.com/project/MultiBUGS/multibugs/branch/master)
### Windows pre-built unstable binaries
We recommend using the stable version from the main [MultiBUGS website](https://www.multibugs.org), but if you want to try out the current unstable version:
1. Download and install [Microsoft MPI (MS-MPI)](https://docs.microsoft.com/en-us/message-passing-interface/microsoft-mpi#ms-mpi-downloads) (v8.1 or newer)
2. Download the [latest `master` branch build of MultiBUGS](https://ci.appveyor.com/api/projects/MultiBUGS/MultiBUGS/artifacts/MultiBUGS.zip?branch=master). Unzip this to, e.g., `C:\Program Files (x86)\MultiBUGS`.
### Linux pre-built unstable binaries
Pre-built unstable Linux binaries available from Azure Pipeline.
## Compiling from source
### Compiling from source on Windows
We recommend using the stable version from the main [MultiBUGS website](https://www.multibugs.org), but if you want to compile the current unstable version from source:
1. Download and install [Microsoft MPI (MS-MPI)](https://docs.microsoft.com/en-us/message-passing-interface/microsoft-mpi#ms-mpi-downloads). Version 8.1 or newer is required, since MultiBUGS uses `MPI_Comm_spawn`. This framework allows running parallel applications on the Windows platform.
2. Download and install [BlackBox 1.7.2](http://blackboxframework.org/index.php?cID=goto-download-page,en-us) from the BlackBox Framework Center. This is the framework that MultiBUGS is written using.
3. Download the [zip archive](https://github.com/MultiBUGS/MultiBUGS/archive/master.zip) of MultiBUGS. Unzip this to, for example, `C:\`
4. Make a new shortcut to the BlackBox.exe file in the newly-installed BlackBox directory (right-click on BlackBox.exe, choose "Create shortcut"). Then, right click the newly-created shortcut, choose "Properties", and choose the "Shortcut" tab. Then add the following text to the `Target` box, with the paths `C:\Program Files (x86)\BlackBox Component Builder 1.7\BlackBox.exe` (path to BlackBox.exe) and `C:\MultiBUGS-master` (path to the MultiBUGS directory) changed to match wherever you installed BlackBox and MultiBUGS:
```
mpiexec -n 1 "C:\Program Files (x86)\BlackBox Component Builder 1.7\BlackBox.exe" /USE "C:\MultiBUGS-master"
```
Then change the `Start in` to match the path to the MultiBUGS directory, e.g.
```
"C:\MultiBUGS-master"
```
You may want to move the shortcut itself to the Desktop to make it easy to access.
5. Double click the shortcut to open MultiBUGS/BlackBox.
6. Within MultiBUGS/BlackBox open `Make.odc`, which is found in the `Developer` directory in the MultiBUGS directory. Click on the `!` beside `DevCompiler.CompileThis`. This will compile MultiBUGS. The compiler will ask you to confirm the creation of many directories: click OK to confirm all of these in turn. Compiling will take a couple of minutes. Once compiling is finished the status bar should say "ok".
7. Close BlackBox/MultiBUGS and then reopen it to complete installation. Note that the first time you compile a model, BlackBox/MultiBUGS will confirm creation of a couple of extra directories. The Windows Firewall may also require you to give BlackBox/MultiBUGS permission: this is needed to allow communication between cores.
8. The shortcut link version will now work. If you would also like to create a self-contained compiled version of MultiBUGS (that doesn't need the BlackBox install) and/or use the `MultiBUGS.exe` executable, follow the following steps:
(a) Within MultiBUGS/BlackBox open `Linking.odc`, which is found in the `Developer` directory in the MultiBUGS directory. Click on the first two `!` buttons in the "How to link MultiBUGS" section in turn. This creates `OpenBUGS.exe`, which `MultiBUGS.exe` needs. (More precisely, `MultiBUGS.exe` is just a wrapper around `OpenBUGS.exe` that handles setting up MPI.)
(b) Next, open up `BugsPackage.odc`, which is within the `Rsrc` folder within the `Bugs` folder in the MultiBUGS directory. This opens up the tool that is used to create the self-contained version of MultiBUGS. The path specifies where MultiBUGS will be installed. The other options specify which files are copied to the self-contained installation. Before clicking `ok` to create the self-contained version it is useful to open the Log window (`Info` menu > `Open log`) to make it easy to monitor progress.
(c) Once this process is complete, `MultiBUGS.exe` within the self-contained version should work, and the BlackBox installation is not required. Note that the first time you compile a model, MultiBUGS will confirm creation of a couple of extra directories.
### Compiling from source on Linux
On Debian/Ubuntu-based systems
1. Install [BlackBox Cross-Platform](https://blackbox.oberon.org/download).
2. Install 32-bit [MPICH](https://www.mpich.org)
```
sudo apt install mpich:i386
```
3. Download the current `master` branch and open BlackBox (`bbcb`).
```
wget https://github.com/MultiBUGS/MultiBUGS/archive/master.tar.gz
tar -xzf master.tar.gz
cd MultiBUGS-master
bbcb
```
4. Within MultiBUGS/BlackBox open `MakeLinux.odc`, which is found in the `Developer` directory in the MultiBUGS directory. Click on the `!` beside `DevCompiler.CompileThis`. This will compile MultiBUGS. Once compiling is finished the status bar should say "ok".
5. Start up MultiBUGS under MPI
```
mpiexec -n 1 bbcb
```
## License
MultiBUGS is licensed under LGPL-3.0 (GNU Lesser General Public License v3.0)
It includes code from:
1. [BlackBox Framework Center](http://blackboxframework.org/)
2-Clause BSD License
```
Copyright (c) 2013 - 2019 BlackBox Framework Center
Copyright (c) 1994 - 2013 Oberon microsystems, Inc., Switzerland.
All rights reserved.
```
2. [BlackBox Cross-Platform](https://github.com/bbcb/bbcp)
2-Clause BSD License
```
Copyright (c) 2017 - 2020 Alexander V. Shiryaev, Ivan A. Denisov,
Igor A. Dehtyarenko, Anton A. Dmitriev
Copyright (c) 2013 - 2019 BlackBox Framework Center
Copyright (c) 1994 - 2013 Oberon microsystems, Inc., Switzerland.
All rights reserved.
```
3. [TAUCS](http://www.cs.tau.ac.il/~stoledo/taucs/)
GNU LGPL (Library or Lesser GNU Public Library)
```
TAUCS Version 2.0, November 29, 2001.
Copyright (c) 2001, 2002, 2003
by Sivan Toledo, Tel-Aviv Univesity, stoledo@tau.ac.il.
All Rights Reserved.
````
![swh spinner](/static/img/swh-spinner.gif)
Computing file changes ...