# ARCHEO
[](https://github.com/wyhwong/archeo)
[](https://pypi.org/project/archeo/)
[](https://doi.org/10.5281/zenodo.14306853)
[](https://github.com/wyhwong/archeo)
[](https://pypi.org/project/archeo/)
[](https://github.com/wyhwong/archeo/blob/main/LICENSE)
[](https://github.com/wyhwong/archeo/actions/workflows/main.yml/)
Archeo is a Python package designed to infer the natal kick, ancestral masses, and spins of black holes in the Pair-instability Supernova (PISN) gap,
with a particular focus on hierarchical black hole formation.
## Basic Usage with Command Line Interface (CLI)
We provide a command line interface (CLI) for archeo, which allows users to generate preset priors and visualize prior distributions easily.
```
> python -m archeo --help
Usage: python -m archeo [OPTIONS] COMMAND [ARGS]...
Command line interface for archeo
Options:
--help Show this message and exit.
Commands:
generate-preset-prior Generate a preset prior.
visualize-prior Visualize the prior distribution.
```
In the following,
we will introduce the available commands in the CLI.
### Generate a Preset Prior with CLI
We provide a command to generate preset priors, which can be used for further analysis.
```
> python -m archeo generate-preset-prior --help
Usage: python -m archeo generate-preset-prior [OPTIONS]
Generate a preset prior.
Options:
-n, --name TEXT Preset prior name, available values are default,
agnostic_precessing_spin, agnostic_aligned_spin,
precessing_spin, aligned_spin,
positively_aligned_spin.
-o, --output-dir TEXT Directory to save the generated prior configuration.
--help Show this message and exit.
```
Here is an example of how to generate a preset prior using the CLI:
```bash
python -m archeo generate-preset-prior
```
This command will generate the default prior configuration and save it in the current directory.
Note that the default prior is an aligned spin prior with only 1000 samples.
So we expect it to be fast to generate (within 1 minute).
To generate other priors, you can specify the `--name` option with one of the available values.
For example,
```bash
python -m archeo generate-preset-prior --name agnostic_precessing_spin
```
### Visualize the Prior Distribution with CLI
We provide a command to visualize the generated ancestral prior distribution.
```
> python -m archeo visualize-prior --help
Usage: python -m archeo visualize-prior [OPTIONS]
Visualize the prior distribution.
Options:
-f, --filepath TEXT Path to the prior data. [required]
-o, --output-dir TEXT Directory to save the visualization output.
--help Show this message and exit.
```
Here is an example of how to visualize the prior distribution using the CLI:
```bash
python -m archeo visualize-prior --filepath ./prior.parquet
```
This command will read the prior data from `prior.parquet` and save the visualization output in the current directory.
Note that the visualizations include:
- Animation of how distributions (various parameters) change over kick magnitude constraint.
- 2D histogram of the mass-spin distribution.
- Kick distribution for each spin-bin (binwidth=0.1).
## Ancestral Parameter Estimation
The following example demonstrates how to use the package to visualize the prior and posterior distributions of a single event.
```python
import archeo
# Load the mass/spin samples from a file (usually PE results from LVK)
# They are expected to be a list of floats
mass_posterior = [68.0, 71.4, ..., 91.4]
spin_posterior = [0.31, 0.54, ..., 0.64]
# Create a prior
prior = archeo.Prior.from_config("precessing_spin")
# Create a posterior from the samples and the prior
posterior = prior.to_posterior(mass_posterior, spin_posterior)
# Visualize the prior and the posterior
archeo.visualize_prior_distribution(prior, output_dir="./")
archeo.visualize_posterior_estimation({"GW190521": posterior}, output_dir="./")
```
## Available Preset Priors
This table provides an overview of the different prior configurations available in archeo.
| Name | Samples | Fits Model | Spin Aligned | Only Up-Aligned Spin | $\chi_1$ | $\chi_2$ | $\phi_1$ [rad] | $\phi_2$ [rad] | $\theta_1$ [rad] | $\theta_2$ [rad] | $m_1 [M_\odot]$ | $m_2 [M_\odot]$ | $q$ | Uniform in $q$ |
|------------------------------------|-----------|------------------|----|-----|-------|-------|------------|------------|-----------|-----------|---------|---------|-------|-----|
| agnostic_precessing_spin (default) | 2,000,000 | NRSur7dq4Remnant | ❌ | ❌ | 0 - 1 | 0 - 1 | 0 - $2\pi$ | 0 - $2\pi$ | 0 - $\pi$ | 0 - $\pi$ | 5 - 200 | 5 - 200 | 1 - 6 | ❌ |
| agnostic_aligned_spin | 2,000,000 | NRSur3dq8Remnant | ✅ | ❌ | 0 - 1 | 0 - 1 | 0 - $2\pi$ | 0 - $2\pi$ | 0 - $\pi$ | 0 - $\pi$ | 5 - 200 | 5 - 200 | 1 - 6 | ❌ |
| precessing_spin | 2,000,000 | NRSur7dq4Remnant | ❌ | ❌ | 0 - 1 | 0 - 1 | 0 - $2\pi$ | 0 - $2\pi$ | 0 - $\pi$ | 0 - $\pi$ | 5 - 65 | 5 - 65 | 1 - 6 | ❌ |
| aligned_spin | 2,000,000 | NRSur3dq8Remnant | ✅ | ❌ | 0 - 1 | 0 - 1 | 0 - $2\pi$ | 0 - $2\pi$ | 0 - $\pi$ | 0 - $\pi$ | 5 - 65 | 5 - 65 | 1 - 6 | ❌ |
| positively_aligned_spin | 2,000,000 | NRSur3dq8Remnant | ✅ | ✅ | 0 - 1 | 0 - 1 | 0 - $2\pi$ | 0 - $2\pi$ | 0 - $\pi$ | 0 - $\pi$ | 5 - 65 | 5 - 65 | 1 - 6 | ❌ |
## Configure your own prior
Check out the preset priors in [quick.py](https://github.com/wyhwong/archeo/blob/main/src/archeo/preset/quick.py). From that, one should be able to create their own prior by following the same structure.
## Try our UI
Archeo also provides a simple web-based user interface to visualize the distributions of remnant properties.
To run the UI locally, simply run the following command:
```bash
pip3 install archeo[ui]
python3 -m archeo.ui
```
Then the UI will be available at [localhost:8501](http://localhost:8501).
You may also try our [demo version](https://archeo.streamlit.app/) online, which is hosted on Streamlit Community Cloud.
## Getting Help
The code is maintained by [Henry Wong](https://github.com/wyhwong) under [Juan Calderon Bustillo](https://git.ligo.org/juan.calderonbustillo)'s supervision. You can find the [list of contributors](https://github.com/wyhwong/archeo/graphs/contributors) here. Please report bugs by raising an issue on our [GitHub](https://github.com/wyhwong/archeo) repository.
## License
Archeo has a MIT License - see the [LICENSE](https://github.com/wyhwong/archeo/blob/main/LICENSE).
Raw data
{
"_id": null,
"home_page": "https://pypi.org/project/archeo/",
"name": "archeo",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": "black-holes, gravitational-waves, black-hole-archeology",
"author": "wyhwong",
"author_email": "wyhwong@link.cuhk.edu.hk",
"download_url": "https://files.pythonhosted.org/packages/29/8f/d7aa7d7a123145fe45b8414c403704c5919a80bc17d29669ed50019d88e6/archeo-1.6.12.tar.gz",
"platform": null,
"description": "# ARCHEO\n[](https://github.com/wyhwong/archeo)\n[](https://pypi.org/project/archeo/)\n[](https://doi.org/10.5281/zenodo.14306853)\n[](https://github.com/wyhwong/archeo)\n[](https://pypi.org/project/archeo/)\n[](https://github.com/wyhwong/archeo/blob/main/LICENSE)\n[](https://github.com/wyhwong/archeo/actions/workflows/main.yml/)\n\nArcheo is a Python package designed to infer the natal kick, ancestral masses, and spins of black holes in the Pair-instability Supernova (PISN) gap,\nwith a particular focus on hierarchical black hole formation.\n\n## Basic Usage with Command Line Interface (CLI)\n\nWe provide a command line interface (CLI) for archeo, which allows users to generate preset priors and visualize prior distributions easily.\n\n```\n> python -m archeo --help\n\nUsage: python -m archeo [OPTIONS] COMMAND [ARGS]...\n\n Command line interface for archeo\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n generate-preset-prior Generate a preset prior.\n visualize-prior Visualize the prior distribution.\n```\n\nIn the following,\nwe will introduce the available commands in the CLI.\n\n### Generate a Preset Prior with CLI\n\nWe provide a command to generate preset priors, which can be used for further analysis.\n\n```\n> python -m archeo generate-preset-prior --help\nUsage: python -m archeo generate-preset-prior [OPTIONS]\n\n Generate a preset prior.\n\nOptions:\n -n, --name TEXT Preset prior name, available values are default,\n agnostic_precessing_spin, agnostic_aligned_spin,\n precessing_spin, aligned_spin,\n positively_aligned_spin.\n -o, --output-dir TEXT Directory to save the generated prior configuration.\n --help Show this message and exit.\n```\n\nHere is an example of how to generate a preset prior using the CLI:\n\n```bash\npython -m archeo generate-preset-prior\n```\n\nThis command will generate the default prior configuration and save it in the current directory.\nNote that the default prior is an aligned spin prior with only 1000 samples.\nSo we expect it to be fast to generate (within 1 minute).\nTo generate other priors, you can specify the `--name` option with one of the available values.\nFor example,\n\n```bash\npython -m archeo generate-preset-prior --name agnostic_precessing_spin\n```\n\n### Visualize the Prior Distribution with CLI\n\nWe provide a command to visualize the generated ancestral prior distribution.\n\n```\n> python -m archeo visualize-prior --help\nUsage: python -m archeo visualize-prior [OPTIONS]\n\n Visualize the prior distribution.\n\nOptions:\n -f, --filepath TEXT Path to the prior data. [required]\n -o, --output-dir TEXT Directory to save the visualization output.\n --help Show this message and exit.\n```\n\nHere is an example of how to visualize the prior distribution using the CLI:\n\n```bash\npython -m archeo visualize-prior --filepath ./prior.parquet\n```\n\nThis command will read the prior data from `prior.parquet` and save the visualization output in the current directory.\nNote that the visualizations include:\n- Animation of how distributions (various parameters) change over kick magnitude constraint.\n- 2D histogram of the mass-spin distribution.\n- Kick distribution for each spin-bin (binwidth=0.1).\n\n## Ancestral Parameter Estimation\n\nThe following example demonstrates how to use the package to visualize the prior and posterior distributions of a single event.\n\n```python\nimport archeo\n\n# Load the mass/spin samples from a file (usually PE results from LVK)\n# They are expected to be a list of floats\nmass_posterior = [68.0, 71.4, ..., 91.4]\nspin_posterior = [0.31, 0.54, ..., 0.64]\n\n# Create a prior\nprior = archeo.Prior.from_config(\"precessing_spin\")\n# Create a posterior from the samples and the prior\nposterior = prior.to_posterior(mass_posterior, spin_posterior)\n\n# Visualize the prior and the posterior\narcheo.visualize_prior_distribution(prior, output_dir=\"./\")\narcheo.visualize_posterior_estimation({\"GW190521\": posterior}, output_dir=\"./\")\n```\n\n## Available Preset Priors\n\nThis table provides an overview of the different prior configurations available in archeo.\n\n| Name | Samples | Fits Model | Spin Aligned | Only Up-Aligned Spin | $\\chi_1$ | $\\chi_2$ | $\\phi_1$ [rad] | $\\phi_2$ [rad] | $\\theta_1$ [rad] | $\\theta_2$ [rad] | $m_1 [M_\\odot]$ | $m_2 [M_\\odot]$ | $q$ | Uniform in $q$ |\n|------------------------------------|-----------|------------------|----|-----|-------|-------|------------|------------|-----------|-----------|---------|---------|-------|-----|\n| agnostic_precessing_spin (default) | 2,000,000 | NRSur7dq4Remnant | \u274c | \u274c | 0 - 1 | 0 - 1 | 0 - $2\\pi$ | 0 - $2\\pi$ | 0 - $\\pi$ | 0 - $\\pi$ | 5 - 200 | 5 - 200 | 1 - 6 | \u274c |\n| agnostic_aligned_spin | 2,000,000 | NRSur3dq8Remnant | \u2705 | \u274c | 0 - 1 | 0 - 1 | 0 - $2\\pi$ | 0 - $2\\pi$ | 0 - $\\pi$ | 0 - $\\pi$ | 5 - 200 | 5 - 200 | 1 - 6 | \u274c |\n| precessing_spin | 2,000,000 | NRSur7dq4Remnant | \u274c | \u274c | 0 - 1 | 0 - 1 | 0 - $2\\pi$ | 0 - $2\\pi$ | 0 - $\\pi$ | 0 - $\\pi$ | 5 - 65 | 5 - 65 | 1 - 6 | \u274c |\n| aligned_spin | 2,000,000 | NRSur3dq8Remnant | \u2705 | \u274c | 0 - 1 | 0 - 1 | 0 - $2\\pi$ | 0 - $2\\pi$ | 0 - $\\pi$ | 0 - $\\pi$ | 5 - 65 | 5 - 65 | 1 - 6 | \u274c |\n| positively_aligned_spin | 2,000,000 | NRSur3dq8Remnant | \u2705 | \u2705 | 0 - 1 | 0 - 1 | 0 - $2\\pi$ | 0 - $2\\pi$ | 0 - $\\pi$ | 0 - $\\pi$ | 5 - 65 | 5 - 65 | 1 - 6 | \u274c |\n\n## Configure your own prior\n\nCheck out the preset priors in [quick.py](https://github.com/wyhwong/archeo/blob/main/src/archeo/preset/quick.py). From that, one should be able to create their own prior by following the same structure.\n\n## Try our UI\n\nArcheo also provides a simple web-based user interface to visualize the distributions of remnant properties.\nTo run the UI locally, simply run the following command:\n\n```bash\npip3 install archeo[ui]\npython3 -m archeo.ui\n```\n\nThen the UI will be available at [localhost:8501](http://localhost:8501).\n\nYou may also try our [demo version](https://archeo.streamlit.app/) online, which is hosted on Streamlit Community Cloud.\n\n## Getting Help\n\nThe code is maintained by [Henry Wong](https://github.com/wyhwong) under [Juan Calderon Bustillo](https://git.ligo.org/juan.calderonbustillo)'s supervision. You can find the [list of contributors](https://github.com/wyhwong/archeo/graphs/contributors) here. Please report bugs by raising an issue on our [GitHub](https://github.com/wyhwong/archeo) repository.\n\n## License\n\nArcheo has a MIT License - see the [LICENSE](https://github.com/wyhwong/archeo/blob/main/LICENSE).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Bayesian framework for inferring natal kick, ancestral masses and spins of black holes.",
"version": "1.6.12",
"project_urls": {
"Homepage": "https://pypi.org/project/archeo/",
"Repository": "https://github.com/wyhwong/archeo"
},
"split_keywords": [
"black-holes",
" gravitational-waves",
" black-hole-archeology"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "32db2d9240c65b081e38c2c6e9476d39b650c4c6fc4bfbfb9bfc13d72584cc1e",
"md5": "9a3eacb4d2e067223d648134b047ff77",
"sha256": "f85be30e79f35531a2f6d9504a5eb9478e0f83d36e90d10881a23bbc0c308eae"
},
"downloads": -1,
"filename": "archeo-1.6.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9a3eacb4d2e067223d648134b047ff77",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 36336,
"upload_time": "2025-08-03T16:54:29",
"upload_time_iso_8601": "2025-08-03T16:54:29.389143Z",
"url": "https://files.pythonhosted.org/packages/32/db/2d9240c65b081e38c2c6e9476d39b650c4c6fc4bfbfb9bfc13d72584cc1e/archeo-1.6.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "298fd7aa7d7a123145fe45b8414c403704c5919a80bc17d29669ed50019d88e6",
"md5": "a5e542325fd49371bf8307738e1f2019",
"sha256": "72cc1f608c5773212dd1b0982df6c96552641a5e4ec5a5ba7bfada5c01cd61d3"
},
"downloads": -1,
"filename": "archeo-1.6.12.tar.gz",
"has_sig": false,
"md5_digest": "a5e542325fd49371bf8307738e1f2019",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 27386,
"upload_time": "2025-08-03T16:54:30",
"upload_time_iso_8601": "2025-08-03T16:54:30.668437Z",
"url": "https://files.pythonhosted.org/packages/29/8f/d7aa7d7a123145fe45b8414c403704c5919a80bc17d29669ed50019d88e6/archeo-1.6.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-03 16:54:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wyhwong",
"github_project": "archeo",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "archeo"
}
JSON
