Hosts

class gwGenealogy.hosts.plummer.PlummerCluster(Mcl, r_h, cluster_type=None, epsilon=None, tau_gyr=None, rt_over_rh=None, ln_lambda=2.5)

Bases: object

Plummer sphere cluster model with merger retention analysis.

Parameters:

• Mcl (float) – Cluster mass [Msun]

• r_h (float) – Half-mass radius [pc]

• cluster_type (str, optional) – ‘GC’ or ‘NSC’. Sets epsilon, tau_gyr, rt_over_rh defaults.

• epsilon (float, optional) – Repeat-merger efficiency. Overrides cluster_type default.

• tau_gyr (float, optional) – Repeat-merger timescale [Gyr]. Overrides cluster_type default.

• rt_over_rh (float, optional) – Tidal radius in units of r_h. Overrides cluster_type default.

• ln_lambda (float) – Coulomb logarithm (default: 2.5)

potential(r)

Gravitational potential at distance r [pc]. Returns (km/s)^2.

density(r)

Density at distance r [pc]. Returns Msun/pc^3.

sigma(r)

1-D velocity dispersion at distance r [pc]. Returns km/s.

merger_analysis(v_kick, M_bh)

Run full merger retention analysis for a set of kicks.

Parameters:

• v_kick (array) – Kick velocity samples [km/s]

• M_bh (array) – Remnant BH masses [Msun]

• attributes (Sets)

• ---------------

• v_kick

• M_bh

• retained (boolean array)

• r_max (array (NaN for unbound kicks))

• t_df (array (NaN for ejected kicks) [Myr])

• P_ret (float)

• P_core (float)

• P_hier (float)

gwGenealogy.hosts.plummer.plummer_scale_radius(r_h)

Convert half-mass radius to Plummer scale radius: a = r_h / 1.305.

Parameters:

r_h (float or array) – Half-mass radius [pc]

Returns:

a – Scale radius [pc]

Return type:

float or array

gwGenealogy.hosts.plummer.plummer_potential(r, Mcl, a)

Plummer gravitational potential Phi(r).

Parameters:

• r (float or array) – Radial distance [pc]

• Mcl (float) – Cluster mass [Msun]

• a (float) – Scale radius [pc]

Returns:

Phi – Potential [(km/s)^2]

Return type:

float or array

gwGenealogy.hosts.plummer.plummer_density(r, Mcl, a)

Plummer density profile rho(r).

Parameters:

• r (float or array) – Radial distance [pc]

• Mcl (float) – Cluster mass [Msun]

• a (float) – Scale radius [pc]

Returns:

rho – Density [Msun / pc^3]

Return type:

float or array

gwGenealogy.hosts.plummer.plummer_velocity_dispersion(r, Mcl, a)

Isotropic 1-D velocity dispersion sigma(r) for a Plummer sphere.

Parameters:

• r (float or array) – Radial distance [pc]

• Mcl (float) – Cluster mass [Msun]

• a (float) – Scale radius [pc]

Returns:

sigma – Velocity dispersion [km/s]

Return type:

float or array

gwGenealogy.hosts.plummer.plummer_escape_speed(Mcl, a)

Central escape speed v_esc = sqrt(2 G Mcl / a).

Parameters:

• Mcl (float or array) – Cluster mass [Msun]

• a (float or array) – Scale radius [pc]

Returns:

v_esc – Escape speed [km/s]

Return type:

float or array

gwGenealogy.hosts.plummer.plummer_core_speed(Mcl, a)

Core-crossing speed v_c ~ 0.54 v_esc.

Parameters:

• Mcl (float or array) – Cluster mass [Msun]

• a (float or array) – Scale radius [pc]

Returns:

v_c – Core-crossing speed [km/s]

Return type:

float or array

gwGenealogy.hosts.plummer.plummer_tidal_radius(r_h, rt_over_rh=5.0)

Tidal truncation radius r_t = rt_over_rh * r_h.

Parameters:

• r_h (float or array) – Half-mass radius [pc]

• rt_over_rh (float) – Tidal radius in units of r_h (default: 5.0)

Returns:

r_t – Tidal radius [pc]

Return type:

float or array

gwGenealogy.hosts.plummer.plummer_apocentre(v_kick, v_esc, a)

Radial-orbit apocentre r_max in a Plummer potential.

Parameters:

• v_kick (float or array) – Kick velocity (must be < v_esc for bound orbits) [km/s]

• v_esc (float) – Central escape speed [km/s]

• a (float) – Scale radius [pc]

Returns:

r_max – Apocentre distance [pc]

Return type:

float or array

gwGenealogy.hosts.plummer.chandrasekhar_F(X)

Chandrasekhar velocity term F(X) = erf(X) - (2X/sqrt(pi)) exp(-X^2).

Parameters:

X (float or array) – Velocity ratio v / (sqrt(2) sigma)

Returns:

F

Return type:

float or array

gwGenealogy.hosts.plummer.orbit_shape_factor(u, n_xi=400)

Dimensionless orbit-shape factor R(u) for a radial Plummer orbit.

Parameters:

• u (float) – Ratio v_kick / v_esc (0 < u < 1)

• n_xi (int) – Number of quadrature points (default: 400)

Returns:

R – Dimensionless orbit-shape factor

Return type:

float

gwGenealogy.hosts.plummer.dynamical_friction_time(v_kick, v_esc, Mcl, a, M_bh, ln_lambda=2.5)

Orbit-averaged Chandrasekhar dynamical-friction return time.

Parameters:

• v_kick (float or array) – Kick velocities of RETAINED remnants (v_kick < v_esc) [km/s]

• v_esc (float) – Central escape speed [km/s]

• Mcl (float) – Cluster mass [Msun]

• a (float) – Plummer scale radius [pc]

• M_bh (float or array (matching v_kick)) – Remnant BH mass(es) [Msun]

• ln_lambda (float) – Coulomb logarithm (default: 2.5)

Returns:

t_DF – Return time [Myr]

Return type:

float or array

gwGenealogy.hosts.plummer.retained_mask(v_kick, v_esc, a, r_t)

Boolean mask: bound (v_kick < v_esc) AND apocentre within tidal radius.

Parameters:

• v_kick (array) – Kick velocities [km/s]

• v_esc (float) – Central escape speed [km/s]

• a (float) – Plummer scale radius [pc]

• r_t (float) – Tidal truncation radius [pc]

Returns:

mask

Return type:

boolean array (same shape as v_kick)

gwGenealogy.hosts.star_clusters.Mcl_rh_to_vescape(Mcl, r_h)

Escape velocity from cluster mass and half-mass radius (virial theorem).

v_esc = 2 * sqrt(0.4 G M_cl / r_h)

Parameters:

• Mcl (float or array) – Total cluster mass [Msun]

• r_h (float or array) – Half-mass radius [pc]

Returns:

• v_esc (float or array) – Escape velocity [km/s]

• Reference (https://arxiv.org/pdf/2210.10055, Equation 1)

gwGenealogy.hosts.star_clusters.Mcl_rho_to_vescape(Mcl, rho)

Escape velocity from cluster mass and half-mass density (scaling relation).

v_esc = 40 km/s * (M_tot / 1e5 Msun)^(1/3) * (rho / 1e5 Msun pc^-3)^(1/6)

Parameters:

• Mcl (float or array) – Total cluster mass [Msun]

• rho (float or array) – Density at the half-mass radius [Msun pc^-3]

Returns:

• v_esc (float or array) – Escape velocity [km/s]

• References (Georgiev et al. (2009a,b), Fragione & Silk (2020),)

• https (//arxiv.org/pdf/2103.05016 Equation 22)

gwGenealogy.hosts.star_clusters.sample_star_clusters_mapelli2021(n_samples, cluster_type='GC', sigma_M=0.4, sigma_rho=0.4, seed=None)

Sample star cluster properties following Mapelli et al. (2021) Sec 2.5.

Parameters:

• n_samples (int) – Number of clusters to draw.

• cluster_type (str) – ‘NSC’, ‘GC’, or ‘YSC’.

• sigma_M (float) – Std dev of log10(M_cluster/Msun) distribution (default: 0.4).

• sigma_rho (float) – Std dev of log10(rho/(Msun pc^-3)) distribution (default: 0.4).

• seed (int or None) – Random seed.

Returns:

M_cluster : total mass [Msun] rho : half-mass density [Msun pc^-3] rho_c : core density = 20*rho [Msun pc^-3] v_esc : escape velocity [km/s] t_SC : cluster lifetime [Gyr] f_bin : binary fraction

Return type:

dict

gwGenealogy.hosts.star_clusters.sample_star_clusters(n_samples, M_cluster_min=1000.0, M_cluster_max=100000000.0, r_h_min=0.1, r_h_max=100.0, Z_min=0.0001, Z_max=0.02, seed=None)

Sample generic star cluster properties from log-uniform priors.

Parameters:

• n_samples (int) – Number of clusters to draw.

• M_cluster_min (float) – Minimum cluster mass [Msun] (default: 1e3).

• M_cluster_max (float) – Maximum cluster mass [Msun] (default: 1e8).

• r_h_min (float) – Minimum half-mass radius [pc] (default: 0.1).

• r_h_max (float) – Maximum half-mass radius [pc] (default: 100).

• Z_min (float) – Minimum metallicity (default: 1e-4).

• Z_max (float) – Maximum metallicity (default: 0.02).

• seed (int or None) – Random seed.

Returns:

M_cluster : cluster mass [Msun] r_h : half-mass radius [pc] Z : metallicity v_esc : escape velocity [km/s]

Return type:

dict

gwGenealogy.hosts.host_retention.sample_escape_speed(n_samples, environment, seed=None)

Draw escape velocity samples from an environment’s distribution.

Parameters:

• n_samples (int) – Number of samples to draw.

• environment (dict) – Environment specification (see escape_speed_cdf).

• seed (int or None) – Random seed.

Returns:

v_esc – Escape velocity samples [km/s]

Return type:

numpy array

gwGenealogy.hosts.host_retention.sample_multi_escape_speed(n_samples, environments=None, seed=None)

Draw escape velocity samples for multiple environments.

Parameters:

• n_samples (int) – Number of samples per environment.

• environments (dict of {name: environment_dict}, optional) – Defaults to all predefined environments.

• seed (int or None) – Random seed.

Returns:

dict of {name

Return type:

numpy array of v_esc}

gwGenealogy.hosts.host_retention.escape_speed_cdf(v, environment)

CDF of the escape-speed distribution for a given environment.

Parameters:

• v (float or array) – Escape speed value(s) [km/s]

• environment (dict) –

  Environment specification with ‘kind’ key:

  • {'kind': 'lognormal', 'mu': float, 'sig': float} mu and sig are base-10 log mean and std dev (v_esc ~ 10^N(mu, sig))

  • {'kind': 'uniform', 'vmin': float, 'vmax': float}

  • {'kind': 'gaussian', 'mean': float, 'std': float}

Returns:

cdf

Return type:

float or array

gwGenealogy.hosts.host_retention.compute_environment_retention(v_kick, environment)

Per-kick retention probability for a given environment.

p_ret_i = 1 - CDF(v_kick_i)

Parameters:

• v_kick (array) – Kick velocity samples [km/s]

• environment (dict) – Environment specification (see escape_speed_cdf)

Returns:

p_ret – Individual retention probability for each kick sample

Return type:

numpy array

gwGenealogy.hosts.host_retention.compute_multi_environment_retention(v_kick, environments=None)

Per-kick retention probabilities across multiple environments.

Parameters:

• v_kick (array) – Kick velocity samples [km/s]

• environments (dict of {name: environment_dict}, optional) – Defaults to all predefined environments (GC, NSC, EG, DG)

Returns:

dict of {name

Return type:

numpy array of p_ret}

gwGenealogy.hosts.host_retention.retention_curve(v_kick, v_esc_array)

Retention probability as a function of escape speed.

p_ret(v_esc) = P(v_kick < v_esc), the empirical CDF of kick samples evaluated on v_esc_array.

Parameters:

• v_kick (array) – Kick velocity samples [km/s]

• v_esc_array (array) – Escape speed values at which to evaluate retention [km/s]

Returns:

p_ret – Retention probability at each v_esc value

Return type:

numpy array

gwGenealogy.hosts.host_retention.compute_environment_cumulative_retention(v_kick, environment, method='kde', vmax=5000.0, ngrid=5000)

Integrated retention fraction P_ret for a given environment.

P_ret = ∫ p_kick(v) [1 - CDF_esc(v)] dv

Parameters:

• v_kick (array) – Kick velocity samples [km/s]

• environment (dict) – Environment specification (see escape_speed_cdf)

• method (str) – ‘kde’ (default): fit a KDE to the kick samples and integrate analytically. More accurate for posterior/MCMC samples. ‘mc’: Monte Carlo mean (1/N) Σ p_ret_i. Exact when samples are iid draws from the kick distribution.

• vmax (float) – Upper integration limit for KDE method [km/s] (default: 5000).

• ngrid (int) – Number of grid points for KDE integration (default: 5000).

Returns:

P_ret – Integrated retention fraction

Return type:

float

gwGenealogy.hosts.host_retention.compute_multi_environment_cumulative_retention(v_kick, environments=None, method='kde', **kwargs)

Integrated retention fraction P_ret across multiple environments.

Parameters:

• v_kick (array) – Kick velocity samples [km/s]

• environments (dict of {name: environment_dict}, optional) – Defaults to all predefined environments.

• method (str) – ‘kde’ (default) or ‘mc’. See compute_environment_cumulative_retention.

• **kwargs – Additional keyword arguments passed to compute_environment_cumulative_retention (vmax, ngrid).

Returns:

dict of {name

Return type:

P_ret}