# 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
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 [precessing.py](https://github.com/wyhwong/archeo/blob/main/src/archeo/preset/precessing.py) and [aligned.py](https://github.com/wyhwong/archeo/blob/main/src/archeo/preset/aligned.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).
## 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/39/16/9d27435f9521575912790c29b8e3de6c9617dc067ad52ac0ce83ccb49f8a/archeo-1.6.5.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\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 [precessing.py](https://github.com/wyhwong/archeo/blob/main/src/archeo/preset/precessing.py) and [aligned.py](https://github.com/wyhwong/archeo/blob/main/src/archeo/preset/aligned.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\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.5",
"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": "b8a46afef7c7d9c8b0d588f2bc65b729993d48377f19c4b458c6c01d68c8a111",
"md5": "f93e4f012336f077f33dcc1f050958ad",
"sha256": "2c5896ef215d1a88c8e89ed4c4e604b40651e62f265f17c126d627b02b6f8fac"
},
"downloads": -1,
"filename": "archeo-1.6.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f93e4f012336f077f33dcc1f050958ad",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 33577,
"upload_time": "2025-07-09T13:51:56",
"upload_time_iso_8601": "2025-07-09T13:51:56.153043Z",
"url": "https://files.pythonhosted.org/packages/b8/a4/6afef7c7d9c8b0d588f2bc65b729993d48377f19c4b458c6c01d68c8a111/archeo-1.6.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "39169d27435f9521575912790c29b8e3de6c9617dc067ad52ac0ce83ccb49f8a",
"md5": "364aa017d7ef113a015b44138fb87f60",
"sha256": "aef793ad5ff7fff1473b12eee030593a475006499adb7725e2991e875eb52193"
},
"downloads": -1,
"filename": "archeo-1.6.5.tar.gz",
"has_sig": false,
"md5_digest": "364aa017d7ef113a015b44138fb87f60",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 23821,
"upload_time": "2025-07-09T13:51:57",
"upload_time_iso_8601": "2025-07-09T13:51:57.443089Z",
"url": "https://files.pythonhosted.org/packages/39/16/9d27435f9521575912790c29b8e3de6c9617dc067ad52ac0ce83ccb49f8a/archeo-1.6.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-09 13:51:57",
"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
