holodeck.host_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.

Detailed information about the different types of relationships that are implemented can be found in the documentation for the base-classes. Most of the relationships currently implemented are among two groups (and corresponding base classes):

  • BH-Host Relations (subclasses of _BH_Host_Relation): These produce mappings between host galaxy properties (e.g. bulge mass) and the mass of their black holes. Currently, generally only the M-Mbulge relationships should be used for assigning MBH masses (see below).

    • Mbh-Mbulge relations (“M-Mbulge”; subclasses of _MMBulge_Relation): mapping from host galaxy stellar-bulge mass to black-hole mass. MMBulge relationships must be able to calculate black hole masses given total stellar-masses, not just stellar-bulge masses. This requires the usage of bulge-fractions (the fraction of total stellar-mass in the bulge). These bulge fractions are implemented using subclasses of the _Bulge_Frac, in the simplest case a constant bulge fraction using BF_Constant.

    • Mbh-Sigma relations (“M-Sigma”; subclasses of _MSigma_Relation): mapping from host galaxy velocity dispersion (sigma) to black-hole mass. NOTE: as of writing this (2024-03-29) the M-Sigma relationships are not fully supported in semi-analytic models in that the initial galaxy populations do not have stellar velocity-dispersions set.

  • Stellar-Mass vs. Halo-Mass Relations (subclasses of _StellarMass_HaloMass): mapping from dark matter halo-mass to stellar-mass.

Mbh-MBulge (M-Mbulge)

M-Mbulge relationships, implemented as subclasses of _MMBulge_Relation, map from stellar-bulge masses to black-hole masses. These classes also use a bulge-fraction, implemented as subclasses of _Bulge_Frac, instance to map from total stellar-masses to bulge masses internally, so that often the _MMBulge_Relation.mbh_from_mstar() method will be the primary API interface. The _MMBulge_Relation subclasses also provide partial derivative terms, in particular the _MMBulge_Relation.dmstar_dmbh() method, which is used by SAMs to convert from galaxy-galaxy mergers to MBH-MBH mergers. See the class docstrings for more information.

Note that redshift-dependent versions of M-Mbulge relationships are also provided, but note that these are still under development and testing (2024-03-28).

It is very easy to implement new M-Mbulge relationships by creating new subclasses of _MMBulge_Relation. See the class documentation for more information.

Relations: To-Do

  • Pass concentration-relation (or other method to calculate) to NFW classes on instantiation

References

class holodeck.host_relations._BH_Host_Relation(*args, **kwargs)[source]

Bases: ABC

Base class for general relationships between MBHs and their host galaxies.

This base-class is mostly organizational. For discrete populations, it specifies the API method get_host_properties which is a generic interface to derive BH masses from arbitrary properties of host galaxies (e.g. velocity dispersion, bulge mass, etc). This must be implemented by the subclasses. For SAMs, this base class provides no functionality.

_PROPERTIES = []

list of property names to retrieve from population instances.

get_host_properties(pop, copy=True) → dict[source]

Get the host properties specified in the _PROPERTIES list of variable names.

NOTE: if the copy flag is False, then values are returned by reference and the original values may be modified accidentally. Use copy=True to avoid modifying values in place. Use copy=False carefully, when trying to avoid unnecessary memory duplication.

Parameters:

  • pop (holodeck.population.Population instance) – Binary population including necessary host properties.

  • copy (bool, optional) – Copy the pop data into new arrays instead of returning references to original values.

Returns:

vals – Values loaded from pop. Names/keys correspond to _PROPERTIES strings.

Return type:

dict

abstract mbh_from_host(pop, *args, **kwargs) → ndarray[source]

Convert from abstract host galaxy properties to blackhole mass.

This method is intended for discrete (e.g. illustris) based populations.

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:

array_like [g]

_abc_impl = <_abc._abc_data object>
class holodeck.host_relations._MMBulge_Relation(bulge_frac=None, bulge_mfrac=None)[source]

Bases: _BH_Host_Relation

Base class for implementing Mbh–Mbulge relationships, between MBH and their host galaxies.

Typically there is an intermediate step of converting from the galaxy total stellar-mass into a bulge mass, so these relations would more accurately be called Mbh-Mstar relationships. For discrete populations, derived classes must provide a BH mass for a given stellar/bulge mass. For SAMs derived classes must additionally provide the partial derivatives of the black hole mass (so that galaxy-galaxy number densities can be converted to MBH-MBH number densities).

API / Subclass Implementation

Provided - Functions provided directly by this base-class (_MMBulge_Relation).

  • dmstar_dmbh : uses dmstar_dmbulge from the bulge-fraction instance, and the dmbulge_dmbh method which must be provided by subclass implementations.

  • mbh_from_mstar: requires mbulge_from_mstar in the bulge-fraction instance.

Required - for core functionality, all _MMBulge_Relation subclasses are required to implement the following methods:

  • mbh_from_mbulge : the core purpose/functionality of all subclasses.

  • dmbulge_dmbh : required for calculating semi-analytic model populations. More specifically, the dmstar_dmbh method is required for SAMs, and that method in turn requires dmbulge_dmbh to be implemented.

Optional - For extended functionality, _MMBulge_Relation subclasses may implement additional functions, but it is not guaranteed/required. Specifically the following methods:

  • mbulge_from_mbh: the inverse relationship. Not necessarily calculable analytically.

Dependent - Implemented functionality that depends on ‘Optional’ API methods.

  • mstar_from_mbh: requires the mbulge_from_mbh method to be implemented.

_PROPERTIES = ['mbulge']

list of property names to retrieve from population instances.

_bulge_frac

_Bulge_Frac subclass instance to obtain bulge masses

dmstar_dmbh(mstar, redz=None, **bfkwargs)[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]\]

The dMbulge/dMbh component is calculated explicitly using self.ddmbulge_dmbh, while the dMstar/dMbulge component is obtained from the bulge_frac instance.

Parameters:

  • mstar (array_like, [g]) – Total stellar mass of galaxy in units of grams.

  • redz (array_like or None) – Redshifts of the galaxies under consideration.

  • bfkwargs (dict) – Additional arguments passed to the bulge-fraction isntance (self._bulge_frac).

Returns:

dmstar_dmbh – Jacobian term: partial derivative of stellar mass w.r.t. black-hole mass. This quantity is unitless.

Return type:

array_like []

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

Calculate a black-hole mass from the given total stellar-mass.

NOTE: this function requires the mbulge_from_mstar function to be implemented by the bulge-fraction instance (self._bulge_frac) that’s being used. This is not guaranteed!

Parameters:

  • mstar (array_like, [g]) – Total stellar mass of host galaxy in units of grams.

  • redz (array_like or None) – Redshifts of the galaxies under consideration.

  • scatter (bool,) – Whether or not to include scatter when converting to BH masses.

Returns:

mbh – Black hole masses in units of grams.

Return type:

array_like [g]

abstract mbh_from_mbulge(mbulge, redz=None, scatter=None, **kwargs)[source]

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

Returns:

  • mbh (array_like [g]) – Mass of black hole in units of grams.

  • redz (array_like or None) – Redshifts of the galaxies under consideration.

  • scatter (bool,) – Whether or not to include scatter when converting to BH masses.

  • kwargs (dict,) – Additional keyword-arguments.

Returns:

mbh – Black-hole masses in units of grams.

Return type:

array_like [g]

abstract dmbulge_dmbh(mbulge, redz=None)[source]

The partial derivative of stellar mass versus black-hole mass.

Parameters:

mbulge (array_like, [g]) – Mass of the host galaxy stellar bulges in units of grams.

Returns:

dmbulge_dmbh – Jacobian term: partial derivative of stellar-bulge mass w.r.t. black-hole mass. This quantity is unitless.

Return type:

array_like, []

mbulge_from_mbh(*args, **kwargs)[source]

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

Returns:

mbulge – Mass of stellar bulge. [grams]

Return type:

array_like,

mstar_from_mbh(mbh, redz=None)[source]

Calculate a total stellar-mass from the given BH mass.

NOTE: this function requires the mbulge_from_mbh function to be implemented by the particular _MMBulge_Relation subclass, and additionally that the mstar_from_mbulge function is implemented by the bulge-fraction instance (self._bulge_frac) that’s being used. Neither is guaranteed!

Parameters:

  • mbh (array_like [g]) – Mass of black hole in units of grams.

  • redz (array_like or None) – Redshifts of the galaxies under consideration.

Returns:

mstar – Total stellar-mass of galaxies in units of grams.

Return type:

array_like [g]

_abc_impl = <_abc._abc_data object>
class holodeck.host_relations.MMBulge_Standard(mamp_log10=None, mplaw=None, mref=None, scatter_dex=None, bulge_frac=None, bulge_mfrac=None, **kwargs)[source]

Bases: _MMBulge_Relation

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

This Mbh-Mbulge relation implements a single power-law relationship between BH mass and stellar-bulge mass:

\[M_{bh} = M_0 * (M_{bulge}/M_{ref})^\gamma * 10^Normal(0, \epsilon)\]

See documemtation for _MMBulge_Relation for more information.

MASS_AMP_LOG10 = 8.17
MASS_PLAW = 1.01
MASS_REF = 1.9884098706980508e+44
SCATTER_DEX = 0.3
BULGE_MASS_FRAC = 0.615

Default bulge mass as fraction of total stellar mass

_mamp

Mass-Amplitude [grams]

_mplaw

Mass Power-law index

_mref

Reference Mass (argument normalization)

mbh_from_host(pop, scatter=None)[source]

Convert from abstract host galaxy properties to blackhole mass.

This method is intended for discrete (e.g. illustris) based populations.

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:

array_like [g]

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

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

Returns:

  • mbh (array_like [g]) – Mass of black hole in units of grams.

  • redz (array_like or None) – Redshifts of the galaxies under consideration.

  • scatter (bool,) – Whether or not to include scatter when converting to BH masses.

  • kwargs (dict,) – Additional keyword-arguments.

Returns:

mbh – Black-hole masses in units of grams.

Return type:

array_like [g]

dmbulge_dmbh(mbulge, redz=None, **bfkwargs)[source]

Calculate the partial derivative of bulge mass versus BH mass \(d M_bulge / d M_bh\).

\[[d M_bulge / d M_bh] = [M_bulge / (plaw * M_bh)]\]
Parameters:

  • mbulge (array_like, [g]) – Bulge stellar mass of galaxy in units of grams.

  • redz (array_like or None) – Redshifts of the galaxies under consideration.

Returns:

deriv – Jacobian term: partial derivative of stellar mass w.r.t. black-hole mass. This quantity is unitless.

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, [g]) – Mass of black holes in units of grams.

  • redz (array_like or None) – Redshifts of the galaxies under consideration.

  • scatter (bool,) – Whether or not to include scatter in scaling relationship. Uses self._scatter_dex attribute.

Returns:

mbulge – Mass of stellar bulge in units of grams.

Return type:

array_like, [g]

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

Calculate a total stellar-mass from the given BH mass.

NOTE: this function requires the mbulge_from_mbh function to be implemented by the particular _MMBulge_Relation subclass, and additionally that the mstar_from_mbulge function is implemented by the bulge-fraction instance (self._bulge_frac) that’s being used. Neither is guaranteed!

Parameters:

  • mbh (array_like [g]) – Mass of black hole in units of grams.

  • redz (array_like or None) – Redshifts of the galaxies under consideration.

Returns:

mstar – Total stellar-mass of galaxies in units of grams.

Return type:

array_like [g]

_abc_impl = <_abc._abc_data object>
class holodeck.host_relations.MMBulge_KH2013(mamp_log10=None, mplaw=None, mref=None, scatter_dex=None, bulge_frac=None, bulge_mfrac=None, **kwargs)[source]

Bases: MMBulge_Standard

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

Values taken from [KH2013] Eq.10.

MASS_AMP_LOG10 = 8.69
MASS_REF = 1.9884098706980508e+44
MASS_PLAW = 1.17
SCATTER_DEX = 0.28
_abc_impl = <_abc._abc_data object>
class holodeck.host_relations.MMBulge_MM2013(mamp_log10=None, mplaw=None, mref=None, scatter_dex=None, bulge_frac=None, bulge_mfrac=None, **kwargs)[source]

Bases: MMBulge_Standard

Mbh-MBulge Relation from McConnell & Ma 2013

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

MASS_AMP_LOG10 = 8.46
MASS_REF = 1.9884098706980508e+44
MASS_PLAW = 1.05
SCATTER_DEX = 0.34
_abc_impl = <_abc._abc_data object>
class holodeck.host_relations.MMBulge_Redshift(*args, zplaw=None, **kwargs)[source]

Bases: MMBulge_Standard

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 = 8.17
MASS_PLAW = 1.0
MASS_REF = 1.9884098706980508e+44
SCATTER_DEX = 0.0
Z_PLAW = 0.0
_PROPERTIES = ['mbulge', 'redz']

list of property names to retrieve from population instances.

mbh_from_host(pop, scatter)[source]

Convert from abstract host galaxy properties to blackhole mass.

This method is intended for discrete (e.g. illustris) based populations.

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:

array_like [g]

mbh_from_mbulge(mbulge, redz, scatter)[source]

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

Returns:

  • mbh (array_like [g]) – Mass of black hole in units of grams.

  • redz (array_like or None) – Redshifts of the galaxies under consideration.

  • scatter (bool,) – Whether or not to include scatter when converting to BH masses.

  • kwargs (dict,) – Additional keyword-arguments.

Returns:

mbh – Black-hole masses in units of grams.

Return type:

array_like [g]

mbulge_from_mbh(mbh, redz, scatter)[source]

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

Parameters:

  • mbh (array_like, [g]) – Mass of black holes in units of grams.

  • redz (array_like or None) – Redshifts of the galaxies under consideration.

  • scatter (bool,) – Whether or not to include scatter in scaling relationship. Uses self._scatter_dex attribute.

Returns:

mbulge – Mass of stellar bulge in units of grams.

Return type:

array_like, [g]

_abc_impl = <_abc._abc_data object>
class holodeck.host_relations.MMBulge_Redshift_MM2013(*args, zplaw=None, **kwargs)[source]

Bases: MMBulge_Redshift

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_LOG10 = 8.46
MASS_REF = 1.9884098706980508e+44
MASS_PLAW = 1.05
SCATTER_DEX = 0.34
Z_PLAW = 0.0
_abc_impl = <_abc._abc_data object>
class holodeck.host_relations.MMBulge_Redshift_KH2013(*args, zplaw=None, **kwargs)[source]

Bases: MMBulge_Redshift

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 = 8.69
MASS_REF = 1.9884098706980508e+44
MASS_PLAW = 1.17
SCATTER_DEX = 0.28
Z_PLAW = 0.0
_abc_impl = <_abc._abc_data object>
holodeck.host_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

class holodeck.host_relations._MSigma_Relation(*args, **kwargs)[source]

Bases: _BH_Host_Relation

Base class for ‘M-Sigma relations’ between BH mass and host velocity dispersion.

_PROPERTIES = ['vdisp']

list of property names to retrieve from population instances.

abstract mbh_from_vdisp(vdisp, scatter)[source]
abstract vdisp_from_mbh(mbh, scatter)[source]
_abc_impl = <_abc._abc_data object>
class holodeck.host_relations.MSigma_Standard(mamp=None, sigma_plaw=None, sigma_ref=None, scatter_dex=None)[source]

Bases: _MSigma_Relation

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)\)

MASS_AMP = 1.988409870698051e+41
SIGMA_PLAW = 4.24
SIGMA_REF = 20000000.0
SCATTER_DEX = 0.0
mbh_from_host(pop, scatter)[source]

Convert from abstract host galaxy properties to blackhole mass.

This method is intended for discrete (e.g. illustris) based populations.

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:

array_like [g]

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,

_abc_impl = <_abc._abc_data object>
class holodeck.host_relations.MSigma_MM2013(mamp=None, sigma_plaw=None, sigma_ref=None, scatter_dex=None)[source]

Bases: MSigma_Standard

Mbh-Sigma Relation from McConnell & Ma 2013.

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

MASS_AMP = 4.1543770494014215e+41
SIGMA_REF = 20000000.0
MASS_PLAW = 5.64
SCATTER_DEX = 0.38
_abc_impl = <_abc._abc_data object>
class holodeck.host_relations.MSigma_KH2013(mamp=None, sigma_plaw=None, sigma_ref=None, scatter_dex=None)[source]

Bases: MSigma_Standard

Mbh-Sigma Relation from Kormendy & Ho 2013.

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

MASS_AMP = 5.734636708221092e+41
SIGMA_REF = 20000000.0
MASS_PLAW = 4.26
SCATTER_DEX = 0.3
_abc_impl = <_abc._abc_data object>
holodeck.host_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

class holodeck.host_relations.Guo_2010[source]

Bases: _StellarMass_HaloMass

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

[Guo2010] Eq.3

_NORM = 0.129
_M0 = 4.994659774486157e+44
_ALPHA = 0.926
_BETA = 0.261
_GAMMA = 2.44
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

_abc_impl = <_abc._abc_data object>
class holodeck.host_relations.Behroozi_2013(*args, **kwargs)[source]

Bases: _StellarMass_HaloMass_Redshift

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)

_nu_func()[source]

[Behroozi2013] Eq. 4

classmethod _param_func(redz, v0, va, vz, va2=None)[source]

[Behroozi2013] Eq. 4

classmethod _eps(redz=0.0)[source]
classmethod _m1(redz=0.0)[source]
classmethod _alpha(redz=0.0)[source]
classmethod _delta(redz=0.0)[source]
classmethod _gamma(redz=0.0)[source]
classmethod _xsi(redz=0.0)[source]

[Behroozi+2013] Eq.5

classmethod _f_func(xx, redz=0.0)[source]

[Behroozi+2013] Eq.3 (lower)

_abc_impl = <_abc._abc_data object>