holodeck.discrete.population

Discrete MBH Binary Populations (from cosmological hydrodynamic simulations) and related tools.

Cosmological hydrodynamic simulations model the universe by coevolving gas along with particles that represent dark matter (DM), stars, and often BHs. These simulations strive to model physical processes at the most fundamental level allowed by resolution constraints / computational limitations. For example, BH accretion will typically be calculated by measuring the local density (and thermal properties) of gas, which may also be subjected to ‘feedback’ processes from the accreting BH itself, thereby producing a ‘self-consistent’ model. However, no cosmological simulations are able to fully resolve either the accretion or the feedback process, such that ‘sub-grid models’ (simplified prescriptions) must be adopted to model the physics at sub-resolution scales.

The numerical methods and subgrid modeling details of cosmological hydrodynamic simulations vary significantly from one code-base and simulation suite to another. This holodeck submodule generates populations of MBH binaries using processed data files derived what whatever cosmo-hydro simulations are used. To get to MBHBs, data must be provided either on the encounter (‘merger’) rate of MBHs from the cosmological simulations directly, or based on the galaxy-galaxy encounters and then prescribing MBH-MBH pairs onto those.

This submodule provides a generalized base-class, _Population_Discrete, that is subclassed to implement populations from particular cosmological simulations. At the time of this writing, an Illustris-based implementation is included, Pop_Illustris. Additionally, a set of classes are also provided that can make ‘modifications’ to these populations based on subclasses of the _Population_Modifier base class. Examples of currently implemented modifiers are: adding eccentricity to otherwise circular binaries (PM_Eccentricity), or changing the MBH masses to match prescribed scaling relations (PM_Mass_Reset).

The implementation for binary evolution (e.g. environmental hardening processes), as a function of separation or frequency, are included in the holodeck.evolution module. The population classes describe the ‘initial conditions’ of binaries. The initial conditions, or ‘formation’, of the binary can be defined arbitrarily. In practice, due to cosmologcal-simulation resolution constraints, this is at/during the galaxy merger when the two MBHs are at separations of roughly a kiloparsec, and not gravitational bound, or even interacting. Depending on what evolution model is used along with the initial population, all or only some fraction of ‘binaries’ (MBH pairs) will actually reach the small separations to become a true, gravitationally-bound binary.

The fundamental, required attributes for all population classes are:

• sepa the initial binary separation in [cm]. This should be shaped as (N,) for N binaries.

• mass the mass of each component in the binary in [gram]. This should be shaped as (N, 2) for N binaries, and the two components of the binary. The 0th index should refer to the more massive primary, while the 1th component refers to the less massive secondary.

• scafa the scale-factor defining the age of the universe for formation of this binary. This should be shaped as (N,).

Notes

• Populations (subclasses of _Population_Discrete)

  • The _init() method is used to set the basic attributes of the binary population (i.e. sepa, mass, and scafa).

  • The _update_derived() method is used to set quantities that are derived from the basic attributes. For example, the size attribute should be set here, based on the length of the attribute arrays.

• Modifiers (subclasses of _Population_Modifier)

  • The modify() method must be overridden to change the attributes of a population instance. The changes should be made in-place (i.e. without returning a new copy of the population instance).

References

• [Genel2014] Genel et al. (2014)

• [Kelley2017a] Kelley, Blecha, and Hernquist (2017a).

• [Kelley2017b] Kelley et al. (2017b).

• [Kelley2018] Kelley et al. (2018).

• [Nelson2015] Nelson et al. (2015)

• [Rodriguez-Gomez2015] Rodriguez-Gomez et al. (2015)

• [Sijacki2015] Sijacki et al. (2015)

• [Springel2010] Springel (2010)

• [Vogelsberger2014] Vogelsberger et al. (2014)

class holodeck.discrete.population._Population_Discrete(*args, mods=None, check=True, **kwargs)

Bases: ABC

Base class for representing discrete binaries, e.g. from cosmo hydrodynamic simulations.

This class must be subclasses for specific implementations (i.e. for specific cosmo sims).

mass

blackhole masses (N, 2)

sepa

binary separation a (N,)

scafa

scale factor of the universe (N,)

eccen

binary eccentricities (N,) [optional]

weight

weight of each binary as a sample point (N,) [optional]

_size

number of binaries

_sample_volume

comoving volume containing the binary population [cm^3]

abstract _init()

Initialize basic binary parameters.

This function should typically be overridden in subclasses.

_update_derived()

Set or reset any derived quantities.

property size

Number of binaries in descrete population.

Returns:

Number of binaries.

Return type:

int

property mtmr

Total mass and mass-ratio of each binary.

Returns:

The total-mass (0) and mass-ratio (1) of each binary.

Return type:

ndarray (2, N)

property redz

Redshift at formation of each binary.

Returns:

Redshift.

Return type:

ndarray (N,)

modify(mods=None)

Apply any population modifiers to this population.

Process: 1) Each modifier is applied to the population and _update_derived() is called. 2) After all modifiers are applied, _finalize() is called. 3) If the _check_flag attribute is true, then the _check() method is called.

Parameters:

mods (None or (list of Population_Modifer)) – Population modifiers to apply to this population.

_finalize()

Method called after all population modifers have been applied, in the modify() method.

_check()

Perform diagnostic/sanity checks on the binary population.

_abc_impl = <_abc._abc_data object>

class holodeck.discrete.population.Pop_Illustris(fname=None, **kwargs)

Bases: _Population_Discrete

Discrete population derived from the Illustris cosmological hydrodynamic simulations.

Illustris are a suite of cosmological simulations that co-evolve gas, stars, dark-matter, and BHs from the early universe until redshift zero. The simulations are based on the moving-mesh hydrodynamics code arepo [Springel2010]. The basic results of the simulations are presented in [Vogelsberger2014] & [Genel2014], which emphasize the simulations’ accuracy in reproducing the properties and evolution of galaxies across cosmic time. [Sijacki2015] goes into more depth about the MBH implementation, their results, and comparisons with observational measuremens of MBHs and AGN. The Illustris data, including MBH binary catalogs, are available online, described in [Nelson2015]. Catalogs of galaxy-galaxy mergers have also been calculated and released publically, described in [Rodriguez-Gomez2015].

Takes as input a data file that includes BH and subhalo data for BH and/or galaxy mergers.

Notes

• Parameters required in input hdf5 file:

  • box_volume_mpc:

  • part_names:

  • time:

  • SubhaloHalfmassRadType:

  • SubhaloMassInRadType:

  • SubhaloVelDisp:

  • SubhaloBHMass:

_fname

Filename for binary data

_init()

Set the population parameters using an input simulation file.

_abc_impl = <_abc._abc_data object>

class holodeck.discrete.population._Population_Modifier

Bases: _Modifier

Base class for constructing Modifiers that are applied to _Discrete_Population instances.

_abc_impl = <_abc._abc_data object>

class holodeck.discrete.population.PM_Eccentricity(eccen_dist: Tuple[float, float] = (1.0, 0.2))

Bases: _Population_Modifier

Population Modifier to implement eccentricity in the binary population.

eccen_dist

Two parameter specification for eccentricity distribution

modify(pop)

Add eccentricity to the given population.

Passes the self.eccen_dist attribute to the holodeck.utils.eccen_func function.

Parameters:

pop (instance of _Population_Discrete or subclass,) – Binary population to be modified.

_random_eccentricities(size) → ndarray

Draw random eccentricities from the standard distribution.

Parameters:

size (scalar,) – The number of eccentricity values to draw. Cast to int.

Returns:

Eccentricities, with shape (N,) such that N is the parameter size cast to int type.

Return type:

ndarray

_abc_impl = <_abc._abc_data object>

class holodeck.discrete.population.PM_Resample(resample=10.0, plot=False, additional_keys=True)

Bases: _Population_Modifier

Population Modifier to resample a population instance to a new number of binaries.

Uses kalepy kernel density estimation (KDE) to resample the original population into a new one, changing the total number of binaries by some factor (usually increasing the population).

Notes

Resampled Parameters: By default, four or five parameters are resampled: 1) mtot: total mass; 2) mrat: mass ratio; 3) redz: redshift; and 4) sepa: separation; and if the eccen attrbute of the population is not None, then it is also resampled. Additional parameters can be specified using the _DEF_ADDITIONAL_KEYS attribute which is a list of str giving the parameter names, which must then be accessible attributes of the population instance being resampled. Sample Volume: _Discrete_Population instances refer to some finite (comoving) volume of the Universe, which is given in the population’s _sample_volume attribute. When resampling is performed, this volume is also multiplied by the same resampling factor. For example, if the population is resampled 10x (i.e. resample==10.0), then the _sample_volume attribute is also multiplied by 10x.

_DEF_ADDITIONAL_KEYS = ['vdisp', 'mbulge']

_old_data

Version of the previous population stored for plotting purposes

_new_data

Version of the updated population stored for plotting purposes

_additional_keys

Additional parameter names to be resampled

modify(pop)

Resample the binaries from the given population to achieve a new number of binaries.

Parameters:

pop (instance of _Population_Discrete or subclass,) – Binary population to be modified.

plot()

Plot a comparison of the old and new data, before and after resampling.

A kalepy.Corner plot is generated.

Returns:

The figure object containing the plot.

Return type:

mpl.figure.Figure instance,

_abc_impl = <_abc._abc_data object>

class holodeck.discrete.population.PM_Mass_Reset(mhost, scatter=True)

Bases: _Population_Modifier

Reset the masses of a target population based on a given M-Host relation.

mhost

Scaling relationship between host and MBH (holo.host_relations._BH_Host_Relation)

_scatter

Bool determining whether resampled masses should include statistical scatter

modify(pop)

Reset the BH masses of the given population.

Parameters:

pop (instance of _Population_Discrete or subclass,) – Binary population to be modified.

_abc_impl = <_abc._abc_data object>

class holodeck.discrete.population.PM_Density(factor)

Bases: _Population_Modifier

modify(pop)

Perform an in-place modification on the passed object instance.

Parameters:

base (object) – The object instance to be modified.

_abc_impl = <_abc._abc_data object>