Concentration

This module implements a range of models for halo concentration as a function of mass, redshift, and cosmology.

Basics

The main function in this module, concentration(), is a wrapper for all models:

from colossus.cosmology import cosmology
from colossus.halo import concentration

cosmology.setCosmology('planck15')
cvir = concentration.concentration(1E12, 'vir', 0.0, model = 'bullock01')

Alternatively, the user can also call the individual model functions directly. However, there are two aspects which the concentration() function handles automatically. First, many concentration models are only valid over a certain range of masses, redshifts, and cosmologies. If the user requests a mass or redshift outside these ranges, the function returns a soft fail: the concentration value is computed, but a warning is displayed and/or a False flag is returned in a boolean array. If a concentration model cannot be computed, this leads to a hard fail and a returned value of INVALID_CONCENTRATION (-1).

Second, each model was only calibrated for one of a few particular mass definitions, such as \(c_{200c}\), \(c_{vir}\), or \(c_{200m}\). The concentration() function automatically converts these definitions to the definition chosen by the user (see Halo Mass Definitions for more information on spherical overdensity masses). For the conversion, we necessarily have to assume a particular form of the density profile (see the documentation of the changeMassDefinition() function).

Note

The conversion to other mass definitions can degrade the accuracy of the predicted concentration by up to ~15-20% for certain mass definitions, masses, and redshifts. Using the DK14 profile (see the halo.profile_dk14 module) for the mass conversion gives slightly improved results, but the conversion is slower. Please see Appendix C in Diemer & Kravtsov 2015 for details.

Note

The user must ensure that the cosmology is set consistently. Many concentration models were calibrated only for one particular cosmology (though the default concentration model, diemer15, is valid for all masses, redshifts, and cosmologies). Neither the concentration() function nor the invidual model functions issue warnings if the set cosmology does not match the concentration model (with the exception of the modelKlypin16fromM() and modelKlypin16fromNu() functions). For example, it is possible to set a WMAP9 cosmology, and evaluate the Duffy et al. 2008 model which is only valid for a WMAP5 cosmology. When using such models, it is the user’s responsibility to ensure consistency with other calculations.

Concentration models

The following models are supported in this module, and their ID can be passed as the model parameter to the concentration() function:

ID Native mdefs M-range (z=0) z-range Cosmology Reference
bullock01 200c Almost any Any Any Bullock et al. 2001
duffy08 200c, vir, 200m 1E11 < M < 1E15 0 < z < 2 WMAP5 Duffy et al. 2008
klypin11 vir 3E10 < M < 5E14 0 WMAP7 Klypin et al. 2011
prada12 200c Any Any Any Prada et al. 2012
bhattacharya13 200c, vir, 200m 2E12 < M < 2E15 0 < z < 2 WMAP7 Bhattacharya et al. 2013
dutton14 200c, vir M > 1E10 0 < z < 5 planck13 Dutton & Maccio 2014
diemer15_orig 200c Any Any Any Diemer & Kravtsov 2015
diemer15 200c Any Any Any Diemer & Joyce 2019
klypin16_m 200c, vir M > 1E10 0 < z < 5 planck13/WMAP7 Klypin et al. 2016
klypin16_nu 200c, vir M > 1E10 0 < z < 5 planck13 Klypin et al. 2016
ludlow16 200c Any Any Any Ludlow et al. 2016
child18 200c M > 2.1E11 0 < z < 4 WMAP7 Child et al. 2016
diemer19 200c Any Any Any Diemer & Joyce 2019

The original version of the diemer15 model suffered from a small numerical error, a corrected set of parameters is given in Diemer & Joyce 2019. The differences between the models are less than 5%, but the original model should be used only for the purpose of backwards compatibility.

Module contents

ConcentrationModel() Characteristics of concentration models.
models Dictionary containing a list of models.
concentration(M, mdef, z[, model, …]) Concentration as a function of halo mass and redshift.
modelBullock01(M200c, z) The model of Bullock et al 2001.
modelDuffy08(M, z, mdef) The model of Duffy et al.
modelKlypin11(Mvir, z) The model of Klypin et al 2011.
modelPrada12(M200c, z) The model of Prada et al 2012.
modelBhattacharya13(M, z, mdef) The model of Bhattacharya et al 2013.
modelDutton14(M, z, mdef) The model of Dutton & Maccio 2014.
modelDiemer15fromM(M200c, z[, statistic, …]) The model of Diemer & Kravtsov 2015.
modelDiemer15fromNu(nu200c, z[, statistic, …]) The model of Diemer & Kravtsov 2015.
modelKlypin16fromM(M, z, mdef) The model of Klypin et al 2016, based on mass.
modelKlypin16fromNu(M, z, mdef) The model of Klypin et al 2016, based on peak height.
modelLudlow16(M200c, z) The model of Ludlow et al 2016.
modelChild18(M200c, z[, halo_sample]) The model of Child et al 2018.
modelDiemer19(M200c, z[, statistic]) The model of Diemer & Joyce 2019.

Module reference

class halo.concentration.ConcentrationModel

Characteristics of concentration models.

This object contains certain characteristics of a concentration model, most importantly the mass definitions for which concentration can be output (note that the concentration() function can automatically convert mass definitions). The models dictionary contains one item of this class for each available model.

mdefs = None

The native mass definition(s) of the model.

universal = None

Whether this model is universal in the sense that it can be evaluated at any mass or redshift.

depends_on_statistic = None

Whether this model can predict different statistics such as mean and median concentration.

halo.concentration.models = {'bhattacharya13': <halo.concentration.ConcentrationModel object at 0x10eab1ac8>, 'bullock01': <halo.concentration.ConcentrationModel object at 0x11089a0f0>, 'child18': <halo.concentration.ConcentrationModel object at 0x10eab1c50>, 'diemer15': <halo.concentration.ConcentrationModel object at 0x10eab1b70>, 'diemer15_orig': <halo.concentration.ConcentrationModel object at 0x10eab1b38>, 'diemer19': <halo.concentration.ConcentrationModel object at 0x10eab1c88>, 'duffy08': <halo.concentration.ConcentrationModel object at 0x1129c4320>, 'dutton14': <halo.concentration.ConcentrationModel object at 0x10eab1b00>, 'klypin11': <halo.concentration.ConcentrationModel object at 0x112adbef0>, 'klypin16_m': <halo.concentration.ConcentrationModel object at 0x10eab1ba8>, 'klypin16_nu': <halo.concentration.ConcentrationModel object at 0x10eab1be0>, 'ludlow16': <halo.concentration.ConcentrationModel object at 0x10eab1c18>, 'prada12': <halo.concentration.ConcentrationModel object at 0x112adbeb8>}

Dictionary containing a list of models.

An ordered dictionary containing one ConcentrationModel entry for each model.

halo.concentration.INVALID_CONCENTRATION = -1.0

The concentration value returned if the model routine fails to compute.

halo.concentration.concentration(M, mdef, z, model='diemer19', statistic='median', conversion_profile='nfw', range_return=False, range_warning=True, **kwargs)

Concentration as a function of halo mass and redshift.

This function encapsulates all the concentration models implemented in this module. It automatically converts between mass definitions if necessary. For some models, a cosmology must be set.

In some cases, the function cannot return concentrations for the masses, redshift, or cosmology requested due to limitations on a particular concentration model. If so, the mask return parameter contains a boolean list indicating which elements are valid. It is highly recommended that you switch this functionality on by setting range_return = True if you are not sure about the concentration model used.

Some of the individual concentration model functions take additional parameters, e.g., they are calibrated for different halo samples. These parameters can be passed through this function as keyword args. Please see the documentations of the individual functions for details.

Parameters:
M: array_like

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

mdef: str

The mass definition in which the halo mass M is given, and in which c is returned. See Halo Mass Definitions for details.

z: float

Redshift

model: str

The model of the c-M relation used; see list above.

statistic: str

Some models distinguish between the mean and median concentration. Note that most models do not, in which case this parameter is ignored.

conversion_profile: str

The profile form used to convert from one mass definition to another. See the changeMassDefinition() function).

range_return: bool

If True, the function returns a boolean mask indicating the validty of the returned concentrations.

range_warning: bool

If True, a warning is thrown if the user requested a mass or redshift where the model is not calibrated. This warning is suppressed if range_return == True, since it is assumed that the user will evaluate the returned mask array to check the validity of the returned concentrations.

kwargs: kwargs

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

Returns:
c: array_like

Halo concentration(s) in the mass definition mdef; has the same dimensions as M.

mask: array_like

If range_return == True, the function returns True/False values, where False indicates that the model was not calibrated at the chosen mass or redshift; has the same dimensions as M.

halo.concentration.modelBullock01(M200c, z)

The model of Bullock et al 2001.

This function implements the improved version of Maccio et al. 2008. The model is universal, but limited by the finite growth factor in a given cosmology which means that the model cannot be evaluated for arbitrarily large masses (halos that will never collapse).

Parameters:
M200c: array_like

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

z: float

Redshift

Returns:
c200c: array_like

Halo concentration; has the same dimensions as M.

mask: array_like

Boolean, has the same dimensions as M. Where False, one or more input parameters were outside the range where the model was calibrated, and the returned concentration may not be reliable.

halo.concentration.modelDuffy08(M, z, mdef)

The model of Duffy et al. 2008.

This power-law fit was calibrated for a WMAP5 cosmology.

Parameters:
M: array_like

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

z: float

Redshift

mdef: str

The mass definition in which the mass is given, and in which concentration is returned. Can be 200c, vir, or 200m for this function. See Halo Mass Definitions for details.

Returns:
c: array_like

Halo concentration; has the same dimensions as M.

mask: array_like

Boolean, has the same dimensions as M. Where False, one or more input parameters were outside the range where the model was calibrated, and the returned concentration may not be reliable.

halo.concentration.modelKlypin11(Mvir, z)

The model of Klypin et al 2011.

This power-law fit was calibrated for the WMAP7 cosmology of the Bolshoi simulation. Note that this model relies on concentrations that were measured from circular velocities, rather than from a fit to the actual density profiles. Klypin et al. 2011 also give fits at particular redshifts other than zero. However, there is no clear procedure to interpolate between redshifts, particularly since the z = 0 relation has a different functional form than the high-z relations. Thus, we only implement the z = 0 relation here.

Parameters:
Mvir: array_like

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

z: float

Redshift

Returns:
cvir: array_like

Halo concentration; has the same dimensions as Mvir.

mask: array_like

Boolean, has the same dimensions as Mvir. Where False, one or more input parameters were outside the range where the model was calibrated, and the returned concentration may not be reliable.

halo.concentration.modelPrada12(M200c, z)

The model of Prada et al 2012.

This model predicts \(c_{200c}\) based on the \(c-\nu\) relation. The model was calibrated on the Bolshoi and Multidark simulations, but is in principle applicable to any cosmology. The implementation follows equations 12 to 22 in Prada et al. 2012. This function uses the exact values for peak height rather than their approximation.

Parameters:
M200c: array_like

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

z: float

Redshift

Returns:
c200c: array_like

Halo concentration; has the same dimensions as M200c.

halo.concentration.modelBhattacharya13(M, z, mdef)

The model of Bhattacharya et al 2013.

This power-law fit in \(c-\nu\) was calibrated for a WMAP7 cosmology.

Parameters:
M: array_like

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

z: float

Redshift

mdef: str

The mass definition in which the mass is given, and in which concentration is returned. Can be 200c, vir, or 200m. See Halo Mass Definitions for details.

Returns:
c: array_like

Halo concentration; has the same dimensions as M.

mask: array_like

Boolean, has the same dimensions as M. Where False, one or more input parameters were outside the range where the model was calibrated, and the returned concentration may not be reliable.

halo.concentration.modelDutton14(M, z, mdef)

The model of Dutton & Maccio 2014.

This power-law fit was calibrated for the planck13 cosmology.

Parameters:
M: array_like

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

z: float

Redshift

mdef: str

The mass definition in which the mass is given, and in which concentration is returned. Can be 200c or vir. See Halo Mass Definitions for details.

Returns:
c: array_like

Halo concentration; has the same dimensions as M.

mask: array_like

Boolean, has the same dimensions as M. Where False, one or more input parameters were outside the range where the model was calibrated, and the returned concentration may not be reliable.

halo.concentration.modelDiemer15fromM(M200c, z, statistic='median', original_params=False)

The model of Diemer & Kravtsov 2015.

This universal model in \(c_{\rm 200c}-\nu\) space is a function of peak height and the slope of the power spectrum. A cosmology must be set before executing this function.

Parameters:
M200c: array_like

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

z: float

Redshift

statistic: str

Can be mean or median.

original_params: bool

If True, use the parameters given in the original paper. By default, use the updated parameters.

Returns:
c200c: array_like

Halo concentration; has the same dimensions as M200c.

See also

modelDiemer15fromNu
The same function, but with peak height as input.
halo.concentration.modelDiemer15fromNu(nu200c, z, statistic='median', original_params=False)

The model of Diemer & Kravtsov 2015.

This universal model in \(c_{\rm 200c}-\nu\) space is a function of peak height and the slope of the power spectrum. A cosmology must be set before executing this function.

Parameters:
nu200c: array_like

Halo peak heights; can be a number or a numpy array. The peak heights must correspond to \(M_{\rm 200c}\) and a top-hat filter.

z: float

Redshift

statistic: str

Can be mean or median.

original_params: bool

If True, use the parameters given in the original paper. By default, use the updated parameters.

Returns:
c200c: array_like

Halo concentration; has the same dimensions as nu200c.

See also

modelDiemer15fromM
The same function, but with mass as input.
halo.concentration.modelKlypin16fromM(M, z, mdef)

The model of Klypin et al 2016, based on mass.

The paper suggests both peak height-based and mass-based fitting functions for concentration; this function implements the mass-based version. The fits are given for the planck13 and bolshoi cosmologies. Thus, the user must set one of those cosmologies before evaluating this model. The best-fit parameters refer to the mass-selected samples of all halos (as opposed to \(v_{max}\)-selected samples, or relaxed halos).

Parameters:
M: array_like

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

z: float

Redshift

mdef: str

The mass definition in which the mass(es) are given, and in which concentration is returned. Can be 200c or vir. See Halo Mass Definitions for details.

Returns:
c: array_like

Halo concentration; has the same dimensions as M.

mask: array_like

Boolean, has the same dimensions as M. Where False, one or more input parameters were outside the range where the model was calibrated, and the returned concentration may not be reliable.

See also

modelKlypin16fromNu
The model of Klypin et al 2016, based on peak height.
halo.concentration.modelKlypin16fromNu(M, z, mdef)

The model of Klypin et al 2016, based on peak height.

The paper suggests both peak height-based and mass-based fitting functions for concentration; this function implements the peak height-based version. The fits are given for the planck13 and bolshoi cosmologies. Thus, the user must set one of those cosmologies before evaluating this model. The best-fit parameters refer to the mass-selected samples of all halos (as opposed to \(v_{max}\)-selected samples, or relaxed halos). The fits refer to median concentrations at fixed mass and redshift.

Parameters:
M: array_like

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

z: float

Redshift

mdef: str

The mass definition in which the mass is given, and in which concentration is returned. Can be 200c or vir. See Halo Mass Definitions for details.

Returns:
c: array_like

Halo concentration; has the same dimensions as M.

mask: array_like

Boolean, has the same dimensions as M. Where False, one or more input parameters were outside the range where the model was calibrated, and the returned concentration may not be reliable.

See also

modelKlypin16fromM
The model of Klypin et al 2016, based on mass.
halo.concentration.modelLudlow16(M200c, z)

The model of Ludlow et al 2016.

This function finds the solution by brute-force computation of a large array of concentrations. This technique is efficient if M200c is a large array, but inefficient for few values. Moreover, the function assumes a LCDM cosmology and is not strictly valid for wCDM or other DE models. The code was adapted from a routine by Steven Murray.

Parameters:
M200c: array_like

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

z: float

Redshift

Returns:
c: array_like

Halo concentration; has the same dimensions as M200c.

mask: array_like

Boolean, has the same dimensions as M200c. Where False, one or more input parameters were outside the range where the model was calibrated, and the returned concentration may not be reliable.

halo.concentration.modelChild18(M200c, z, halo_sample='individual_all')

The model of Child et al 2018.

The authors suggest multiple fitting functions, multiple ways to define the halo sample, and concetration measured by multiple profile fits. By default, this function represents Equation 18 using the parameters for individual halos (as opposed to stacks) and all halos (as opposed to relaxed halos). Other samples can be selected with the halo_sample parameter.

The mass definition is 200c for this model. The halo sample used reaches 2.1E11 \(M_{\odot}/h\), this function returns a mask indicating this mass range.

Parameters:
M200c: array_like

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

z: float

Redshift

halo_sample: str

Can be individual_all (default), individual_relaxed (the mean concentration of individual, relaxed halos), stacked_nfw (the stacked profile with with an NFW profile), and stacked_einasto (the stacked profile with with an Einasto profile).

Returns:
c: array_like

Halo concentration; has the same dimensions as M.

mask: array_like

Boolean, has the same dimensions as M. Where False, one or more input parameters were outside the range where the model was calibrated, and the returned concentration may not be reliable.

halo.concentration.modelDiemer19(M200c, z, statistic='median')

The model of Diemer & Joyce 2019.

This model improves on the Diemer & Kravtsov 2015 model in a number of ways. First, it is based on a mathematical derivation of the evolution of concentration at the low-mass end. This more physically motivated functional form allows fewer free parameters (six instead of seven). Second, because of the improved functional form, the model improves the fit, particularly to scale-free cosmologies. Finally, the new model fixed a slight numerical bug in the DK15 model.

The first time this model is ever called, it will compute a lookup table (in three dimensions) for c(G, n) where G is the left-hand side of the c-M model equation. This table then serves as a lookup and avoids having to numerically solve the equation.

Parameters:
M200c: array_like

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

z: float

Redshift

statistic: str

Can be mean or median.

Returns:
c200c: array_like

Halo concentration; has the same dimensions as M200c.