gwmock-pop 0.5.0

A python package for simulating populations of gravitational-wave sources.

gwmock-pop

gwmock-pop is a Python package for simulating populations of gravitational-wave sources.

Current Package Surface

• Protocol-first simulator interface via GWPopSimulator:
  • source_type: str (non-empty routing key)
  • simulate(n_samples, **kwargs) -> Mapping[str, jax.Array]
  • each returned parameter array is 1-D with length n_samples
• Core simulator implementations:
  • GraphSimulator (config-driven dependency graph)
  • CBCPriorSimulator (lightweight analytic CBC priors)
• External catalogue loader:
  • FilePopulationLoader for CSV/HDF5
  • supports structured HDF5 datasets and group-of-datasets layouts

Requirements

• Python >=3.12 (tested on 3.12-3.14)
• Linux, macOS, or Windows

Installation

Install from PyPI:

uv venv --python 3.12
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv pip install gwmock-pop

Install from source:

git clone [e-mail]:Leuven-Gravity-Institute/gwmock-pop.git
cd gwmock-pop
uv venv --python 3.12
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv sync --no-dev

Developer setup:

uv sync --group dev
uv run pre-commit install

Docs setup:

uv sync --group docs
uv run zensical serve

Quick Start (CLI)

Create population.yaml:

run:
    name: demo_population
    mode: fixed_n_samples
    n_samples: 100
    seed: 42
    output:
        directory: outputs
        format: csv
        overwrite: true

parameters:
    mass_1:
        sampler:
            function: gwmock_pop.samplers.planck_tapered_broken_power_law_plus_two_peaks
            arguments:
                alpha_1: 1.72
                alpha_2: 4.51
                transition: 35.6
                minimum: 5.06
                maximum: 300.0
                mean_1: 9.76
                sigma_1: 0.649
                mean_2: 32.8
                sigma_2: 3.92
                taper_range: 4.32
                lambda_0: 0.361
                lambda_1: 0.586

Run:

gwmock-pop simulate population.yaml

Verification

gwmock-pop --help
python -c "import gwmock_pop; print(gwmock_pop.__version__)"

Testing

Default test run excludes integration-marked tests:

uv run pytest

Run integration/smoke tests explicitly:

uv run pytest -m integration

Documentation

• Docs home: https://leuven-gravity-institute.github.io/gwmock-pop/
• API reference: docs/api/index.md

License

BSD 3-Clause, see LICENSE.