.. MAMPOSSt documentation master file, created by sphinx-quickstart on Fri Mar 2 17:01:15 2018. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. .. |br| raw:: html
MAMPOSSt documentation ###################### Contents: .. toctree:: :maxdepth: 2 inifile.rst buildini_mamposst MAMPOSSt_params What is MAMPOSSt? ================= MAMPOSSt stands for **M**\ *odeling* **A**\ *nisotropy and* **M**\ *ass* **P**\ *rofiles of* **O**\ *bserved* **S**\ *pherical* **S**\ *ys*\ **t**\ *ems*. 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`` Bibliography ============ `Mamon, Biviano & Boué (2013), MAMPOSSt: Modelling Anisotropy and Mass Profiles of Observed Spherical Systems - I. Gaussian 3D velocities, MNRAS 429, 3079 `_ `Lewis & Bridle (2002), Cosmological parameters from CMB and other data: A Monte Carlo approach, PRD 66, 3511 `_ `Other articles using MAMPOSSt `_ 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`` (:ref:`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`` .. where the current working version is **5.0**. 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`` :math:`\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 (:ref:`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 ``n``\ th chain, the evolution of the MCMC acceptance ratios, minimum negative log likelihoods, and the :math:`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``. :ref:`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 ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`