holodeck.gravwaves

Gravitational Wave (GW) calculations module.

This module provides tools for calculating GW signals from MBH binaries. Currently the components here are used with the ‘discrete’ / ‘illustris’ population of binaries, and not the semi-analytic or observational population models.

class holodeck.gravwaves.Grav_Waves(bin_evo, fobs_gw, nharms=103, nreals=100)[source]

Bases: object

property freqs
class holodeck.gravwaves.GW_Discrete(*args, **kwargs)[source]

Bases: Grav_Waves

emit(eccen=None, stats=False, progress=True, nloudest=5)[source]
class holodeck.gravwaves.LISA(mission_duration_yrs=5.0, fobs=(1e-07, 1.0, 1000))[source]

Bases: object

property sensitivity
is_above_hc_curve(ff, hc)[source]

Determine which frequencies and strains are above the LISA sensitivity curve.

Parameters:

  • ff (array_like of float) – Frequencies of binaries. Units of [Hz]

  • hc (array_like of float) – Characterstic-strains of binaries.

Returns:

sel – Whether or not the corresponding binary is detectable. Matches the shape of ff.

Return type:

array_like of bool

holodeck.gravwaves._gws_harmonics_at_evo_fobs(fobs_gw, dlnf, evo, harm_range, nreals, box_vol, loudest=5)[source]

Calculate GW signal at range of frequency harmonics for a single observer-frame GW frequency.

Parameters:

  • fobs_gw (float) – Observer-frame GW-frequency in units of [1/sec]. This is a single, float value.

  • dlnf (float) – Log-width of observered-frequency bin, i.e. \(\Delta \ln f\). This is width of observed GW frequency bins.

  • evo (holodeck.evolution.Evolution) – Initialized and evolved binary evolution instance, storing the binary evolution histories of each binary.

  • harm_range (list[int]) – Harmonics of the orbital-frequency at which to calculate GW emission. For circular orbits, only [2] is needed, as the GW frequency is twice the orbital frequency. For eccentric orbital, GW emission is produced both at harmonic 1 and higher harmonics. The higher the eccentricity the more GW energy is emitted at higher and higher harmonics.

  • nreals (int) – Number of realizations to calculate in Poisson sampling.

  • box_vol (float) – Volume of the simulation box that the binary population is derived from. Units of [cm^3].

  • loudest (int) – Number of ‘loudest’ (highest amplitude) strain values to calculate and return separately.

Returns:

  • mc_ecc_both ((R,) ndarray,) – Combined (background + foreground) GW Strain at this frequency, for R realizations.

  • mc_ecc_fore ((R,) ndarray,) – GW foreground strain (i.e. loudest single source) at this frequency, for R realizations.

  • mc_ecc_back ((R,) ndarray,) – GW background strain (i.e. all sources except for the loudest) at this frequency, for R realizations.

  • loud ((L, R) ndarray,) – Strains of the L loudest binaries (L=`loudest` input parameter) for each realization.

  • gwb_harms ((H,))

holodeck.gravwaves._gws_from_samples(vals, weights, fobs_gw_edges)[source]

Calculate GW signals at the given frequencies, from weighted samples of a binary population.

Parameters:

  • vals ((4, N) ndarray of scalar,) – Arrays of binary parameters. * vals[0] : mtot [grams] * vals[1] : mrat [] * vals[2] : redz [] * vals[3] : observer-frame orbital-frequency of binaries [1/sec]

  • weights ((N,) array of scalar,) –

  • fobs_gw_edges ((F,) array of scalar,) – Target observer-frame GW-frequencies to calculate GWs at. Units of [1/sec].

Returns:

  • gff ((F,) ndarray,) – Observer-frame GW-frequencies of the loudest binary in each bin [1/sec].

  • gwf ((F,) ndarray,) – GW Foreground: the characteristic strain of the loudest binary in each frequency bin.

  • gwb ((F,) ndarray,) – GW Background: the characteristic strain of the GWB in each frequency bin. Does not include the strain from the loudest binary in each bin (gwf).

holodeck.gravwaves._strains_from_samples(vals)[source]

From a sampled binary population, calculate the GW strains.

Parameters:

vals ((4,) array_like of array_like,) – Each element of vals is an array of binary parameters, the elements must be: * 0) total binary mass [grams] * 1) binary mass-ratio [], * 2) redshift at this frequency [], * 3) observer-frame orbital-frequency [1/sec].

Returns:

  • hs ((N,) ndarray,) – Source strains (i.e. not characteristic strains) of each binary.

  • fobs_gw ((N,) ndarray,) – Observer-frame GW-frequencies of each sampled binary. [1/sec].

holodeck.gravwaves.gws_from_sampled_strains(fobs_gw_edges, fo, hs, weights)[source]

Calculate GW background/foreground from sampled GW strains.

Parameters:

  • fobs_gw_edges ((F,) array_like of scalar) – Observer-frame GW-frequency bin edges.

  • fo ((S,) array_like of scalar) – Observer-frame GW-frequency of each binary sample. Units of [1/sec]

  • hs ((S,) array_like of scalar) – GW source strain (not characteristic strain) of each binary sample.

  • weights ((S,) array_like of int) – Weighting factor for each binary. NOTE: the GW calculation is ill-defined if weights have fractional values (i.e. float values, instead of integral values; but the type itself doesn’t matter)

Returns:

  • gwf_freqs ((F,) ndarray of scalar) – Observer-frame GW frequency of foreground sources in each frequency bin. Units of [1/sec].

  • gwfore ((F,) ndarray of scalar) – Strain amplitude of foreground sources in each frequency bin.

  • gwback ((F,) ndarray of scalar) – Strain amplitude of the background in each frequency bin.

holodeck.gravwaves.sampled_gws_from_sam(sam, fobs_gw, hard=<class 'holodeck.hardening.Hard_GW'>, **kwargs)[source]

Sample the given binary population between the target frequencies, and calculate GW signals.

NOTE: the input fobs are interpretted as bin edges, and GW signals are calculate within the corresponding bins.

Parameters:

  • sam (Semi_Analytic_Model instance,) – Binary population to sample.

  • fobs_gw ((F+1,) array_like,) – Target observer-frame GW-frequencies of interest in units of [1/sec]

  • hard (holodeck.evolution._Hardening instance,) – Binary hardening model used to calculate binary residence time at each frequency.

  • kwargs (dict,) – Additional keyword-arguments passed to sample_sam_with_hardening()

Returns:

  • gff ((F,) ndarry,) – Observer-frame GW-frequencies of the loudest binary in each bin [1/sec].

  • gwf ((F,) ndarry,) – GW Foreground: the characteristic strain of the loudest binary in each frequency bin.

  • gwb ((F,) ndarry,) – GW Background: the characteristic strain of the GWB in each frequency bin. Does not include the strain from the loudest binary in each bin (gwf).

holodeck.gravwaves._gws_from_number_grid_integrated_redz(edges, redz, number, realize, sum=True)[source]
Parameters:

  • edges ((4,) list of 1darrays) – A list containing the edges along each dimension. The four dimensions correspond to total mass, mass ratio, redshift, and observer-frame orbital frequency. The length of each of the four arrays is M, Q, Z, F.

  • redz –

  • number ((M-1, Q-1, Z-1, F-1) ndarray) – The number of binaries in each bin of parameter space. This is calculated by integrating dnum over each bin.

  • realize (bool or int,) – Specification of how to construct one or more discrete realizations. If a bool value, then whether or not to construct a realization. If an int value, then how many discrete realizations to construct.

  • sum (bool,) – Whether or not to sum over axes {0, 1, 2}.

Returns:

hc – Characteristic strain of the GWB. The shape depends on whether sum is true or false. sum = True: shape is (F-1,) sum = False: shape is (M-1, Q-1, Z-1, F-1)

Return type:

ndarray

holodeck.gravwaves._gws_from_number_grid_integrated(edges, number, realize, sum=True)[source]
Parameters:

  • edges ((4,) list of 1darrays) – A list containing the edges along each dimension. The four dimensions correspond to total mass, mass ratio, redshift, and observer-frame orbital frequency. The length of each of the four arrays is M, Q, Z, F.

  • number ((M-1, Q-1, Z-1, F-1) ndarray) – The number of binaries in each bin of parameter space. This is calculated by integrating dnum over each bin.

  • realize (bool or int,) – Specification of how to construct one or more discrete realizations. If a bool value, then whether or not to construct a realization. If an int value, then how many discrete realizations to construct.

  • sum (bool,) – Whether or not to sum over axes {0, 1, 2}.

Returns:

hc – Characteristic strain of the GWB. The shape depends on whether sum is true or false. sum = True: shape is (F-1,) sum = False: shape is (M-1, Q-1, Z-1, F-1)

Return type:

ndarray

holodeck.gravwaves.gwb_ideal(fobs_gw, ndens, mtot, mrat, redz, dlog10, sum=True)[source]
holodeck.gravwaves.poisson_as_needed(values, thresh=10000000000.0)[source]

Calculate Poisson distribution when values are below threshold, otherwise approximate with normal distribution.

Parameters:

  • values (ndarray) – Expectation values for poisson distribution.

  • thresh (float) – Expectation value above which to use Normal distribution approximation.

Returns:

output – (Approximately) Poisson distributed values. Same shape as input values.

Return type:

ndarray

holodeck.gravwaves.char_strain_sq_from_bin_edges_redz(edges, redz)[source]
holodeck.gravwaves.strain_amp_from_bin_edges_redz(edges, redz)[source]
holodeck.gravwaves.char_strain_sq_from_bin_edges(edges)[source]
holodeck.gravwaves._python_sam_calc_gwb_single_eccen(gwfobs, sam, sepa_evo, eccen_evo, nharms=100)[source]
Parameters:

  • gwfobs ((F,) array_like) – Observer-frame frequencies at which to calculate GWB.

  • sam (Semi_Analytic_Model instance) –

  • forb_rst_evo ((M, E) array_like) – Rest-frame orbital frequencies of binaries, for each total-mass M and evolution step E.

  • eccen_evo ((E,) array_like) – Eccentricities at each evolution step. The same for all binaries, corresponding to fixed binary separations for all binaries.

  • nharms (int) – Number of harmonics to use in calculating GWB.

Returns:

  • gwfobs_harms (Observer-frame GW harmonic frequencies.)

  • gwb ((F,) ndarray) – GW Background: the ideal characteristic strain of the GWB in each frequency bin. Does not include the strain from the loudest binary in each bin (gwf).

  • ecc_out

  • tau_out

holodeck.gravwaves.sam_calc_gwb_single_eccen(gwfobs, sam, sepa_evo, eccen_evo, nharms=100)[source]
holodeck.gravwaves.sam_calc_gwb_single_eccen_discrete(gwfobs, sam, sepa_evo, eccen_evo, nharms=100, nreals=None)[source]
Parameters:

  • gwfobs ((F,) array_like) – Observer-frame frequencies at which to calculate GWB.

  • sam (Semi_Analytic_Model instance) – Binary population to sample. See holodeck.simple_sam or ‘holodeck.sam`

  • sepa_evo – Separation at each evolution step.

  • eccen_evo ((E,) array_like) – Eccentricities at each evolution step. The same for all binaries, corresponding to fixed binary separations for all binaries.

  • nharms (int, optional) – Number of harmonics to use in calculating GWB.

  • nreals (int or None, optional) – Number of realizations to calculate in Poisson sampling.

Returns:

gwb – GW Background: the characteristic strain of the GWB in each frequency bin. Does not include the strain from the loudest binary in each bin (gwf).

Return type:

(F,) ndarray,

holodeck.gravwaves._calc_mc_at_fobs(*args, **kwargs)[source]
holodeck.gravwaves._gws_from_number_grid_centroids(edges, dnum, number, realize)[source]

Calculate GWs based on a grid of number-of-binaries.

# ! BUG: THIS ASSUMES THAT FREQUENCIES ARE NYQUIST SAMPLED ! # ! otherwise the conversion from hs to hc doesnt work !

NOTE: _gws_from_number_grid_integrated() should be more accurate, but this method better matches GWB from sampled (kale.sample_) populations!!

The input number of binaries is N s.t.

\[N = (d^4 N / [dlog10(M) dq dz dlogf] ) * dlog10(M) dq dz dlogf\]
The number N is evaluated on a 4d grid, specified by edges, i.e.
\[N = N(M, q, z, f_r)\]
NOTE: the provided number must also summed/integrated over dlogf. To calculate characteristic strain, this function divides again by the dlogf term.

Parameters:

  • edges ((4,) iterable of array_like,) – The edges of each dimension of the parameter space. The edges should be, in order: [mtot, mrat, redz, fobs], In units of [grams], [], [], [1/sec].

  • dnum ((M, Q, Z, F) ndarray,) – Differential comoving number-density of binaries in each bin.

  • number ((M, Q, Z, F) ndarray,) – Volumetric comoving number-density of binaries in each bin.

  • realize (bool or int,) – Whether or not to calculate one or multiple realizations of the population. BUG: explain more.

Returns:

hc – Total characteristic GW strain from each bin of parameter space. NOTE: to get total strain from all bins, must sum in quarature! e.g. gwb = np.sqrt(np.square(hc).sum())

Return type:

(M’,Q’,Z’,F) ndarray,