Rapster

Rapid population synthesis code for compact binary coalescences in dense stellar clusters.

$\tt Rapster$ stands for $\rm RAPid\ cluSTER$ evolution. (Thanks to Mark Cheung for coming up with the short-hand version!)

Author: Konstantinos Kritos kkritos1@jhu.edu

Version: March 18, 2026. (Thanks to Tousif Islam for helping modularize this repository!)

(Thanks to Hector Cruz for digitizing my hand-drawn logo!)

1. Overview

The repository provides the source code files for the current version in rapster/ and all necessary data files in the Data/ folder, for the rapid evolution of dense star cluster environments and the dynamical assembly of compact-object coalescences and tidal disruption events.

The modeling accounts for the necessary physical processes for forming compact-object binaries and cluster evolution employing semi-analytic prescriptions described in Sec. 2 of K. Kritos et al. PRD (2024). This is our code paper, which we wrote together with Vladirim Strokov, Vishal Baibhav, and Emanuele Berti.

Note:

For computational efficiency, the folder Data/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 $340M_\odot$ and 12 values of absolute metallicity in the range from $10^{-4}$ to $1.7\times10^{-2}$ as calculated with the $\tt SEVN$ code M. Spera & M. Mapelli (2017).

In the current version, we have also included look-up tables for the Mandel-Muller and Fryer et al. (2012) delayed and rapid remnant-mass prescription models in files Mueller_Mandel.txt, MzamsMrem_F12d.txt, and MzamsMrem_F12r.txt, respectively.

Moreover, Data/Planck18_lookup_table.npz is a look-up table for the redshift-lookback time and lookback time-redshift relations assuming the Planck 2018 cosmology.

Finally, Data/x_mb_vec.pkl is a precomputed look-up table generated by Data/.marginally_bound.py for the marginally bound radius normalized to the gravitational radius in the dimensionless spin-inclination parameter space grid.

Abbreviations:

BH: black hole
NS: neutron star
WD: white dwarf
BBH: binary black hole
CBC: compact binary coalescence
GW: gravitational wave
TDE: tidal disruption event

2. Requirements

The following Python packages are required to run the code:

$\tt numpy$ (=2.2.4)
$\tt scipy$ (=1.15.2)
$\tt pandas$ (=2.2.3)

The code is tested with packages in the versions shown in parentheses above; however, likely, other versions work too.

It is recommended that the user create and work in a local Python environment, installing all the dependencies above.

The following packages are recommended for running the tutorial notebook in Examples/, but are not necessary to run cluster simulations:

$\tt matplotlib$
$\tt jupyterlab$
$\tt ipykernel$

First, create an environment called .rapsterenv in the root directory of the repository Rapster/, and hidden from view:

python3 -m venv .rapsterenv

If you use a different name, please add the environment name as a new row in .gitignore, since the environment folder should never be pushed to the repository.

To activate this environment:

source .rapsterenv/bin/activate

To install rapster and all requirements, run:

pip install -e .

Verify the installation (along with dependencies) and package version:

pip list

Finally, include the virtual environment in the kernel:

python -m ipykernel install --user --name=rapsterenv --display-name "Python (.rapsterenv)"

3. Units

The current version of the code uses astrophysical units; see, e.g., Heggie & Hut (2003):

Mass: solar mass ($M_\odot$)
Distance: parsec ($\rm pc$)
Time: million years ($\rm Myr$)
Velocity: $\rm km\ s^{-1}$
Gravitational constant: $G=1/232$
Speed of light: $c=3\times10^5$

4. Input parameters

The code accepts parameters with flag options.

For a description of all input parameters, run the following command in the command line interface:

python -m rapster.run_cluster --help

For the user’s convenience, we paste the list of optional arguments in the form of a Table here as well:

Note:

The initial value of the central stellar density is set by default to 5.3e5 (pc^-3), which assumes a Plummer density profile: $n=3(1.3)^3N/(4\pi)\simeq0.53N$, where $N$ is the number of stars and $r=1,\rm pc$. The cluster then evolves homologically, by assumption. Under the Plummer profile, if the input values for the initial number of stars or initial half-mass radius $r$ are updated, then the central density should be set accordingly, $n=0.53 N/r^3$. If the user prefers an alternative density stellar profile, then a different relation may hold between $N$ and $r$.

5. Running a simulation

usage: -m [-h] [-N] [-r] [-mm] [-mM] [-Z] [-z] [-n] [-fb] [-S] [-dtm] [-dtM] [-tM] [-wK] [-K] [-R] [-vg] [-s] [-SD] [-P] [-Mi] [-MF] [-Ei] [-EF] [-Hi] [-HF] [-BIi] [-BIF] [-BOi] [-BOF] [-RP] [-NS] [-WT] [-Ti] [-TF] [-MBH] [-sBH] [-RF]

Testing:

To test the code, execute the program with all defaults:

python -m rapster.run_cluster

from any directory, with the virtual environment (.rapsterenv) enabled.

This should create five files: Results/mergers.txt, Results/evolution.txt, Results/hardening.txt, Results/tdes.txt, and Results/outputBHs.pkl inside the newly created folder Results/ within your current directory. To check and verify whether you have produced these files correctly, we include the corresponding files /Rapster/Example/Results_Test/mergers.txt, /Rapster/Example/Results_Test/evolution.txt, /Rapster/Example/Results_Test/hardening.txt, /Rapster/Example/Results_Test/tdes.txt,

Rapster

Install / Use

README

Rapster

Contents:

1. Overview

Note:

Abbreviations:

2. Requirements

3. Units

4. Input parameters

Note:

5. Running a simulation

Testing: