Package: halotools
Halotools is a specialized python package for building and testing models of the galaxy-halo connection, and analyzing catalogs of dark matter halos.
The core feature of Halotools is a modular platform for creating mock universes of galaxies starting from a catalog of dark matter halos obtained from a cosmological simulation. Functionality of the package includes:Fast generation of synthetic galaxy populations using HODs, abundance matching, and related methodsEfficient algorithms for calculating galaxy clustering, lensing, z-space distortions, and other astronomical statisticsA modular, object-oriented framework for designing your own galaxy evolution modelEnd-to-end support for downloading publicly-available halo catalogs and reducing them to fast-loading hdf5 filesThe code is publicly available athttps://github.com/astropy/halotools.InstallationThe simplest and most reliable way to install the latest release of the code is with conda-forge:conda install -c conda-forge halotoolsPip installation is not recommended because the conda-forge dependency solver is much more robust.
However, users who prefer pip can install via:pip install halotoolsYou can find detailed installation instructionshalotools.readthedocs.io.After installing the package, you should navigate to theQuickstart Guides and Tutorialssection and follow theGetting started with Halotools10-minute tutorial.
This will get you set up with the default halo catalog so that you can quickly get started with creating mock galaxy populations.DocumentationThe latest build of the documentation can be found athttp://halotools.readthedocs.io. The documentation includes installation instructions, quickstart guides and step-by-step tutorials. TheBasic featuressection below gives an overview of the primary functionality of the package.Basic featuresOnce you have installed the code and downloaded the default halo catalog (see the Getting Started guide in the documentation), you can use Halotools models to populate mock galaxy populations.# Select a modelfromhalotools.empirical_modelsimportPrebuiltHodModelFactorymodel=PrebuiltHodModelFactory('zheng07')# Select a halo catalogfromhalotools.sim_managerimportCachedHaloCataloghalocat=CachedHaloCatalog(simname='bolshoi',redshift=0,halo_finder='rockstar')# populate the catalog with the modelmodel.populate_mock(halocat)After callingpopulate_mock, your model will have amockattribute storing your synthetic galaxy population. All Halotools models have apopulate_mockmethod that works in this way, regardless of the features of the model. There are no restrictions on the simulation or halo-finder with which you can use the populate_mock method.Creating alternate mocksAll Halotools models have aparam_dictthat controls the behavior of the model. By changing the parameters in this dictionary, you can create alternative versions of your mock universe by re-populating the halo catalog as follows.model.param_dict['logMmin']=12.1model.mock.populate()Note how much faster the call tomock.populateis relative tomodel.populate_mock(halocat). This is due to a large amount of one-time-only pre-processing that is carried out upon creation of the first mock universe. The process of varyingparam_dictvalues and repeatedly callingmodel.mock.populate()is part of a typical workflow in an MCMC-type analysis conducted with Halotools.Modeling the galaxy-halo connectionThe pre-built model factories give you a wide range of models to choose from, each based on an existing publication. Alternatively, you can use the Halotools factories to design a customized model of your own creation, such as models for stellar mass, color, size, morphology, or any property of your choosing. The modular design of theempirical_modelssub-package allows you to mix-and-match an arbitrary number or kind of features to create your own composite model of the full galaxy population. You can choose from component models provided by Halotools, components exclusively written by you, or anywhere in between. Whatever science features you choose, any Halotools model can populate any Halotools-formatted halo catalog with the same syntax shown above.Making mock observationsThemock_observablessub-package contains a wide variety of optimized functions that you can use to study your mock galaxy population. For example, you can calculate projected clustering via thewpfunction, identify friends-of-friends groups withFoFGroups, or compute galaxy-galaxy lensing withmean_delta_sigma.fromhalotools.mock_observablesimportwpfromhalotools.mock_observablesimportFoFGroupsfromhalotools.mock_observablesimportmean_delta_sigmaThere are many other functions provided by themock_observablespackage, such as RSD multipoles, pairwise velocities, generalized marked correlation functions, customizable isolation criteria, void statistics, and more.Managing simulation dataHalotools provides end-to-end support for downloading simulation data, reducing it to a fast-loading hdf5 file with metadata to help with the bookkeeping, and creating a persistent memory of where your data is stored on disk. This functionality is handled by thesim_managersub-package:fromhalotoolsimportsim_managerThesim_managerpackage comes with a memory-efficientTabularAsciiReaderdesigned to handle the very large file sizes that are typical of contemporary cosmological simulations. There are 20 halo catalogs available for download from the Halotools website using thedownload_additional_halocat script.py, including simulations run with different volumes, resolutions and cosmologies, and also catalogs identified using different halo-finders and at different redshift. Any simulation you store in cache can be loaded into memory in the same way, and all such catalogs have ahalo_tableattribute storing the actual data.fromhalotools.sim_managerimportCachedHaloCataloghalocat=CachedHaloCatalog(simname=any_simname,redshift=any_redshift,halo_finder=any_halo_finder)print(halocat.halo_table[0:10])You are not limited to use the halo catalogs pre-processed by Halotools. TheUserSuppliedHaloCatalogallows you to use your own simulation data and transform it into a Halotools-formatted catalog in a simple way.fromhalotools.sim_managerimportUserSuppliedHaloCatalogAlthough thesim_managerprovides an object-oriented framework for creating a persistent memory of where you store your halo catalogs, your cache is stored in a simple, human-readable ASCII log in the following location:$HOME/.astropy/cache/halotools/halo_table_cache_log.txtProject statusHalotools is a fully open-source package with contributing scientists spread across many universities. The latest stable release of the package, v0.8, is now available on pip and conda-forge. You can also install the development version of the package by cloning the master branch on GitHub and locally building the source code, as described in the installation instructions.## Asking questions and staying up-to-dateYou can contact Andrew Hearin directly by email at ahearin-at-anl-dot-gov, or by tagging @aphearin on GitHub.Citing HalotoolsIf you use Halotools modules to support your science publication, please citeHearin et al. (2017), ideally taking note of the version of the code you used, e.g., v0.8:@ARTICLE{halotools,
       author = {{Hearin}, Andrew P. and {Campbell}, Duncan and {Tollerud}, Erik and {Behroozi}, Peter and {Diemer}, Benedikt and {Goldbaum}, Nathan J. and {Jennings}, Elise and {Leauthaud}, Alexie and {Mao}, Yao-Yuan and {More}, Surhud and {Parejko}, John and {Sinha}, Manodeep and {Sip{\"o}cz}, Brigitta and {Zentner}, Andrew},
        title = "{Forward Modeling of Large-scale Structure: An Open-source Approach with Halotools}",
      journal = {The Astronomical Journal},
     keywords = {cosmology: theory, galaxies: halos, galaxies: statistics, large-scale structure of universe, Astrophysics - Instrumentation and Methods for Astrophysics, Astrophysics - Cosmology and Nongalactic Astrophysics, Astrophysics - Astrophysics of Galaxies},
         year = 2017,
        month = nov,
       volume = {154},
       number = {5},
          eid = {190},
        pages = {190},
          doi = {10.3847/1538-3881/aa859f},
archivePrefix = {arXiv},
       eprint = {1606.04106},
 primaryClass = {astro-ph.IM},
       adsurl = {https://ui.adsabs.harvard.edu/abs/2017AJ....154..190H},
      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}LicenseHalotools is licensed by Argonne National Lab under a 3-clause BSD style license - see the licenses/LICENSE.rst file.