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
ishiyama21	500c, 200c, vir	Any	Any	Any	Ishiyama et al. 2021

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. 2008.
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, ps_args])	The model of Diemer & Joyce 2019.
modelIshiyama21(M, z, mdef[, ps_args, ...])	The model of Ishiyama et al 2021.

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

The native mass definition(s) of the model.

universal

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

depends_on_statistic

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

halo.concentration.models = {'bhattacharya13': <halo.concentration.ConcentrationModel object>, 'bullock01': <halo.concentration.ConcentrationModel object>, 'child18': <halo.concentration.ConcentrationModel object>, 'diemer15': <halo.concentration.ConcentrationModel object>, 'diemer15_orig': <halo.concentration.ConcentrationModel object>, 'diemer19': <halo.concentration.ConcentrationModel object>, 'duffy08': <halo.concentration.ConcentrationModel object>, 'dutton14': <halo.concentration.ConcentrationModel object>, 'ishiyama21': <halo.concentration.ConcentrationModel object>, 'klypin11': <halo.concentration.ConcentrationModel object>, 'klypin16_m': <halo.concentration.ConcentrationModel object>, 'klypin16_nu': <halo.concentration.ConcentrationModel object>, 'ludlow16': <halo.concentration.ConcentrationModel object>, 'prada12': <halo.concentration.ConcentrationModel object>}

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', ps_args={'model': 'eisenstein98', 'path': None})

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.

ps_args: dict

Arguments passed to the matterPowerSpectrum() function, and functions that depend on it such as the power spectrum slope.

Returns

c200c: array_like

Halo concentration; has the same dimensions as M200c.

halo.concentration.modelIshiyama21(M, z, mdef, ps_args={'model': 'eisenstein98', 'path': None}, c_type='fit', halo_sample='all')

The model of Ishiyama et al 2021.

This model constitutes a recalibration of the Diemer & Joyce 2019 model based on the Uchuu simulation. The model provides median concentrations only but was calibrated for the 500c, 200c, and vir mass definitions and for concentrations derived from an NFW fit and estimated from Vmax.

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.

ps_args: dict

Arguments passed to the matterPowerSpectrum() function, and functions that depend on it such as the power spectrum slope.

c_type: str

The type of concentration; can be fit for concentrations derived from an NFW fit or vmax for concentrations derived from the ratio of Vmax and V200c. Note that no fit is provided for mdef = 500c and c_type = vmax.

halo_sample: str

The halo sample on which the fit is based; can be all or relaxed.

Returns

c: array_like

Halo concentration; has the same dimensions as M.