mpirun -np 4 ./cosmomc params.ini

perl runMPI.pl params 4

If things go wrong check the .log and any error files in your cosmomc/scripts directory.

• Parameter limits and proposal density
  The parameter limits, estimated distribution widths and starting points are listed as the param[paramname] variables for each parameter, of the form

   param[paramname] = center min max start_width propose_width
  

  The start_width entry determines the randomly chosen dispersion of the starting position about the given centre, and should be as large or larger than the posterior (for the convergence diagnostic to be reliable, chains should start at widely separated points). Chains are restricted to stay within the bounds determined by min and max.

  The sampler proposes changes in parameters using a proposal density function with a width determined by propose_width (multiplied by the value of the global propose_scale parameter). The propose_width should be of the order of the conditional posterior width (i.e. the expected error in that parameter when other parameters are fixed). If you specify a propose_matrix (approximate covariance matrix for the parameters), the parameter distribution widths are determined from its eigenvalues instead, and the proposal density changes the parameter eigenvectors. The covariance matrix can be computed using "getdist" once you have done one run - the file_root.covmat file. The planck_covmats/ directory is supplied with many you can use. The covariance matrix does not have to include all the parameters that are used - zero entries will be updated from the input propose widths of new parameters (the propose width should be of the size of the conditional distribution of the parameter - typically quite a bit smaller than the marginalized posterior width; generally too small is better than too large). The scale of the proposal density relative to the covariance is given by the propose_scale parameter. If your propose_matrix is significantly broader than the expected posterior, this number can be decreased.

  If you don't have a propose_matrix, you can use estimate_propose_matrix = T to automatically estimate it by numerical fitting about the best fit point (with action=2 to stop, or action=0 to continue straight into an MCMC run).
  
  

• Sampling method
  Set sampling_method=1 to use a vanilla Metropolis algorithm (in the optimal fast/slow subspaces if use_fast_slow is true). Set sampling_method=7 to use a fast-slow dragging algorithm (Neal 2005), which allows fast nuisance parameters to be handled efficiently; this is the default for Planck runs.

  Other sampling methods that were implemented in previous version have not currently been updated for the latest version.

• CAMB's numerical accuracy
  The default accuracy is aimed at WMAP. Set high_accuracy_default = T to target ~0.1% accuracy on the CMB power spectra from CAMB. This is sufficient for numerical biases to be small compared to the error bar for Planck; for an accuracy study see arXiv:1201.3654. You can also use the accuracy_level parameter to increase accuracy further, however this is numerically inefficient and is best used mainly for numerical stability checks using importance sampling (action=1).
  
  
• Best-fit point
  Set action =2 to just calculate the best-fit point and stop (also outputting a .covmat estimate from the inverse Hessian if estimate_propose_matrix=T). As of Oct 2012 this uses Powell's 2009 BOBYQA bounded minimization routine, which works from two parameters up to hundreds of parameters, but does require that the likelihood return a valid number at all points between the bounds given on the base parameters in the input .ini file. The algorithm starts at the point given by the center parameter values given in the .ini file, and iterates until the parameter values are converged to within a radius of max_like_radius in units of the input parameter propose widths; by default max_like_radius = 0.01. The best-fit values (and derived and nuisance parameters) are output to a file called file_root.minimum. The method works for parameters with hard bounds that truncate the posterior, e.g. for neutrino mass mnu>0. It does not use the propose_matrix, only the input parameter bounds, center and propose_width.
  
  action=2 only runs on one node, so compile without MPI or run only one MPI instance. Note that the minimizer appears not to be totally reliable for Planck (may stop not at the global minimum) - starting at different points can be a good check.
  
  
• Data file output
  Since consecutive points are correlated and the output files can get quite large, you may want to thin the chains automatically: set the indep_sample parameter to determine at what frequency full information is dumped to a binary .data file (which includes the Cls, matter power spectrum, parameters, etc). If zero no .data file is generated. You only need to keep nearly uncorrelated samples for later importance sampling. You can specify a burn_in, though you may prefer to set this to zero and remove entries when you come to process the output samples.
  
  
• Threads and run-time adjustment
  The num_threads parameter will determine the number of openMP threads (in MPI runs, usually set to the number of CPUs on each node). Scaling is linear up to about 8 processors on most systems, then falls off slowly. It is probably best to run several chains on 8 or fewer processors. You can terminate a run before it finishes by creating a file called file_root_NN.read containing "exit =1" - it will read it in, delete the .read file and stop. The .read file can also have "num_threads =xx" to change the number of threads (per chain) dynamically. If you have multiple chains you can create file_root.read which will be read by all the chains. In this case the .read file is not deleted automatically.
  
  
• Post-processing (e.g. importance sampling)
  The action variable determines what to do. Use action=1 to process a .data file produced by a previous MCMC run - this is used for importance sampling with new data, correcting results generated by approximate means, or re-calculating the theoretical predictions in more detail. If action=1 set the redo_xxx parameters to determine what to do. With redo_add=F you should include all the data you want used for the final result (e.g. if you generated original samples with CMB data, also include CMB data when you importance sample - it will not be weighted twice). With redo_add=T you should include only data you want to add - the new likelihoods are added to those already stored in the chains. PostProcessing is fastest if you have binary .data files from an original run, however if you do not have these you can use redo_from_text=T to read in chains from .txt files.
  
  
• Exploring tails and high-significant limits
  The temperature setting allows you to sample from P^(1/T) rather than P - this is good for exploring the tails of distributions, discovering other local minima, and for getting more robust high-confidence error bars. See also the different sampling_methods.
  
  
• Checkpointing
  Set checkpoint = T in the .ini file to checkpoint: i.e. generate files so that if the processes are terminated they can be restarted again from close to where they left off. With MPI this setting creates file_root.chk files used to store the current status. To continue a prematurely terminated run, just run again using exactly the same commands and files as originally. Note that if you use checkpointing, but you want to overwrite existing chains of the same name, you must manually delete all the file_root.* files (otherwise it will attempt to continue from where they left off). Please note this feature is not fantastically well tested, please let us know of any problems. Also note that for checkpointing to work the first run must run for at least past the initial burn phase (you can see when the file_root.chk files have been produced), otherwise the run will just start from scratch again.

    weight like param1 param2 param3 ...

The weight gives the number of samples (or importance weight) with these parameters. like gives -log(likelihood). The getdist program could be used completely independently of the cosmomc program.

Run getdist distparams.ini to process the chains specified in the parameter input file distparams.ini. This should be fairly self-explanatory, in the same format as the cosmomc parameter input file.

GetDist Parameters

• GetDist processes the file_root.txt file (or, if there are multiple chains, set the chain_num parameter), and outputs statistics, marginalized plots, samples plots, and performs PCA (principle component analysis).
  
  
• Set the parameter_names parameter to specify a .paramnames file with the names and labels for parameters corresponding to the various columns in the chain files (see the supplied examples). If this parameter is empty getdist reads the parameters from the file_root.paramnames file that is output when generating the chains. If neither exist parameters are referenced by number, so parameter labels have to be specified in the .ini file (lab1=\Omega_b h^2, etc.).
  
  
• Set ignore_rows to a positive integer to ignore that number of output rows as burn-in, or to a fraction <1 to skip that fraction of each chain's rows.
  
  
• Set the thin_factor parameter to produce a file_root_thin.txt file containing every thin_factorth sample.
  
  
• Set adjust_priors to adjust the sample multiplicities for a new prior (write the corresponding code in GetDist.f90).
  
  
• If you have a derived parameter which has a prior which cuts off when the posterior is non-negligible you need to set the limits[paramname] variables to the corresponding limits - for example r02 for the tensor ratio. Otherwise limits are computed automatically. DO NOT use limits[paramname] to change the bounds on other plots - the program uses the limits information when it is estimating the posteriors from the samples. Limits for base MCMC parameters are set automatically from the .ranges file. When limits[paramname] are used the .margestats file contains one tail statistics - i.e. the lower bound is where 1-x of points are lower and x of the points higher, the upper bound is where 1-x of the points are higher and x lower (usually only one of the limits would be used). If only one end is fixed you can use N the floating end, e.g. "limitsxx = 0 N" for the tensor amplitude which has a greater than zero prior.

  Example: Since many people get this wrong, here is an illustration of what happens when generating plots from a tensor run set of chains (with prior r>0):

  Incorrect result when limits[r02] is not set.

  Correct result when setting limits[r02]=0 N.

  If you are not using parameter names you can set numbered limit parameters, e.g. limits12=0 N for parameter 12.

  You should check that you have set num_bins large enough and that your plots are stable to increasing it. The smooth_scale_1D and smooth_scale_2D parameters can be set to change the smoothing scale with respect to the bin size (or in the 1D case with respect to the posterior width). For smooth_scale_1D:

  • if smooth_scale_1D >= 1 smooth by smooth_scale_1D bin widths
  • if smooth_scale_1D> 0 and <1 smooth by Gaussian of smooth_scale_1D standard deviations in each parameter (around 0.2-0.3 is often good); this gets flat distributions nice and smooth without overly broadening well determined parameters
  • if smooth_scale_1D< 0 uses automatic smoothing length (changes with parameter)-the overall smoothing length is scaled by abs(smooth_scale_1D) from very crude guess at best overall scale

  For 2D plots smooth_scale_2D is the smoothing scale relative to the bin size

Output Text Files

• file_root.margestats file contains the means, standard deviations and marginalized limits for the different parameters (including derived parameters). Limits to calculate are set using the contourxx input parameters.
  
  
• file_root.likestats gives the best fit sample model, its likelihood, and limits from the extremal values of the N-dimensional distribution. Note that MCMC does not generally provide accurate values for the best-fit.
  
  
• file_root.converge contains various convergence diagnostics
  
  
• file_root.PCA contains a principle component analysis (PCA) for PCA_num parameters, specified in PCA_params parameter. You can specify the mapping used with PCA_func, for example 'L' to use logs (what you usually want for positive definite parameters). The output file contains the analysis including the correlation matrix, eigenvectors and eigenvalues, as well as the well constrained parameter combinations and their marginalized errors. This is how you automatically work out constraints of the form param1^a param2^b param3^c ...  = x \pm y.
  
  
• file_root.corr contains parameter correlations
  
  
• file_root.covmat contains a covariance matrix you can use as a proposal matrix for generating future chains
  
  

Plotting

If GetDist produces scripts files to make simple 1D, 2D and 3D plots. These can be either python or matlab, set plot_ext=py or plot_ext=m for which you prefer. The script files produced are called

• file_root for 1D maringalized plots
• file_root_2D for 2D maringalized plots
• file_root_3D to make coloured 2D samples plots
• file_root_tri to make 'triangle' plots (example. Set triangle_plot=T in the .ini file)

• Python plots
  If plot_ext=py GetDist produces python '.py' files. GetDist also produces a set of files in the plot_data directory that can be used by custom python scripts for plotting, independently of the plot_ext scripts described above. See the CosmoMC python readme for details of how to use the plotting library.

• Matlab plots
  If plot_ext=m GetDist produces Matlab '.m' files. Matlab support is not likely to be developed further, but maintained from the previous version for convenience. Type file_root into a Matlab window set to the directory containing the .m files to produce 1D marginalized plots. You can use the blue Matlab script (in the mscripts) directory to change to a B&W-friendly colourmap (see also other colormaps in that directory).
  
  Custom Matlab plots
  Some Matlab scripts are also supplied for making custom Matlab plots using the files produced by GetDist (see also CosmoloGui). The scripts are in the mscripts directory - you will probably want to add this to your Matlab path using e.g. addpath('mscripts'). confid2D makes marginalized contour plots like this. But now the python scripts do this much better and more easily.

Parameter labels are set in distparams.ini - if any are blank the parameter is ignored. You can also specify which parameters to plot, or if parameters are not specified for the 2D plots or the colour of the 3D plots getdist automatically works out the most correlated variables and uses them. The data files used by python and Matlab are output to the plot_data directory.

Convergence diagnostics

• For multiple chains the code computes the Gelman and Rubin "variance of chain means"/"mean of chain variances" R statistic for each parameter using the second half of each chain (reference). The .converge file produced by getdist contains the numbers for each parameter individually. The program also writes out the value for the worst eigenvalue of the covariance of the means, which should be a worst case (catching poor chain coverage in directions not aligned with the base parameters). This "R-1" statistic is also used for the stopping criterion when generating chains with MPI. If the numbers are much less than one then the second half of each chain probably provides an accurate estimate of the means and variances. If the distribution is bimodal and no chains find the second mode low values can be misleading. Typically you want the value to be less than 0.2. Low values do not guarantee that small percentiles will be measured accurately (though it certainly helps), or that the value won't increase as you run longer and probe further into the tails.
  
  
• For MPI runs, in addition to specifying a stopping criterion as above, you can also give a convergence criterion for a confidence limit. In general it is much harder to get an accurate value for a small confidence value than for the mean, so imposing a tight limit may make your chains run for a very long time (though you can then be pretty confident in your confidence). The value computed is the variance of the chain percentiles from the last half of the different chains, in units of the standard deviation of each parameter. You can either specify a particular parameter to check, or do all of them. Any parameter with a slowly explored tail will only converge very slowly, in which case you may be able to improve things by generating chains at a higher temperature (so the tails are explored more readily; GetDist can adjust for the temperature automatically), or re-parameterizing.
  
  
• For individual chains (before importance sampling) getdist computes the Raftery and Lewis convergence diagnostics. This uses a binary chain derived from each parameter depending on whether the parameter is above or below a given percentile of its distribution (specified by the converge_test_limit input parameter). The code works out how much the binary chain needs to be thinned to approximate a Markov process better than a second order process, and then uses analytical results for the convergence of binary Markov chains to assess the burn in period. It also assesses the thin factor needed for the binary chain to approximate an independence chain, which gives an idea of how much you need to thin the chain to obtain independent samples (i.e. how much you can get away with thinning it for importance sampling, though thinning isn't entirely lossless). The .converge file contains the numbers for each chain used, getdist writes out the worst case. See this reference for details.
  
  
• A simpler way to assess the error on quantile limits is by computing them using subsets of the samples. GetDist produces the file_root.converge contains the 'split-test' rms change on the parameter quantiles in units of the standard deviation when the samples are split into 2,3 or 4 parts. Small numbers are clearly better. A number of 0.5 for a 2-way split indicates that the 95% confidence limit may in fact be off by the order of half a standard deviation (though probably better, as the limit is computed using all the samples). Large values in a particular parameter may indicate that there is a long tail that is only being explored slowly (in which case generating the chain at a higher temperature or changing parameters to the log might help).
  
  
• The file_root.converge file also outputs the parameter auto-correlations as a function of step separation (see e.g. astro-ph/0310723). The correlation length is similar to the Raftery&Lewis statistics in giving a measure (though harder to quantify) of how far apart independent samples are, though it is less sensitive to how well the tails are explored (see bad case example in the notes).

Differences between GetDist and MPI run-time statistics

GetDist will cut out ignore_rows from the beginning of each chain, then compute the R statistic using all of the remaining samples. The MPI run-time statistic uses the last half of all of the samples. In addition, GetDist will use all the parameters, including derived parameters. If a derived parameter has poor convergence this may show up when running GetDist but not when running the chain (however the eigenvalues of covariance of means is computed using only base parameters). The run-time values also use thinned samples (by default every one in ten), whereas GetDist will use all of them. GetDist will allow you to use only subsets of the chains.

• params_CMB.f90

This defines what the input variables mean. Change this to use different variables. You can change which parameterization file to use in the Makefile.
• cmbtypes.f90

You can also change the num_cls number of (temperature plus polarization) Cls to compute and store, power spectrum parameter, etc.
• settings.f90

This defines the maximum number of parameters and their types.
• cmbdata.f90

This reads in the CMB .dataset information and computes likelihoods. You may wish to edit this, for example to use likelihood distributions for the band powers, or to compute the likelihood from actual polarized data. This version assumes polarized data points are an arbitrary combination of the raw TT, TE, EE, and BB Cls, as specified in the window files in data/windows. WMAP data is handled as a special case.
• propose.f90

This is the proposal density and related constants and subroutines. The efficiency of MCMC is quite dependent on the proposal. Fast+slow and fast parameter subspaces are proposed separately. See the paper for a discussion of the proposal density and use of fast and slow parameters.
• CMB_Cls_simple.f90

Routines for generating Cls, matter power spectra and sigma8 from CAMB. Replace this file to use other generators, e.g. a fast approximator like CMBfit, DASH, PICO, etc.
• DataLikelihoods.f90
  This is where you can add in new likelihood functions
• postprocess.f90

Reads in .data files and re-calculates likelihoods or theory predictions. Unused in MCMC runs.
• calclike.f90

Calls the data likelihood functions, etc.
• driver.F90

Main program that reads in parameters and calls MCMC or post-processing.
• GetDist.f90

The "getdist" program for analysing chains. Write your own importance weighting function or parameter mapping.

• SDSS DR8 BAO data

• xxx 2013
  
  • Added DR11 BAO module changes and data from SDSS
• December 2013
  
  • Updated BBN module, using interpolation table (from AlterBBN) with updated neutron decay constant and converting from BBN to total mass conventions for Y_P. Uses new Interpolation module with reusable 2D bicubic interpolation class. Changes in Y_P are O(1%) and hence have only tiny effect on other parameters.
  • Fixed bugs when using LSS, including one giving wrong sigma8 (thanks Matteo Costanzi)
  • CAMB updated to December 2013 version (minor changes)
• November 2013
  
  • CAMB updated to November 2013 version (fixes problem with e.g. tensor runs)
  • Python grid scripts bug fixes and minor new options
• October 2013
  
  • CAMB updated to October 2013 version (inc. Jason Dossett changes to support non-linear lensing and non-linear MPK, changing numerical results slightly; fix for ppf bug that significantly changes results at low L for w>>-0.8, thanks David Rapetti and Matteo Cataneo)
  • Added WiggleZ and MPK modules, and corresponding general changes for likelihoods using the linear or non-linear matter power spectrum as a function of redshift. Double interpolation is now avoided, and combinations of requirements for different likelihoods are automatically internally combined. (All thanks to Jason Dossett)
  • Added halofit_ppf (Jason Dossett)
  • Minimization now has more options, including high-temperature MCMC check, and uses existing .covmat for widths: best fits seems to be a lot more stable now; also MPI support to compare result from multiple minimizations (not usually required)
  • Added checkConflicts to likelihood class (so new likelihoods can check full list for conflicts and abort if necessary e.g. BAO/MPK) and added .dataset file-based likelihood ancestor class, with conflict specification input parameters
  • New python plotting options and Planck default settings; sample Planck output scripts updated
• June 2013
  
  • Fix getdist bounds outputs when plot_params is set and triangle plot data generation
  • Fix for cosmomc runs with no covmat; more robust checkpoint file output
• April 2013
  
  • [23 April] fix to work with default test_likelihood parameter (F)
  • Automatic thinning by oversample_fast factor for sampling_method=1 (prevents files getting very large)
  • oversample_fast meaning slightly changed to give more regular fast updates in standard sampling, and generate oversample_fast standard fast metropolis samples per slow update in the dragging method.
  • Tweaks to various internal convergence and update parameters
  • GetDist option can be set to m for old matlab outputs or py for similar python plot outputs
  • Added getdist parameter converge_test_limit to set limit for convergence tests
  • Fixes for runGridGetdist.py, and default to producing .py python plot files in each dist folder rather than matlab .m.
  • Renamed matlab_subplot_xx etc to subplot_xxx
  • Various other minor bug fixes, tidied up MCMC.f90 code (for the moment removing old un-updated sampling methods)
• March 2013
  
  • Sampling
    • New fast-slow sampling_method=7, using new fast/slow blocked decorrelation scheme (paper) and fast dragging following Neal 2005. This is recommended for Planck.
      • fast_param_index specifies that all parameters with number greater or equal to fast_param_index should be treated as fast. Can alternatively use fast_parameters to set specific parameter to be treated as fast.
      • dragging_steps determines the number of fast steps per slow step. In total dragging_steps x num_fast metropolis steps are taken in the fast direction for each slow step. Does not need to be an integer, 2-3 works well for Planck.
      • for fine-tuning block_semi_fast boolean defines whether initial power spectrum parameters are treated as separate blocks, block_fast_likelihood_params determines if fast parameters are blocked depending on likelihood dependencies. Both true (default) is usually fastest.
  • Grids of models and python utilities
    • A new suite of python scripts for running CosmoMC for grids of models, running GetDist over the result, management, analysis and plotting. See the python scripts readme
  • Structure
    • Restructuring using Fortran 2003 features (probably does not compile on gfortran, ifort 13 OK); likelihoods and theory now only re-computed as required as parameters change (enables the fast-slow sampling method to work). Each likelihood specifies its own theory and nuisance parameter requirements.
    • Data likelihoods now specify their own .paramnames file for any nuisance parameters (samples in ./data). Combining theory and data parameters is done internally, there's no need to change hard-coded parameter numbers when new nuisance parameters are added, and unused likelihood nuisance parameter are no longer output. Each likelihood function is passed the array of its nuisance parameters, completely independent of what other likelihoods are doing (but multiple likelihood functions can use the same nuisance parameter names when they are the same parameter). Likelihoods specify their speed (<0 is slow, >=0 is fast, with higher faster), and are internally sorted to be in speed order before use.
    • Reorganized parameterization class and module implementation; can now set H0_min and H0_max as .ini input parameters. Added parameterization=background option (e.g. for supernovae-only runs): parameter numbers can now be changed dynamically without re-compiling.
  • CAMB and cosmology
    • CAMB (and CosmoMC) updates fix issues with larger neutrino masses and non-linear calculation in very closed models (Mar 2013 version)
    • Added support for massive neutrinos with varying n_eff (nnu), treating massive as nearly thermal and the rest as massless (for n>3.046), or reducing the temperature of the massive neutrinos for n<3.046.
    • Added use_lensing_potential and use_nonlinear_lensing (currently can't be used with any LSS data; also note that it is not calculated consistency when only the initial power spectra are changed). Changed default num_cls_ext=1. Lensing potential accuracy increased for use_lensing_potential=T.
    • Derived parameters now include r_s/D_v(0.57)
    • T_CMB changed to 2.7255
    • lmax_computed_cl to define CAMB maximum L; higher L are approximated by scaling fixed template file (highL_theory_cl_template), for use where non-primordial contributions dominate.
    • Input parameter num_massive_neutrinos for use with the mnu parameter (e.g. can fix to 0.06 with num_massive_neutrinos=1 to approximate minimal hierarchy)
    • Links by default with CAMB simplified ppf module for varying w (parameter wa).
    • Base parameters changed to use m_nu rather than f_nu; several new chain and derived parameters supported and output by default.
  • GetDist
    • parameter credible_interval_threshold to determine when credible intervals or tail integrals are used
    • .margestats has new format, with separate limit type for each confidence
    • Prior ranges set automatically for MCMC parameters from .ranges file
    • applies 1D smoothing scale relative to standard deviation, or semi-optimal: smooth_scale_1D
    • 2D plots use adaptive elliptical kernel density, smooth_scale_2D sets smoothing scale relative to posterior width or bin size.
    • Removed sm support. Added python/GetDistPlots.py with fairly general plotting support.
    • R-1 statistics now use all samples left after cutting ignore_rows. The value is redefined more uniquely to be the worst eigenvalue of the covariance of the chain means of mean-covariance-orthonormalized parameters
    • Change for making large arrays of 1D plots not too small; matlab_subplot_size_inch, matlab_plot_output parameters
  • Likelihoods
    • Support for the Planck likelihood
    • Added SNLS supernovae (with option for internal marginalization) and updated Union to Union 2.1
    • BAO data up dated to BOSS DR9 final results (DR7, DR9 and 6DF). Note the code is not identical, cosmomc computes the drag sound horizon numerically (recalibrated to be consistent in the fiducial model); also be aware of correlation with Wigglez.
    • HST data updated to Riess et al: 1103.2976 (from BOSS mod)
    • Updated for WMAP9 (edit the Makefile in your wmap_likelihood_v5 directory appropriately first).
    • Input parameters use_WMAP_TT_beam_ptsrc, use_WMAP_TE, use_WMAP_TT that can all be set to false to use only WMAP low L
    • added prior[xxx]=mean std inputs to specific Gaussian priors on parameters
    • removed Use_BBN, use_mpk and others that are currently not updated
    • a large number of old files in data/ have been deleted
  • Importance sampling
    • Added redo_like_name for importance sampling when only one likelihood is changed
    • Added redo_no_new_data option to redo only a specific likelihood when importance sampling
    • Added redo_add to only calculate changes due to new set of likelihoods (without re-computing old ones)
    • .data format for importance sampling re-organised; can now be re-used if unused parameter ordering and numbering changes
  • Minimization
    • Minimizer uses fast and slow subspaces for speed and sanity check on convergence
    • Likelihood/chi-square values for the separate data sets tracked separately (as well as total), and output in .minimum file
    • start_at_bestfit = T option to start chains at best fit point (if true, be careful with convergence since non-dispersed)
    • Output .bestfit_cl files with best-fit C_L from action=2 runs. .minimum files now include latex labels (from .paramnames)
    • action=3 to find best-fit and hessian (if it works!), and then stop; output .hessian.covmat file and best-fit
  • Output chains .txt files only include parameters that are actually varied (specified in .paramnames file; .ranges file specifies all parameters with ranges, including fixed parameters)
  • Output .initparams file for each chain giving input parameters used
  • Can be compiled in single or double precision (double is new default)
  • Added many Planck .covmat files and common/batch input parameter set .ini files.
  • Numerous other things
• October 2012
  
  • New best-fit finding routine (action=2) uses Powell's 2009 BOBYQA routine (faster and reliable with bounded parameters). Best-fit parameter values written out including derived parameters.
  • estimate_propose_matrix outputs file in named parameter .covmat compatible format and copes better with parameters with hard prior cuts
  • CAMB October 2012 update: tweaked recfast model and support for compiling CosmoMC with CosmoRec and HyRec recombination codes; updated halofit model
  • .ini files support reading in file of default parameter values that can then be overridden (greatly reduce duplication between similar runs), e.g. DEFAULT(baseparameter_defaults.ini); can be used in nested way, and with INCLUDE.
• January 2012
  
  • Fixed generation of .paramnames file when using post processing (importance sampling)
  • CAMB update for January 2012 (~1e-3 improvement in interpolation error, slightly faster for high accuracy); see arXiv:1201.3654
  • Added compare_means.m matlab script to graphically compare differences between posterior means from two or more .margestats files with the same parameters (like this)
  • Increased precision in GetDist's .margestat files
  • Included a couple of extra Planck-like .covmat files for non-flat models and massive neutrinos
• October 2011
  
  • New BAO multiple-dataset module including Wigglez (thanks to Jason Dosset)
  • stop_on_error parameter, if F global_error_flag>0 from CAMB results in a rejected point rather than stop
  • Fix to setting fractional number of neutrinos since July CAMB version (thanks to Zhiqi Huang)
  • CAMB Oct 2011 update: high_accuracy_default precision in non-flat models, minor tweaks, and error flag
  • Makefile updates
• August 2011
  
  • Changes to params_CMB.f90 for gfortran 4.6 compatibility
• July 2011
  
  • Updated matlab colormaps in mscripts directory; added color_for_bw.m (yellow-blue/black, which should look consistent printing in B&W).
  • all_l_exact likelihood now uses fsky rather than fsky² scaling at all L
  • GetDist changes to use more IO wrapper functions
  • %DATASETDIR% and %LOCALDIR% placeholder support for all input file names; custom_params input parameter to read and store additional parameter file in CustomParams object (settings.f90), also used as optional additional placeholders.
  • .ini files now support INCLUDE(filename) to share common parameters between files. INCLUDES can be nested.
  • MPI job now finishes neatly (not aborted) if convergence criterion is achieved
  • num_cls now set to 4 by default (include BB). C_l .data files now store every L by default
  • CAMB updated to July 2011 version; new high_accuracy_default input parameter to target 0.1%-accuracy on small scales
  • Added directory of generic python scripts; simple example to make fake perfect CMB dataset with given beam and noise
  • Cosmologui compatibility
• May 2010
  
  • Sets helium abundance using BBN consistency ignoring very small error bar (bbn.f90 thanks to Jan Hamann). Set bbn_consistency=F to fix to old default value of 0.24.
  • Added nnu (effective number of neutrinos) and YHe (helium fraction) to cmbtypes.f90; now easier to make these varying parameters [by default nnu is fixed to 3.046 and YHe set from BBN consistency)
  • Updated supernovae.f90 to Union 2 (Nao Suzuki)
  • Updates to BAO for more general acoustic scale calculation (thanks to Jan Hamann and Beth Reid)
  • Covariance matrices (.covmat) now only include varied parameters and have a header giving names of parameters used (so much easier to reuse if parameters are re-ordered or other parameters added)
  • Aded local_dir parameter to change default location for .covmat and .paramname files
  • New GetDist options
    • line_labels=T to write out legend of roots being plotted (matlab)
    • finish_run_command to run system command when getdist finished (e.g. "matlab < %ROOTNAME%.m" to make 1D plot)
    • no_triangle_axis_labels to suppress axis tick labels (except on edges) when making large triangle plots
  • Makefile updated for simpler MKL linking with ifort version 11.1+
• Jan 2010
  
  • Updated to use WMAP 7-year likelihood
  • Updated CAMB to Jan 2010 version - main change is use of RECFAST 1.5 (up to 2% change in C_l at l=2000)
  • Added ParamNamesFile optional input parameter for cosmomc
  • Added basic support for CMB lensing reconstruction power spectrum, and full-sky implementation in Planck_like.
• October 2009
  
  • [9th Nov] changed use_bao to use_BAO in the sample .ini file
  • [27th Oct] fixed GetDist bug in credible intervals with prior cutoffs (Jan Hammann); fixed all_l_exact
  • [27th Oct] fixed problems with .newdat files, and sometime-problem in LRG likelihood; updated ACBAR and BICEP dataset; COSMOS computer detected by Makefile
  • Support for naming parameters to simplify changing number of parameters and parameterization. Transfer of names and labels between cosmomc chains and getdist via .paramnames files (should be backwards compatible with old .ini files). Reference indexed .ini parameters by name, e.g. param[omegambh2] as alias for param1. Give getdist plot parameters as name lists (e.g. H0 omegam tau).
  • Added SDSS LRG dataset (thanks to Beth Reid; many changes to mpk.f90; to use must have EXTDATA = LRG in the Makefile)
  • supernovae.f90 now replaced by default with SDSS Supernovae compilation (previous code now supernovae_Union.f90; thanks to Wessel Valkenburg); config in data/supernovae.dataset.
  • Added simple baryon oscillation option (thanks to Beth Reid)
  • Added Quad pipeline 1 dataset (QUAD_pipeline1_2009.newdat). Support for QUAD-format .newdat files.
  • Changed HST data to use the latest result (HST.f90; thanks to Beth Reid).
  • Added optional data_dir input parameter to use different directory than ./data; .newdat data files read window functions from relative path location.
  • Updated CAMB to Feb 2009 version (fixed issue with lensed non-flat models) + change to halofit to include w/=-1 in the background (Beth Reid)
  • New IO wrapper module to simplify pipelining.
  • Generalized A_SZ internally to allow num_freq_params parameters governing frequency-dependent part of CMB signal (default in settings.f90 set to one, A_SZ as before - an SZ template amplitude).
  • Fixed buffer overflow with CMB lensing and AccuracyLevel > 1.
  • Only one source Makefile supplied, and now builds CAMB automatically; if WMAP variable is unset builds without WMAP
• June 2008
  Fixed problem initializing nuisance parameters. Updated CAMB to June 2008 version (fix for very closed models).
• May 2008
  supernovae.f90 now replaced by default with UNION Supernovae Ia dataset (previous code now supernovae_ReissSNLS.f90; thanks to Anze Slosar). Additions to Planck_like module; support for sampling and hence marginalizing over data nuisance parameters, point sources, beam uncertainty modes. New GetDist option single_column_chain_files to support WMAP 5-year format chains (thanks to Mike Nolta): 1col_distparams.ini is a supplied sample input file. New GetDist option do_minimal_1d_intervals to calculate equal-likelihood 1-D limits (see 0705.0440, thanks to Jan Hamann). New GetDist option num_contours to produce more than two sets of limits.
• April 2008
  Includes latest CAMB version with new reionization parameterization - default now assumes first ionization of helium happened at the same time as hydrogen, and z_re is defined as the point where x_e is half its maximum (the optical depth and z_re are related in a way independent of the speed of the transition in the new parameterization). This changes the z_re numbers at the ~6% level. Fixed bug reading in mpk parameters.
• March 2008
  Uses WMAP 5-year likelihood code. Added cmb_dataset_SZx and cmb_dataset_SZ_scalex parameters to specify (parameter independent) SZ template for each CMB dataset (WMAP_SZ_VBand.dat included from LAMBDA). Parameter 13 is now A_SZ - the scaling of all the SZ templates, as used in WMAP3/WMAP5 papers. Updated supplied covariance params_CMB.covmat for WMAP5. Minor compatibility changes.
• February 2008
  Added generic_mcmc in settings.f90 to easily use CosmoMC as generic sampling program without calling CAMB etc (write GenericLikelihoodFunction in calclike.f90 and use Makefile_nowmap). Added latest ACBAR dataset. CAMB update (including RECFAST 1.4). New Planck_like.f90 module for C_l likelihoods using approximation of arXiv:0801.0554 (also basic low-l likelihood). Added markerx GetDist parameters for adding vertical lines to parameter x in 1D Matlab plots. Various minor changes/compatibility fixes.
• November 2006
  Updated CBI data. Compiler compatibility tweaks. Fixed error msg in mpk.f90. Minor CAMB update. Better error reporting in conjgrad_wrapper (thanks to Sam Leach).
• October 2006
  (20th October 2006)Fixed k-scaling for SDSS LRG likelihood in mpk.f90. Changes for new version of WMAP likelihood code. Added out_dir and plot_data_dir options for GetDist. Minor compatibility fixes.
  Added support for SDSS LRG data (astro-ph/0608632; thanks to Licia Verde, Hiranya Peiris and Max Tegmark). CAMB fixes and other minor changes.
• August 2006
  Improved speed of GetDist 2D plot generation, added limitsxxx support when smoothing = F. Added sampling_method = 5,6, preliminary implementations of multicanonical and Wang-Landau sampling for nasty (e.g. multi-modal) distributions (currently does not compute Evidence, just generates weighted samples). Changed matter_power_minkh (cmbtypes) to work around potential rounding errors on some computers. Updated CAMB following August 2006 version. Added warning about missing limitsxx parameters to getdist. Added MPI_Max_R_ProposeUpdateNew parameter (when varying parameters that are fixed in covmat). Updated CBI data files.
• May 2006
  Supernovae.f90 updated to use SNLS by default, edit to use Riess Gold. 2dF updated (twodf.f90 file deleted, use 2df_2005.dataset); covariance matrix support in mpk.f90. Fixed bug using LSS with non-flat models. Improved error checking and Matlab 7 enhancements in getdist. Getdist auto column counting with columnnum=0, various hidden extra options now shown in sample distparams.ini. Extra fix for confid2D. Fixed MPI thinning bug in utils.F90. Makefile fixes. Fixed mpk.f90 analytical marginalization (since March 2006). SDSS likelihood now computed from k/h=1e-4.
• April 2006
  Fixed bug in lya.f90 (SDSS lyman-alpha now the default; lya.f90 now includes Croft by default). Fixes to Confid2D Matlab script. Added .covmat files for WMAP with running and tensors, and basic Planck simulation. Fixed version confusion in GetDist (one-tail limits set to prior limit value).
• March 2006
  Updated for 3-year WMAP. Added use_lya to include lyman-alpha data (standard LCDM only). Default in lya.f90 is LUQAS (can also compile with SDSSLy-a-v3.f90 for SDSS). New Matlab scripts for producing solid contour and 4D plots. New checkpoint option to generate checkpoint files and continue terminated runs. Added action=1 parameters redo_add (adds new likelihoods rather than recalculating) and redo_from_text (if you don't have .data files). Added pivot_k and inflation_consistency for use with default power spectrum parameterization.
• July 2005
  Added get_sigma8 to force calculation of σ₈. Updated .newdat CMB dataset format (also added B03 data files). New use_fast_slow parameter to turn on/off fast-slow optimizations. Fixed bug which resulted in occasional wrong tau values when importance sampling .data files. GetDist now outputs one/two-tail limit info in .margestats file. Updated CAMB version (support for non-linear matter power spectrum).
• February 2005
  Updated CAMB for new accurate lensed C_l calculation of astro-ph/0502425. Minor changes to getdist (new Matlab_version input parameter, all_limits to set same limits for all parameters). cmbdata.f90 includes new format used by BOOMERANG/CBI for polarization.
• October 13 2004
  Fixed bug in mpk.f90 when using 2df. Changes to GetDist for compatibility with Matlab 7. Fixed Makefile_intel (though now obsolete if you have Intel fortran v8).
• October 2004
  Added mpk.f90 for reading in general (multiple) matter power spectrum data files in a similar way to CMB dataset files - corresponding changes to input parameter file. Included SDSS data files (note CosmoMC only models linear spectrum). Various minor bug fixes and improved MPI error handling. Included (though not compiled by default) supernovae_riess_gold.f90 file to include more recent supernova data. Some mscripts fixes for compatibility with Matlab 7.
• August 2004
  Improved proposal density for efficient handling of fast and slow parameters, plus more robust distance proposal (should see significant speed improvement). New sampling_method parameter: new options for slice sampling (robust) and directional gridding (robust and efficient use of fast parameters). Also option to use slice sampling for burn in (more robust than Metropolis in many cases), then switch to Metropolis (faster with good covariance matrix). See the notes for details. Improved MPI handling and minor bug fixes. Fixed effect of reionization on CAMB's lensed C_l results.
• June 2004
  Uses June 2004 CAMB version: bessel_cache.camb file no longer produced or needed (prevents MPI problems). Increased sig figs of chain output and GetDist analysis. New parameter propose_scale, the ratio of proposal width to st. dev., default 2.4 (following Roberts, Gelman, Gilks, astro-ph/0405462) - often significantly speeds convergence (parameters in .ini file are now estimates of the st. dev., not desired proposal widths). Added MPI_R_StopProposeUpdate to stop updating proposal covariance matrix after a given convergence level has been reached. Added accuracy_level parameter to run at higher CAMB accuracy level (may be useful for forecasting).
• March 2004
  Added new VSA and CBI datasets. Added first_band= option to .dataset files to cut out low l that aren't wanted. CAMB pivot scale for tensors changed to 0.05/MPc (same as scalar). Fixed various compiler compatibility issues. Corrected CMB_lensing parameter in sample .ini file. Fixed minor typo in params_CMB.f90. Fixed reading in of MPI_Limit_Converge parameter in driver.F90. Fixed bounds checking in MatterPowerAt (harmless with 2df). Added an exact likelihood calculation/data format to cmbdata.f90 for polarized full sky CMB C_l.
• December 2003
  Added MPI support, with stopping on convergence and optional proposal density updating. Added calculation of matter power spectrum at different redshifts using CAMB (settings in cmbtypes.f90). Fixed bug when restarting chains using "continue_from" parameter [March 2006: now obsolete], and a few compiler compatibility issues. Updated CAMB for more accurate non-flat model results. Added output of parameter auto-correlations to GetDist, along with support for ignore_rows<1 to cut out a fraction of the chain and percentile split-test error estimators. Changed proposal density to proposal a random number of parameter changes on each step. Added GetDist samples_are_chains option - if false, rows can be any samples of anything (starting in column one, without an importance weight or likelihood value as produced by CosmoMC) - useful for analysing samples that don't come from CosmoMC. Added GetDist auto_label parameter to label parameters automatically by their parameter number.
• July 2003
  Fixed bug in MCMC.f90 affecting all raw chains - weights and likelihoods were displaced by one row. Post-processed results were correct, and effect on parameters is very small. Minor bug fixes in GetDist. Can now make file_root.read file to be read by all chains file_root_1, file_root_2, etc (this file is not auto-deleted after being read).
• May 2003
  Added support for 'triangle' plots to GetDist (example. Set triangle_plot=T in the .ini file). If truncation is required, the covariance matrix for CMB data sets is now truncated (rather than truncating the inverse covariance). Fixed CAMB bug with non-flat models, and problem setting CAMB parameters when run separately from CosmoMC.
• March 4 2003
  Fixed bug in GetDist - the .margestats file produced contained incorrect limits (the mean and stddev were OK)
• Feb 2003
  Support for WMAP data (customized code fixes TE and amplitude bugs). CMB computation now uses C_l transfer functions - complete split possible between transfer functions and the initial power spectrum, so improved efficiency handling fast parameters. Bug fixes and tidying of proposal function. Initial power spectrum no longer assumed smooth for P_k. GetDist limitsxxx variables can be N to auto-size one end (margestats are still one tail). Support of IBM XL fortran (workarounds for bug on Seaborg). GetDist will automatically compute some chain statistics to help diagnose convergence and accuracy. CAMB updated, including more accurate and faster handling of tight coupling. Option to generate chains including CMB lensing effect. Various other changes.
• Nov 2002
  Added support for polarization, and improved compatibility with different compilers and systems.

• Efficient sampling of fast and slow cosmological parameters
• Cosmological parameters from CMB and other data: a Monte-Carlo approach
• Probabilistic Inference Using Markov Chain Monte Carlo Methods
• Information Theory, Inference and Learning Algorithms
• MCMC Preprint Service

1. What are the dotted lines on the plots?
   Dotted lines are mean likelihoods of samples, solid lines are marginalized probabilities. For Gaussian distributions they should be the same. For skew distributions, or if chains are poorly converged, they will not be. Sometime there is a much better fit (giving high mean likelihood) in a small region of parameter space which has very low marginalized probability. There is more discussion in the original paper.
    
2. What's in the .likestats file produced by getdist?
   These are values for the best-fit sample, and projections of the n-Dimensional confidence region. Usually people only look at the best-fit values. The n-D limits give you some idea of the range of the posterior, and are much more conservative than the marginalized limits.
    
3. I'm writing a paper "constraints on X". How do I add X to cosmomc?
   To add new theory parameters
   • add the definition of the physical parameter to CMBParams in cmbtypes.f90
   • Change params_CMB.f90 to add a new parameterization or modify an existing one (with a corresponding .paramnames file with the new parameter names in). In particular the _Init routine does

     call SetTheoryParameterNumbers(num_slow_params,num_semi_slow_params)
     

     which sets the number of hard and semi-hard parameters (the latter being things like initial power spectrum parameters) and then

     call this%Init(Ini,Names, 'params_CMB.paramnames')
     

     to set the parameter names file.
   • Modify CMB_Cls_Simple.f90 to pass your new CMBParams parameters to CAMB to actually change the result
   • Edit your .ini files to to add range and width settings for the new parameter names
   
   If instead your parameter is a likelihood parameter (nuisance parameter), the new parameter can be handled entirely inside your likelihood function code (see supernovae_SNLS.f90 for a simple example that has two nuisance parameters): you just set the .paramnames file (which determimes the number of new parameters), and then use them when passed in to your likelihood function.
    
4. Why do some chains sometimes appear to get stuck?
   Usually this is because the starting position for the chain is a long way from the best fit region. Since the marginal distributions of e.q. A_s are rather narrow, it can take a while for chains to move from into an acceptable region of A_s exp(-2τ). The cure is to check your starting parameter values and start widths (especially make sure the widths are not too wide-- too small is better than too wide when running with MPI), or to use a sampling method that is more robust (e.g. use sampling_method = 7). If you are patient, stuck chains should eventually find a sensible region of parameter space anyway. Occasionally the staring position may be in a corner of parameter space so that prior ranges prevent any reasonable proposed moves. In this case check your starting values and ranges, or just try re-starting the chain (a different random starting position will possibly be OK).
    
5. How to I simulate futuristic CMB data? See CosmoCoffee. Also if you want to include lensing potential reconstruction, see this page.

Feel free to ask questions (and read answers to other people's) on the CosmoCoffee software forum. There is also a FAQ in the CosmoloGUI readme.