Semi-Analytic Galaxy Evolution (SAGE)

SAGE is a publicly available code-base for modelling galaxy formation in a cosmological context. A description of the model and its default calibration results can be found in Croton et al. (2016). SAGE is a significant update to that previously used in Croton et al. (2006).

SAGE is written in C and was built to be modular and customisable. It will run on any N-body simulation whose trees are organised in a supported format and contain a minimum set of basic halo properties. For testing purposes, treefiles for the mini-Millennium Simulation are available here.

Galaxy formation models built using SAGE on the Millennium, Bolshoi and simulations can be downloaded at the Theoretical Astrophysical Observatory (TAO). You can also find SAGE on ascl.net.

Getting started

Pre-requisites

SAGE should compile on most systems out of the box and the only required tool is a C99 compiler. GSL is recommended but not necessary.

Downloading

SAGE can be installed by cloning the GitHub repository:

$ git clone https://github.com/sage-home/sage-model
$ cd sage-model/

Building

To create the SAGE executable, simply run the following command:

$ make

SAGE is MPI compatible which can be enabled setting USE-MPI = yes in the Makefile. To run in parallel, ensure that you have a installed an MPI distribution (OpenMPI, MPICH, Intel MPI etc). When compiling with MPI support, the Makefile expects that the MPI compiler is called mpicc and is configured appropriately.

Addtionally, SAGE can be configured to read trees in HDF5 format by setting USE-HDF5 = yes in the Makefile. If the input trees are in HDF5 format, or you wish to output the catalogs in HDF5 (rather than the default binary format), then please compile with the USE-HDF5 = yes option.

Running the code

If this the first time running the code, we recommend executing first_run.sh. This script will initialize the directories for the default parameter file and download the Mini-millennium dark matter halo trees:

$ ./first_run.sh

After this, the model can be run using:

$ ./sage input/millennium.par

or in parallel as:

$ mpirun -np <NUMBER_PROCESSORS> ./sage input/millennium.par

Plotting the output (basic method)

If you already have Python 3 installed, you can switch to the plotting directory, where you will find two scripts, allresults-local.py (for z=0 results) and allresults-history.py (for higher redshift results). If you're following the above, these scripts can run as-is to produce a series of figures you can use to check the model output.

$ cd plotting/
$ python3 allresults-local.py
$ python3 allresults-history.py

Near the top of both scripts, there is a "USER OPTIONS" section where you can modify the simulation and plotting details for your own needs. These scripts can be used as a template to read the hdf5 SAGE model output and to make your own custom figures.

Plotting the output (sage-analysis package)

We have a separate sage-analysis python package for plotting SAGE output. Please refer to the sage_analysis documentation for more details.

Installing sage-analysis (requires python version >= 3.6)

$ cd ../    # <- Change to the location where you want to clone the sage-analysis repo
$ git clone https://github.com/sage-home/sage-analysis.git
$ cd sage-analysis

You may need to first create a Python virtual environment in your sage-analysis directory and source it:

$ python3 -m venv .sage_venv
$ source .sage_venv/bin/activate

Then finish installing sage-analysis:

$ python3 -m pip install -e .    # Install the sage-analysis python package
$ cd ../sage-model

Assuming that the sage-analysis repo was installed successfully, you are now ready to plot the output from SAGE.

Plotting

The plotting directory contains an example.py script that can be run to plot the basic output from SAGE.

$ cd plotting/
$ python3 example.py

This will create a number of plots in the plotting/plots/ directory. Please refer to the sage_analysis documentation for a thorough guide on how to tweak the plotting script to suit your needs.

Citation

If you use SAGE in a publication, please cite the following items:

@ARTICLE{2016ApJS..222...22C,
    author = {{Croton}, D.~J. and {Stevens}, A.~R.~H. and {Tonini}, C. and
            {Garel}, T. and {Bernyk}, M. and {Bibiano}, A. and {Hodkinson}, L. and
            {Mutch}, S.~J. and {Poole}, G.~B. and {Shattow}, G.~M.},
    title = "{Semi-Analytic Galaxy Evolution (SAGE): Model Calibration and Basic Results}",
    journal = {\apjs},
    archivePrefix = "arXiv",
    eprint = {1601.04709},
    keywords = {galaxies: active, galaxies: evolution, galaxies: halos, methods: numerical},
    year = 2016,
    month = feb,
    volume = 222,
    eid = {22},
    pages = {22},
    doi = {10.3847/0067-0049/222/2/22},
    adsurl = {http://adsabs.harvard.edu/abs/2016ApJS..222...22C},
    adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}

Author

Questions and comments can be sent to Darren Croton: dcroton@astro.swin.edu.au.

Maintainers

• Jacob Seiler (@jacobseiler)
• Manodeep Sinha (@manodeep)
• Darren Croton (@darrencroton)