Skip to content

Commit 1a0738f

Browse files
committed
Added non-technical summary to Readme file
1 parent 7b39861 commit 1a0738f

1 file changed

Lines changed: 27 additions & 9 deletions

File tree

README.md

Lines changed: 27 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,30 +2,48 @@
22
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
33

44
# Multigrid Monte Carlo
5-
C++ implementation of multigrid Monte Carlo (MGMC) algorithm. In addition to MGMC, the code also implements sampling based on different Cholesky factorisations as an alternative algorithm.
5+
Implementation of the **Multigrid Monte Carlo (MGMC)** algorithm, a computational technique for sampling from complex probability distributions that arise in high‑dimensional spatial statistics. The code provides a C++ implementation of MGMC alongside alternative classical sampling strategies, supporting experimentation with efficient posterior inference in large scale spatial statistics.
66

7-
## Dependencies
8-
The code requires the [Eigen library](https://eigen.tuxfamily.org/index.php?title=Main_Page) for linear algebra as well as [libconfig](https://hyperrealm.github.io/libconfig/) for parsing configuration files. To install libconfig, clone the [libconfig repository](https://github.com/hyperrealm/libconfig) and build/install it with CMake.
7+
## Goals
8+
Many classical samplers (Gibbs, Cholesky) for high-dimensional probability distributions suffer from serious drawbacks:
99

10-
If possible, Eigen will use [BLAS/LAPACK support](https://eigen.tuxfamily.org/dox/TopicUsingBlasLapack.html) for dense linear algebra, but it will fall back to the non-BLAS/LAPACK version if these libraries are not installed.
10+
- Large autocorrelation times prevent generation of independent samples
11+
- Parallelisation on distributed memory machines can be difficult for Cholesky samplers
12+
- Incorporation of measurements in a Bayesian setting can be challenging.
1113

12-
CholMod is an optional dependency, if it is not found the code falls back to using the Simplicial Cholesky factorisation in Eigen, which is not necessarily slower. Cholmod is available as part of [SuiteSparse](https://people.engr.tamu.edu/davis/suitesparse.html). To prevent the use of CholMod even if it has been installed, set the `USE_CHOLMOD` flag to `Off` during the CMake configure stage.
14+
Multigrid Monte Carlo combines ideas from **multigrid methods**—a class of efficient solvers for large numerical problems—and **Monte Carlo sampling**, a probabilistic approach widely used for exploring high‑dimensional probability distributions. By leveraging multiple scales of computation (coarse to fine), MGMC can significantly reduce the computational cost of sampling in settings where standard methods become expensive. An additional innovation of this project is the support for sampling from posterior distributions.
1315

14-
## Building the code
15-
To compile, create a new directory called `build`. Change to this directory and run
16+
## Features
17+
18+
- Offers a flexible implementation of MGMC and related samplers
19+
- Allows sampling from posterior distributions conditioned on measurements
20+
- Corresponding multigrid solvers can be run alongside samplers to compare convergence properties
21+
- Partial OpenMP acceleration for faster sampling
22+
- Supports configurable experiments with different solvers and sampling approaches
23+
- Enables comparison of performance and statistical behaviour
24+
25+
## Installation
26+
To compile in the subdirectory `build` run
1627

1728
```
18-
cmake ..
29+
cmake -B build
1930
```
2031

2132
to configure, followed by
2233

2334
```
24-
make
35+
cmake --build build
2536
```
2637

2738
to build the code.
2839

40+
## Dependencies
41+
The code requires the [Eigen library](https://eigen.tuxfamily.org/index.php?title=Main_Page) for linear algebra as well as [libconfig](https://hyperrealm.github.io/libconfig/) for parsing configuration files. To install libconfig, clone the [libconfig repository](https://github.com/hyperrealm/libconfig) and build/install it with CMake.
42+
43+
If possible, Eigen will use [BLAS/LAPACK support](https://eigen.tuxfamily.org/dox/TopicUsingBlasLapack.html) for dense linear algebra, but it will fall back to the non-BLAS/LAPACK version if these libraries are not installed.
44+
45+
CholMod is an optional dependency, if it is not found the code falls back to using the Simplicial Cholesky factorisation in Eigen, which is not necessarily slower. Cholmod is available as part of [SuiteSparse](https://people.engr.tamu.edu/davis/suitesparse.html). To prevent the use of CholMod even if it has been installed, set the `USE_CHOLMOD` flag to `Off` during the CMake configure stage.
46+
2947
## Testing the code
3048
To run the unit tests, use
3149

0 commit comments

Comments
 (0)