Metadata-Version: 2.4
Name: fastropop
Version: 0.1.0
Summary: Fast JAX-first astrophysical population generation.
Project-URL: Homepage, https://github.com/jonaselgammal/fastropop
Project-URL: Documentation, https://fastropop.readthedocs.io/
Project-URL: Repository, https://github.com/jonaselgammal/fastropop
Project-URL: Issues, https://github.com/jonaselgammal/fastropop/issues
Author: Chiara Cecchini, Gabriele Franciolini, Mauro Pieroni
Author-email: Jonas El Gammal <jonas.el.gammal@rwth-aachen.de>
License: MIT
License-File: LICENSE
Keywords: astrophysics,gravitational-waves,jax,populations,pta
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Requires-Dist: jax>=0.4.30
Requires-Dist: jaxlib>=0.4.30
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.13
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
Provides-Extra: examples
Requires-Dist: healpy>=1.17; extra == 'examples'
Requires-Dist: jax-healpy>=0.6; extra == 'examples'
Requires-Dist: matplotlib>=3.9; extra == 'examples'
Provides-Extra: viz
Requires-Dist: healpy>=1.17; extra == 'viz'
Requires-Dist: jax-healpy>=0.6; extra == 'viz'
Requires-Dist: matplotlib>=3.9; extra == 'viz'
Description-Content-Type: text/markdown

# fastropop

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/img/fastropop-logo-transparent-dark.png">
    <img src="docs/img/fastropop-logo-transparent-light.png" alt="fastropop logo" width="880">
  </picture>
</p>

`fastropop` is the package that generates your SMBHB populations at lightning speed. It is designed to be a fast, flexible, and user-friendly tool for simulating the cosmic population of supermassive black hole binaries (SMBHBs) and their gravitational wave signatures in the nanohertz regime.

The package is centered on the semi analytic population from [arXiv:0804.4476](https://arxiv.org/abs/0804.4476), which is implemented in the `SemiAnalyticPopulation` class. It also includes a suite of utilities for computing characteristic-strain quantities, sampling population realizations, binning into PTA-style spectra

Documentation: [fastropop.readthedocs.io](https://fastropop.readthedocs.io/)

This repository is maintained by Jonas El Gammal and reflects scientific work carried out with Chiara Cecchini, Gabriele Franciolini, and Mauro Pieroni. The package was used for the analysis in [arXiv:2605.05157](https://arxiv.org/abs/2605.05157), but of course you can use it for whatever you want!

## What It Does

- defines a semi-analytic SMBHB population model
- computes characteristic-strain quantities and expected binary counts
- samples population realizations with JAX-backed randomness
- bins sampled realizations into PTA-style spectra
- generates HEALPix skymaps with either `jax-healpy` or `healpy`

## Installation

```bash
git clone git@github.com:jonaselgammal/fastropop.git
cd fastropop
pip install -e .
```

Notes:
- `jax` and `jaxlib` are core dependencies
- skymap generation requires a HEALPix backend
- `jax-healpy` is preferred when installed
- standard `healpy` is supported as a fallback backend

## Quick Start

```python
import fastropop

pop = fastropop.SemiAnalyticPopulation()

distM, distz, distlog10f = pop.sample_dist(Nbinaries=1000, key=0)
spec = fastropop.binning(distM, distz, distlog10f, do_plot=False)
```

For reproducible stochastic methods, pass a JAX key or integer seed:

```python
params = fastropop.draw_parameters(key=0)
Nbinaries = pop.generate_poisson_realization(1, key=1)
```

If `key=None`, the package creates a fresh nondeterministic JAX key internally.

## Notebooks

The main examples currently live in:
- `examples/semi-analytic.ipynb`
- `examples/population-spectra.ipynb`
- `examples/skymaps.ipynb`

## Repository Layout

```text
src/fastropop/        Package source
tests/                Unit and regression tests
examples/             Example scripts and notebooks
.github/workflows/    CI and release automation
```
