Created By: Dina Meylakh
A command line tool to sample 3 body properties within clusters using probability density fuctions for different distributions.
Based on the Meylakh, Stone & Leigh 2026 paper. View all references within the paper.
For version history and information, see the changelog.
flowchart TB
T(("Triple")) -- Chaotic triple --> S(("Scramble"))
T -- "Non-Chaotic" --> IT{"Ionized Triple"}
T -- Almost Chaotic --> EX(("Exchange"))
S -- "1 - p_dis" --> IMS["IMS"]
IMS --> S & BTD{"Binary TD"}
S -- p_dis --> FS["FS"]
IMS -- IMS Merger --> M(("Merger"))
FS -- FS Merger --> M
FS --> BTD & B(("Binary"))
FS -- recoil > cluster pull --> EJ(("Ejected"))
EJ -- Ejected FS Merger --> M
EJ --> EB{"Ejected Binary"}
STD(("Single TD")) --> B
EX --> B & T
B -- Hubble time is passed --> ICB{"In-Cluster Binary"}
B --> NS(("New Single"))
M --> EC{"Eccentric"} & NEC{"Non-Eccentric"}
NS --> T
IMS --> STD
T:::Rose
S:::Rose
IT:::Ash
EX:::Sky
IMS:::Rose
BTD:::Ash
FS:::Rose
M:::Peach
B:::Rose
EJ:::Sky
EB:::Ash
STD:::Sky
ICB:::Ash
NS:::Sky
EC:::Peach
NEC:::Peach
classDef Ash stroke-width:1px, stroke-dasharray:none, stroke:#999999, fill:#EEEEEE, color:#000000
classDef Sky stroke-width:1px, stroke-dasharray:none, stroke:#374D7C, fill:#E2EBFF, color:#374D7C
classDef Aqua stroke-width:1px, stroke-dasharray:none, stroke:#46EDC8, fill:#DEFFF8, color:#378E7A
classDef Peach stroke-width:1px, stroke-dasharray:none, stroke:#FBB35A, fill:#FFEFDB, color:#8F632D
classDef Rose stroke-width:1px, stroke-dasharray:none, stroke:#FF5978, fill:#FFDFE5, color:#8E2236
-
Install pipx
-
Install the probab3 command line tool via pipx
pipx install git+https://github.com/DinaMeylakh/probab3.git#latest
Comment: To install a specific version, instead of latest, write the relevant version tag.
- Check that the probab3 command line tool is installed correctly by running
probab3 versionThis should return in yellow:
You are using probab3 version 1.0.0Optional. To use probab3 as a python package, for custom cookbooks for example, one must install it as a package via pip.
pip install git+https://github.com/DinaMeylakh/probab3.git#latest
You can check the installation is successful by the following steps:
-
Entering a python shell:
python
-
and importing the package:
import probab3
If no errors were encountered, the python package is successfully installed.
After successful installation, you can run view probab3 commands by typing:
probab3 --helpThis will return a list of all the available commands and their descriptions.
You can then continue to inspect probab3 command options by typing:
probab3 <command> --helpThis will return a list of all the available options for the command and their descriptions.
After choosing a command and its options, you can run it by typing:
probab3 <command> <options>Evolve a black hole binary in a star cluster, introducing equal mass teritiary all the time and save to "example.jsonl" file.
probab3 sample-dbs --output_path "example.jsonl" equal-mass-basic --m1 10 This command might take a few minutes depending on how fast your computer is and how lucky you are. You should see outputs similar to the following:
You are using probab3 version 0.1.0
Starting batch of size 1
[------------------------------------] 0% Starting evolution 1/1
evolution ended with ionized_binary after 167.96994709968567 seconds
Exporting evolution 1/1 to file example.json
[####################################] 100%
time: 168.04273581504822This will create a file named "example.json" in your current directory. You can view the metadata of this file by typing:
probab3 show-stats --input-path example.jsonl --N 0 --outcomesThis will return a dictionary with all the metadata of the 0th evolution and statistics of evolution ends inside the whole file like the following:
You are using probab3 version 0.1.0
{'Mc': 6.289517283862093e+35,
'alpha': 2.5,
'end': 'ionized_binary',
'm1': 1.9889200000000001e+31,
'm2': 1.9889200000000001e+31,
'm3': 1.9889200000000001e+31,
'output_file_path': 'example.json',
'rc': 3086000000000000.0,
'rejection': True,
'rh': 3.086e+16,
'size': 1}
({'ej_binary': 0,
'ej_fs_collision': 0,
'ej_fs_em': 0,
'ej_fs_merger': 0,
'ej_fs_tde': 0,
'fs_collision': 0,
'fs_em_merger': 0,
'fs_merger': 0,
'fs_tde': 0,
'ims_collision': 0,
'ims_em_merger': 0,
'ims_merger': 0,
'ims_tde': 0,
'in_cluster_binary': 0,
'ionized_binary': 1.0},
1)You can also view the evolution of the system by typing:
probab3 plot --input-path example.jsonl --N 0This will open up a window with a plot of the evolution of the system.
You can close the window to continue using your shell.
You can view the probab3 log file by tailing proabab3.log.
For example for linux based systems:
tail -f probab3.logOr for windows:
Get-Content -Path "probab3.log" -Tail 10 -WaitNote: The log is created in the directory the command was run in.
More information is available about:
In case you want to tinker with the source code or are looking to contribute, you will need to have a few more things in mind.
-
Make sure you have Python >= 3.8.0 installed
-
Make sure you have git installed
-
Make sure you have Poetry installed
-
Clone the probab3 repository to a directory on your local computer
git clone https://github.com/DinaMeylakh/probab3.git- Install the project dependencies with poetry
cd probab3
poetry install- Run your local repository with
poetry run probab3 <command>The open source license for this repository is the MIT license.
Bug fixes and new features are more than welcome.
Please visit the Contributing page for more information about the process.