MultiNest
MultiNest is a Bayesian inference tool which calculates the evidence and explores the parameter space which may contain multiple posterior modes and pronounced (curving) degeneracies in moderately high dimensions.
Install / Use
/learn @rjw57/MultiNestREADME
MultiNest v 2.17 Farhan Feroz, Mike Hobson f.feroz@mrao.cam.ac.uk arXiv:0704.3704 & arXiv:0809.3437 Released Mar 2012
MultiNest Licence
Users are required to accept to the licence agreement given in LICENCE file.
MultiNest library requires lapack library.
The code is MPI compatible. In order to disable the MPI parallelization, remove -DMPI compilation flag.
gfortran compiler:
You might need to use the following flag while compiling MultiNest with gfortran compiler to remove the restriction imposed by gfortran on line length.
-ffree-line-length-none
The subtoutine to begin MultiNest are as follows:
subroutine nestRun(mmodal, ceff, nlive, tol, efr, ndims, nPar, nCdims, maxModes, updInt, Ztol, root, seed, pWrap, feedback, resume, outfile, initMPI, logZero, maxiter, loglike, dumper, context)
logical mmodal !do mode separation? integer nlive !number of live points logical ceff !run in constant efficiency mode double precision tol !evidence tolerance factor double precision efr !sampling efficiency integer ndims !number of dimensions integer nPar !total no. of parameters integer nCdims !no. of parameters on which clustering should be performed (read below) integer maxModes !maximum no. of modes (for memory allocation) integer updInt !iterations after which the output files should be written double precision Ztol !null log-evidence (read below) character(LEN=100) root !root for MultiNest output files integer seed !random no. generator seed, -ve value for seed from the sys clock integer pWrap[ndims] !wraparound parameters? logical feedback !need update on sampling progress? logical resume !resume from a previous run? logical outfile !write output files? logical initMPI !initialize MPI routines?, relevant only if compiling with MPI !set it to F if you want your main program to handle MPI initialization double precision logZero !points with loglike < logZero will be ignored by MultiNest integer maxiter !max no. of iterations, a non-positive value means infinity. MultiNest will terminate if either it !has done max no. of iterations or convergence criterion (defined through tol) has been satisfied loglike(Cube,ndims,nPar,lnew) !subroutine which gives lnew=loglike(Cube(ndims)) dumper(nSamples,nlive,nPar,physLive,posterior,paramConstr,maxloglike,logZ,c) !subroutine called after every updInt*10 iterations with the posterior !distribution, parameter constraints, max loglike & log evidence values integer context !not required by MultiNest, any additional information user wants to pass
likelihood routine: slikelihood(Cube,ndims,nPar,lnew,context)
Cube(1:nPar) has nonphysical parameters scale Cube(1:n_dim) & return the scaled parameters in Cube(1:n_dim) & additional parameters that you want to returned by MultiNest along with the actual parameters in Cube(n_dim+1:nPar) Return the log-likelihood in lnew
dumper routine: dumper(nSamples,nlive,nPar,physLive,posterior,paramConstr,maxloglike,logZ,logZerr,context)
This routine is called after every updInt*10 iterations & at the end of the sampling allowing the posterior distribution & parameter constraints to be passed on to the user in the memory. The argument are as follows:
nSamples = total number of samples in posterior distribution nlive = total number of live points nPar = total number of parameters (free + derived) physLive(nlive, nPar+1) = 2D array containing the last set of live points (physical parameters plus derived parameters) along with their loglikelihood values posterior(nSamples, nPar+2) = posterior distribution containing nSamples points. Each sample has nPar parameters (physical + derived) along with the their loglike value & posterior probability paramConstr(1, 4nPar): paramConstr(1, 1) to paramConstr(1, nPar) = mean values of the parameters paramConstr(1, nPar+1) to paramConstr(1, 2nPar) = standard deviation of the parameters paramConstr(1, nPar2+1) to paramConstr(1, 3nPar) = best-fit (maxlike) parameters paramConstr(1, nPar4+1) to paramConstr(1, 4nPar) = MAP (maximum-a-posteriori) parameters maxLogLike = maximum loglikelihood value logZ = log evidence value logZerr = error on log evidence value context not required by MultiNest, any additional information user wants to pass
The 2D arrays are Fortran arrays which are different to C/C++ arrays. In the example dumper routine provided with C & C++ eggbox examples, the Fortran arrays are copied on to C/C++ arrays.
Tranformation from hypercube to physical parameters:
MultiNest native space is unit hyper-cube in which all the parameter are uniformly distributed in [0, 1]. User is required to transform the hypercube parameters to physical parameters. This transformation is described in Sec 5.1 of arXiv:0809.3437. The routines to tranform hypercube parameters to most commonly used priors are provided in module priors (in file priors.f90).
Checkpointing:
MultiNest is able to checkpoint. It creates [root]resume.dat file & stores information in it after every updInt iterations to checkpoint, where updInt is set by the user. If you don't want to resume your program from the last run run then make sure that you either delete [root]resume.dat file or set the parameter resume to F before starting the sampling.
Periodic Boundary Conditions:
In order to sample from parameters with periodic boundary conditions (or wraparound parameters), set pWrap[i], where i is the index of the parameter to be wraparound, to a non-zero value. If pWrap[i] = 0, then the ith parameter is not wraparound.
Constant Efficiency Mode:
If ceff is set to T, then the enlargement factor of the bounding ellipsoids are tuned so that the sampling efficiency is as close to the target efficiency (set by efr) as possible. This does mean however, that the evidence value may not be accurate.
Sampling Parameters:
The recommended paramter values to be used with MultiNest are described below. For detailed description please refer to the paper arXiv:0809.3437
nPar: Total no. of parameters, should be equal to ndims in most cases but if you need to store some additional parameters with the actual parameters then you need to pass them through the likelihood routine.
efr: defines the sampling efficiency. 0.8 and 0.3 are recommended for parameter estimation & evidence evalutaion respectively.
tol: A value of 0.5 should give good enough accuracy.
nCdims: If mmodal is T, MultiNest will attempt to separate out the modes. Mode separation is done through a clustering algorithm. Mode separation can be done on all the parameters (in which case nCdims should be set to ndims) & it can also be done on a subset of parameters (in which case nCdims < ndims) which might be advantageous as clustering is less accurate as the dimensionality increases. If nCdims < ndims then mode separation is done on the first nCdims parameters.
Ztol: If mmodal is T, MultiNest can find multiple modes & also specify which samples belong to which mode. It might be desirable to have separate samples & mode statistics for modes with local log-evidence value greater than a particular value in which case Ztol should be set to that value. If there isn't any particularly interesting Ztol value, then Ztol should be set to a very large negative number (e.g. -1.d90).
Progress Monitoring:
MultiNest produces [root]physlive.dat & [root]ev.dat files after every updInt iterations which can be used to monitor the progress. The format & contents of these two files are as follows:
[root]physlive.dat: This file contains the current set of live points. It has nPar+2 columns. The first nPar columns are the ndim parameter values along with the (nPar-ndim) additional parameters that are being passed by the likelihood routine for MultiNest to save along with the ndim parameters. The nPar+1 column is the log-likelihood value & the last column is the node no. (used for clustering).
[root]ev.dat: This file contains the set of rejected points. It has nPar+3 columns. The first nPar columns are the ndim parameter values along with the (nPar-ndim) additional parameters that are being passed by the likelihood routine for MultiNest to save along with the ndim parameters. The nPar+1 column is the log-likelihood value, nPar+2 column is the log(prior mass) & the last column is the node no. (used for clustering).
Posterior Files:
These files are created after every updInt*10 iterations of the algorithm & at the end of sampling.
MultiNest will produce five posterior sample files in the root, given by the user, as following
[root].txt Compatable with getdist with 2+nPar columns. Columns have sample probability, -2*loglikehood, parameter values. Sample probability is the sa
