# 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 matter-matter 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 matter-matter correlation

OuterTermPowerLaw

A power-law 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 1-halo 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 of HaloDensityProfile). 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(self, r) The density due to the outer term as a function of radius. densityDerivativeLin(self, r) The linear derivative of the density due to the outer term, $$d \rho / dr$$.
density(self, 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(self, 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 cosmology-dependent, 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(self, r) The density due to the outer term as a function of radius. densityDerivativeLin(self, r) The linear derivative of the density due to the outer term, $$d \rho / dr$$. surfaceDensity(self, r) The projected surface density at radius r due to the outer profile.
surfaceDensity(self, 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 ill-defined: as the mean density is constant out to infinite radii, the line-of-sight 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(self, 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(self, 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 matter-matter correlation function.

On large scales, we can model the 2-halo term, i.e., the excess density due to neighboring halos, by assuming a linear bias. In that case, the halo-matter correlation function is a multiple of the matter-matter 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 self-consistently, 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. If derive_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(self, r) The density due to the outer term as a function of radius. densityDerivativeLin(self, r) The linear derivative of the density due to the outer term, $$d \rho / dr$$.
density(self, 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(self, 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 power-law in radius.

This class implements a power-law 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 power-law 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 power-law profile.

pivot: str

Can either be 'fixed', in which case pivot_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 to pivot_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 passing pivot = 'rs' and pivot_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(self, r) The density due to the outer term as a function of radius. densityDerivativeLin(self, r) The linear derivative of the density due to the outer term, $$d \rho / dr$$.
densityDerivativeLin(self, 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(self, 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.