Mario Juric edited this page Jan 1, 2017 · 1 revision

galfast Documentation

What does it do?

galfast is a very fast generator of flux-limited mock catalogs of stars in the Milky Way.

It is similar to the widely used [http://model.obs-besancon.fr/ Besancon model], with a few crucial differences:

  1. The ability to generate catalogs for arbitrary, user-supplied Galactic models, including the empirically derived ones. The default settings use the SDSS-derived models based on fits to SDSS stellar observations over 8000 deg^2^ of the sky: Juric et al. (2008) for the density law, Ivezic et al. (2008) for the Fe/H distribution, and Bond et al. (20xx) for the distribution of kinematics.
  2. Can account for the effects of unresolved binary systems
  3. The ability to generate output in arbitrary photometric systems
  4. The ability to generate output in arbitrary observation footprints on the sky.
  5. Speed. galfast can generate large (~thousands of deg^2^) catalogs in a matter of minutes.

Because of this added flexibility and the use of empirically derived models, galfast should produce closer matches to the actual observed star counts and color-magnitude diagrams.

What it currently misses?

  1. Module to add observational errors to proper motions
  2. Stellar ages, logg, and anything that sensitively depends on them

The guilty party

This code is being maintained by [http://www.sns.ias.edu/~mjuric Mario Juric]. Direct all your questions/comments to mjuric [at] cfa.harvard.edu.

Using galfast on HYBRID computer cluster

[http://fizika.pmfst.hr/hybrid/ hybrid] (or HYBRID) is a hybrid GPU/CPU cluster project lead by [http://vinkovic.org Dejan Vinkovic] at the University of Split (Croatia). It has eight compute nodes (node01 through 08), each node having two quad core processors, and two NVIDIA Tesla T10 GPUs.

Assuming you have an account on hybrid, log on to the frontend via SSH to hybrid.pmfst.hr (or hybrid.mwscience.net -- it's an alias). From there jobs can be scheduled to compute nodes through PBS, or executed directly by ssh-ing to individual nodes (e.g., ssh node02, ... run code there ...). '''The latter is the currently recommended way to run GPU codes, as PBS is currently unaware of GPU resources'''. However, it requires some coordination and manners (e.g., before running a job on a node, try to see if anyone else is running there or not). For the same reason, please prefer nodes 05 through 08 for mwscience related computations.

Finding/Using galfast Binaries

The latest version of galfast can always be found in ~mjuric/galfast/bin. '''I recommend you add that directory to your path''' so that you can run it from anywhere just by typing `galfast'.

Also, you will need to add the path to libraries that galfast uses to your LD_LIBRARY_PATH: {{{ export LD_LIBRARY_PATH=~mjuric/galfast/lib:$LD_LIBRARY_PATH }}}

Introduction: What galfast does?

Given:

  1. A model (or multiple models) consisting of a luminosity function and a stellar number density distribution
  2. A model of their metallicity distribution and distribution of kinematics (not required if not needed)
  3. A specification of other stellar properties, such as the binary fraction (not required if not needed)
  4. A 3D extinction map (not required if not needed)
  5. A specification of footprint to be observed and flux limits of the survey
  6. The photometric system and instrumental errors of the telescope (not required if not needed)
  7. A specification of the output format (ASCII or FITS tables)

galfast will generate a mock catalog of stars that is as close as possible to what would have actually been observed given the specified system and population model(s).

As an example, here are a few lines of ASCII output from a job that generated a catalog for a l=70, b=29 pencil beam of 1deg radius, with SDSS proper motions and photometry.

# lb[2] radec[2] XYZ[3] DM absSDSSr comp FeH vcyl[3] pmlb[3] pmradec[3] absSDSSrSys[2] absSDSSrSysNcomp obsSDSSugriz[5] SDSSugriz[5] SDSSugrizPhotoFlags
  70.36942490   28.57254446  268.21446145   43.88503571    5959.35   -5721.16    3307.99  14.199   5.771   0 -0.812   -72.6  -114.4   -24.6    -5.47     1.21  -139.05    -2.26    -5.13  -139.05   5.773  12.530 2  21.974  20.482  19.995  19.738  19.765  21.974  20.501  19.971  19.779  19.776    0
  70.35898822   29.29306011  267.22963989   44.01354387    6553.41   -4053.32    2414.45  13.466   5.407   0 -0.703   -53.6   -76.8   -42.4    -5.76     1.32  -156.54    -2.37    -5.42  -156.54   5.407  13.817 2  20.684  19.358  18.839  18.712  18.703  20.742  19.353  18.873  18.704  18.715    0
  69.32100596   29.16087116  267.17252909   43.09904964    4797.83   -8483.70    5059.76  15.082   5.873   0 -1.269   -64.4    56.4   -64.4    -1.70     1.69  -295.86    -1.98    -1.34  -295.86   5.873  99.999 1  22.828  21.356  20.939  20.762  20.804  22.721  21.439  20.955  20.786  20.799    0

These mock catalogs can be used for observation planning, Galactic model fitting, etc.

Running a Sample Model

Copy a sample model from `/home/mjuric/projects/milkyway-model' on hybrid. You should have something like:

[mjuric@hybrid milkyway-model]$ ls -lB *.conf
-rw-rw-r-- 1 mjuric mjuric  101 Aug  2 04:36 astrometry.equ.conf
-rwxrwxr-x 1 mjuric mjuric 2866 Aug  5 06:51 cmd.all.conf
-rw-rw-r-- 1 mjuric mjuric 2831 Aug  2 04:36 cmd.BHB.conf
-rw-rw-r-- 1 mjuric mjuric 1250 Aug  2 04:36 cmd.MS+RGB.bulge.conf
-rwxrwxr-x 1 mjuric mjuric 1381 Aug  5 06:51 cmd.MS+RGB.conf
-rwxrwxr-x 1 mjuric mjuric 2833 Aug  2 04:36 cmd.RRLy.conf
-rw-rw-r-- 1 mjuric mjuric 2829 Aug  2 04:36 cmd.WD.conf
-rw-rw-r-- 1 mjuric mjuric 2492 Aug  2 04:37 definitions.conf
-rw-rw-r-- 1 mjuric mjuric  457 Aug  2 04:37 den.Juric+2008.halo.conf
-rw-rw-r-- 1 mjuric mjuric  424 Aug  2 04:37 den.Juric+2008.thick.conf
-rw-rw-r-- 1 mjuric mjuric  421 Aug  2 04:37 den.Juric+2008.thin.conf
-rw-rw-r-- 1 mjuric mjuric  547 Aug  2 04:37 den.LopezCorredoira+2005.bulge.conf
-rw-rw-r-- 1 mjuric mjuric  214 Aug  2 04:37 extinction.conf
-rw-rw-r-- 1 mjuric mjuric   17 Aug  2 04:37 fitsout.conf
-rw-rw-r-- 1 mjuric mjuric  156 Aug  5 06:55 footprint.conf
-rw-rw-r-- 1 mjuric mjuric   35 Aug  2 04:37 gal2other.conf
-rw-rw-r-- 1 mjuric mjuric  371 Aug  5 06:40 instrument.photo_errors.conf
-rw-rw-r-- 1 mjuric mjuric  710 Aug  2 04:37 kinematics.Bond+2010.conf
-rw-rw-r-- 1 mjuric mjuric  231 Aug  2 04:37 metallicity.bulge.conf
-rw-rw-r-- 1 mjuric mjuric  310 Aug  2 04:37 metallicity.gaussian.conf
-rw-rw-r-- 1 mjuric mjuric  413 Aug  2 04:37 metallicity.Ivezic+2008.conf
-rw-rw-r-- 1 mjuric mjuric  392 Aug  2 04:37 model.thindisk.conf
-rw-rw-r-- 1 mjuric mjuric  369 Aug  2 04:37 output.counts.conf
-rw-rw-r-- 1 mjuric mjuric  782 Aug  5 06:39 photometry.conf
-rw-rw-r-- 1 mjuric mjuric  219 Aug  2 04:37 propermotion.equ.conf
-rw-rw-r-- 1 mjuric mjuric  219 Aug  2 04:37 propermotion.gal.conf
-rw-rw-r-- 1 mjuric mjuric  394 Aug  5 06:55 skygen.conf
-rw-rw-r-- 1 mjuric mjuric  117 Aug  2 04:37 vel2pmgal.conf

The details of what these files are and how to write/modify them will be explained below.

Log onto one of the compute nodes on hybrid, e.g.:

[mjuric@hybrid demo]$ ssh node07
Last login: Tue Nov 24 23:49:40 2009 from hybrid.local
[mjuric@node07 ~]$ cd demo
[mjuric@node07 demo]$ 

Assuming you have ~mjuric/galfast/bin' in your path, rungalfast' by typing:

galfast catalog cmd.MS+RGB.conf

You should see output similar to this one:

[mjuric@node07 demo]$ galfast catalog cmd.conf
GPU accelerator     : Using Device 0: "GeForce GTX 285" (autoselected)
Astrometry          : Equatorial coordinates in column radec   ## gal2other[0]
Output file         : sky.obs.txt (text)
Kinematics          : Bond+2010 for components { 0, 10, 15, 20, 30 } (thin), { 1, 11, 16, 21, 31 } (thick), { 2, 12, 17, 22, 32 } (halo)   ## Bond2010[0]
Metallicity         : Ivezic+2008 for components { 0, 20, 30 } (thin), { 1, 21, 31 } (thick), { 2, 22, 32 } (halo)   ## FeH[0]
Photometry          : SDSSugriz (-2.5 <= FeH <= 0 [0.01], -1 <= M <= 28 [0.01], data/MSandRGBcolors_v1.3.dat) for components { 0, 1, 2, 3 }   ## photometry[0]
Proper motions      : Equatorial proper motions in column pmradec   ## vel2pm[0]
Proper motions      : Galactic proper motions in column pmlb   ## vel2pm[1]
Footprint           : Beam towards (l, b) = 0 90, radius = 5deg
Footprint           : Tiled with 90 1x1 deg^2 pixels
Extinction maps     : data/makeArTableForMarioanorth021810.fits (north), data/makeArTableForMarioasouth021710.fits (south).
Component 2         : broken power law {-2.62=(28kpc)=-3.8, 0.7, 1, data/MrLF.MSandRGB_halo_v1.1.dat}
Component 1         : exponential disk {3261, 743, data/MrLF.MSandRGB_v1.1.dat}
Component 0         : exponential disk {2150, 245, data/MrLF.MSandRGB_v1.1.dat}
Photometric errors  : Adding errors to {obsSDSSg, obsSDSSi, obsSDSSr, obsSDSSu, obsSDSSz}   ## photometricErrors[0]
Pipeline [comp=0]   : skygen | clipper[0] | FeH[0] | Bond2010[0] | photometry[0] | photometricErrors[0] | gal2other[0] | vel2pm[0] | vel2pm[1] | fitsout[0]
Pipeline [comp=1]   : skygen | clipper[0] | FeH[0] | Bond2010[0] | photometry[0] | photometricErrors[0] | gal2other[0] | vel2pm[0] | vel2pm[1] | fitsout[0]
Pipeline [comp=2]   : skygen | clipper[0] | FeH[0] | Bond2010[0] | photometry[0] | photometricErrors[0] | gal2other[0] | vel2pm[0] | vel2pm[1] | fitsout[0]
Integrating         : # [1].
Comp. 0 counts      : 48585.3147 to generate, 42316.9881 within footprint.
Integrating         : # [1].
Comp. 1 counts      : 133036.41 to generate, 115858.283 within footprint.
Integrating         : # [1].
Comp. 2 counts      : 184174.689 to generate, 160438.943 within footprint.
Stars expected      : 318614
Comp. 0 completed   : 42099 stars (48467 generated, -0.5 sigma from 48585.3).
Comp. 1 completed   : 115787 stars (133368 generated, 0.9 sigma from 133036).
Comp. 2 completed   : 158770 stars (183353 generated, -1.9 sigma from 184175).
Total               : 316656 stars written out.

The sample configuration files generate a realization of a Galactic model containing only main sequence and RGB stars in a 5deg wide (10deg radius) pencil beam pointed towards the north Galactic pole, assuming Juric et al. (2008) model the density law (two exponential disks + a power law halo), Sesar, Juric, Ivezic (2011) for the halo, Ivezic et al. (2008) model for the metallicity distributions, and Bond et al. (2010) model for the kinematics. The generation should take about ~30 seconds.

The output will be stored in sky.obs.txt. Here are a few lines of the output:

# lb[2] radec[2] XYZ[3] DM absSDSSr{alias=M1;alias=absmag;band=SDSSr;} comp FeH vcyl[3] pmlb[3] pmradec[3] Am AmInf obsSDSSugriz[5]{class=magnitude;fieldNames=0:obsSDSSu,1:obsSDSSg,2:obsSDSSr,3:obsSDSSi,4:obsSDSSz;} SDSSugriz[5]{class=magnitude;fieldNames=0:SDSSu,1:SDSSg,2:SDSSr,3:SDSSi,4:SDSSz;} SDSSugrizPhotoFlags{class=flags;} 
# generated with galfast version 0.8.0-6.ff674d6
   0.01100255   85.89933369  196.65242417   24.84907135     109.88       0.02    1532.60  10.933   8.663   0 -0.514   -56.6  -176.2    14.4    -6.74    -6.30    10.54     1.36    -9.13    10.54  0.042  0.042  24.535  21.037  19.624  18.966  18.606  23.551  21.013  19.637  18.953  18.613    0
   0.01510783   87.87075717  194.84740741   25.95730645      25.15       0.01     676.57   9.153   5.914   0 -0.553   -20.2  -172.3    47.9   -16.53    -2.70    41.05    -6.95   -15.24    41.05  0.031  0.031  17.483  15.740  15.115  14.843  14.833  17.460  15.730  15.098  14.870  14.792    0
   0.02487523   85.68357504  196.84864139   24.72733586      22.70       0.01     300.74   7.397  11.469   0 -0.116   -63.8  -176.5    22.1   -34.12   -36.71    18.91    10.80   -48.94    18.91  0.044  0.045  23.055  20.309  18.894  17.464  16.686  22.893  20.341  18.911  17.436  16.663    0
   0.03467178   87.03991507  195.61287186   25.49387893      38.07       0.02     736.22   9.338  12.314   0 -0.878    -3.5  -145.7    34.5   -22.77     2.28    26.97   -14.65   -17.57    26.97  0.041  0.041  24.864  22.943  21.728  20.141  19.259  25.579  23.133  21.692  20.179  19.373    0
   0.05013986   87.31270338  195.36280396   25.64727419      12.11       0.01     257.92   7.060   8.273   0 -0.577   -45.3  -188.8     5.9   -29.83   -28.83     0.38     7.23   -40.85     0.38  0.037  0.038  19.184  16.713  15.386  14.772  14.522  19.242  16.691  15.370  14.780  14.492    0
   0.06032662   89.33568303  193.48441791   26.76639017       6.13       0.01     528.57   8.616  10.484   0 -0.794    60.6  -184.9    10.5   -16.08    28.19     2.49   -32.39     1.96     2.49  0.022  0.022  23.741  20.553  19.170  18.035  17.536  23.024  20.521  19.122  18.043  17.482    0
   0.06484077   86.48103429  196.12529374   25.18104694      36.85       0.04     599.19   8.892  11.366   0 -0.599    28.7  -188.5    24.2   -12.93    13.97    14.59   -18.83    -2.81    14.59  0.037  0.037  24.352  21.735  20.315  18.979  18.276  24.227  21.705  20.295  18.958  18.257    0
   0.07585019   85.55741366  196.96530654   24.65880519      31.29       0.04     402.79   8.032  11.620   0 -0.604    38.4  -185.7    -0.9   -20.64    24.90   -11.88   -32.21    -2.82   -11.88  0.049  0.049  25.702  21.155  19.659  18.294  17.629  23.645  21.121  19.701  18.302  17.566    0

The first line is a header describing the columns (together with some internally used metadata). It is followed by fixed-width columns with the properties of generated stars.

Understanding how catalogs are generated

galfast aims to create mock catalogs of observations of stars that would be obtained by a telescope or survey. This catalog will depend on many things, beginning with what's out there (how the stars are distributed in the Galaxy), their physics (e.g., stellar luminosities, whether they're single stars or unresolved binary/multiple systems), the properties of interstellar space through which the light travels (e.g., extinction), the properties of the survey (e.g. the observed footprint, photometric system, and flux limits), and finally the properties of the telescope and the detector (e.g., the instrumental errors that each introduces).

This idealized path of the stellar flux from the star to the observer is followed in galfast and implemented as a '''pipeline''' consisting of '''stages''', implemented by different "'''processing modules'''". Stars are created at the beginning of the pipeline based on one or more density '''models''', and have their properties modified (or new ones added) as they move towards the end.

This is best illustrated by a typical example of a pipeline:

skygen | Fe/H generator | Photometry generator | Photometric error generator | textout
  1. skygen module generates the stars. It randomly draws a star from a spatial distribution given by one or more of predefined '''models''' (consisting of a density law with some user-settable parameters, and a user-settable luminosity function) and passes it on to the next module in the pipeline. At this point, the generated star has only the position (X,Y,Z) and the absolute magnitude M. Note that even this may already be enough for many purposes.
  2. The Fe/H generator module assigns a stellar metallicity based on one of the offered Fe/H distribution models (for now, Ivezic et al. 2008 and a simple Gaussian).
  3. Given the absolute magnitude and metallicity generated by the previous two stages, the Photometry generator module is now able to compute the absolute magnitudes in the requested set of bands (e.g., SDSS bands). Using position (distance) information, this stage further computes and adds the apparent magnitudes to the set of information we have about the star.
  4. The Photometric error generator takes the apparent magnitudes computed in the previous stage, and the properties of the telescope (specified by the user), to generate the expected observed magnitudes by mixing in some observational error.
  5. The final stage of the pipeline, the textout module, stores all of the information generated by previous stages as a new row in the output text file.

Note that this pipeline can be more complex than shown above. For example, skygen can be made to draw stars from different density distributions describing different stellar populations (which we call ''''components'''; e.g., exponential disk and a halo). Since those stars may have different modules assigning their photometry or the kinematics, the pipeline is actually per-component.

Putting together a `galfast' Simulation: The Configuration Files

The details of how each stage of the pipeline does its work, as well as which stages will form the pipeline, are controlled through configuration files. These are simple (but powerful) text files following the usual [http://en.wikipedia.org/wiki/INI_file INI file syntax]. An example:

[mjuric@hybrid ngp]$ cat cmd.conf
module = config
maxstars = 0
seed = 22

definitions = definitions.conf
footprints = foot.ngp.conf
input = skygen.conf
models = model.thindisk.conf model.thickdisk.conf model.halo.conf
modules = photometry.MS.conf feh.Ivezic08.conf Bond2010.conf extinction.conf gal2other.conf
output = fitsout.conf

Note the 'module=config' line above. It tells galfast that this configuration file is to be read by the 'config' module. In general, all galfast configuration files '''MUST''' have a 'module' keyword specifying to which module they relate to.

The operation of `galfast' is controlled by a main configuration file (typically named 'cmd.conf', but (importantly) having 'module=config' as shown in the example above). It usually contains the following settings:

  • seed:: The random seed of for the simulation. Given the same seed, a same set of config files run with the same version of galfast will produce binary-identical output. maxstars:: The maximum number of stars to generate (default: 100M). This serves as a safety mechanism against accidentally generating huge catalogs (e.g., due to typos in the config files). Turned off by setting it to zero.

  • definitions:: Lists one or more config files containing 'definitions'. In these you may set any key=value pairs you want to be magically predefined in all of the config files. It is useful for setting in one place all values that are frequently needed by various other modules (e.g., the distance to the Galactic center). Note that a definitions file has to have a 'module=definitions' line.

  • footprints:: Specifies the geometry and parameters of the observed area on the sky. For now you can choose between observing a (potentially up to full-sky wide!) pencil beam, or a rectangle in longitude/latitude (either Galactic or J2000 equatorial).

  • input:: Points to the config file of a module that will serve as the first stage of the pipeline (that will draw stars). See below for more details.

  • models:: One or more (whitespace separated) config files with density model selections and parameters. The module specified by the 'input' keyword will load and use these to draw stars. Typical examples are the exponential disk, power-law ellipsoid, broken power law, etc... These primitives should be sufficient to build a fairly complex model of (any) Galaxy.

  • output:: Points to a config file specifying the configuration of the output module (the last stage of the pipeline). This is either a 'fitsout' or a 'textout' module. If left unspecified, 'textout' is the default.

  • modules:: One or more (whitespace separated) config files with configuration of modules that will make-up the "postprocessing" pipeline (all those after input, and before the output module). They don't have to be specified in the order they are to appear in the pipeline - the code will automatically put them in the correct order.

Monte-Carlo Generation of Stars: Important Notes and Configuration Parameters

The only module that currently generates stars (that is, that can serve as 'input' (see above)) is skygen'. Skygen module takes the density laws specified by the given density models (the 'models' keyword in cmd.conf), and draws stars from those distributions. The current implementation ofskygen' accelerates this process by 100x-200x by utilizing GPUs (graphics processing units) to do the required math and random number generation.

Here are the contents of a typical skygen.conf file.

mjuric@corrin:~/projects/galaxy/tests/ngp$ cat skygen.conf 
module = skygen

# Apparent magnitude limits (mags)
m0 = 15
m1 = 25

# Absolute magnitude range (mags)
M0 = 0
M1 = 15

# Apparent/Absolute magnitude band
band = SDSSr

# Sampling resolution (mags)
dm = 0.05

# Sky sampling resolution (degrees)
dx = 1

Besides the obligatory 'module=skygen' line, the config file serves mainly to specify the the flux limits of the catalog you wish to generate, the absolute magnitude limits that encompass all of your luminosity functions, and the two "pixelization scales": angular (dx, in degrees), apparent magnitude (dm, in magnitudes) scale.

Skygen generates stars by dividing the celestial sphere into equal area "beams" ("pixels") whose angular scale is determined by dx. It further subdivides each beam in distance modulus (DM = M - m = 5log(D/pc) - 5) bins, with the size of each distance DM being dm. Furthermore, the luminosity function (that is, the absolute magnitude) within each spatial pixel is further discretized into bins of width dm. This produces a 4D pixelization of whole 3D+absolute magnitude space. Then, the stellar number density \rho(l,b,D,M) is computed at the center of each bin. This value, multiplied by the volume of the bin, is used to draw a Poisson-distributed random variate dN (the number of stars in the bin). If dN is nonzero, dN stars are generated and sent further down the pipeline.

By construction of the algorithm above, '''within each (x,y,z,M) pixel, the Galactic model is assumed to be approximately constant. You must therefore ensure this really is the case by choosing appropriate values for dx and dm'''. Note however that the computation time scales quadratically with both dx^-1^ and dm^-1^. As always, you should strive for an acceptable balance between accuracy and computational time.

skygen is smart enough not to cover any (x,y,z,M) pixel which will fall out of the flux or footprint limits of the survey, as well as smart enough not to cover pixels in M space for which the luminosity function is zero. However, if you set M0 and M1 to a smaller range than your input luminosity functions, they will be truncated to zero outside of it.

Density Laws (models)

The density laws (sometimes called 'density models', or just 'models') specify how different stellar populations (internally referred to as 'components') are distributed in the Galaxy. These are basically arbitrary functions that given a 3D position (X,Y,Z) and an absolute magnitude M, return the density of stars at that point in 4D XYZM space (in units of stars pc^-3^ mag^-1^). There are currently three density laws that have been implemented for `galfast':

  • '''exponential disk''':: Generates stars distributed in an exponential disk using the following formula:
rho = f * LF_effective(M) * expf(-R/l - fabsf(Z)/h);
where R and Z are the cylindrical Galactocentric radius and height above the Galactic plane, respectively. LF(M) is the effective luminosity function appropriately renormalized so that rho(XYZ_{Sun}) is equal to the LF loaded from the configuration file (where XYZ_{Sun} are the XYZ coordinates of the Sun). 'f' is an overall, user-specified, scaling factor. The scale parameters R and h are specified in the configuration file (more about that later).

'''power law ellipsoid''':: Generates stars distributed in a triaxial ellipsoid with a power-law radial profile:

r = sqrt(X^2 + (Y/b_a)^2 + (Z/c_a)^2)
rho = f * LF_effective(M) * r^n
where b_a and c_a are the b/a and c/a axis ratios, and n is the power law index.
  • '''broken power law''':: This is a straight-forward extension of the power law ellipsoid, where the power law index can change at an arbitrary number of radii r (where r is defined as above). It inherits all the same keywords as the '''power law ellipsoid''' module, with the only change being that n can now be a list of power law indexes instead of just single one. If more than one index is specified, a rbreak keyword must also be present containing the break radii at which the switch from index to index occures. If there k indices are given, there must be k-1 rbreak radii.

By mixing and matching these primitives, fairly complex models can be realized. For example, two exponential disks, a power law ellipsoid (for the halo) and another one (for the bulge/bar) should give a good description for >99% of the stellar content of the Galaxy.

The models are instantiated and defined through their configuration files. Their module keyword is module=model. A model keyword MUST also be present and can be one of the three listed above. The other parameters depend on which model was chosen.

Here is an example configuration file for an exponential disk:

module = model
model = exponential disk

# Unique component ID
comp = 0

# Thin disk parameters (scale length, sale height)
# Juric et al. (2008), table 10, the BIASED scales
# (assume no binaries will be added in postprocessing)
l = 2150
h = 245

# Luminosity function file, and an overall normalization factor
# i.e. LF(effective) = f * LF(from_file)
lumfunc = MrLF.MSandRGB_v1.0.dat
f = 1

There are two important points to emphasize in this example:

  • '''comp-onent ID''':: Since there can be many density law instances in a single galfast simulation (e.g., there are usually at least two exponential disks) we have to have a way to track stars from each of those '''components''' (stellar populations). This is the purpose served by the comp keyword above, that has to be set to a unique integer for each model instance. This allows you to, for example, generate different kinematics for a star depending on whether it is a thin disk, thick disk or halo star. The comp keyword is universal across all models.

  • '''Luminosity function specification''':: The luminosity function is specified via the lumfunc keyword, that expect a name of a single ASCII file with two columns: M and \Phi(M), where M is the absolute magnitude, and \Phi(M) is the number of stars per pc^3^ per mag at that M at the position of the Sun (i.e., the usual definition of the local luminosity function). The extra parameter f can be used to renormalize the values read from the file by some factor (if unspecified, f=1).

Footprints

Footprint configuration files have module=footprint keyval set. They must also have a type=xxx set, where xxx is one of the following:

  • '''beam''':: A pencil beam of a given radius, towards a given direction. Use the coordys keyword to set the coordinate system in which you're specifying the direction (can be either gal or equ). Use footprint_beam=<lon> <lat> <r> [rhole] to specify the direction, the radius of the beam, and (if needed) the radius of the "hole" inside the beam (thus making the footprint an annulus. All quantities are in degrees.

  • '''rect''':: A rectangle on the sky, in a given coordinate system (specified by the coordsys keyword). The keyword rect=<lon0> <lon1> <lat0> <lat1> specifies the rectangle.

Pipeline Modules

There are a number of pipeline modules present in the code, with only a few of the most important ones documented so far. They are activated by config files with module=xxx keyword, where xxx can be one of the following:

  • '''FeH''':: Ivezic et al. (2008) metallicity distribution model. This model is designed to describe the metallicity distribution of the thin disk, thick disk and the inner halo, based on the observations of the Sloan Digital Sky Survey (see the paper for details). The model needs to know which density components correspond to the thin/thick disk/halo; these must be specified by '''comp_thin''', '''comp_thick''' and '''comp_halo''' keywords. There are also a number of the parameters of the model (A0, sigma0, offs0, A1, sigma1, offs1, muInf, deltaMu, Hmu, offsH, sigmaH; see Ivezic et al. 2008), whose defaults have been set as given in that paper, but which can also be changed if one is interested in experimenting. Leaving them as-is should be fine for 99% of purposes.

  • '''photometry''': Photometry module takes the (X,Y,Z) position, the absolute magnitude M, the metallicity Fe/H, and generates apparent magnitudes in an arbitrary photometric system given a grid of (M, FeH) -> (colors) values. An example photometry configuration:

module = photometry

# Apply to components 0,1,2
compFirst = 0
compLast = 2

#
# Define the photometric system
#
bandset = SDSSugrizy
file = MSandRGBcolors_v1.1.dat
bands = SDSSu SDSSg SDSSr SDSSi SDSSz
bootstrap_band = SDSSr
absband = absSDSSr

#
# A grid on which to resample the isochrones
#
absmag_grid = -1 28 0.01
FeH_grid = -2.5 0 0.01

# Reddening coefficients (the ones used below _assume_ the extinction map is
# in the r-band; you must ensure it is)
reddening = 1.8739 1.3788 1 0.7583 0.5376
The most important piece is the specification of the photometric system (bandset, file, bands, bootstrap_band and absband keywords). The `bandset` keyword is a galfast-standardized name of the photometric system (e.g., SDSSugriz or LSSTugrizy), but can be anything as long as there are no whitespaces in the name. `file` specifies an ASCII text file containing a grid of (M, FeH) -> (colors) values, where if `n` is the number of bands in the system, (colors) will be the `n-1` colors that can be constructed from adjacent bands. For example, a file describing the SDSS photometric system has the following columns: (Mr, FeH, u-g, g-r, r-i, i-z). The `bands` keyword is used to give symbolic names to each of the bands in the photometric system. The suggested convention is <name_of_the_instrument><band_name>. In case of Sloan, these would be `SDSSu SDSSg SDSSr SDSSi SDSSz`. The `absband` band specifies the band in which the absolute magnitude M is. It must be one of the bands listed in the `bands` keyword, with the word 'abs' prepended to it (e.g., absSDSSr). '''IMPORTANT: For the time being, this MUST be the same as the band specified in skygen.conf's `band` keyword'''. Finally, the `bootstrap_band` must be the same as the absmag band, without the 'abs' prefix.

For computational efficiency, the (M, FeH) -> (color) table will be internally resampled (using bilinear interpolation) to a uniform grid. The properties (limits and bin size) of this grid are specified by the `absmag_grid` and `FeH_grid` keywords. '''YOU MUST ENSURE THE LIMITS ARE WIDE ENOUGH TO ENCOMPASS THE FULL RANGE OF M AND Fe/H THAT YOU HAVE IN YOUR PHOTOMETRIC SYSTEM DEFINITION FILE'''.

Command arguments of galfast

Command line operation of galfast is similar programs like cvs, svn or git, in that it accepts a ''subcommand'' and a series of (potentially optional) ''arguments'' following the command. Running galfast without the subcommand and a `-h' switch brings up a list of available subcommands, e.g.:

[mjuric@hybrid ~]$ ~/galfast/bin/galfast -h

galfast, a mock star catalog simulator.
Usage: galfast <cmd>

Arguments:
   cmd   What to do. Can be one of:
         
             catalog - create a mock catalog
                util - various utilities
         

Options:
   -v, --version   Version and author information
   -h, --help      This help page

For detailed help on a particular subcommand, do `galfast <cmd> -h'

'''You should for now ignore all subcommands other than catalog'''. Running galfast catalog -h brings up additional help:

[mjuric@hybrid ~]$ ~/galfast/bin/galfast catalog -h

galfast, a mock star catalog simulator. Generate and postprocess a mock catalog.
Usage: galfast catalog <module> [other_modules [...]]

Arguments:
   module          Module configuration file.
   other_modules   More module configuration files. ('' if unspecified)

Options:
   -s<param>,           Seed for the random number generator ('19821129' if 
   --seed=<param>       unspecified)
   -i<param>,           Input catalog file ('' if unspecified)
   --input=<param>
   -o<param>,           Output catalog file ('' if unspecified)
   --output=<param>
   -n<param>,           Renormalize the density so that on average <nstars> 
   --nstars=<param>     stars are generated within the observed volume. ('0' 
                        if unspecified)
   --dryrun             Skip the actual generation/output of the catalog. 
                        ('false' if unspecified)
   --maxstars=<param>   Maximum number of stars the code is allowed to 
                        generate. ('100000000' if unspecified)
   -v, --version        Version and author information
   -h, --help           This help page

As you can see from the above, galfast postprocess takes its marching orders from a set of configuration files. Default output will go into a file named sky.obs.txt, but can be overridden with -o option. The default input option is there for legacy reasons has no function at the moment.

Hints & Tips for running batch jobs

Say you want to generate a batch of catalogs for different model parameters. You may be tempted to write a script that will generate configuration files with the required parameters, and then run jobs with these as input. But there's a better way!.

The configuration files understand environment variables as values. E.g, I have the following:

[mjuric@node02 simulate_sample]$ cat model.thindisk.conf
...
h = $H
....

and then run galfast like this:

for H in 200 250 300 350
do
	env H=$H galfast catalog cmd.conf --output=sky.h=$H.obs.txt
done

to generate catalogs for four different values of thin disk scale height h.

Producing compressed outputs

If you specify an output file (via --output option) that ends in .gz or .bz2, the output will be gzip or bzip2 compressed, respectively. As mock catalogs can grow to be ''really'' large, gzip compression is advisable. bzip2 compression, while achieving up to 30% better ratios than gzip, is prohibitively slow for everyday use.

However, the best option is to forgo ASCII output alltogether, in favor of output to binary FITS tables (using the fitsout module).

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.