HMC Lab

Andrea Zunino, Lars Gebraad, Andreas Fichtner

HMC Lab is a numerical laboratory for research in Bayesian seismology, written in Python and Julia. Jump to Docker one-command setup.

• Website: https://hmclab.science
• Python documentation: https://python.hmclab.science
• Source code: https://github.com/larsgeb/hmclab
• Docker image: https://hub.docker.com/repository/docker/larsgebraad/hmclab
• Bug reports: https://github.com/larsgeb/hmclab/issues

It provides all the ingredients to set up probabilistic (and deterministic) inverse problems, appraise them, and analyse them. This includes a plethora of prior distributions, different physical modelling modules and various MCMC (and other) algorithms.

In particular it provides prior distributions, physics and appraisal algorithms.

Prior distributions:

• Normal
• Laplace
• Uniform
• Arbitrary composites of other priors
• Bayes rule
• User supplied distributions

Physics:

• Linear equations
• Straight ray tomography
• 3d source location
• 2d elastic full-waveform inversion
• User supplied physics

Algorithms:

• Hamiltonian Monte Carlo (and variations)
• Random Walk Metropolis Hastings
• Stein Variational Gradient Descent
• Gradient descent
• Interfaces to non-linear optimization methods from SciPy
• Animated versions of various algorithms

Docker one-command setup

To get staerting with the tutorial and example notebooks, one can use a single command in Docker. This will pull a Docker image based on the Jupyter Datascience stack. The final container is approximately 5GB.

    docker run -p 9123:9123 larsgebraad/hmclab \
    start-notebook.sh --NotebookApp.token='hmclab'  \
    --NotebookApp.port='9123' --LabApp.default_url='/lab/tree/Home.ipynb'

Then either copy-past the link from your terminal, or navigate manually to http://127.0.0.1:9123/lab/tree/Home.ipynb?token=hmclab.

Online tutorial notebooks

All tutorial notebooks can also be accessed online in a non-interactive fashion. Simply use https://python.hmclab.science or use the following links:

Tutorials:

• Getting started.ipynb
• Tuning Hamiltonian Monte Carlo.ipynb
• Separate priors per dimension.ipynb
• Creating your own inverse problem.ipynb
• Running parallel Markov chains.ipynb

Demos:

• Sampling linear equations
• Sampling sparse linear equations
• Locating quakes on Grimsvötn, Iceland
• Elastic 2d FWI

The long way around: installing the package on your system

For full installation instructions, including creating a proper Python environment, see the installation instructions.

Start with making sure that you have HDF5 or h5py installed properly.

Directly to your environment:

pip install -e git+git@github.com:larsgeb/hmclab.git@master#egg=hmclab

From the project root directory:

pip install -e .

Development dependencies

If you want to develop within this repo, we recommend a few extra packages. They can also be installed using pip.

In Bash:

pip install -e git+git@github.com:larsgeb/hmclab.git@master#egg=hmclab[dev] # from github repo
pip install -e .[dev] # from local clone

... or Zsh (which requires escapes for brackets):

pip install -e git+git@github.com:larsgeb/hmclab.git@master#egg=hmclab\[dev\] # from github repo
pip install -e .\[dev\] # from local clone