:orphan: .. currentmodule:: halotools.empirical_models .. _profile_template_tutorial: **************************************************** Source code notes on `AnalyticDensityProf` **************************************************** This section of the documentation provides background material and detailed implementation notes on the functions and methods of the primary base class used to model the spatial distribution of matter and galaxies within halos, `~halotools.empirical_models.AnalyticDensityProf`. This as an abstract base class and so it cannot itself be instantiated; only concrete sub-classes can be used to directly model the spatial profile of halos. The purpose of the `~halotools.empirical_models.AnalyticDensityProf` class is to provide a template for any Halotools model of the spatial distribution of points within a halo. So in Halotools, any analytical model for how either matter or galaxies are spatially distributed within their halos will subclass from the `~halotools.empirical_models.AnalyticDensityProf` class. This tutorial is organized as follows. The :ref:`halo_mass_definitions` section reviews how halo boundaries and masses are defined with respect to a cosmologically evolving reference density. The :ref:`halo_profile_definitions` section covers the mathematics of halo density profiles, including explicit derivations of the exact form of all equations are they are implemented in code. The tutorial concludes with the :ref:`analytic_density_prof_constructor` section by describing how the `__init__` constructor standardizes the attributes and behavior of the class to facilitate mock-making with a uniform syntax. .. _halo_mass_definitions: Halo Mass and Radius Definitions =================================== Basic equations ----------------------------------- The `~halotools.empirical_models.AnalyticDensityProf` class models a dark matter halo to be a spherically symmetric overdensity relative to some reference density, :math:`\rho_{\rm ref}(z)`. The reference density is typically either the critical energy density of the universe, :math:`\rho_{\rm crit}(z)`, or the mean matter density :math:`\rho_{\rm m}(z) = \Omega_{m}(z)\rho_{\rm crit}(z)`. In the spherical-overdensity definition of a halo, the spherical boundary of a halo is defined such that the region inside the spherical shell has a fixed density .. math:: \rho_{\rm thresh}(z) \equiv \Delta_{\rm ref}(z)\rho_{\rm ref}(z); the redshift-dependence of :math:`\rho_{\rm thresh}` reflects both the evolution of the reference density :math:`\rho_{\rm ref}` as well as any possible redshift-dependence in the scalar multiple :math:`\Delta_{\rm ref}`. The cosmological model determines :math:`\rho_{\rm ref}(z)`; the choice of a halo mass definition is determined by how one chooses :math:`\Delta_{\rm ref}(z)`. Typically, one chooses :math:`\Delta_{\rm ref}` to be some redshift-independent multiple of the reference density. In the conventional notation for this choice, :math:`\Delta_{\rm ref}(z) = 500c` refers to the case where .. math:: \rho_{\rm thresh}(z) = 500\rho_{\rm crit}(z), and :math:`\Delta_{\rm ref}(z) = 200m` is shorthand for .. math:: \rho_{\rm thresh}(z) = 200\rho_{\rm m}(z). The other common choice for :math:`\Delta_{\rm ref}(z)` is :math:`\Delta_{\rm vir}(z)`, which defined by the solution of the gravitational collapse of a top-hat overdensity evolving in an expanding background. Once a choice is made for :math:`\Delta_{\rm ref}(z)`, the mass of a spherically symmetric halo is defined by: .. math:: M_{\Delta}(z) \equiv \frac{4\pi}{3}R_{\Delta}^{3}\Delta_{\rm ref}(z)\rho_{\rm ref}(z) This equation defines the relationship between the total mass of a halo :math:`M_{\Delta}` and the halo boundary :math:`R_{\Delta}`. Computing the relevant quantities ----------------------------------- In Halotools, the reference densities are computed using the `~astropy.cosmology` sub-package of Astropy, and the remaining quantities are computed in the `~halotools.empirical_models.profile_models` sub-package, specifically the `~halotools.empirical_models.profile_helpers` module. ============================================ ========================================================================================================= Quantity Source Code ============================================ ========================================================================================================= :math:`\rho_{\rm thresh}(z)` `~halotools.empirical_models.profile_helpers.density_threshold` :math:`\Delta_{\rm vir}(z)` `~halotools.empirical_models.profile_helpers.delta_vir` :math:`M_{\Delta}(z)` `~halotools.empirical_models.profile_helpers.halo_radius_to_halo_mass` :math:`R_{\Delta}(z)` `~halotools.empirical_models.profile_helpers.halo_mass_to_halo_radius` :math:`\rho_{\rm crit}(z)` `~astropy.cosmology.FLRW.critical_density` :math:`\Omega_{\rm m}(z)` `~astropy.cosmology.FLRW.Om` ============================================ ========================================================================================================= .. _halo_profile_definitions: Spatial Profiles of Halos =================================== Basic equations ----------------------------------- For a given choice of :math:`\Delta_{\rm ref}(z)`, the mass of a spherically symmetric halo is is related to the spatial profile of the matter in its interior via: .. math:: M_{\Delta}(z) \equiv 4\pi\int_{0}^{R_{\Delta}}dr' r'^{2}\rho_{\rm prof}(r') This equation defines the normalization of the halo profile :math:`\rho_{\rm prof}(r)`, which for any sub-class of `~halotools.empirical_models.AnalyticDensityProf` is computed with the `~halotools.empirical_models.AnalyticDensityProf.mass_density` method. For numerical stability, it is always preferable to work with order-unity quantities rather than astronomical numbers. So throughout the `~halotools.empirical_models.profile_models` sub-package, most methods work with the *scaled radius*, :math:`\tilde{r}`, defined as: .. math:: \tilde{r} \equiv r/R_{\Delta}, and the `~halotools.empirical_models.AnalyticDensityProf.dimensionless_mass_density`, :math:`\tilde{\rho}_{\rm prof}`, defined as: .. math:: \tilde{\rho}_{\rm prof}(\tilde{r}) \equiv \rho_{\rm prof}(\tilde{r})/\rho_{\rm thresh} In the implementation of `~halotools.empirical_models.AnalyticDensityProf`, for reasons of numerical stability a profile is actually defined by :math:`\tilde{\rho}_{\rm prof}(\tilde{r})`, and :math:`\rho_{\rm prof}(r)` is a derived quantity. In fact, in order to define a new profile model, one only need define a sub-class `~halotools.empirical_models.AnalyticDensityProf` and provide an implementation of the `~halotools.empirical_models.AnalyticDensityProf.dimensionless_mass_density` method, as *all* other profile quantities can be computed from this function. Convenience functions ----------------------- In addition to the `~halotools.empirical_models.AnalyticDensityProf.dimensionless_mass_density` method that defines the profile, instances of the `~halotools.empirical_models.AnalyticDensityProf` class have a number of other useful bound methods: .. _computing_enclosed_mass: Enclosed mass ~~~~~~~~~~~~~~ The mass enclosed within a given radius is defined as: .. math:: M_{\Delta}(