Halo mass function

The mass function quantifies how many halos of a certain mass exist at a given redshift and in a given cosmology.

Basics

This module implements a number of models for the halo mass function. The easiest and recommended use of the module is through the massFunction() function, a wrapper for all individual models:

from colossus.cosmology import cosmology
from colossus.lss import mass_function

cosmology.setCosmology('WMAP9')
mfunc_so = mass_function.massFunction(1E12, 0.0, mdef = 'vir', model = 'tinker08')
mfunc_fof = mass_function.massFunction(1E12, 0.0, mdef = 'fof', model = 'watson13')

Of course, the function accepts numpy arrays for the mass parameter. By default, the mass function is returned as \(f(\sigma)\), the natural units in Press-Schechter theory, where

\[\frac{dn}{d \ln(M)} = f(\sigma) \frac{\rho_0}{M} \frac{d \ln(\sigma^{-1})}{d \ln(M)} .\]

Here, \(\rho_0\) is the matter density at \(z = 0\) and \(\sigma\) is the variance on the lagrangian size scale of the halo mass in question (see sigma()). The function can also return the mass function in other units, namely as the number density per logarithmic interval in mass, \(dn/d\ln(M)\) (units of comoving \(({\rm Mpc}/h)^{-3}\), indicated by q_out = dndlnM) and as \(M^2 / \rho_0 dn/dM\) (dimensionless, indicated by q_out = M2dndM). These conversions can separately be performed separately using the convertMassFunction() function. Please see the Tutorials for more extensive code examples.

Mass function models

The following models are supported, and are listed in the models dictionary. Their ID can be passed as the model parameter to the massFunction() function:

ID	mdefs	z-dep.	Reference
press74	fof	delta_c	Press& Schechter 1974
sheth99	fof	delta_c	Sheth & Tormen 1999
jenkins01	fof	No	Jenkins et al. 2001
reed03	fof	delta_c	Reed et al. 2003
warren06	fof	No	Warren et al. 2006
reed07	fof	delta_c	Reed et al. 2007
tinker08	Any SO	Yes	Tinker et al. 2008
crocce10	fof	No	Crocce et al. 2010
bhattacharya11	fof	Yes	Bhattacharya et al. 2011
courtin11	fof	No	Courtin et al. 2011
angulo12	fof	No	Angulo et al. 2012
watson13	fof, any SO	Yes (SO)	Watson et al. 2013
bocquet16	200m,200c,500c	Yes	Bocquet et al. 2016
despali16	Any SO	Yes	Despali et al. 2016
comparat17	vir	No	Comparat et al. 2017
diemer20	sp-apr-*	No	Diemer 2020b
seppi20	vir	Yes	Seppi et al. 2020

Note that the mass definition (set to fof by default) needs to match one of the allowed mass definitions of the chosen model. For most models, only fof is allowed, but some SO models are calibrated to various mass definitions. The tinker08 model can handle any overdensity between 200m and 3200m (though they can be expressed as critical and virial overdensities as well).

There are two different types of redshift dependence of \(f(\sigma)\) listed above: some models explicitly depend on redshift (e.g., bhattacharya11), some models only change through the small variation of the collapse overdensity \(\delta_{\rm c}\) (see collapseOverdensity()). The tinker08 model depends on redshift only through the conversion of the overdensity threshold.

Mass functions based on the Press-Schechter formalism (i.e., parameterizations in terms of f(sigma) which includes all of the mass functions implemented here) are, in principle, supposed to be valid across redshifts and cosmologies. However, it has been shown that this is true only approximately. Nevertheless, this function does not check whether the user input is outside the range where the model was calibrated, be it in halo mass, redshift, or cosmology.

Module contents

HaloMassFunctionModel()	Characteristics of halo mass function models.
models	Dictionary containing a list of models.
massFunction(x, z[, q_in, q_out, mdef, ...])	The abundance of halos as a function of mass, variance, or peak height.
convertMassFunction(mfunc, M, z, q_in, q_out)	Convert different units of the mass function.
modelPress74(sigma, z[, deltac_args])	The mass function model of Press & Schechter 1974.
modelSheth99(sigma, z[, deltac_args])	The mass function model of Sheth & Tormen 1999.
modelJenkins01(sigma)	The mass function model of Jenkins et al 2001.
modelReed03(sigma, z[, deltac_args])	The mass function model of Reed et al 2003.
modelWarren06(sigma)	The mass function model of Warren et al 2006.
modelReed07(sigma, z[, ps_args, sigma_args, ...])	The mass function model of Reed et al 2007.
modelTinker08(sigma, z, mdef)	The mass function model of Tinker et al 2008.
modelCrocce10(sigma, z)	The mass function model of Crocce et al 2010.
modelCourtin11(sigma)	The mass function model of Courtin et al 2011.
modelBhattacharya11(sigma, z[, deltac_args])	The mass function model of Bhattacharya et al 2011.
modelAngulo12(sigma)	The mass function model of Angulo et al 2012.
modelWatson13(sigma, z, mdef)	The mass function model of Watson et al 2013.
modelBocquet16(sigma, z, mdef[, ps_args, ...])	The mass function model of Bocquet et al 2016.
modelDespali16(sigma, z, mdef[, ...])	The mass function model of Despali et al 2016.
modelComparat17(sigma)	The mass function model of Comparat et al 2017.
modelDiemer20(sigma, z, mdef[, deltac_args])	The splashback mass function model of Diemer 2020b.
modelSeppi20(sigma, z[, deltac_args, xoff, ...])	The mass function model of Seppi et al 2020.

Module reference

class lss.mass_function.HaloMassFunctionModel

Characteristics of halo mass function models.

This class contains certain characteristics of a mass function model, namely the mass definitions for which it is valid, whether it explicitly depends on the redshift (in some cases this dependence arises because of the slight dependence of the collapse overdensity on z), and how the collapse overdensity is computed by default (if applicable).

The models dictionary contains one item of this class for each available model.

z_dependence

Indicates whether \(f(\sigma)\) depends on redshift in this model.

ps_dependence

Indicates whether \(f(\sigma)\) depends directly on the power spectrum.

sigma_dependence

Indicates whether \(f(\sigma)\) depends directly on \(\sigma(M)\) beyond the input \(\sigma\).

deltac_dependence

Indicates whether \(f(\sigma)\) depends directly on the collapse overdensity.

mdef_dependence

Indicates whether \(f(\sigma)\) depends on the mass definition (for SO models).

mdefs

A list of mass definitions for which this model is valid. See Halo Mass Definitions for details.

lss.mass_function.models = {'angulo12': <lss.mass_function.HaloMassFunctionModel object>, 'bhattacharya11': <lss.mass_function.HaloMassFunctionModel object>, 'bocquet16': <lss.mass_function.HaloMassFunctionModel object>, 'comparat17': <lss.mass_function.HaloMassFunctionModel object>, 'courtin11': <lss.mass_function.HaloMassFunctionModel object>, 'crocce10': <lss.mass_function.HaloMassFunctionModel object>, 'despali16': <lss.mass_function.HaloMassFunctionModel object>, 'diemer20': <lss.mass_function.HaloMassFunctionModel object>, 'jenkins01': <lss.mass_function.HaloMassFunctionModel object>, 'press74': <lss.mass_function.HaloMassFunctionModel object>, 'reed03': <lss.mass_function.HaloMassFunctionModel object>, 'reed07': <lss.mass_function.HaloMassFunctionModel object>, 'seppi20': <lss.mass_function.HaloMassFunctionModel object>, 'sheth99': <lss.mass_function.HaloMassFunctionModel object>, 'tinker08': <lss.mass_function.HaloMassFunctionModel object>, 'warren06': <lss.mass_function.HaloMassFunctionModel object>, 'watson13': <lss.mass_function.HaloMassFunctionModel object>}

Dictionary containing a list of models.

An ordered dictionary containing one HaloMassFunctionModel entry for each model.

lss.mass_function.massFunction(x, z, q_in='M', q_out='f', mdef='fof', model='watson13', ps_args={'model': 'eisenstein98', 'path': None}, sigma_args={}, deltac_args={}, **kwargs)

The abundance of halos as a function of mass, variance, or peak height.

This function is a wrapper for all individual models implemented in this module. It accepts either mass, variance, or peak height as input (controlled by the q_in parameter, see the sigma() and peakHeight() functions for details on those quantities). The output units are controlled by the q_out parameter, see the basic usage section for details.

This function also deals with different mass definitions. By default, the definition is set to fof, but some models can also return the mass function for SO definitions (see models list).

Parameters

x: array_like

Either halo mass in \(M_{\odot}/h\), the variance \(\sigma\), or peak height \(\nu\), depending on the value of the q_in parameter; can be a number or a numpy array.

z: float

Redshift

q_in: str

Either M, sigma, or nu indicating which is passed for the x parameter.

q_out: str

The units in which the mass function is returned; can be f, dndlnM, or M2dndM. See the Basics section for details on these units.

mdef: str

The mass definition in which the halo mass M is given (or from which the variance or peak height were computed). The returned mass function refers to this mass definition. Please see the model table for the mass definitions for which each model is valid. See Halo Mass Definitions for details.

model: str

The model of the mass function used.

ps_args: dict

Arguments passed to the matterPowerSpectrum() function.

sigma_args: dict

Extra arguments to be passed to the sigma() function if mass is converted to a variance.

deltac_args: dict

Extra parameters that are passed to the collapseOverdensity() function; see the documentation of the individual models for possible parameters. Note that not all models of the mass function rely on the collapse overdensity.

kwargs: kwargs

Extra arguments passed to the function of the particular model. See the documentation of those functions for valid arguments.

Returns

mfunc: array_like

The halo mass function in the desired units.

lss.mass_function.convertMassFunction(mfunc, M, z, q_in, q_out, ps_args={'model': 'eisenstein98', 'path': None}, sigma_args={})

Convert different units of the mass function.

Virtually all models parameterize the mass function in the natural Press-Schechter units, \(f(\sigma)\). This function convert any allowed units into any other units. See the basic usage section for details on the meaning of the units.

Parameters

mfunc: array_like

The mass function in the input units.

M: array_like

Halo mass in \(M_{\odot}/h\); can be a number or a numpy array.

z: float

Redshift

q_in: str

The units in which the mass function is input; can be f, dndlnM, or M2dndM. See Basics section for the meaning of these units.

q_out: str

The units in which the mass function is returned; see above.

ps_args: dict

Arguments passed to the matterPowerSpectrum() function.

sigma_args: dict

Extra arguments to be passed to the sigma() function when mass is converted to a variance.

Returns

mfunc: array_like

The halo mass function in the desired units.

lss.mass_function.modelPress74(sigma, z, deltac_args={'corrections': True})

The mass function model of Press & Schechter 1974.

This model depends on redshift only through the collapse overdensity \(\delta_{\rm c}\). By default, the collapse overdensity is computed including corrections due to cosmology.

Parameters

sigma: array_like

Variance; can be a number or a numpy array.

z: float

Redshift

deltac_args: dict

Arguments passed to the collapseOverdensity() function.

Returns

f: array_like

The halo mass function \(f(\sigma)\), has the same dimensions as sigma.

lss.mass_function.modelSheth99(sigma, z, deltac_args={'corrections': True})

The mass function model of Sheth & Tormen 1999.

This model was created to account for the differences between the classic Press& Schechter 1974 model and measurements of the halo abundance in numerical simulations. The model is given in Equation 10. Note that, by default, the collapse overdensity is computed including corrections due to cosmology. Compared to the paper, the equation implemented here contains an extra factor of 2 because the original equation refers to the A = 1/2 normalization of Press & Schechter. This model is sometimes also known as “SMT” for Sheth, Mo and Tormen 2001 who use the same fitting function.

Parameters

sigma: array_like

Variance; can be a number or a numpy array.

z: float

Redshift

deltac_args: dict

Arguments passed to the collapseOverdensity() function.

Returns

f: array_like

The halo mass function \(f(\sigma)\), has the same dimensions as sigma.

lss.mass_function.modelJenkins01(sigma)

The mass function model of Jenkins et al 2001.

The model is given in Equation 9. It does not explicitly rely on the collapse overdensity and thus has no redshift evolution.

Parameters

sigma: array_like

Variance; can be a number or a numpy array.

Returns

f: array_like

The halo mass function \(f(\sigma)\), has the same dimensions as sigma.

lss.mass_function.modelReed03(sigma, z, deltac_args={'corrections': True})

The mass function model of Reed et al 2003.

This model corrects the Sheth & Tormen 1999 model at high masses, the functional form is given in Equation 9.

Parameters

sigma: array_like

Variance; can be a number or a numpy array.

z: float

Redshift

deltac_args: dict

Arguments passed to the collapseOverdensity() function.

Returns

f: array_like

The halo mass function \(f(\sigma)\), has the same dimensions as sigma.

lss.mass_function.modelWarren06(sigma)

The mass function model of Warren et al 2006.

This model does not explicitly rely on the collapse overdensity and thus has no redshift dependence. The functional form is given in Equation 5.

Parameters

sigma: array_like

Variance; can be a number or a numpy array.

Returns

f: array_like

The halo mass function \(f(\sigma)\), has the same dimensions as sigma.

lss.mass_function.modelReed07(sigma, z, ps_args={'model': 'eisenstein98', 'path': None}, sigma_args={}, deltac_args={'corrections': True}, exact_n=True)

The mass function model of Reed et al 2007.

This model takes the changing slope of the power spectrum into account. This slope can be computed numerically using the Colossus interpolation tables, or using the approximation in Equation 14 (the more exact numerical version is the default). The paper gives two expressions for their mass function, this code uses Equation 11.

Parameters

sigma: array_like

Variance; can be a number or a numpy array.

z: float

Redshift

ps_args: dict

Arguments passed to the matterPowerSpectrum() function.

sigma_args: dict

Extra arguments to be passed to the sigma() function when mass is converted to a variance.

deltac_args: dict

Arguments passed to the collapseOverdensity() function.

exact_n: bool

Compute the slope of the power spectrum numerically or approximate it.

Returns

f: array_like

The halo mass function \(f(\sigma)\), has the same dimensions as sigma.

lss.mass_function.modelTinker08(sigma, z, mdef)

The mass function model of Tinker et al 2008.

This model was the first calibrated for SO rather than FOF masses, and can predict the mass function for a large range of overdensities (\(200 \leq \Delta_{\rm m} \leq 3200\)). The authors found that the SO mass function is not universal with redshift and took this dependence into account explicitly (Equations 3-8).

Parameters

sigma: array_like

Variance; can be a number or a numpy array.

z: float

Redshift

mdef: str

The mass definition to which sigma corresponds. See Halo Mass Definitions for details.

Returns

f: array_like

The halo mass function \(f(\sigma)\), has the same dimensions as sigma.

lss.mass_function.modelCrocce10(sigma, z)

The mass function model of Crocce et al 2010.

This function was calibrated between z = 0 and 1, and is given in Equation 22.

Parameters

sigma: array_like

Variance; can be a number or a numpy array.

Returns

f: array_like

The halo mass function \(f(\sigma)\), has the same dimensions as sigma.

lss.mass_function.modelCourtin11(sigma)

The mass function model of Courtin et al 2011.

The model uses the same functional form as the Sheth & Tormen 1999, but with different parameters and a fixed collapse overdensity \(\delta_{\rm c} = 1.673\). Note that there appears to be an error in Equations 8 and 22: the factor of \(\sqrt{a}\) should be in the numerator rather than denominator in order to reproduce the ST expression. Other authors have taken the formula literally, e.g. Watson et al. 2013. Here, we assume that the intended expression is, indeed, that of ST.

Parameters

sigma: array_like

Variance; can be a number or a numpy array.

Returns

f: array_like

The halo mass function \(f(\sigma)\), has the same dimensions as sigma.

lss.mass_function.modelBhattacharya11(sigma, z, deltac_args={'corrections': False})

The mass function model of Bhattacharya et al 2011.

This model was calibrated between redshift 0 and 2. The authors found that varying \(\delta_{\rm c}\) does not account for the redshift dependence. Thus, they keep it fixed and added an explicit redshift dependence into the model. The functional form is given in Table 4.

Parameters

sigma: array_like

Variance; can be a number or a numpy array.

z: float

Redshift

deltac_args: dict

Arguments passed to the collapseOverdensity() function.

Returns

f: array_like

The halo mass function \(f(\sigma)\), has the same dimensions as sigma.

lss.mass_function.modelAngulo12(sigma)

The mass function model of Angulo et al 2012.

The model is specified in Equation 2. Note that there is a typo in this equation that was corrected in other implementations of the model.

Parameters

sigma: array_like

Variance; can be a number or a numpy array.

Returns

f: array_like

The halo mass function \(f(\sigma)\), has the same dimensions as sigma.

lss.mass_function.modelWatson13(sigma, z, mdef)

The mass function model of Watson et al 2013.

This function contains multiple models, namely the redshift-independent model for the FOF mass function as given in Equation 12, the redshift-evolving fit to the AHF mass function given in Equations 14-16, as well as the dependence on mass definition given in Equations 17-19. At z = 0 and z > 6 the authors suggest slightly different sets of parameters for the SO mass function which are used at those redshifts. Please note that the different parameterizations do not agree, as in, the redshift-dependent formula at z ~ 0 does not match the z = 0 expression. To get the redshift-dependent version at z = 0, simply use a very small redshift.

Note that there is a typo in the paper text, where the values of \(\alpha\) and \(\beta\) are switched. The correct values are in Table 2.

Parameters

sigma: array_like

Variance; can be a number or a numpy array.

z: float

Redshift

mdef: str

The mass definition to which sigma corresponds. See Halo Mass Definitions for details.

Returns

f: array_like

The halo mass function \(f(\sigma)\), has the same dimensions as sigma.

lss.mass_function.modelBocquet16(sigma, z, mdef, ps_args={'model': 'eisenstein98', 'path': None}, sigma_args={}, deltac_args={'corrections': True}, hydro=True)

The mass function model of Bocquet et al 2016.

The parameters were separately fit for dark matter-only and hydrodynamical simulations. The fits cover three mass definitions (200m, 200c, and 500c); requesting a different definition raises an exception. Note that, beyond different best-fit parameters, the 200c and 500c mass functions rely on a conversion that depends explicitly on redshift, cosmology, and halo mass (rather than peak height).

Due to this conversion to halo mass, the model does implicitly depend on the power spectrum, variance etc parameters beyond the value of sigma.

Parameters

sigma: array_like

Variance; can be a number or a numpy array.

z: float

Redshift

mdef: str

The mass definition to which sigma corresponds. See Halo Mass Definitions for details.

ps_args: dict

Arguments passed to the matterPowerSpectrum() function.

sigma_args: dict

Extra arguments to be passed to the sigma() function when mass is converted to a variance.

deltac_args: dict

Arguments passed to the collapseOverdensity() function.

hydro: bool

If True, return the model for hydro simulations, otherwise DM-only.

Returns

f: array_like

The halo mass function \(f(\sigma)\), has the same dimensions as sigma.

lss.mass_function.modelDespali16(sigma, z, mdef, deltac_args={'corrections': True}, ellipsoidal=False)

The mass function model of Despali et al 2016.

The parameters were fit for a number of different mass definitions, redshifts, and cosmologies. Here, we use the most general parameter set using the rescaling formula for redshift and mass definitions given in Equation 12. Furthermore, the user can choose between results based on conventional SO halo finding and an ellipsoidal halo finder.

Parameters

sigma: array_like

Variance; can be a number or a numpy array.

z: float

Redshift

mdef: str

The mass definition to which sigma corresponds. See Halo Mass Definitions for details.

ellipsoidal: bool

If True, return the results for an ellipsoidal halo finder, otherwise standard SO.

Returns

f: array_like

The halo mass function \(f(\sigma)\), has the same dimensions as sigma.

lss.mass_function.modelComparat17(sigma)

The mass function model of Comparat et al 2017.

This model was calibrated only at redshift 0, and for the virial SO mass definition. The cosmology used is the multidark-planck cosmology (which is very close to planck13). Outside of this redshift and cosmology, the model relies on the universality of the mass function.

The functional form is the same as in the Bhattacharya et al 2011 model, but without their redshift dependence. The parameters used here are updated compared to the published version of the paper.

Parameters

sigma: array_like

Variance; can be a number or a numpy array.

Returns

f: array_like

The halo mass function \(f(\sigma)\), has the same dimensions as sigma.

lss.mass_function.modelDiemer20(sigma, z, mdef, deltac_args={'corrections': True})

The splashback mass function model of Diemer 2020b.

This model represents a universal fitting function for splashback masses measured dynamically, that is, as the mean or percentiles of the particle apocenter distribution. The model is nominally valid for any redshift or cosmology, see the corresponding paper for details on its accuracy.

Parameters

sigma: array_like

Variance; can be a number or a numpy array.

z: float

Redshift

mdef: str

The splashback mass definition to which sigma corresponds. This function predicts the mass function for dynamically measured splashback masses, namely the mean (sp-apr-mn) or higher percentiles (sp-apr-p75 etc) of the splashback distribution. Any percentile between 50 and 90 is allowed. See Halo Mass Definitions for details.

deltac_args: dict

Arguments passed to the collapseOverdensity() function.

Returns

f: array_like

The halo mass function \(f(\sigma)\), has the same dimensions as sigma.

lss.mass_function.modelSeppi20(sigma, z, deltac_args={'corrections': True}, xoff=None, spin=None, int_over_sigma=False, int_over_xoff=True, int_over_spin=True)

The mass function model of Seppi et al 2020.

This model constitutes a 3D distribution of halo abundance over the variance, the spatial offset between a halo’s center of mass and the peak of its mass profile and the Peebles spin parameter. Depending on the int_over_sigma, int_over_xoff, and int_over_spin parameters, this function can return 1D, 2D, or 3D results on a grid given by sigma, xoff, and spin. If those arrays are not given, a standard set of bins is used (and integrated over depending on the dimensionality of the desired output).

Note that if 2D or 3D arrays are returned, the output units must be f when using the generalized massFunction() function because the output cannot be converted.

The model was calibrated only for masses above 4*10^13 solar masses and should not be used below this mass scale. The function is given in Equation 21 of the paper.

Parameters

sigma: array_like

Variance; can be a number or a numpy array.

xoff: array_like

Offset between cluster peak and center of mass; can be a number or a numpy array.

spin: array_like

Peebles spin parameter; can be a number or a numpy array.

int_over_sigma: bool

If True, marginalize over the sigma parameter.

int_over_xoff: bool

If True, marginalize over the xoff parameger.

int_over_spin: bool

If True, marginalize over the spin parameger.

Returns

h: array_like

The 3D halo mass-xoff-spin function \(h(\sigma,xoff,\lambda)\)

g_sigma_xoff: array_like

The 2D halo mass-xoff function \(g(\sigma,xoff)\), marginalized over spin

g_sigma_spin: array_like

The 2D halo mass-spin function \(g(\sigma,\lambda)\), marginalized over xoff

g_xoff_spin: array_like

The 2D halo xoff-spin function \(g(xoff,\lambda)\), marginalized over mass

f_xoff: array_like

The halo xoff function \(f(xoff)\), marginalized over mass and spin

f_spin: array_like

The halo spin function \(f(\sigma)\), marginalized over mass and xoff

f: array_like

The halo mass function \(f(\sigma)\), marginalized over xoff and spin