MAMPOSSt documentation

Contents:

What is MAMPOSSt?

MAMPOSSt stands for Modeling Anisotropy and Mass Profiles of Observed Spherical Systems. One can view MAMPOSSt as a lamppost where light is replaced by mass. In Spanish, mamposst means mortar for bricks, i.e. the building blocks of structures.

MAMPOSSt is a Bayesian code to perform mass/orbit modeling of spherical systems. It determines marginal parameter distributions and parameter covariances of parametrized radial distributions of dark or total matter, as well as the mass of a possible central black hole, and the radial profles of density and velocity anisotropy of one or several tracer components, all of which are jointly fit to the discrete data in projected phase space. It is based upon the MAMPOSSt likelihood function for the distribution of individual tracers in projected phase space (projected radius and line-of-sight velocity) by Mamon, Biviano & Boué (2013) and the CosmoMC Markov Chain Monte Carlo code of Anthony Lewis (Lewis & Bridle 2002), run in generic mode. MAMPOSSt is not based on the 6D distribution function (which would require triple integrals), but on the assumption that the local 3D velocity distribution is an (anisotropic) Gaussian (requiring inly a single integral).

Author of this code

Gary Mamon

Please report bugs to gam A A T iap.fr

Installation

Type INSTALL.csh. This should automatically perform the following actions:

  • Select a Fortran compiler, ifort or else gfortran

  • Compile the code

  • Move scripts to suitable script directory, making sure that this directory is in the user’s path

  • Crate a NOSAVE directory for storing large MCMC output files

  • Setting up the sm plotting

    • checking for the existence of sm on the system
    • checking for the existence of the user’s sm initialization file
    • checking for the existence of the user’s custom sm macro file directory in the sm initialization file
    • checking for the existence of this directory
    • checking for the existence of the default sm macro file in this directory
    • checking for the existence of the startup2 sm macro in this file
    • inserting mamposst in the list of automatically loaded sm macro files

If problems occur, note that, for sm plotting, the $HOME/.sm file should have a macro2 entry such as

macro2 /users/gam/SM/

  1. with the final /
  2. with the exact path without using shortcuts such as ~ or $HOME

which provides the directory to place the mamposst.sm file, which should be renamed mamposst.

Running MAMPOSSt

Generalities

The MAMPOSSt likelihood f77 routine, mamposstlnlik.f (arguments), which uses the SLATEC Fortran 77 library, is called by a suitably adapted version of the Fortran 2008 CosmoMC (October 2012 version) code.

Markov Chain Monte Carlo

CosmoMC uses the Metropolis-Hastings MCMC algorithm to probe the multi-dimensional parameter space. CosmoMC is usually run using several chains probing the parameter space in parallel. CosmoMC was originally developed to analyze the CMB, but for MAMPOSSt it is compiled and run in generic_MCMC mode.

The parameters of the radial profiles of mass, tracer densities (for different components) and velocity anisotropy, as well as a central black hole mass are obtained using flat priors (on log quantities except indices and possibly velocity anisotropy), except for possible Gaussian priors on pre-determined fits of the tracer density profiles.

Modifications to CosmoMC

Several CosmoMC routines were modified for MAMPOSSt:

  • driver.F90 –> driver_mamposst.F90 (the main program for reading parameter file)
  • settings.f90 –> settings_mamposst.f90 (for declarations)
  • params_CMB.f90 –> params_mamposst.f90 (for reading the file of parameter names, automatically generated by the code)
  • calclike.f90 –> calclike_mamposst.f90 (to read the data and call the MAMPOSSt likelihood function)

Compilation

The code is compiled with:

make

In CosmoMC, the number of hard ajustable (free or fixed) parameters must be specified in settings_mamposst.f90. This means that if additional ajustable (free or fixed) parameters are added, one needs to recompile CosmoMC. Compilation has only been tested for the ifort Intel Fortran compiler (which is not free, and thus not available on all machines). In particular, compilation and running in MPI parallelism has not yet been tested with the gfortran compiler.

Running

The code is un with:

mpirun -np num_chains cosmomc_mamposst initialization_file

where num_chains is the number of chains to run in parallel. If you run on an 8-core machine, you should specify num_chains \(\leq 8\). Running 6 chains is sufficient.

Data file

The data file to be analyzed by MAMPOSSt is column-tabulated with tabs or spaces as separators. It can come in different formats.

The first 2 columns must be the projected radius (in kpc) and the line of sight velocity (in km/s) in this order. The system center and velocity must be determined beforehand.

If velocity errors are available, they should be listed in the 3rd column (in km/s).

If several tracer components are jointly analyzed, they should come after the velocity errors (or after the velocities if no velocity errors are provided). The format of the class is number_string, e.g. 1_red and 2_blue.

If distance moduli and their uncertainties are known for some or all the tracers, they should be listed in the last 2 columns.

Initialization file

The CosmoMC initialization file has been now tailored for MAMPOSSt (see here an example of a initialization file). It is called prefix.ini, where prefix is a string representing the particular choice of the full set of parameters (ajustable or not).

Output files

Two sets of output files are saved to the specified subdirectory of the COSMOMC/chains directory.

  1. mamposst_prefix_n.txt: the chain file, with columns: 1) number of passages through the point of parameter space; 2) likelihood; 3+) ajustable (free and fixed) parameters.
  2. mamposst_prefix_n.log: the log file, which provides, for the nth chain, the evolution of the MCMC acceptance ratios, minimum negative log likelihoods, and the \(R^{-1}\) convergence test values.

Plotting

Plotting is currently set up for sm (SuperMongo). The sm macros are located in tools/mamposst.sm. The principal macro is mosaicMCMC, which creates the following:

  • a PDF file prefix_chains.pdf with the evolution of likelihood and free ajustable parameters for each chain (optional);
  • a PDF file prefix_mosaic.pdf of a triangular mosaic of marginal parameter distributions and parameter covariances. The red arrows and asterisks indicate the maximum likelihood parameters.
  • maximum likelihood and marginal distributions for the ajustable parameters, appended to the file prefix.MLE.
  • maximum likelihood, maximum likelihood parameters, and Bayesian evidence (AICc and BIC), appended to the file prefix.BayesEvidence.

The plotting procedure is as follows:

  • % sm (where % is the UNIX prompt)
  • sm> mosaicMCMC prefix burn-in [output-file-prefix [gaussian-smooth [chain-plot?]]]
  • (…)
  • sm> quit

where sm> is the sm prompt (not to be typed) and burn-in is the number of initial chain elements to be discarded for each chain (a rule of thumb is to discard the first 2000 * number-of-free-parameters elements for each chain). The last 3 arguments to mosaicMCMC are optional, with default values equal to the run prefix (for the plot prefix), 1 (for 1 pixel gaussian smoothing of the covariance plots) and 1 (for skipping the evolution plot), respectively.

Scripts to speed things up

The procedure to build the initialization file, to compile and run MAMPOSSt are greatly facilitated with automated scripts. The C-shell scripts below accept option -help for help.

  • buildini_mamposst [-options] prefix:
    • converts data-file to MAMPOSSt format;
    • counts the number of hard parameters and creates numhard.i that is included in settings_mamposst.f90;
    • counts the number num-free of free parameters and queries the user if 10000 * num-free is the desired number of elements per MCMC chain;
    • generates the initialization file params_mamposst_prefix.ini;
      • chains will be called mamposst_prefix_n.txt where n is the chain number, starting at 1;
    • proposes to compile and run the code (with the autoruncosmomc script, see below) OR to simply run the code, in both cases saving the output (for debugging) into an appropriate file, with the possibility of monitoring that file.
    • saves the buildini_mamposst command and arguments in the file prefix.buildini.

    Description of options.

    It is strongly recommended to compile and run MAMPOSSt with buildini_mamposst

  • autoruncosmomc [-options] prefix:

    automatic script for compilation and optional running. By default, autoruncosmomc recompiles the code including the internal CosmoMC libraries and then launches the code. Options are:

    • -noclean: do not recompile the CosmoMC libraries
    • -nocomp: do not recompile MAMPOSSt nor the CosmoMC libraries
    • -gfortran: force gfortran compilation
    • -ifort: force ifort compilation
    • -f90 compiler: compile with compiler
    • -n number: run MAMPOSSt on number nodes in parallel
    • -v version: run version version
    • -h or -help: get help
  • getcosmomcruns sub_directory [prefix]:

    script to copy chain outputs, from subdirectory subdir of the chain directory from remote to local machine (with similar file hierarchy; it is recommended to exchange ssh keys between remote and local machines).

Directory structure

The following directory structure is recommended.

  • $HOME/
    • script/ (script directory in path)
      • getcosmomcruns
      • autoruncosmomc
      • buildini_mamposst
    • MAMPOSST/
      • src/
        • Makefile
        • mamposstlnlik.f
        • COSMOMC/ (with COSMOMC source files)
      • Project/
        • data_file (original data file)
        • data_file_prefix.dat_mamposst (data file for MAMPOSSt)
        • prefix.ini
        • prefix.MLE
        • prefix.BayesEvidence
    • NOSAVE/ (large directory not necessary to backup)
      • COSMOMC/
        • prefix.output (code output and debugging messages)
        • chains/
          • Project/
            • prefix_1.txt
            • prefix_1.log
            • (…)
            • prefix_n.txt
            • prefix_n.log
    • .sm (SM initialization file)
    • SM/ (or where macro2 of the .sm file points to)
      • mamposst (copy of source/mamposst.sm)

Note that the mosaicMCMC sm macro in the mamposst file assumes that the chains lie in a sub-directory of $HOME/NOSAVE/COSMOMC/chains.

Indices and tables