Rapid population synthesis code for binary black-hole mergers in dynamical environments.
Author: Konstantinos Kritos [email protected]
Version: January 18, 2023
(Thanks to H. Cruz for digitizing my hand-drawn logo!)
- Overview
- Requirements
- Input parameters
- Running a simulation
- Output files
- Applications of the code
- Citing this work
- Reporting bugs
- Thanks
The repository provides the source codes, files ./rapster.py
and ./functions.py
, and all necessary data files in folder ./MzamsMrem/
, for the rapid evolution of dense star cluster environments and the dynamical assembly of binary black hole mergers.
The modeling accounts for the necessary physical processes regarding the formation of binary black holes employing semi-analytic prescriptions as described in Sec. 2 of K. Kritos et al. (2022). This is our code paper we wrote together with V. Strokov, V. Baibhav, and E. Berti. (Thanks to C. Rodriguez and G. Fragione for suggesting improvements to our model!)
For computational efficiency, the folder ./MzamsMrem/
contains 12 files with pre-calculated look-up tables of stellar remnants masses on a grid of zero-age main sequence values up to
- BH: black hole
- BBH: binary black hole
- GW: gravitational wave
The following Python packages are required
-
$\tt precession$ (1.0.3) -
$\tt astropy$ (5.0.4) -
$\tt argparse$ (1.1) $\tt cmath$ -
$\tt numpy$ (>=1.12.3) -
$\tt scipy$ (1.8.0) $\tt math$ $\tt time$
The code is tested with packages in the versions shown in parentheses above, however it is likely that other versions work too.
It is suggested that the
Our code accepts parameters with flag options.
For a description of all input parameters, run the following command in the command line interface:
python3 rapster.py --help
or see Table 1 from K. Kritos et al. (2022).
For the user’s convenience we paste the list of optional arguments in the form of a Table here as well:
Flag | Description | Type | Default |
---|---|---|---|
-Mcl, --ClusterMass | Initial cluster mass |
float | |
-rh, --HalfMassRadius | Initial half-mass radius (pc) | float | 1 pc |
-rhoC, --CentralDensity | Initial central star density |
float | |
-Rgal, --GalactocentricRadius | Initial galactocentric radius (kpc) | float | 8 kpc |
-Z, --Metallicity | Cluster metallicity |
float | |
-fb, --BinaryFraction | Initial binary star fraction | float | 10% |
-w, --NatalKickParameter | Natal velocity kick parameter of BHs (km/s) | float | 265 km/s |
-chi, --NatalSpinParameter | Natal spin parameter of first generation (1g) BHs | float | 0 |
-SM, --NatalSpinDistribution | Natal spin distribution (1 for monochromatic, 0 for uniform) | int | 0 |
-tMax, --SimulationTime | Maximum simulation time (Myr) | float | 13,800 Myr |
-dtMin, --MinimumTimeStep | Minimum simulation timestep (Myr) | float | 0.1 Myr |
-dtMax, --MaximumTimeStep | Maximum simulation timestep (Myr) | float | 50 Myr |
-z, --FormationRedshift | Redshift of cluster formation | float | 3 |
-aIMF, --HighMassIMFslope | High mass initial star mass function slope | floar | -2.3 |
-ZAMSmax, --MaximumZAMSmass | Maximum ZAMS star mass |
float | |
-c, --ConcentrationNFW | Concentration parameter of the NFW profile | float | 10 |
-Rs, --ScaleRadiusNFW | Scale radius of the NFW profile (kpc) | float | 50 kpc |
-Mh, --DarkMatterHaloMass | Total DM halo mass of the host galaxy |
float | |
-s, --Seed | Random number generator seed | int | 123456789 |
-MF, --MergersFile | Name of output file with BBH merger source parameters | str | mergers |
-EF, --EvolutionFile | Name of output file with time-dependent quantities | str | evolution |
-BF, --BlackHoleFile | Name of output file containing the masses of all 1g BHs in |
str | blackholes |
usage: rapster.py [-h] [-Mcl ] [-rh ] [-rhoC ] [-Rgal ] [-Z ] [-fB ] [-w ] [-chi ] [-SM ] [-tMax ] [-dtMin ] [-dtMax ] [-z ] [-aIMF ] [-ZAMSmax ] [-c ] [-Rs ] [-Mh ] [-s ] [-MF ] [-EF ] [-BF ]
As an example we give the commands that produce data used to generate the results in Fig.4 of K. Kritos et al. (2022):
python3 rapster.py -Mcl 1.36e5 -rh 1.6 -rhoC 5.6e4 -EF ev_a -MF me_a -BF bh_a -Z 0.08 -z 3 -Rgal 8
python3 rapster.py -Mcl 5.40e5 -rh 1.6 -rhoC 26.9e4 -EF ev_b -MF me_b -BF bh_b -Z 0.08 -z 3 -Rgal 8
python3 rapster.py -Mcl 10.82e5 -rh 1.6 -rhoC 15.1e4 -EF ev_c -MF me_c -BF bh_c -Z 0.03 -z 3 -Rgal 20
The default values are assumed for other parameters not entered in the commands above.
To test the code, execute the program with all default values:
python3 rapster.py
This should create three files mergers.txt
, evolution.txt
, and blackholes.npz
in your current directory. To check and verify whether you have produced these files correctly, we include the corresponding files mergers_TEST.txt
, evolution_TEST.txt
, and blackholes_TEST.npz
in folder ./Testing/
in this repository with data that should match your ouput.
Taking different values of seed number corresponds to different realizations of the system under the same initial conditions. Passing the argument $$\tt$ RANDOM$$ in the -s flag, simulates the star cluster with a pseudo-randomly generated number.
At the end of each simulation the code generates three .txt files, one with the black hole masses of all first generation black holes that are initially retained in the cluster, a second file with information about all dynamical mergers that took place during the simulation, and finally a file that keeps track of time-dependent quantities.
a) Column description of mergers .txt file:
Column | Variable | Description |
---|---|---|
1 | channel | Formation mechanism of BBH |
2 | Semimajor axis (AU) when BBH enters the GW regime | |
3 | Eccentricity of BBH when BBH enters the GW regime | |
4 | Primary mass |
|
5 | Secondary mass |
|
6 | Primary dimensionless spin parameter | |
7 | Secondary dimensionless spin parameter | |
8 | Generation of primary | |
9 | Generation of secondary | |
10 | Time (Myr) BBH formed since simulation started | |
11 | Time (Myr) BBH merged since simulation started | |
12 | Redshift BBH formed | |
13 | Redshift BBH merged | |
14 | Number of hardening interactions | |
15 | Number of BH exchanges | |
16 | Mass ratio | |
17 | Effective spin parameter | |
18 | Polar angle (rad) of primary's spin with orbital angular momentum | |
19 | Polar angle (rad) of secondary's spin with orbital angular momentum | |
20 | Azimuthal angle (rad) between BH spins in the orbital plane | |
21 | Remnant mass |
|
22 | Dimensionless remnant spin parameter | |
23 | Remnant generation | |
24 | GW kick (km/s) of remnant BH | |
25 | Reference to primary’s progenitor BBH (if hierarchical product) | |
26 | Reference to secondary’s progenitor BBH (if hierarchical product) | |
27 | Initial cluster mass |
|
28 | Cluster formation redshift |
BBH assembly channel (first column of mergers file), the -
sign means BBH was ejected and merged outside the cluster:
- (-)1: exchange processes
- 2: two-body capture
- (-)3: three-BH binary induced
- (-)4: von Zeipel-Lidov-Kozai (ZLK) merger
- (-)5: ZLK remnant BBH
b) Column description of evolution .txt file:
Columnn | Variable | Description |
---|---|---|
1 | Simulation time (Myr) | |
2 | Redshift | |
3 | Cluster mass |
|
4 | Cluster half-mass radius (pc) | |
5 | Cluster’s galactocentric radius (kpc) | |
6 | Total number of BHs in cluster | |
7 | Number of single BHs in cluster | |
8 | Number of BH-star pairs in cluster | |
9 | Number of BBHs in cluster | |
10 | Number of triple BHs in cluster | |
11 | Number of BBH mergers in total | |
12 | Number of retained mergers | |
13 | Number of ejected mergers | |
14 | Number of dynamical BBHs that merge in field | |
15 | Number of ZLK mergers | |
16 | Number of captured BBHs | |
17 | Number of BBH ejections | |
18 | Escape velocity (km/s) | |
19 | Number density of binary stars |
|
20 | Mean segregation volume of BHs |
|
21 | Equipartition parameter | |
22 | Stellar velocity (km/s) | |
23 | Mean BH velocity (km/s) | |
24 | Mean capture timescale (Myr) | |
25 | Mean star-star |
|
26 | Mean BH-star |
|
27 | Mean 3bb formation timescale (Myr) | |
28 | Mean binary-binary interaction timescale (Myr) | |
29 | Mean BH-star |
|
30 | Cumulative number of star-star |
|
31 | Cumulative number of BH-star |
|
32 | Cumulative number of 3bb interactions | |
33 | Cumulative number of BBH$-$BBH interactions | |
34 | Cumulative number of BH-star$-$BH-star interactions | |
35 | Mean BH mass |
c) The blackholes .npz file contains two arrays, called mBH_ini
and mBH_fin
which provide in
The code can be useful when executed multiple times, for instance when simulating a set of clusters and generating a population of dynamically formed BBH mergers.
Although the program itself is not computationally expensive (we have tested in a laptop that we generate a few binary black hole mergers per second), independent parallelization is still encouraged when simulating a very large number of star clusters for efficiency.
If you utilize this code in your research, please cite the following reference:
K. Kritos, V. Strokov, V. Baibhav & E. Berti (2022).
If you find a bug in the code, please contact us in [email protected] with a description of the bug.
Suggestions and pull requests are welcome :)
Vladimir Strokov, Vishal Baibhav, Emanuele Berti, Andrea Antonelli, Mark Cheung, Roberto Cotesta, Hector Cruz, Giacomo Fragione, Gabriele Franciolini, Thomas Helfer, Veome Kapil, Kyle Kremer, Iason Krommydas, Luca Reali, Carl Rodriguez, Xiao-Xiao Kou.