bagemass Files

 This is the README file for version 1.1 of bagemass.

***************
VERSION HISTORY
***************

 1.1 - Updated citation notice 
       02 Oct 2014
 1.0 - First export version.
       31 Jul 2014, p.maxted@keele.ac.uk

 This software is distributed under the terms of the GNU General
Public License GPLv3 (https://www.gnu.org/licenses/gpl.html).

 Please cite the following publication if you publish results based
on this software.
 
 P. F. L. Maxted, A. M. Serenelli and J. Southworth 2014, A&A, submitted.

Index:
   1. CONTENTS
   2. INSTALLATION
   3. RUNNING THE PROGRAM
   4. OUTPUT FILES

***********
1. CONTENTS
***********

README:  This file. 

Makefile: Used by GNU make to compile and install the software.

data/: Directory containing spline fits to grids of stellar models
       stored as FITS files.

src/: Source code 

***************
2. INSTALLATION
***************

 This software should compile without much trouble on any modern
linux system, the only package you may need to install is cfitsio:

  http://heasarc.gsfc.nasa.gov/fitsio/fitsio.html

Step-by-step instructions 
-------------------------

 Commands entered on the command line are preceeded by "$".

 Output from the program is preceeded by ">".

 1. Download the compressed tar file bagemass.tar.gz from sourceforge
 
     http://sourceforge.net/projects/bagemass/

 2. Unpack the archive 

     $ tar xzvf bagemass-1.1.tar.gz

    This will create a directory bagemass-1.1

 3. Move to the directory created in the previous step.

    $ cd bagemass-1.1

 4. Use any text editor to edit the file Makefile, e.g., 

    $ pico Makefile

     Change the values of the variables INSTALL, LCFITSIO, F77 and
    FFLAGS as needed. 

 5. Compile and install

    $ make

     You may see some warnings when src/herm2ev.f and src/herm3ev.f are 
    compiled - these can be ignored.

     The following directories will be created in the installation
    directory if they do not already exist.

     bin/
     share/
     share/bagemass/

6. [Optional] Remove object files

    $ make clean

7. If the "bin" sub-directory in the installation directory is not
   already in the PATH system variable of your shell, add it now 
   (and "rehash" if needed).

8. Test run bagemass

   $ bagemass

 You should see the following output on your terminal

>   
> This is bagemass version 1.1
> (p.maxted@keele.ac.uk)
>   
>   Available alpha_MLT and He-enhancement values are ...
>   1    1.78    0.00
>   2    1.50    0.00
>   3    1.78    0.02
>  Enter model grid number [1] > 

   
 If you hit return at all the prompts you should see lots of numbers
printed to screen, finishing with the following output. (The actual
values printed will be slightly different to this example.)

>  
> Mean age         =    1.788 +/-    1.238
> Mean mass        =    1.075 +/-    0.045
> Mean [Fe/H]_init =    0.019 +/-    0.084
>   
>  --
>   
>   Please cite the following paper if you publish the 
>   results of this analysis.
>   P. F. L. Maxted, A. M. Serenelli and J. Southworth
>   2014, A&A, submitted.
>   
 
 The following output files should also be created every time bagemass is run.
  zams.dat
  track_mlo.dat
  track_mhi.dat
  track.dat
  isochrone_alo.dat
  isochrone_ahi.dat
  isochrone.dat
  chain.dat



**********************
3. RUNNING THE PROGRAM
**********************

 First read the description of the method and models in Maxted et al., 2014.

 The program is run using the following command

 $ bagemass

 The version number of the program is printed and the user is
offered a choice of model grids, e.g., 

>  Available alpha_MLT and He-enhancement values are ...
>  1    1.78    0.00
>  2    1.50    0.00
>  3    1.78    0.02
> Enter model grid number [1] > 

 The default grid number is shown in square brackets. Hit return to
accept the default or enter the grid number desired and then hit
return.

 The full path to the model grid is displayed and the models are
loaded (this can take a few seconds).

 The next set of prompts enable the user to enter the observed data
for the star to be studied. See Maxted et al. 2014 for a description
of these four observed quantities.

> Enter T_eff [K] [6000.,   100.,  -100.] > 
> Enter log L/Lsun [0.0,  5.0, -5.0] > 
> Enter observed metalicity, [Fe/H]_s [0.0,  0.1, -0.1] > 
> Enter observed density, rho/rho_Sun [1.00,  0.01, -0.01] > 

 Observations are entered in the format

  value +error -error 

 This enables the user to use asymmetrical error bars if needed. If
the measurements has symmetrical error bars, simply enter this value
twice, once as a positive value and once as a negative value. All
three numbers must be entered on the same line, followed by return.

 The next three prompts enable the user to enter priors on the age,
initial metallicity and mass of the star. 

 For the age and metallicity, the default values are a flat
distribution over the valid model range. Priors values are entered
in the format

  loerr lolim hilim hierr
  
 For chain values between lolim and hilim, the prior has a value of
1. If hierr is >0 and the chain value is >hilim, then the prior has
a value exp(-0.5*(value-hilim)^2/hierr^2), and similarly for lolim
and loerr. For example, you can add a prior constraint that the age
of star must be less than the age of the Galactic disc (10 +/- 1
Gyr) using the following input.

$  Enter prior on age [Gyr] [0.0,   0.0,  17.5,   0.0] >  0 0 10 1

 If hilim=0 then all trial chain points greater than hilim are
rejected, and similarly for lolim.

 The prior on the mass is given by 

  log(Likelihood) = alpha*Mass
 
 The default is to use a flat prior prior for mass, i.e.,alpha=0.
For a Salpeter distribution use alpha=-2.35.

 The following prompts control the behaviour of Markov Chain
calculation.

 First there are 2 scaling factors that can be adjusted.

> Enter initial step size scale [0.500] > 
> Enter MCMC step size scaling factor [1.00] > 

 These can generally be left at their default values, but you can
experiment with these values if you are having trouble getting your
Markov chain to converge. The first value scales the step size
calculated by perturbing each of the parameters in-turn prior to the
first Markov chain. The second value sets the step size in the two
Markov chains as a factor of the standard deviation of each jump
parameter.

 The last two prompts set the lengths of the two Markov chains.

> Number of steps for MCMC burn-in [1000] > 
> Number of MCMC steps [10000] > 

 The default values are ok for test runs, but for proper analysis
you will probably want to use values of 50-100,000 for both chains.

 The calculation starts as soon as the last prompt is completed.

 The output to screen summarizes the progress of the calculation.
This is self-explanatory once you have read and understood the
description of the method in Maxted et al. (2014) and the
description of the various output variables in the following
section.
 
 One value of interest is the mean acceptance rate for the 2nd MCMC
chain. This will generally have a value of 0.5+-0.1 for a well-mixed
chain, perhaps slightly lower for complex cases. Values of the
acceptance rate lower than about 0.2 may suggest that the MCMC chain
has not converged.


***************
4. OUTPUT FILES
***************

 
 The following output files will also be created every time bagemass
is run.

  chain.dat          - Second Markov chain. 
  zams.dat           - zero-age main sequence at best-fit [Fe/H]
  track.dat          - evolution file for best-fit mass and [Fe/H]
  track_mlo.dat      - evolution track for best-fit mass - error, and 
                       best-fit [Fe/H] 
  track_mhi.dat      - evolution track for best-fit mass + error, and 
                       best-fit [Fe/H] 
  isochrone.dat      - isochrone for best-fit age and [Fe/H]
  isochrone_alo.dat  - isochrone for best-fit age - error,  and
                       best-fit [Fe/H] 
  isochrone_ahi.dat  - isochrone for best-fit age + error,  and
                       best-fit [Fe/H] 

 These are ascii files with comments in the headers preceeded with
'#' that describe the content of the file and give the variable
names for each column.

The variables in chain.dat are as follows.

Step     - Markov chain step number
Age      - Age in Gyr
Mass     - Stellar mass in solar units
[Fe/H]_i - Initial metallicity 
DeltaR   - Undocumented/disabled feature (should always by 0.0)
Teff     - Effective temperature in Kelvin
LogL     - Logarithm of the luminosity in solar units
[Fe/H]_s - Surface metallicity
rho      - Stellar density in solar units.
Xc       - Central hydrogen abundance per unit mass
loglike  - Logarithm of the likelihood 
Chisq    - chi-squared.

 The content  of the files zams.dat, etc. is similar, but it
addition the following variables are provided.
 
Radius   - Radius in solar units logg     - Logarithm of the surface
gravity in units of cm.s^-2

 Some variables appear twice in these files under column headings
Radius_0, Teff_0, etc.