holodeck.relations

Empirical and phenomenological scaling relationships.

This module defines numerous classes and accessor methods to implement scaling relationships between different empirical quantities, for example BH-Galaxy relations, or Stellar-Mass vs Halo-Mass relations. abc base classes are used to implement generic functionality, and define APIs while subclasses are left to perform specific implementations. In general most classes implement both the forward and reverse versions of relationships (e.g. stellar-mass to halo-mass, and also halo-mass to stellar-mass). Reverse relationships are often interpolated over a grid.

Most of the relationships currently implemented are among three groups (and corresponding base classes):

BH-Host Relations (_Host_Relation): These produce mappings between host galaxy properties (e.g. bulge mass) and the properties of their black holes (i.e. BH mass).
- Mbh-Mbulge relations (“M-Mbulge”; _MMBulge_Relation): mapping from host galaxy stellar bulge mass to black-hole mass.
- Mbh-Sigma relations (“M-Sigma”; _MSigma_Relation): mapping from host galaxy velocity dispersion (sigma) to black-hole mass.
Density Profiles (_Density_Profile): matter density as a function of spherical radius.
Stellar-Mass vs. Halo-Mass Relations (_StellarMass_HaloMass): mapping from halo-mass to stellar-mass.

To-Do

Pass concentration-relation (or other method to calculate) to NFW classes on instantiation
For redshift-dependent extensions to relations, use multiple-inheritance instead of repeating attributes.

References

[Behroozi2013] : Behroozi, Wechsler & Conroy 2013.
[Guo2010] Guo, White, Li & Boylan-Kolchin 2010.
[Klypin2016] Klypin et al. 2016.
[KH2013] Kormendy & Ho 2013.
[MM2013] McConnell & Ma 2013.
[NFW1997] Navarro, Frenk & White 1997.

class holodeck.relations.Behroozi_2013(*args, **kwargs)[source]

Redshift-dependent Stellar-Mass - Halo-Mass relation based on Behroozi et al. 2013.

[Behroozi2013] best fit values are at the beginning of Section 5 (pg.9), uncertainties are 1-sigma.

stellar_mass(mhalo, redz)[source]: This is [Behroozi2013] Eq.3 (upper)

class holodeck.relations.Guo_2010[source]

Stellar-Mass - Halo-Mass relation from Guo et al. 2010.

[Guo2010] Eq.3

classmethod stellar_mass(mhalo)[source]

Calculate the stellar-mass for the given halo mass.

Parameters:: mhalo (ArrayLike) – Halo mass. [gram]
Returns:: mstar – Stellar mass. [gram]
Return type:: ArrayLike

class holodeck.relations.Klypin_2016[source]

Class to calculate dark matter halo ‘concentration’ parameters based on [Klypin2016].

This class does not need to be instantiated, all methods are class methods, simply call Klypin_2016.concentration().

Interpolate between redshifts and masses to find DM halo concentrations. [Klypin2016] Eq. 24 & Table 2.

Return the halo concentration for the given halo mass and redshift.

Parameters:

mhalo (ArrayLike) – Halo mass. [grams]
redz (ArrayLike) – Redshift.

Returns:

conc – Halo concentration parameters. []

Return type:

ArrayLike

class holodeck.relations.MMBulge_KH2013(mamp=None, mamp_log10=None, mplaw=None, mref=None, bulge_mfrac=0.615, scatter_dex=None)[source]

Mbh-MBulge Relation, single power-law, from Kormendy & Ho 2013.

Values taken from [KH2013] Eq.10.

MASS_AMP_LOG10 = None

class holodeck.relations.MMBulge_MM2013(mamp=None, mamp_log10=None, mplaw=None, mref=None, bulge_mfrac=0.615, scatter_dex=None)[source]

Mbh-MBulge Relation from McConnell & Ma 2013

[MM2013] Eq. 2, with values taken from Table 2 (“Dynamical masses”, first row, “MPFITEXY”)

class holodeck.relations.MMBulge_Redshift(*args, zplaw=None, **kwargs)[source]

Mbh-Mbulge relation with an additional redshift power-law dependence.

Provides black hole mass as a function of galaxy bulge mass and redshift with a normalization that depends on redshift. zplaw=0 (default) is identical to MMBulge_Standard. mamp = mamp0 * (1 + z)**zplaw

TODO: make sure all of the inherited methods from MMBulge_Standard are appropriate for: redshift dependencies!! In particular, check dmstar_dmbh check which redshifts need to be passed into this function. does not pass all cases as is

MASS_AMP_LOG10 = None

dmstar_dmbh(mstar, redz)[source]

Calculate the partial derivative of stellar mass versus BH mass \(d M_star / d M_bh\).

\[d M_star / d M_bh = [d M_star / d M_bulge] * [d M_bulge / d M_bh] \ = [1/f_bulge] * [M_bulge / (plaw * M_bh)]\]

Parameters:: mstar (array_like,) – Total stellar mass of galaxy. [grams]
Returns:: deriv – Jacobian term.
Return type:: array_like,

mbh_from_host(pop, scatter)[source]

Convert from abstract host galaxy properties to blackhole mass.

The pop instance must contain the attributes required for this class’s scaling relations. The required properties are stored in this class’s _PROPERTIES attribute.

Parameters:: pop (_Discrete_Population,) – Population instance having the attributes required by this particular scaling relation.
Returns:: mbh – Black hole mass. [grams]
Return type:: ArrayLike

mbh_from_mbulge(mbulge, redz, scatter)[source]

Convert from stellar-bulge mass to black-hole mass.

Parameters:

mbulge (array_like,) – Stellar bulge-mass of host galaxy. [grams]
scatter (bool,) – Whether or not to include scatter in scaling relationship. Uses self._scatter_dex attribute.

Returns:

mbh – Mass of black hole. [grams]

Return type:

array_like,

mbh_from_mstar(mstar, redz, scatter)[source]

Convert from total stellar mass to black-hole mass.

Parameters:

mstar (array_like,) – Total stellar mass of host galaxy. [grams]
scatter (bool,) – Whether or not to include scatter in scaling relationship. Uses self._scatter_dex attribute.

Returns:

mbh – Mass of black hole. [grams]

Return type:

array_like,

mbulge_from_mbh(mbh, redz, scatter)[source]

Convert from black-hole mass to stellar-bulge mass.

Parameters:

mbh (array_like,) – Mass of black hole. [grams]
scatter (bool,) – Whether or not to include scatter in scaling relationship. Uses self._scatter_dex attribute.

Returns:

mbulge – Mass of stellar bulge. [grams]

Return type:

array_like,

mstar_from_mbh(mbh, redz, scatter)[source]

Convert from black-hole mass to total stellar mass.

Parameters:

mbh (array_like,) – Mass of black hole. [grams]
scatter (bool,) – Whether or not to include scatter in scaling relationship. Uses self._scatter_dex attribute.

Returns:

Total stellar mass of host galaxy. [grams]

Return type:

array_like,

class holodeck.relations.MMBulge_Redshift_KH2013(*args, zplaw=None, **kwargs)[source]

Mbh-MBulge Relation from Kormendy & Ho 2013, w/ optional redshift evolution of normalization.

BUG/FIX: use multiple-inheritance for this

Values taken from [KH2013] Eq.10 (pg. 61 of PDF, “571” of ARAA)

MASS_AMP_LOG10 = None

class holodeck.relations.MMBulge_Redshift_MM2013(*args, zplaw=None, **kwargs)[source]

Mbh-MBulge Relation from McConnell & Ma 2013 for z=0 plus redshift evolution of the normalization

BUG/FIX: use multiple-inheritance for this

[MM2013] Eq. 2, with values taken from Table 2 (“Dynamical masses”, first row, “MPFITEXY”)

MASS_AMP = None

class holodeck.relations.MMBulge_Standard(mamp=None, mamp_log10=None, mplaw=None, mref=None, bulge_mfrac=0.615, scatter_dex=None)[source]

Simple Mbh-Mbulge relation as a single power-law.

Notes

Single power-law relationship between BH mass and Stellar-bulge mass. \(Mbh = M0 * (M_bulge/Mref)^plaw * 10^Normal(0, eps)\)
Constant bulge mass-fraction relative to total stellar mass. \(M_bulge = f_bulge * M_star\)

bulge_mass_frac(mstar)[source]

Return the stellar-bulge mass fraction (M_bulge / M_star).

Parameters:: mstar (array_like,) – Host stellar-mass.
Returns:: Bulge mass fraction.
Return type:: array_like,

dmstar_dmbh(mstar, redz=None)[source]

Calculate the partial derivative of stellar mass versus BH mass \(d M_star / d M_bh\).

\[d M_star / d M_bh = [d M_star / d M_bulge] * [d M_bulge / d M_bh] \ = [1/f_bulge] * [M_bulge / (plaw * M_bh)]\]

Parameters:: mstar (array_like,) – Total stellar mass of galaxy. [grams]
Returns:: deriv – Jacobian term.
Return type:: array_like,

Convert from abstract host galaxy properties to blackhole mass.

The pop instance must contain the attributes required for this class’s scaling relations. The required properties are stored in this class’s _PROPERTIES attribute.

Parameters:: pop (_Discrete_Population,) – Population instance having the attributes required by this particular scaling relation.
Returns:: mbh – Black hole mass. [grams]
Return type:: ArrayLike

mbh_from_mbulge(mbulge, redz=None, scatter=None)[source]

Convert from stellar-bulge mass to black-hole mass.

Parameters:

mbulge (array_like,) – Stellar bulge-mass of host galaxy. [grams]
scatter (bool,) – Whether or not to include scatter in scaling relationship. Uses self._scatter_dex attribute.

Returns:

mbh – Mass of black hole. [grams]

Return type:

array_like,

mbh_from_mstar(mstar, redz=None, scatter=None)[source]

Convert from total stellar mass to black-hole mass.

Parameters:

mstar (array_like,) – Total stellar mass of host galaxy. [grams]
scatter (bool,) – Whether or not to include scatter in scaling relationship. Uses self._scatter_dex attribute.

Returns:

mbh – Mass of black hole. [grams]

Return type:

array_like,

mbulge_from_mbh(mbh, redz=None, scatter=None)[source]

Convert from black-hole mass to stellar-bulge mass.

Parameters:

mbh (array_like,) – Mass of black hole. [grams]
scatter (bool,) – Whether or not to include scatter in scaling relationship. Uses self._scatter_dex attribute.

Returns:

mbulge – Mass of stellar bulge. [grams]

Return type:

array_like,

mstar_from_mbh(mbh, redz=None, scatter=None)[source]

Convert from black-hole mass to total stellar mass.

Parameters:

mbh (array_like,) – Mass of black hole. [grams]
scatter (bool,) – Whether or not to include scatter in scaling relationship. Uses self._scatter_dex attribute.

Returns:

Total stellar mass of host galaxy. [grams]

Return type:

array_like,

mstar_from_mbulge(mbulge, redz=None)[source]

Convert from stellar bulge-mass to black-hole mass.

Parameters:

mbulge (array_like,) – Stellar bulge-mass of host galaxy. [grams]
scatter (bool,) – Whether or not to include scatter in scaling relationship. Uses self._scatter_dex attribute.

Returns:

mbh – Mass of black hole. [grams]

Return type:

array_like,

class holodeck.relations.MSigma_KH2013(mamp=None, sigma_plaw=None, sigma_ref=None, scatter_dex=None)[source]

Mbh-Sigma Relation from Kormendy & Ho 2013.

[KH2013] Eq. 10, (pg. 65 of PDF, “575” of ARAA)

class holodeck.relations.MSigma_MM2013(mamp=None, sigma_plaw=None, sigma_ref=None, scatter_dex=None)[source]

Mbh-Sigma Relation from McConnell & Ma 2013.

[MM2013] Eq. 2, with values taken from Table 2 (“M-sigma all galaxies”, first row, “MPFITEXY”)

class holodeck.relations.MSigma_Standard(mamp=None, sigma_plaw=None, sigma_ref=None, scatter_dex=None)[source]

Simple M-sigma relation (BH mass vs. host velocity dispersion) as a single power-law.

Notes

Single power-law relationship between BH mass and Stellar-bulge mass. \(Mbh = M0 * (sigma/sigma_ref)^plaw * 10^Normal(0, eps)\)

mbh_from_host(pop, scatter)[source]

Convert from abstract host galaxy properties to blackhole mass.

The pop instance must contain the attributes required for this class’s scaling relations. The required properties are stored in this class’s _PROPERTIES attribute.

Parameters:: pop (_Discrete_Population,) – Population instance having the attributes required by this particular scaling relation.
Returns:: mbh – Black hole mass. [grams]
Return type:: ArrayLike

mbh_from_vdisp(vdisp, scatter)[source]

Convert from host galaxy stellar velocity dispersion to black-hole mass.

Parameters:

vdisp (array_like,) – Host-galaxy velocity dispersion. [cm/s].
scatter (bool,) – Whether or not to include scatter in scaling relationship. Uses self._scatter_dex attribute.

Returns:

mbh – Mass of black hole. [grams]

Return type:

array_like,

vdisp_from_mbh(mbh, scatter)[source]

Convert from black-hole mass to host galaxy stellar velocity dispersion.

Parameters:

mbh (array_like,) – Mass of black hole. [grams]
scatter (bool,) – Whether or not to include scatter in scaling relationship. Uses self._scatter_dex attribute.

Returns:

vdisp – Host-galaxy velocity dispersion. [cm/s].

Return type:

array_like,

class holodeck.relations.NFW[source]

Navarro, Frank & White dark-matter density profile from [NFW1997].

NFW DM Density profile.

Parameters:

rads (ArrayLike) – Target radial distances. [cm]
mhalo (ArrayLike) – Halo mass. [grams]
redz (ArrayLike) – Redshift. []

Returns:

dens – Densities at the given radii. [g/cm^3]

Return type:

ArrayLike

Return the DM halo parameters for characteristic density.

Parameters:

mhalo (ArrayLike) – Halo mass. [grams]
redz (ArrayLike) – Redshift.

Returns:

rho_s – DM halo characteristic density. [g/cm^3]

Return type:

ArrayLike

DM mass enclosed at the given radii from an NFW profile.

Parameters:

rads (ArrayLike) – Target radial distances. [cm]
mhalo (ArrayLike) – Halo mass. [gram]
redz (ArrayLike) – Redshift. []

Returns:

mass – Mass enclosed within the given radii. [gram]

Return type:

ArrayLike

Return the DM-halo scale radius.

Parameters:

mhalo (ArrayLike) – Halo mass. [grams]
redz (ArrayLike) – Redshift.

Returns:

rs – Scale radius of the DM halo. [cm]

Return type:

ArrayLike

holodeck.relations.get_mmbulge_relation(mmbulge: _MMBulge_Relation | Type[_MMBulge_Relation] | None = None) → _MMBulge_Relation[source]

Return a valid Mbh-Mbulge instance.

Parameters:: mmbulge (None or (type or instance of _MMBulge_Relation),) – If None, then a default M-Mbulge relation is returned. Otherwise, the type is checked to make sure it is a valid instance of an _MMBulge_Relation.
Returns:: Instance of an Mbh-Mbulge relationship.
Return type:: _MMBulge_Relation

holodeck.relations.get_msigma_relation(msigma: _MSigma_Relation | Type[_MSigma_Relation] | None = None) → _MSigma_Relation[source]

Return a valid M-sigma (BH Mass vs. host galaxy velocity dispersion) instance.

Parameters:: msigma (None or (class or instance of _MSigma_Relation),) – If None, then a default M-sigma relation is returned. Otherwise, the type is checked to make sure it is a valid instance of an _MSigma_Relation.
Returns:: Instance of an Mbh-sigma relationship.
Return type:: _MSigma_Relation

holodeck.relations.get_stellar_mass_halo_mass_relation(smhm: _StellarMass_HaloMass | Type[_StellarMass_HaloMass] | None = None) → _StellarMass_HaloMass[source]

Return a valid Stellar-Mass vs. Halo-Mass relation instance.

Parameters:: smhm (None or (type or instance of _StellarMass_HaloMass),) – If None, then a default relation is returned. Otherwise, the type is checked to make sure it is a valid instance of an _StellarMass_HaloMass.
Returns:: Instance of an Mbh-Mbulge relationship.
Return type:: _StellarMass_HaloMass