Simulating the source population

GWForge can simulate a wide range of binary source populations (at the moment). This page tells you how you can use them.

The first step in generating a source population is to determine the distribution of sources in luminosity distance \((D_L)\) (or equivalently redshift \((z))\) and the expected number of signals in the data. So, we will start by setting up the [Redshift] section.

Redshift

For this, you need to specify:

• Redshift distribution model

• Local merger rate density in \((Gpc^{-3}yr^{-1})\)

• Maximum redshift of the source

• Cosmological parameters such as \(H_0,~O_{m0}, O_{de0}\) and \(T_{cmb0}\), assuming LambdaCDM cosmology

• A reference start time when you switch on your detector.

The last is optional. If not provided, GWForge assumes Planck18 cosmology. $$ H_0 = 67.66~km/s/Mpc,~O_{m0} = 0.30966,~T_{cmb0} = 2.7255 K $$

Alternatively, you can select any of the cosmological realisations implemented in astropy.

If you choose to define a custom Universe, you can do so as follows:

[Redshift]
redshift-model = MadauDickinson
redshift-parameters = {'gamma': 2.7, 'kappa': 5.6, 'z_peak': 1.9}
local-merger-rate-density = 22
maximum-redshift = 30
; custom cosmology
cosmology = custom 
H0 = 70
Om0 = 0.3
Ode0 = 0.7
Tcmb0 = 2.735
; analysis start time
gps-start-time = 1893024018

For reference, the Madau-Dickinson distribution function is: $$ p(z | \gamma, \kappa, z_\mathrm{peak}) \propto \frac{1}{1+z} \frac{dV_c}{dz} \psi(z | \gamma, \kappa, z_\mathrm{peak}) $$ where $$ \psi(z | \gamma, \kappa, z_\mathrm{peak}) \propto \frac{(1+z)^\gamma}{1+\big(\frac{1+z}{1+z_\mathrm{peak}}\big)^\kappa} M_\odot/\mathrm{year}/\mathrm{Mpc}^3 $$ and

parameter	descsription
\(\gamma\)	Slope of the distribution at low redshift
\(\kappa\)	Slope of the distribution at high redshift
\(z_\textrm{peak}\)	Redshift at which the distribution peaks.
\(z_\textrm{max}\)	The maximum redshift allowed.

It is important to note that this describes the progenitor formation rate distribution. To obtain the compact binary merger rate distribution, GWForge convolves it with a time-delay distribution.

The reader can refer to the following for further details:

• A Mock Data Challenge for the Einstein Gravitational-Wave Telescope

• Mock data study for next-generation ground-based detectors: The performance loss of matched filtering due to correlated confusion noise

Note

The above implementation assumes that all compact binary systems are formed by isolated binary evolution via the common-envelope phase. It also adopts a flat-in-log distribution for a time delay between binary formation and merger.

Mass

The [Mass] section helps define the mass distribution of the binary population. Similar to the [Redshift] section, a model name and a dictionary of parameters must be provided. For example:

[Mass]
mass-model = PowerLaw+Peak
mass-parameters = {'alpha':3.37, 'beta': 0.76, 'delta_m':5.23,  'mmin':4.89, 'mmax':88.81, 'lam':0.04, 'mpp': 33.60, 'sigpp':4.59}

The currently available mass distribution models and their parameters are:

List of mass distribution models

Model Name	Parameters	Description
PowerLaw+Peak	alpha, beta, mmin, mmax, lam, mpp, sigpp, delta_m	Powerlaw + peak model for two-dimensional mass distribution with low mass smoothing.
MultiPeak	alpha, beta, mmin, mmax, lam, lam_1, mpp_1, mpp_2, sigpp_1, sigp_2, delta_m	Powerlaw + two peak model for two-dimensional mass distribution with low mass smoothing.
BrokenPowerLaw	alpha_1, alpha_2, beta, break_fraction, mmin, mmax, delta_m	Broken power law for two-dimensional mass distribution with low mass smoothing.
UniformSecondary	alpha, beta, delta_m, mmin, mmax, 88.81, lam, mpp, sigpp, minimum_secondary_mass, maximum_secondary_mass	PowerLaw + Peak for primary mass and uniform for secondary
DoubleGaussian	mu_1, sigma_1, mu_2, sigma_2, breaking_fraction, mmin, mmax	Truncated Gaussian distribution for primary and secondary
LogNormal	mu, sigma	Log-normal distribution with mean mu and width sigma for primary and secondary
PowerLawDipBreak	mmin, mmax, alpha_1, alpha_2, gamma_low, gamma_high, eta_low, eta_high, A, n	Extension of power law break model
PowerLaw	alpha_1, mmin, mmax	Power law with bounds and alpha, spectral index for primary and secondary

The parameter names are heavily dependent on gwpopulation and bilby. Thus, it is essential to keep track of definition changes.

For more details, refer to the following publications:

• Binary Black Hole Population Properties Inferred from the First and Second Observing Runs of Advanced LIGO and Advanced Virgo

• Population Properties of Compact Objects from the Second LIGO-Virgo Gravitational-Wave Transient Catalog

• Population of Merging Compact Binaries Inferred Using Gravitational Waves through GWTC-3

Note

GWForge overlooks special characters and converts everything to lower cases. So PowerLaw+Peak is equivalent to powerlawpeak.

Spin

The [Spin] section determines the spin distribution of the population. For example:

[Spin]
spin-model = Beta-Aligned
spin-parameters = {'minimum_primary_spin' : 0, 'maximum_primary_spin':  0.99, 'minimum_secondary_spin' : 0, 'maximum_secondary_spin' : 0.5, 'mu_chi' : 0.26, 'sigma_squared_chi' : 0.02}

defines a quasi-circular (non-precessing) binary population whose spin magnitude is sampled from a beta distribution.

Here is the list of currently available spin distribution

List of spin distribution models

Model	Parameters	Description
Non-spinning	None	Non-spinning
Aligned	minimum_primary_spin, minimum_secondary_spin, maximum_primary_spin, maximum_secondary_spin	Aligned spin distribution Bilby-style
Aligned-Bilby	minimum_primary_spin, minimum_secondary_spin, maximum_primary_spin, maximum_secondary_spin	Aligned spin distribution Bilby-style
Aligned-Uniform	minimum_primary_spin, minimum_secondary_spin, maximum_primary_spin, maximum_secondary_spin	Aligned component of spins are sampled from uniform distribution
Beta-Aligned	minimum_primary_spin, minimum_secondary_spin, maximum_primary_spin, maximum_secondary_spin, mu_chi, sigma_squared_chi	Bilby style aligned spin distribution Bilby-style with spin magnitudes obeying Beta distribution
Aligned-Gaussian-Uniform	minimum_primary_spin, minimum_secondary_spin, maximum_primary_spin, maximum_secondary_spin,mu_chi_1, sigma_chi_1	Aligned component of primary is sampled from Truncated Gaussian and secondary from uniform
Isotropic	minimum_primary_spin, minimum_secondary_spin, maximum_primary_spin, maximum_secondary_spin	Spin Magnitudes sampled from Uniform distribution + Isotropic distribution of spin angles
Isotropic-Beta	minimum_primary_spin, minimum_secondary_spin, maximum_primary_spin, maximum_secondary_spin, mu_chi, sigma_squared_chi	Spin Magnitudes sampled from Beta distribution. Isotropic distribution of spin angles
Isotropic-Beta_Gaussian	minimum_primary_spin, minimum_secondary_spin, maximum_primary_spin, maximum_secondary_spin, mu_chi, sigma_squared_chi, sigma_t	Spin magnitudes sampled from Beta distribution. Truncated Gaussian distribution for cosine tilt angles.
Isotropic-Beta_Gaussian_Uniform	minimum_primary_spin, minimum_secondary_spin, maximum_primary_spin, maximum_secondary_spin, mu_chi, sigma_squared_chi, sigma_t, xi_spin	Spin magnitudes sampled from Beta distribution. A fraction of the binaries have cosine tilt angles from Truncated Gaussian distribution and the rest from a uniform distribution between (-1,1)
Default	minimum_primary_spin, minimum_secondary_spin, maximum_primary_spin, maximum_secondary_spin, mu_chi, sigma_squared_chi, sigma_t, xi_spin	Same as Isotropic-Beta_Gaussian_Uniform

For more details, refer to the following publications:

• Binary Black Hole Population Properties Inferred from the First and Second Observing Runs of Advanced LIGO and Advanced Virgo

• Population Properties of Compact Objects from the Second LIGO-Virgo Gravitational-Wave Transient Catalog

• Population of Merging Compact Binaries Inferred Using Gravitational Waves through GWTC-3

Extrinsic

The [Extrinsic] section is designed to handle sky location and binary orientation parameters. You can specify a bilby prior file as input. By default, it assumes an isotropic distribution for sky location and orientation parameters and a uniform distribution for the polarization angle.

For example:

[Extrinsic]

will use the second.

EOS (Equation of State)

The [EOS] section allows specifying an eos-file that provides the mass and tidal parameters for a neutron star equation of state. By default, the SLy EOS (Skyrme-Lyon) is used, but you can override this by specifying a different eos-file in the following way:

[EOS]
eos-file = /ligo/home/ligo.org/koustav.chandra/projects/Cosmic-Explorer-MDC/gwforge/GWForge/inject/eos_tables/TOVSeq_SLy.dat

provided it is consistent with how Rahul likes to define them. You can find examples of eos-tables in the GWForge repository.

Structure of eos-file The EOS tables are structured in columns, where each column corresponds to different physical parameters. Below is a breakdown of few of these columns:

C: Compactness of neutron star.

Mb: Baryonic mass in solar masses

M: Mass in solar mass units

R: Radius in solar mass units

kl : Second love number

Generating the population.

To generate the binary parameters for the population, execute the following:

gwforge_population --config-file bbh.ini --output-file bbh.h5

It should take at most a minute to generate the output file. By default gwforge_population assumes your source type is BBH. For other options, please check gwforge_population --help. Please note that the waveform approximant that you use for your waveform generation supports tidal parameters if the source-type is bns or nsbh.

By default a year gwforge_population generates a year worth of population. If you want some other value, please add the `duration` flag and add a value in seconds.
Example: `duration=4096`. Please note that the population generated should be greater than the number of signals injected.

A few more example configuration file exist here: ~/.conda/envs/gwforge-venv/lib/python3.9/site-packages/GWForge/population/. Feel free to modify and see what you get.

Naive way to check the population

You can check the binary parameters of the population by doing the following:

from GWForge.utils import cornerplot
cornerplot(file='bbh.h5', parameters=['mass_1_source', 'mass_2_source', 'spin_1z','spin_2z',  'redshift'], save='pop.png')

This will create a plot called pop.png in the current working directory with the parameters. The list of parameters can be found by doing h5ls -r bbh.h5. It list all the keys of an HDF5 file.