Users guide for code Galaxia:


  1. Introduction
  2. Installation
  3. Usage
    1. Initial setup, BHTree files:
    2. Generating a synthetic survey :
    3. Generating  a stellar halo survey  using Bullock and Johnston simulations:
    4. Available photometric system and filters:
    5. Appending  catalog file with magnitudes in other photometric bands:
  4. Parameterfile
  5. Output data details:
  6. Adding Extinction
  7. Stellar Halo
  8. Data I/O tools and the ebf library
  9. References:

Introduction

Galaxia is a code written in C++ to generate a synthetic survey of the Milky Way. One can either use an analytic model or an N-body model.
The present version of the code implements the Besancon analytical model of the galaxy. 
For the stellar halo, one has the additional option of using N-body simulations of Bullock and Johnston in which the halo is build up purely
by accretion of satellite galaxies.  The program has been compiled and tested using GNU C++ compiler on both Linux and Mac OS X. 


Installation


Select Data directory

A preset data directory  is used by the code to store some data which is used internally. During configure a user should provide a path for it. This directory should be somewhere in the home ,  so  as to avoid root access while running setup later on (some extra files are created during setup).  Also  the data  directory can
grow upto 2GB in size, hence it is best to keep it in home.

Assuming that the chosen data directory is   /home/user/GalaxiaData,  then to install do the following

Untar, compile and install

tar -zxvf galaxia-X.X.X.tar.gz
cd galaxia-X.X.X
./configure --datadir=/home/user/GalaxiaData
make
sudo make install

cp -r GalaxiaData /home/user/

Non root installation

By default the above commands will install the executable file in /usr/local/bin  and so needs root access in make install.
If one wants to install locally without root access e.g. in home/user/sw/bin/ , then do

./configure --prefix=home/user/sw --datadir=/home/user/GalaxiaData
make
make install
cp -r GalaxiaData /home/user/GalaxiaData



If /home/user/sw/bin/  is not already in your search path then you can add it as follows.

For bash shell: 
in ~/.bashrc file add
export PATH=$PATH:/home/user/sw/bin

For tcsh or csh:
in ~/.chsrc file add
set PATH = ($PATH /home/user/sw/bin)


Installing ebf library

Output files are in a special binary format known as EBF.  To read them one has to additionally install the
ebf library corresponding to the programming language of ones choice. To download ebf library go to
http://ebfformat.sourceforge.net
Currently supported languages are c, c++, fortran, java, python, idl
and matlab. See the ebf documentation ebfdocs-x.x.x/index.html  for details on installing the ebf library for your preferred programming
language. Note, just putting the matlab and IDL scripts in your search path is not enough see the README
or installation instruction for each library.


Installing ebftkpy

To manipulate the output files one needs to install ebftkpy, which is automatically installed when the python ebf module is installed.
The python module will be installed in a standard location but  where the ebftkpy script is installed can be controlled
by specifying --install_scripts=mypath. The mypath can be /usr/local/bin/  or somewhere in your home directory
where you keep your programs e.g., /home/user/sw/bin/.  If mypath is not in your search path then you
need to add it as shown in previous section.  Note if python numpy module is not installed (although it is quite standard to have it)
you will also have to install it.

tar -zxvf libebf_python-X.X.X.tar.gz
cd libebf_python-X.X.X
sudo python setup.py install --install-scripts=mypath
OR
python setup.py install --user --install-scripts=mypath (for non root)




Contents of GalaxiaData:

Below is the list of contents of directory  GalaxiaData/ .Only the first two items are of interest for the user.

Examples/                           :    contains example parameterfile and fieldfile.
docs/index.html              :    html guide.
BHTree-2.2/bhtree_no_wf/       :    directory containing the BHtree  files (no warp and flare).
BHTree-2.2/bhtree_with_wf/    :    directory containing the BHtree  files (with warp and flare).
Isochrones/                         :    directory containing isochrones
Extinction/ExMap3d_1024.ebf  :   file containing 3d extinction map  
Extinction/Schlegel_4096.ebf :   file containing 2d Schlegel map
Model/vcirc.dat                    :    A file containing tabulated values of the circular velocity
Model/surface_density.ebf    :   file containing surface density data for disc analytic functions  
nbody1/                      :   directory for N-body models  



After the installation is complete you can safely delete the directory  galaxia-X.X.X .

Usage

Initial setup, BHTree files:

Before the code can be used one should generate the BHTree files  by issuing the following command.

galaxia -s warp

which will create the required files in bhtree_with_wf/.  This can take about an hour but needs to be done only once. The code will ask for confirmation before producing these files.  In case you delete the files in bhtree_with_wf/   the code will ask you to generate them again.  Althought not necessary but if one plans to use the option  warpFlareOn=0 in the parameterfile, i.e., without warp and flare,  then one one should also generate its separate BHTree files (bhtree_no_wf/) with galaxia -s nowarp

Generating a synthetic survey :

galaxia -r myparameterfile

This will generate a file galaxy1.ebf in the output directory specified in myparameterfile.
A copy of parameterfile is also saved in galaxy1.ebf which can be viewed with

ebftkpy -cat galaxy1.ebf "/log"

To generate a survey for a specified field list. This feature is experimental for the time being.

./Galaxia -r --fieldfile=fieldfile.txt myparameterfile

The fieldfile should be
<head>
30 3 -1 2 0 1
<head>
 long[0]  lat[0] extra[0]
long[1]  lat[1] extra[1]
......   .....  .......
and so on

The long and lat should be  in degrees and the area of each field will be taken from the parameterfile.
The numbers in the <head> mean the following number of rows (r), number of columns (c) , unused,  number of columns to read ,
the order in which to read columns (columns are numbered from 0 to c-1).
Example myparameterfile and fieldfile are provided in GalaxiaData/Examples/

Generating  a stellar halo survey  using Bullock and Johnston simulations:

galaxia -r --nfile=halo02 --hdim=6  myparameterfile     //With kinematics
OR
galaxia -r --nfile=halo02 --hdim=3  myparameterfile     //Without kinematics

This will generate a file halo02.ebf in the output directory specified in myparameterfile which corresponds to halo02.

Available photometric system and filters: For each photometric band the column number and data name for the isochrone files are shown below. The filter or band names are from column 7 onwards.
Photometric
system
 0
 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
SDSS
 log(age/yr) M_ini M_act logL/Lo logTe logG mbol u
g
 r
 i
 z
 C/O
 M_hec
 period
 pmode
 logMdot
 int_IMF


UBV
 log(age/yr) M_ini M_act logL/Lo logTe logG mbol U
 B
 V
 R
 I
 J
 H
 K





DCMC
 log(age/yr) M_ini M_act logL/Lo logTe logG mbol I
 J
 H
 Ks









STROEMGREN






V1
 u
 v
 b
 y
 Hb_w
 Hb_n








Appending  catalog file with magnitudes in other photometric bands:

galaxia -a --psys=photometricSystem galaxy1.ebf
 
This will append to the existing file galaxy1.ebf, absolute magnitude in a different photometric system e.g  SDSS, DCMC and so on.

ebftkpy galaxy1.ebf
should show the new data objects.

Help:

galaxia --help
 This  displays the usage instructions incase you forget them.
NAME:
     galaxia-x.x.x -a code to generate a synthetic galaxy survey

USAGE:
     galaxia     -s parameterfile
     galaxia     -r parameterfile
     galaxia     -a --psys=photometricSystem filename
     galaxia     -r --nfile=haloname [--hdim=3 or 6] parameterfile
     galaxia     --copyright
     galaxia     --help
DESCRIPTION:
     -s           initial setup to generate BHTREE files
     -r           run the code to generate stellar data
     -a           append catalog file with magnitudes in an alternate photometric system
     --nfile      halo02,halo05 etc to sample Bullock Johnston stellar halos
     --fieldfile  to generate stars in specific fields
     --hdim       dimensionality of smoothing lengths, for N-body models only
     --copyright  print the copyright and warranty
CONTACT:
Report bugs to <bugsanjib@gmail.com>



Running multiple instances:
You can run multiple instances of the program galaxia but they should have unique output file names or you may risk two different instances of the program writing to the same file and hence corrupting the data. Note, the code creates a bunch of temporary files  (for the parameter outputFile set to galaxy1 the final output file  is galaxy1.ebf  and the temporary files are named as galaxy1.ebf.tmpX) and these are deleted in the end.  If the program terminates abruptly these files might not be deleted. In sush cases it is safe to delete them manually if needed.

Parameterfile

This file is used to setup the configuration of the synthetic survey. This file must contain all the listed parameters followed by their values. In case you miss a parameter the code will remind you. See the supplied test file "myparameterfile" for further details.  "% or #"  can be used to put comments in file.  Below is brief guide to setting up the parameters.


Parameter
 Description
 Fiducial Values
outputFile
 output file name.   A suffix  ".ebf"  will be added to the provided filename
This parameter is ignored if using option --nfile=filename , for such a case output filename is always filename.ebf .
 galaxy1
outputDir the directory where output file will be stored
 Examples/
photoSys UBV or  SDSS or   DCMC or STROEMGREN UBV
magColorNames V,B-V
first argument is used for appMagLimits and the second for colorLimits		 V,B-V
appMagLimits[0] Apparent magnitude limit: lower
-100
appMagLimits[1] Apparent magnitude limit: upper
30
absMagLimits[0] Absolute magnitude limit: lower
-100
absMagLimits[1] Absolute magnitude limit: upper
100
colorLimits[0] Color limit: lower
 -100
colorLimits[1] Color limit: upper
 100
geometryOption Option to set up the survey geometry.
0: All Sky
1: Circular Patch  		1
longitude Used only if geometryOption=1. Galactic longitude in degrees of the center of the patch 0
latitude Used only if geometryOption=1. Galactic latitude in degrees of the center of the patch 90
surveyArea Used only if geometryOption=1 or when fieldfile is set. Survey area in square degree 100
fSample
 Fraction of stars to generate.
Normally set it to 1.0 to get the correct number of stars. If you want to generate
fewer stars i.e subsample the data, set it to less than one. The total number of stars is reduced by the factor given.
 1.0
popID
 the ID of the population to be generated. If set to -1 all populations (0-9) are generated i.e
  0: Thin Disk  < 0.15    Gyr
  1: Thin Disk     0.15-1 Gyr
  2: Thin Disk     1-2      Gyr
  3: Thin Disk     2-3      Gyr
  4: Thin Disk     3-5      Gyr
  5: Thin Disk     5-7      Gyr
  6: Thin Disk     7-10    Gyr
  7: Thick Disk
  8: Stellar Halo
  9: Bulge
10: Bullock & Johnston stellar halos
If set to a number 0-10  only that population is generated.
If using option --nfile=filename, the value is ignored and set to 10.
 -1
warpFlareOn
 Option to set the warp and flare in the thin disk. If set to 1 warping and flaring is done and if set to 0 its not done.
 1
seed
 a seed used to generate the random numbers. To generate a new random data set use a new seed.
 17
rmax
 the maximum radial distance to which the stars are desired kpc
1000
starType
 For future use. Currently must be set to 0
 0
photoError
 For future use. Currently must be set to 0
 0


Output data details:

The output data is in a special binary format which we call EBF (Efficient and Easy Binary Format) and these files are denoted with .ebf extension.
An EBF file is a collection of data objects which are labelled by unique tag-names. Tag names begin with a "/".  By default the code Galaxia produces the following data objects (in the table below N is the number of stars)

Tag name         
Description
 Units
 layout
/px /py pz      Position  (x,y,z)    heliocentric
 kpc Nx1
/vx /vy /vz
 Velocity  (U,V,W) heliocentric km/s Nx1
/glon
 galacitic longitude
 degree
 N x 1
/glat
 galacitic latitude degree N x 1
/age Age  
log (age/yr) N x 1
/feh Metallicity
[Fe/H] N x 1
/alpha Alpha element abundance (only for Bullock & Johnston models)
 [alpha/Fe]
 N x 1
/smass Stellar mass
Msolar N x 1
/mag0 for internal use and consistency check only
N x 1
/mag1 for internal use and consistency check only
N x 1
/mag2 for internal use and consistency check only
N x 1
/rad Radial distance
kpc N x 1
/popid Population ID, an integer indicating the population type ranging from 0 to 10. See parameterfile table for more details.
Nx1
/satid Satellite ID, an integer indicating the satellite number in simulations. For Bullock and Johnston simulations a satellite is uniquely identified by a pair of numbers (h,s)  halo no and satellite no respectively.  (h,s) is encoded as  SatID=1000*h+s 

Nx1
/fieldid
 Field no of star if --fieldfile option is used
Nx1
/partid 0 if the star has same co-orodinates as that of its parent N-body particle or else 1
Nx1
/center Position and velocity of sun in galactocentric coordinates.
First 3 cooridnates are position and last three veolicty.
 kpc, km/s
 6
/log A log about the simulation containing details such as parameter  file, code version etc.

/teff Effective Temperature log(T/Kelvin) Nx1
/grav Surface gravity log(gravity) Nx1
/mbol Bolometric magnitude log(L/LSun)
 Nx1
/photosys_band Absolute magnitude for different bands and photometric system Mi, e.g DCMC_J, DCMC_K, UBV_B etc
 mag
 Nx1
/exbv_schelegl Extinction E(B-V)at the location of the star as given by the 3d Extinction model which is normalized to match the Schlegel maps at infinity, ESchelgelB-V mag
 Nx1
/exbv_schlegel_inf Extinction E(B-V) at infinity as given by Schelgel maps
 mag
 Nx1
/exbv_solar Extinction E(B-V) normalized to a constant redenning rate of 1 in solar neighborhood, ESolarB-V.  Multiply by 0.53 to get the correct redenning rate that bets fits the Schelegel data or use ones own value.
 mag
 Nx1
/mact
 While smass is the initial mass of the star, mact is the actual mass.
 Msolar
 Nx1
/mtip For the given age and metallicity of the star, the mass for a star to be at the tip of the giant branch. Useful for detecting if the star is on horizontal branch or is red clump stars, the condition for which would be smass>mtip.
Msolar Nx1

./ebftkpy galaxy1.ebf
will list the data objects in the file galaxy1.ebf.

Adding Extinction

The output magnitudes are absolute magnitudes Mi (i stands for the name of the band). One can convert them to apparent magnitudes, mi ,and also apply the extinction as follows
mi=Mi+5 alog[100 (r/kpc)] +ESchelgelB-V f(i)   where f(i)=A(i)/E(B-V)
or one could use ESolarB-V*0.53 .

The values of f(i) for different bands are given below, the data being taken from
David Schlegel, Princeton, 16 April 1999
Doug Finkbeiner, Berkeley

   Assuming an R_V=3.1 extinction curve, the dust maps should be multiplied
   by the value in the final column to determine the extinction in a given
   passband.  The standard optical-IR bandpasses are represented by the CTIO
   and UKIRT transmission curves.  For further details, see Appendix B of
   the text.

   Filter name       LamEff  A/A(V)   A/E(B-V)
   ----------------  ------  -------  -------
   Landolt U           3372    1.664    5.434
   Landolt B           4404    1.321    4.315
   Landolt V           5428    1.015    3.315
   Landolt R           6509    0.819    2.673
   Landolt I           8090    0.594    1.940
   CTIO U              3683    1.521    4.968
   CTIO B              4393    1.324    4.325
   CTIO V              5519    0.992    3.240
   CTIO R              6602    0.807    2.634
   CTIO I              8046    0.601    1.962
   UKIRT J            12660    0.276    0.902
   UKIRT H            16732    0.176    0.576
   UKIRT K            22152    0.112    0.367
   UKIRT L'           38079    0.047    0.153
   Gunn g              5244    1.065    3.476
   Gunn r              6707    0.793    2.590
   Gunn i              7985    0.610    1.991
   Gunn z              9055    0.472    1.540
   Spinrad R           6993    0.755    2.467
   APM b_J             4690    1.236    4.035
   Stromgren u         3502    1.602    5.231
   Stromgren b         4676    1.240    4.049
   Stromgren v         4127    1.394    4.552
   Stromgren beta      4861    1.182    3.858
   Stromgren y         5479    1.004    3.277
   Sloan u'            3546    1.579    5.155
   Sloan g'            4925    1.161    3.793
   Sloan r'            6335    0.843    2.751
   Sloan i'            7799    0.639    2.086
   Sloan z'            9294    0.453    1.479
   WFPC2 F300W         3047    1.791    5.849
   WFPC2 F450W         4711    1.229    4.015
   WFPC2 F555W         5498    0.996    3.252
   WFPC2 F606W         6042    0.885    2.889
   WFPC2 F702W         7068    0.746    2.435
   WFPC2 F814W         8066    0.597    1.948
   DSS-II g            4814    1.197    3.907
   DSS-II r            6571    0.811    2.649
   DSS-II i            8183    0.580    1.893

Stellar Halo

Following is the list of stellar halos that one can generate using Bullock and Johnston simulations.
      'halo02','halo05','halo07','halo08','halo09','halo10','halo12','halo14','halo15','halo17','halo20'   // 11 ΛCDM halos
      'newhalo_rad','newhalo_circ','newhalo_old','newhalo_young','newhalo_highl','newhalo_lowl'   // 6 with artificial accretion history

The file satprop.ebf  contains information related to properties of accretion events. Properties of each satellite are stored in a linear list or array. The property lists are as follows-
    Tsat        = time since accretion, tacc (Gyr)
    Jsat        = circularity of orbit, ε
    Lsat        = luminosity L, (LSun)
    Msat       = dark matter mass of satellite M ,(MSun)
    Bsat       = bound status. 1 if bound else 0
    Esat       = binding energy parameter η=Rcirc/Rvir
A pair of numbers (h,s) uniquely defines a satellite.
    Nsat[h]   = number of satellites in halo number h
    Nsatc[h] = starting position in satellite property list

Tsat[Nsatc[h]+s] is the accretion time of satellite (h,s). Valid values of h are 2,5,7,9,10,12,14,15,17 and 20
and valid values of s are 0 to Nsat[h]-1

The information about the satellite (h,s) is encoded as SatId=1000*h+s

Data I/O tools and the ebf library

The ouput data is in a special binary format called EBF.  These files are denoted by extension .ebf. These files are portable across systems with different endianess.
An EBF file is a collection of data objects which are labeled by unique tag-names. Tag names begin with a "/".  To work with ebf files one should install the libebf  routines for the programming language of ones choice (see the ebf documentation at libebf_multi-x.x.x/docs/index.html for installation instruction and usgae) . To manipulate ebf files one should use the command line program ebftkpy. Installing the python ebf module will automatically install it.  Hence, everyone should first install the python module.   Once ebf library for your choosen programming language is installed, loading data is easy. Below are some examples for MATLAB, Python and IDL.  An example analysis in IDL is also shown one can do a similar analysis in other languages.     


To load data:

IDL>ebf_read,'galaxy1.ebf','/',data
IDL> help,data,/struct

MATLAB> data=Ebf.read('galaxy1.ebf','/')
MATLAB> data

 PYTHON> import ebf
PYTHON> data=ebf.read('galaxy1.ebf','/')
PYHTON> print data.keys()


An example analysis in IDL:


; gives a summary of the data objects in the file.
ebf_info,'galaxy1.ebf'       

; Load the file
ebf_read,'galaxy1.ebf','/',data

; get info about struct and the parameter file used
help,data,/struct
print,string(data.log)

; Galactic to galactocentric
; Typical value of Solar position and motion
; (X,Y,Z,U,V,W) =[-8.0, 0.0, 0.015,11.1,239.08,7.25],
; also contained in data.center
data.px=data.px+data.center[0]
data.py=data.py+data.center[1]
data.pz=data.pz+data.center[2]
data.vx=data.vx+data.center[3]
data.vy=data.vy+data.center[4]
data.vz=data.vz+data.center[5]


; absolute to apparent magnitude,
; SDSS is photometric system and g,r,i are the bands
mapp_r=data.SDSS_r+5*alog10(data.rad*100.0)
mapp_g=data.SDSS_g+5*alog10(data.rad*100.0)
mapp_i=data.SDSS_i+5*alog10(data.rad*100.0)

; Add extinction
; the function aebv_factor(bandname)  gives the factor A/E(B-V) for the required band
; and can be written by the user from the table given above.
; assuming the user has written the function aebv_factor()

mapp_r=mapp_r+data.exbv_schlegel*aebv_factor('Sloan_r')
mapp_g=mapp_g+data.exbv_schlegel*aebv_factor('Sloan_g')
mapp_i=mapp_i+data.exbv_schlegel*aebv_factor('Sloan_i')


; this cotains the satellite properties like circularity, lum,t_acc etc
ebf_read,'../data/satprop.ebf','/',satprop
help,satprop,/struct
print,string(satprop.log) ; information about satprop



; The option below is only for sampled N-body stellar halos
; Shows the use of satid and satprop
; plot satellites with
; (t_acc>10 Gyr) AND (lum>1e6 L_sun) AND (circularity>0.5)
; for sat no 's' in halo 'h'  (h,s)-> satid=h*1000+s 
; id in satprop.tsat array is given by
id=satprop.nsatc[data.satid/1000]+(data.satid mod 1000)
; locate the required particles
ind=where(satprop.tsat[id] gt 10)and(satprop.lsat[id] gt 1e6)and(satprop.jsat[id] gt 0.5)
; plot them
plot,data.px[ind],data.pz[ind],psym=3,xrange=[-100,100],yrange=[-100,100]

References:


The main reference for galaxia is
    1) Sharma, S., Bland-Hawthorn, J., Johnston, K. V., & Binney, J. 2011, ApJ, 730,3

Currently the implemented analytic model is the Besancon model from
    2) Robin, A. C., ReylŽe, C., Derri`ere, S., & Picaud, S. 2003, A&A, 409, 523

Isochrones used in galaxia are from  Padova Stellar Evolution database. They were generated by CMD 2.1 (http://stev.oapd.inaf.it/cmd). Basic reference for them is given below please look at this http://stev.oapd.inaf.it/~lgirardi/cmd_2.3/help.html for more reference on isochrones.
    3) Marigo, P., Girardi, L., Bressan, A., Groenewegen, M. A. T., Silva, L., & Granato, G. L. 2008, A&A, 482, 883
    4) Bertelli, G., Bressan, A., Chiosi, C., Fagotto, F., & Nasi, E. 1994, A&AS, 106, 275


If using N-body stellar halos they are from
    5) Bullock, J. S., & Johnston, K. V. 2005, ApJ, 635, 931
    6) Robertson, B., Bullock, J. S., Font, A. S., Johnston, K. V., & Hernquist, L. 2005, ApJ, 632, 872
    7) Font, A. S., Johnston, K. V., Bullock, J. S., & Robertson, B. E. 2006, ApJ, 646, 886