gwGenealogy

Contents

  • Installation
    • From source
    • Dependencies
    • Building the documentation
  • Quick Start
    • Sample a BBH population
    • Compute remnant properties
    • Hierarchical mergers
    • BH seed growth
    • Retention probability grids
    • GWTC population sampling
    • Host environment retention
  • API Reference
    • Utils
      • seed_legacy_rng()
      • sample_uniform_1d()
      • sample_loguniform_1d()
      • sample_gaussian_1d()
      • sample_lognormal_1d()
      • sample_powerlaw_1d()
      • sample_maxwellian_1d()
      • sample_beta_1d()
      • m1_m2_to_mchirp()
      • m1_m2_to_q()
      • m1_m2_to_eta()
      • source_frame_to_detector_frame_mass()
      • detector_frame_to_source_frame_mass()
      • chi_eff()
      • chi_p()
      • delta_parallel()
      • delta_perp()
      • chi_tilde_parallel()
      • chi_tilde_perp()
      • polar_to_cartesian()
      • cartesian_to_polar()
      • spins_polar_to_cartesian_vectors()
      • spins_cartesian_vectors_to_polar()
      • compute_kullback_leibler_divergence()
      • compute_jensen_shannon_divergence()
      • set_rcparams()
    • Binaries
      • BBHs
      • sample_masses()
      • sample_spins()
      • sample_spin_magnitudes()
      • sample_spin_angles()
      • E()
      • comoving_volume_element()
      • luminosity_distance()
      • redshift_probability_density()
      • sample_redshift()
      • powerlaw_redshift_pdf()
      • sample_redshift_powerlaw()
      • madau_dickinson_redshift_pdf()
      • sample_redshift_madau_dickinson()
      • preload_kick_model()
      • BBHRemnant
      • download_gwtc_data()
      • sample_gwtc_population()
      • available_catalogs()
      • sample_smbbh()
    • Stellar
      • IMF_kroupa()
      • sample_kroupa_masses()
      • sample_zams_masses()
      • evolve_stars()
      • sample_1g_bh_masses_from_stellar_collapse()
      • compute_Mrem_Fryer12_delayed_rapster()
      • compute_Mrem_SEVN_delayed_rapster()
      • sample_maxwellian_kick()
    • Hosts
      • PlummerCluster
        • PlummerCluster.potential()
        • PlummerCluster.density()
        • PlummerCluster.sigma()
        • PlummerCluster.merger_analysis()
      • plummer_scale_radius()
      • plummer_potential()
      • plummer_density()
      • plummer_velocity_dispersion()
      • plummer_escape_speed()
      • plummer_core_speed()
      • plummer_tidal_radius()
      • plummer_apocentre()
      • chandrasekhar_F()
      • orbit_shape_factor()
      • dynamical_friction_time()
      • retained_mask()
      • Mcl_rh_to_vescape()
      • Mcl_rho_to_vescape()
      • sample_star_clusters_mapelli2021()
      • sample_star_clusters()
      • sample_escape_speed()
      • sample_multi_escape_speed()
      • escape_speed_cdf()
      • compute_environment_retention()
      • compute_multi_environment_retention()
      • retention_curve()
      • compute_environment_cumulative_retention()
      • compute_multi_environment_cumulative_retention()
    • Core
      • HierarchicalMergersInCluster
        • HierarchicalMergersInCluster.simulate()
        • HierarchicalMergersInCluster.plot_generations()
      • HierarchicalMergersInClusterPopulation
        • HierarchicalMergersInClusterPopulation.simulate()
        • HierarchicalMergersInClusterPopulation.plot_generations()
      • MonteCarloBHSeedGrowth
        • MonteCarloBHSeedGrowth.simulate()
        • MonteCarloBHSeedGrowth.simulate_grid()
      • IMBHFormationProbability
        • IMBHFormationProbability.compute()
        • IMBHFormationProbability.plot_heatmap()
        • IMBHFormationProbability.plot_heatmap_all_vesc()
      • BBHRetentionProbabilityOverChiq
        • BBHRetentionProbabilityOverChiq.compute()
        • BBHRetentionProbabilityOverChiq.plot_heatmap()
        • BBHRetentionProbabilityOverChiq.plot_heatmap_all_vesc()
      • BBHRetentionProbabilities
        • BBHRetentionProbabilities.compute()
        • BBHRetentionProbabilities.plot_kicks()
        • BBHRetentionProbabilities.plot_retention()
  • Tutorials
    • Core Distribution Samplers
      • Draw samples from all seven distributions
      • Histograms
      • JSD between distributions
    • Stellar Evolution and 1G BH Masses
      • Kroupa IMF
      • Stellar evolution: ZAMS to BH remnant
      • SEVN delayed model
      • 1G BH mass pool
      • Natal kicks
    • BBH Remnants: Nonprecessing Models
      • Sample BBH population
      • Nonprecessing remnants: default (UIB + gwmodel_kick_q200)
      • Alternative: HBR + HLZ
      • Remnant distributions
      • JSD between models
      • Remnant properties vs binary parameters
    • BBH Remnants: Precessing Models
      • Sample BBH population
      • Precessing remnants: default (HBR + gwmodel)
      • Alternative: HBR + HLZ (CLZM2007)
      • Remnant distributions: gwmodel vs HLZ
      • JSD between kick models
      • Scatter comparison
      • Surrogate models (surfinBH)
      • Remnant properties vs binary parameters
    • GWTC Population Sampling
      • Available catalogs
      • Sample from GWTC-5 default model
      • Mass and spin distributions
      • GWTC-3 vs GWTC-5 comparison
      • Posterior vs prior predictive
      • Redshift distribution
    • Retention Probability Over the (chi, q) Plane
      • HLZ kick model
        • Single panel: \(v_{\rm esc} = 200\) km/s
      • HLZ vs gwModel comparison
    • Host Environments and Retention
      • Escape velocity formulas
      • Plummer cluster model
      • Merger retention in a Plummer cluster
      • Cluster population sampling
      • Environment escape-speed distributions
      • Environment-marginalised retention
      • Multi-environment retention
    • Hierarchical BH Mergers in Dense Star Clusters
      • 2. Hierarchical Mergers Across Generations
        • Pairing model comparison
        • Evolving escape velocity
      • 3. Paper-style generation plots
        • HLZ vs gwModel comparison (3-panel)
    • BH Seed Growth Demo
      • Extended run: max_generations=100
      • Escape velocity sweep with run_grid
      • Evolving escape velocity
    • Remnant Displacement and Return Times
      • Generate a realistic kick distribution
      • Apocentre displacement (r_max)
      • Dynamical friction return time (t_DF)
      • Displacement and return time: joint view
      • Dependence on cluster mass
      • GC vs NSC
      • Effect of remnant mass on return time
      • Standalone functions
    • Hierarchical BH Mergers in a Single Star Cluster
      • 1. Basic usage
      • 2. Evolving escape velocity
      • 3. Comparing different clusters
      • 4. Metallicity dependence
      • 5. Pairing model comparison
      • 6. Kick model comparison (HLZ vs gwModel)
    • Inferring the progenitor of a recoiling SMBH: JWST RBH-1
      • Set up and run the inversion
      • Progenitor posterior
      • Posterior-predictive check
      • Many kicks at once
      • Caveats
  • Citation
    • Papers using gwGenealogy
gwGenealogy
  • Overview: module code

All modules for which code is available

  • gwGenealogy.binaries.bbh
  • gwGenealogy.binaries.bbh_gwtc
  • gwGenealogy.binaries.bbh_masses
  • gwGenealogy.binaries.bbh_redshifts
  • gwGenealogy.binaries.bbh_remnant
  • gwGenealogy.binaries.bbh_spins
  • gwGenealogy.binaries.smbbh
  • gwGenealogy.core.hierarchical
  • gwGenealogy.core.retention
  • gwGenealogy.core.seed_growth
  • gwGenealogy.hosts.host_retention
  • gwGenealogy.hosts.plummer
  • gwGenealogy.hosts.star_clusters
  • gwGenealogy.stellar.collapse
  • gwGenealogy.stellar.natal_kick
  • gwGenealogy.stellar.stellar_evolution
  • gwGenealogy.utils.conversions
  • gwGenealogy.utils.coordinates
  • gwGenealogy.utils.distributions
  • gwGenealogy.utils.rcparams
  • gwGenealogy.utils.statistics

© Copyright 2026, Tousif Islam.

Built with Sphinx using a theme provided by Read the Docs.