The outer profile¶
This module implements terms that describe the outer halo density profile. Specific terms are
derived from the OuterTerm
base class. The Tutorials contain more detailed code
examples.
Basics¶
Let us create an NFW profile, but add a description of the outer profile using the mattermatter correlation function:
from colossus.halo import profile_nfw
from colossus.halo import profile_outer
outer_term = profile_outer.OuterTermCorrelationFunction(z = 0.0, bias = 2.0)
profile = profile_nfw.NFWProfile(M = 1E12, mdef = 'vir', z = 0.0, c = 10.0, outer_terms = [outer_term])
The outer_terms
keyword can be used with any class derived from
HaloDensityProfile
.
Models for the outer term¶
Class  Explanation 

OuterTermMeanDensity 
The mean matter density of the universe 
OuterTermCorrelationFunction 
A term based on the mattermatter correlation 
OuterTermPowerLaw 
A powerlaw profile 
Module reference¶

class
halo.profile_outer.
OuterTerm
(par_array, opt_array, par_names, opt_names)¶ Base class for outer profile terms.
In Colossus, the density profile is assumed to consist of an inner term (i.e., a description of the 1halo term, such as an NFW profile) as well as one or multiple outer terms which are added to the inner term.
These outer terms must be derived from the OuterTerm base class, and must at least overwrite the _density() routine. The derived outer terms must also, in their constructor, call the constructor of this class with the parameters specified below. The user interface to such derived classes will, in general, be much simpler than the constructor of this super class.
The user can then add one or multiple outer terms to a density profile by calling its constructor and passing a list of OuterTerm objects in the
outer_terms
argument (see the documentation ofHaloDensityProfile
). Once the profile has been created, the outer terms themselves cannot be added or removed. Their parameters, however, can be modified in the same ways as the parameters of the inner profile.Parameters:  par_array: list
A list of parameter values for the outer term.
 opt_array: list
A list of option values for the outer term.
 par_names: list
A list of parameter names, corresponding to the values passed in par_array. If these names overlap with already existing parameters, the parameter is NOT added to the profile. Instead, the value of the existing parameter will be used. This behavior can be useful when outer profile terms rely on parameters or options of the inner profile.
 opt_names:
A list of option names, corresponding to the values passed in opt_array.
Methods
density
(r)The density due to the outer term as a function of radius. densityDerivativeLin
(r)The linear derivative of the density due to the outer term, \(d \rho / dr\). 
density
(r)¶ The density due to the outer term as a function of radius.
This function provides a convenient wrapper around _density() by ensuring that the radius values passed are a numpy array. This function should generally not be overwritten by child classes.
Parameters:  r: array_like
Radius in physical kpc/h; can be a number or a numpy array.
Returns:  density: array_like
Density in physical \(M_{\odot} h^2 / {\rm kpc}^3\); has the same dimensions as
r
.

densityDerivativeLin
(r)¶ The linear derivative of the density due to the outer term, \(d \rho / dr\).
This function should be overwritten by child classes if there is an analytic, faster expression for the derivative.
Parameters:  r: array_like
Radius in physical kpc/h; can be a number or a numpy array.
Returns:  derivative: array_like
The linear derivative in physical \(M_{\odot} h / {\rm kpc}^2\); has the same dimensions as
r
.

class
halo.profile_outer.
OuterTermMeanDensity
(z=None, z_name='z')¶ An outer term that adds the mean matter density of the universe to a density profile.
This is perhaps the simplest outer term one can imagine. The only parameter is the redshift at which the halo density profile is modeled. Note that this term is cosmologydependent, meaning that a cosmology has to be set before the constructor is called.
Furthermore, note that a constant term such as this one means that the surface density cannot be evaluated any more, since the integral over density will diverge. If the surface density is to be evaluated, one should always remove constant outer terms from the profile. This class does overwrite the surface density function and issues a warning if it is called.
In this implementation, the redshift is added to the profile options rather than parameters, meaning that it cannot be varied in a fit.
Parameters:  z: float
The redshift at which the profile is modeled.
 z_name: str
The internal name of the redshift option. If this name is set to an already existing profile option, the redshift is set to this other profile option, and thus not an independent option any more.
Methods
density
(r)The density due to the outer term as a function of radius. densityDerivativeLin
(r)The linear derivative of the density due to the outer term, \(d \rho / dr\). surfaceDensity
(r)The projected surface density at radius r due to the outer profile. 
surfaceDensity
(r)¶ The projected surface density at radius r due to the outer profile.
This function is overwritten for the mean density outer profile because it is illdefined: as the mean density is constant out to infinite radii, the lineofsight integral diverges. In principle, this function could just return zero in order to ignore this spurious contribution, but that causes an inconsistency between the 3D (rho) and 2D (Sigma) density profiles.
Parameters:  r: array_like
Radius in physical kpc/h; can be a number or a numpy array.
Returns:  Sigma: array_like
An array of zeros.

density
(r)¶ The density due to the outer term as a function of radius.
This function provides a convenient wrapper around _density() by ensuring that the radius values passed are a numpy array. This function should generally not be overwritten by child classes.
Parameters:  r: array_like
Radius in physical kpc/h; can be a number or a numpy array.
Returns:  density: array_like
Density in physical \(M_{\odot} h^2 / {\rm kpc}^3\); has the same dimensions as
r
.

densityDerivativeLin
(r)¶ The linear derivative of the density due to the outer term, \(d \rho / dr\).
This function should be overwritten by child classes if there is an analytic, faster expression for the derivative.
Parameters:  r: array_like
Radius in physical kpc/h; can be a number or a numpy array.
Returns:  derivative: array_like
The linear derivative in physical \(M_{\odot} h / {\rm kpc}^2\); has the same dimensions as
r
.

class
halo.profile_outer.
OuterTermCorrelationFunction
(z=None, derive_bias_from=None, bias=None, z_name='z', bias_name='bias')¶ An outer term that adds an estimate based on the mattermatter correlation function.
On large scales, we can model the 2halo term, i.e., the excess density due to neighboring halos, by assuming a linear bias. In that case, the halomatter correlation function is a multiple of the mattermatter correlation function, independent of radius:
\[\rho(r) = \rho_{\rm m} \times b(\nu) \times \xi_{\rm mm}\]where \(b(\nu)\) is called the halo bias. Note that this implementation does not add the constant due to the mean density of the universe which is sometimes included. If desired, this contribution can be added with the
OuterTermMeanDensity
term.The bias should be initialized to a physically motivated value. This value can be calculated selfconsistently, but this needs to be done iteratively because the bias depends on mass, which circularly depends on the value of bias due to the inclusion of this outer term. Thus, creating such a profile can be very slow. See the
bias
module for models of the bias as a function of halo mass.In this implementation, the redshift is added to the profile options rather than parameters, meaning it cannot be varied in a fit. The halo bias (i.e., the normalization of this outer term) is a parameter though and can be varied in a fit.
Note that this outer term can be evaluated at radii outside the range where the correlation function is defined by the cosmology module without throwing an error or warning. In such cases, the return value is the correlation function at the min/max radius. This behavior is convenient when initializing profiles etc, where the outer term may be insignificant at some radii. However, when integrating this outer term (e.g., when evaluating the surface density), care must be taken to set the correct integration limits. See the documentation of the correlation function in the cosmology module for more information.
Parameters:  z: float
The redshift at which the profile is modeled.
 derive_bias_from: str or None
If
None
, the bias is passed through the bias parameter and added to the profile parameters. Ifderive_bias_from
is a string, it must correspond to a profile parameter or option. Furthermore, this parameter or option must represent a valid spherical overdensity mass or radius such as'R200m'
or'Mvir'
from which the bias can be computed. If so, the bias is updated from that quantity every time the density is computed. bias: float
The halo bias.
 z_name: str
The internal name of the redshift option. If this name is set to an already existing profile option, the redshift is set to this other profile option, and thus not an independent option any more.
 bias_name: str
The internal name of the bias parameter. If this name is set to an already existing profile parameter, the bias is set to this other profile parameter, and thus not an independent parameter any more.
Methods
density
(r)The density due to the outer term as a function of radius. densityDerivativeLin
(r)The linear derivative of the density due to the outer term, \(d \rho / dr\). 
density
(r)¶ The density due to the outer term as a function of radius.
This function provides a convenient wrapper around _density() by ensuring that the radius values passed are a numpy array. This function should generally not be overwritten by child classes.
Parameters:  r: array_like
Radius in physical kpc/h; can be a number or a numpy array.
Returns:  density: array_like
Density in physical \(M_{\odot} h^2 / {\rm kpc}^3\); has the same dimensions as
r
.

densityDerivativeLin
(r)¶ The linear derivative of the density due to the outer term, \(d \rho / dr\).
This function should be overwritten by child classes if there is an analytic, faster expression for the derivative.
Parameters:  r: array_like
Radius in physical kpc/h; can be a number or a numpy array.
Returns:  derivative: array_like
The linear derivative in physical \(M_{\odot} h / {\rm kpc}^2\); has the same dimensions as
r
.

class
halo.profile_outer.
OuterTermPowerLaw
(norm=None, slope=None, pivot=None, pivot_factor=None, z=None, max_rho=1000.0, norm_name='pl_norm', slope_name='pl_slope', pivot_name='pivot', pivot_factor_name='pivot_factor', z_name='z', max_rho_name='pl_max_rho')¶ An outer term that describes density as a powerlaw in radius.
This class implements a powerlaw outer profile with a free normalization and slope, and a fixed or variable pivot radius,
\[\rho(r) = \frac{a \times \rho_m(z)}{\frac{1}{m} + \left(\frac{r}{r_{\rm pivot}}\right)^{b}}\]where a is the normalization in units of the mean density of the universe, b the slope, and m the maximum contribution to the density this term can make. Without such a limit, sufficiently steep powerlaw profiles can lead to a spurious density contribution at the halo center. Note that the slope is inverted, i.e. that a more positive slope means a steeper profile.
The user can also set the internal parameter names of the input variables. If these names are matched with an existing profile variable, that variable is used instead, meaning the outer term variable is not independent any more.
Parameters:  norm: float
The density normalization of the term, in units of the mean matter density of the universe.
 slope: float
The slope of the powerlaw profile.
 pivot: str
Can either be
'fixed'
, in which casepivot_factor
determines the pivot radius in physical units, or the name of one of the profile parameters or options. pivot_factor: float
There are fundamentally two ways to set the pivot radius. If
pivot=='fixed'
,pivot_factor
gives the pivot radius in physical kpc/h. Otherwise,pivot
must indicate the name of a profile parameter or option. In this case, the pivot radius is set topivot_factor
times the parameter or option in question. For example, for profiles based on a scale radius, a pivot radius of \(2 r_s\) can be set by passingpivot = 'rs'
andpivot_factor = 2.0
. z: float
Redshift.
 max_rho: float
The maximum density in units of the normalization times the mean density of the universe. This limit prevents spurious density contributions at the very center of halos. If you are unsure what this parameter should be set to, it can be useful to plot the density contribution of the outer profile term. It should flatten to max_rho times norm times the mean density at a radius where the inner profile strongly dominates the density, i.e. where the contribution from the outer term does not matter.
 norm_name: str
The internal name of the normalization parameter. If this name is set to an already existing profile parameter, the normalization is set to this other profile parameter, and thus not an independent parameter any more.
 slope_name: str
The internal name of the slope parameter. See
norm_name
. pivot_name: str
The internal name of the pivot parameter. See
norm_name
. pivot_factor_name: str
The internal name of the pivot_factor parameter. See
norm_name
. z_name: str
The internal name of the redshift parameter. See
norm_name
. max_rho_name: str
The internal name of the maximum density parameter. See
norm_name
.
Methods
density
(r)The density due to the outer term as a function of radius. densityDerivativeLin
(r)The linear derivative of the density due to the outer term, \(d \rho / dr\). 
densityDerivativeLin
(r)¶ The linear derivative of the density due to the outer term, \(d \rho / dr\).
Parameters:  r: array_like
Radius in physical kpc/h; can be a number or a numpy array.
Returns:  derivative: array_like
The linear derivative in physical \(M_{\odot} h / {\rm kpc}^2\); has the same dimensions as r.

density
(r)¶ The density due to the outer term as a function of radius.
This function provides a convenient wrapper around _density() by ensuring that the radius values passed are a numpy array. This function should generally not be overwritten by child classes.
Parameters:  r: array_like
Radius in physical kpc/h; can be a number or a numpy array.
Returns:  density: array_like
Density in physical \(M_{\odot} h^2 / {\rm kpc}^3\); has the same dimensions as
r
.