Using MultiNest with Monte Python

Monte Python can easily use the implementation of MultiNest by F. Feroz and M. Hobson [1], through the Python wrapper PyMultiNest by J. Buchner [2].

Some hints about why and how to use MultiNest can be found in `A Basic usage and parameters`_. A more thorough description of the MultiNest sampler can be found in the MultiNest papers [1]. The PyMultiNest tutorial is also worth checking out, as well as the respective README files of both MultiNest and PyMultiNest.

Note

By using MultiNest and PyMultiNest, you agree to their respective licenses, that can be found in the LICENSE (or LICENCE) files into the respective installation folders.

Installation

This basically follows the installation procedure in the PyMultiNest documentation.

1. MultiNest

Download MultiNest from here, either using the releases page or cloning with git

$ git clone http://github.com/JohannesBuchner/MultiNest

Note

MultiNest requires the libraries lapack and mpi (optional), and the compilation tool cmake.

We now follow the instructions in the README file to compile:

$ cd /path/to/MultiNest  # Folder where MultiNest was downloaded
$ cd build
$ cmake ..  # -DCMAKE_Fortran_COMPILER=gfortran
$ make

It is not necessary to install (make install), but it is so to add the folder in which the library was installed to the list of paths in which compilers will looll for libraries to link. In Linux (and other systems using a bash shell), this consists simply of adding at the end of the file \home\<your user>\.bashrc the line

export LD_LIBRARY_PATH=/path/to/MultiNest/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}

By default, MultiNest will try to use the Intel Fortran Compiler if installed. If you want to use gfortran instead, add the flag -DCMAKE_Fortran_COMPILER=gfortran to cmake. If you want to force compilation with MPI support (though gfortran should autodetect it and implement it in most systems), use mpif90 as compiler name.

2. PyMultiNest

Note

In a future implementation (hopefully soon), PyMultiNest will be installed automatically. Right now, the installations has to be done manually as it follows.

Download PyMultiNest from here, either using the releases page or cloning with git

$ git clone http://github.com/JohannesBuchner/PyMultiNest

Now go to the installation directory and install:

$ cd PyMultiNest
$ python setup.py install  # --user

You may need the flag --user in the last command if you do not have admin privileges.

If everything went ok, you should be able to run import pymultinest in a python console without getting any output. In that case, you are good to go!

Basic usage and parameters

The MultiNest sampling is invoked with the command line option -m NS. As in the MCMC case, the parameter file is read and the sampling is launched. The output files are created inside a subfolder NS inside the chain folder. This will create the expected log.param file inside the chain’s root folder, and the expected raw MultiNest files in the NS subfolder (see MultiNest’s README), along with two more files: [chain name].paramnames, which contains the ordering of the parameters in the nested sampling chain files (not necessarily the ordering in which they appear in the log.param, since clustering parameters must go first), and [chain name].arguments, which contains the user defined MultiNest arguments and their values (see below).

Note

If the sampling has been interrupted, simply run it again and MultiNest should be able to restart where it finished. If you intend to start a new sampling with different parameters for MultiNest, it is safer to delete the NS subfolder (otherwise, the behaviour is not well defined).

Note

MultiNest can benefit greatly from being run in parallel with MPI. If it has been correctly compiled with MPI (try to run the examples distributed with the MultiNest code with MPI), it is possible to take advantage of it using Monte Python: simply run the sampler python MontePython.py preceded by the appropriate MPI runner (mpirun for Open MPI, mpiexec for MPICH, etc.).

Once the sampling has finished, the output of it can be analised as in the MCMC case with MontePython.py -info [chain_folder]/NS (notice that one must specify the NS subfolder). This will create a chain file in the chain root folder containing the (accepted) points of the nested sampling, and it will be automatically analysed as a MCMC chain, producing the expected files and plots.

The MultiNest parameters are added after the -m NS flag in the command line. They are described in the next section (more thorough descriptions are to be looked for within the MultiNest documentation).

Automatic parameters

(Technical section, you can skip)

The following parameters are defined automatically by the content of the .param file, and you should not care about them:

  • ndims | n_dims : number of varying parameters.
  • nPar | n_params : number of varying parameters.
  • root | outputfiles_basename : prefix of the MultiNest output files: name of the chain plus a hyphen.
  • outfile | write_output : whether to write output files (yes, of course).
  • resume | resume : whether to allow for resuming a previously killed run, enabled by default.
  • initMPI | init_MPI : initialise MPI within MultiNest (disabled: MPI, if requested, is initialised by Monte Python).
  • feedback | verbose (True) : print information periodically.

Manually set parameters

The following parameters can be changed by hand to adjust the sampling to one’s needs. In the following, they are presented as

[MultiNest name] | [PyMultiNest name] (default value)

and are set in every run by command line options as

--NS_[PyMultiNest name] [value]

E.g. to set the number of “live points” to 100, one should add to the command python MontePython.py [...] -m NS the option

--NS_n_live_points 100

Note

The default values are those defined in PyMultiNest (at least most of them), and are not hard-coded in Monte Python.

Note

The parameters not appearing in the following lists are not managed in the current implementation.

General sampling options

  • nlive | n_live_points (400) : number of points used in every iteration.
  • IS | importance_nested_sampling (True) : whether to use Importance Nested Samplin (see arXiv:1306.2144).
  • efr | sampling_efficiency (0.8) : defines the sampling efficiency (see ‘Use cases’ below).
  • ceff | const_efficiency_mode (True) : constant efficiency mode – slower, but more accurate evidence estimation.
  • seed | seed (-1): seed of the random number generator (if negative, uses system clock).
  • logZero | log_zero (-1e90) : if the log-likelihood of a sample is smaller than this value, the sample is ignored.
  • updInt | n_iter_before_update (100) : number of iteration after which the output files are updated.

Ending conditions

  • tol | evidence_tolerance (0.5)
  • maxiter | max_iter (0)

The sampling ends after maxiter iterations, or when the tolerance condition on the evidence defined by tol is fulfilled, whatever happens first.

Multi-modal sampling

  • mmodal | multimodal (False) : whether to try to find separate modes in the posterior.
  • maxModes | max_modes (100) : maximum number of separate modes to consider.
  • Ztol | mode_tolerance (-1e90) : if the local log-evidence is greater than this value, a mode is created.

Note

Here, multi-modal sampling is disabled by default. If enabled, Imporance Nested Sampling will be automatically disabled, since both modes are not compatible.

We left out the option concerning the clustering parameters, i.e. on which parameters’s subspace is MultiNest to look for posterior mode separation:

nCdims | n_clustering_params

In (Py)MultiNest, clustering parameters are specified as the n first ones, which must be at the beginning of the parameters list. Here, instead, we override that limitation, and the clustering parameters are specified as

--NS_clustering_params param1 param2 ...

The reason for doing it this way is giving more flexibility to the user, being able to change the clustering parameters without having to modify the ordering of the parameters in the param file to put the clustering parameters at the beginnig. But this comes at a price: the raw MultiNest chain files have the parameters ordered with the clustering parameters at the beginning, and then the rest as they appear in the .param file. The ordering of the parameters is save to a file [chain name].paramnames in the NS subfolder. If you intend to use MustiNest’s raw output files, you must take this into account! If, instead, you use nested sampling simply as a means to get a covariance matrix and some sample points (saved in chain_NS__[accepted/rejected].txt), you do not need to care about this.