Getting Started

System Requirements

MC3 (version 1.2) is known to work on Unix/Linux (Ubuntu) and OSX (10.9+) machines, with the following software:

• Python (version 2.7)
• Numpy (version 1.8.2+)
• Scipy (version 0.13.3+)
• Matplotlib (version 1.3.1+)
• mpi4py (version 1.3.1+)
• Message Passing Interface, MPI (MPICH preferred)

MC3 may work with previous versions of these software; however, we do not guarantee nor provide support for that.

Install

To obtain the latest MCcubed code, clone the repository to your local machine with the following terminal commands. First, keep track of the folder where you are putting MC3:

topdir=`pwd`
git clone https://github.com/pcubillos/MCcubed

Compile

Compile the C-extensions of the package:

cd $topdir/MCcubed/
make

To remove the program binaries, execute (from the respective directories):

make clean

Example 1 (Interactive)

The following example (demo01) shows a basic MCMC run with MC3 from the Python interpreter. This example fits a quadratic polynomial curve to a dataset. First create a folder to run the example (alternatively, run the example from any location, but adjust the paths of the Python script):

cd $topdir
mkdir run01
cd run01

Now start a Python interactive session. This script imports the necesary modules, creates a noisy dataset, and runs the MCMC:

import sys
import numpy as np
import matplotlib.pyplot as plt
sys.path.append("../MCcubed/")
import MCcubed as mc3

# Get function to model (and sample):
sys.path.append("../MCcubed/examples/models/")
from quadratic import quad

# Create a synthetic dataset:
x = np.linspace(0, 10, 100)          # Independent model variable
p0 = 3, -2.4, 0.5                    # True-underlying model parameters
y = quad(p0, x)                      # Noiseless model
uncert = np.sqrt(np.abs(y))          # Data points uncertainty
error = np.random.normal(0, uncert)  # Noise for the data
data = y + error                     # Noisy data set

# Fit the quad polynomial coefficients:
params = np.array([ 20.0, -2.0, 0.1])  # Initial guess of fitting params.

# Run the MCMC:
posterior, bestp = mc3.mcmc(data, uncert, func=quad, indparams=[x],
                            params=params, numit=3e4, burnin=100)

Outputs

That’s it, now let’s see the results. MC3 will print out to screen a progress report every 10% of the MCMC run, showing the time, number of times a parameter tried to go beyond the boundaries, the current best-fitting values, and corresponding \(\chi^{2}\); for example:

::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  Multi-Core Markov-Chain Monte Carlo (MC3).
  Version 1.2.0.
  Copyright (c) 2015-2016 Patricio Cubillos and collaborators.
  MC3 is open-source software under the MIT license (see LICENSE).
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

Start MCMC chains  (Fri Feb  5 10:45:17 2016)

[:         ]  10.0% completed  (Fri Feb  5 10:45:17 2016)
Out-of-bound Trials:
 [0 0 0]
Best Parameters:   (chisq=111.0541)
[ 3.79473869 -2.73050517  0.51636233]

...

[::::::::::] 100.0% completed  (Fri Feb  5 10:45:18 2016)
Out-of-bound Trials:
 [0 0 0]
Best Parameters:   (chisq=111.0449)
[ 3.77284276 -2.72330815  0.51634107]

Fin, MCMC Summary:
------------------
 Burned in iterations per chain:   100
 Number of iterations per chain:  3000
 MCMC sample size:               29000
 Acceptance rate:   39.04%

 Best-fit params   Uncertainties        S/N      Sample Mean   Note
   3.7728428e+00   3.8407332e-01       9.82    3.7694995e+00
  -2.7233081e+00   2.1964109e-01      12.40   -2.7232216e+00
   5.1634107e-01   2.6891868e-02      19.20    5.1641806e-01

 Best-parameter's chi-squared:     111.0449
 Bayesian Information Criterion:   124.8604
 Reduced chi-squared:                1.1448
 Standard deviation of residuals:  2.93518

At the end of the MCMC run, MC3 displays a summary of the MCMC sample, best-fitting parameters, uncertainties, mean values, and other statistics.

Note

More information will be displayed, depending on the MCMC configuration (see the Tutorial).

Additionally, the user has the option to generate several plots of the MCMC sample: the best-fitting model and data curves, parameter traces, and marginal and pair-wise posteriors (these plots can also be generated automatically with the MCMC run). The plots sub-package provides the plotting functions:

# Plot best-fitting model and binned data:
mc3.plots.modelfit(data, uncert, x, y, title="Best-fitting Model",
                   savefile="quad_bestfit.png")
# Plot trace plot:
parname = ["constant", "linear", "quadratic"]
mc3.plots.trace(posterior, title="Fitting-parameter Trace Plots",
                parname=parname, savefile="quad_trace.png")

# Plot pairwise posteriors:
mc3.plots.pairwise(posterior, title="Pairwise posteriors", parname=parname,
                   savefile="quad_pairwise.png")

# Plot marginal posterior histograms:
mc3.plots.histogram(posterior, title="Marginal posterior histograms",
                    parname=parname, savefile="quad_hist.png")

Note

These plots can also be automatically generated along with the MCMC run (see File Outputs).

Example 2 (Shell Run)

The following example (demo02) shows a basic MCMC run from the shell prompt. To start, create a working directory to place the files and execute the program:

cd $topdir
mkdir run02
cd run02

Copy the demo files to run MC3 (configuration and data files):

cp $topdir/MCcubed/examples/demo02/* .

Call the MC3 executable, providing the configuration file as command-line argument:

mpirun $topdir/MCcubed/MCcubed/mccubed.py -c MCMC.cfg

Note

If you don’t have MPI or dont want to use it, make the previous call as:

python $topdir/MCcubed/MCcubed/mccubed.py -c MCMC.cfg

Noting that, in this last case, you need to have mpi=False.