The outer (infalling) 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. For an introduction on how to use the outer terms, please see Halo Density Profiles.

Basics

The following outer terms are currently implemented:

• OuterTermMeanDensity (shortcode mean): The mean density of the universe at redshift z. This term should generally be present, given that density profiles must eventually approach the mean density at very large radii. However, it can be advantageous to omit this term, for example when computing surface densities.

• OuterTermCorrelationFunction (shortcode cf): The matter-matter correlation function times a halo bias. Here, the user has a choice regarding halo bias: it can enter the profile as a parameter (if derive_bias_from == None or it can be derived according to the default model of halo bias based on \(M_{\rm 200m}\) (in which case derive_bias_from = 'R200m' and the bias parameter is ignored). The latter option can make the constructor slow because of the iterative evaluation of bias and \(M_{\rm 200m}\). Note that the CF becomes negative at some (relatively large) radius, which leads to errors when computing the surface density or lensing signal. In this case, the integration radius must be limited manually (see the respective function documentation).

• OuterTermPowerLaw (shortcode pl): A power-law profile in overdensity. This form was suggested to be added to the DK14 profile, with a pivot radius of \(5 R_{\rm 200m}\). Note that \(R_{\rm 200m}\) is set as a profile option in the constructor once, but not adjusted thereafter unless the update() function is called. Thus, in a fit, the fitted norm and slope refer to a pivot of the original \(R_{\rm 200m}\) until update() is called which adjusts these parameters. Thus, it is often better to fix the pivot radius by setting pivot = 'fixed' and pivot_factor = 100.0 or some other chosen radius in physical units. The parameters for the power-law outer profile (norm and slope, called \(b_{\rm e}\) and \(s_{\rm e}\) in DK14) exhibit a complicated dependence on halo mass, redshift and cosmology. At low redshift, and for the cosmology considered in DK14, power_law_norm = 1.0 and power_law_slope = 1.5 are reasonable values over a wide range of masses (see Figure 18 in DK14), but these values are by no means universal or accurate.

• OuterTermInfalling (shortcode infalling): Infalling term: another power-law profile in overdensity with an asymptotic maximum density at the center, but also with a parameter that controls the smoothness of the transition to this fixed overdensity. This parameter is usually fixed to 0.5. This profile was specifically designed to fit the infalling term in simulations. It is parameterized somewhat differently than the pl profile. See Diemer 2022b for details.

Module reference

class halo.profile_outer.OuterTerm(par_array, opt_array, par_names, opt_names)

Base class for outer profile terms.

All outer terms must be derived from this OuterTerm base class overwrite at least the 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(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\).
update()	Update the profile object after a change in parameters or cosmology.

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.

update()

Update the profile object after a change in parameters or cosmology.

class halo.profile_outer.OuterTermMeanDensity(z=None, **kwargs)

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.

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.
update()	Update the profile object after a change in parameters or cosmology.

update()

Update the profile object after a change in parameters or cosmology.

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 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(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, bias_name='bias', **kwargs)

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.

Also note that the correlation function inevitably becomes negative at some radius! This can lead to a number of errors, for example, when computing surface density, where the density profile is integrated to a large radius. These errors can be prevented by manually limiting this integration depth.

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 set to 'R200m', the bias is automatically updated when the profile is changed.

bias: float

The halo bias.

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\).
update()	Update the profile object after a change in parameters or cosmology.

update()

Update the profile object after a change in parameters or cosmology.

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='R200m', pivot_factor=5.0, z=None, max_rho=1000.0, **kwargs)

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_{\rm 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.

This outer profile is kept for backward compatibility; for new code, please use OuterTermInfalling, which fulfils the same function if the smoothness parameter is set to its default, \(\zeta = 1\) (although the recommended value is now \(\zeta = 0.5\)).

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

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. However, only setting the pivot to R200m ensures that the profile is kept consistent.

pivot_factor: float

See above.

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.

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\).
update()	Update the profile object after a change in parameters or cosmology.

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.

update()

Update the profile object after a change in parameters or cosmology.

class halo.profile_outer.OuterTermInfalling(pl_delta_1=None, pl_s=None, pl_zeta=0.5, pl_delta_max=100.0, pivot='R200m', pivot_factor=1.0, z=None, **kwargs)

Infalling term according to Diemer 2023, modeled as a power law with smooth transition.

This class implements a power-law outer profile with a free normalization and slope, a fixed or variable pivot radius, and a smooth transition to a maximum value at small radii,

\[\rho(r) = \delta_1 \rho_{\rm m}(z) \left[ \left( \frac{\delta_1}{\delta_{\rm max}} \right)^{1/\zeta} + \left( \frac{r}{r_{\rm pivot}} \right)^{s/\zeta} \right]^{-\zeta} \]

where \(\delta_1\) is the normalization in units of the mean density of the universe, \(s\) is the slope, \(\delta_{\rm max}\) is the maximum overdensity at the center of the halo, and \(\zeta\) determines how rapidly the profile transitions to this density. Note that a more positive slope means a steeper profile. By default, \(\zeta = 0.5\). In the formulation of Diemer 2023, the pivot radius is \(R_{\rm 200m}\); other radii can be chosen but then the profile is not automatically kept up to date if the parameters of the inner profile change.

Parameters

pl_delta_1: float

The normalization of the infalling profile at the pivot radius (R200m by default) in units of the mean matter density of the universe.

pl_s: float

The (negative) slope of the power-law profile.

pl_zeta: float

The smoothness of the transition to the asymptotic value at the halo center.

pl_delta_max: float

The asymptotic overdensity at the center of the halo, in units of the mean matter density of the universe.

pivot: str

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. However, only setting the pivot to R200m ensures that the profile is kept consistent. When fitting, a fixed pivot radius is recommended because even R200m is not updated with every iteration in a fit, leading to inconsistencies.

pivot_factor: float

See above.

z: float

Redshift.

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\).
update()	Update the profile object after a change in parameters or cosmology.

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.

update()

Update the profile object after a change in parameters or cosmology.