Skip to content

gwmock-pop

Python CI pre-commit.ci status Documentation Status codecov PyPI Version Python Versions License Ruff DOI SPEC 0 — Minimum Supported Dependencies

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

Current package surface

  • Protocols: GWPopSimulator (population simulators), ExternalPopulationLoader (catalogue loaders).
  • Graph-driven sampling: GraphSimulator from a YAML/TOML parameters graph (packaged presets via list_presets() / GraphSimulator.from_preset).
  • Graph-backed CBC simulators: CBCSimulator, BBHSimulator, BNSSimulator, and NSBHSimulator — configurable priors built on the graph engine; override any parameter's distribution via the parameters= argument.
  • Composition: MixtureSimulator, PoissonEventSampler (event-count helper used in mixture workflows).
  • Catalogues: FilePopulationLoader and read_population_catalogue / write_population_catalogue for CSV and HDF5 (structured or group-of-datasets layouts), including remote URL loading with local caching and CBC canonicalization in the loader.
  • Quality checks: validate_sample for arrays returned by simulators.

Public re-exports live in gwmock_pop.__all__; full module reference is in the API docs.

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 git@github.com: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 prek install

Docs setup:

uv sync --group docs
uv run zensical serve

Getting started (CLI)

The gwmock-pop CLI uses Typer. Typical flow: pick a packaged preset or a graph config file, set the sample count, and write a CSV or HDF5 catalogue.

# Packaged preset (see `gwmock-pop list` for names)
gwmock-pop simulate --config gwtc4 --n 1000 --output population.csv --seed 42

# Or a graph YAML/TOML (top-level `parameters:` as in `examples/gwtc4/bbh_population.yaml`)
gwmock-pop simulate --config examples/gwtc4/bbh_population.yaml --n 500 --output out.h5

Other commands:

Command Purpose
gwmock-pop convert Convert population files between CSV and HDF5; optional --column-map JSON/YAML
gwmock-pop validate Check a graph config without sampling
gwmock-pop inspect Summary statistics for a population file
gwmock-pop list List presets and public simulator classes 
gwmock-pop --help
gwmock-pop simulate --help

Getting started (library)

from gwmock_pop import CBCSimulator

sim = CBCSimulator(seed=42)
population = sim.simulate(100)
assert population["detector_frame_mass_1"].shape == (100,)

Use GraphSimulator.from_config_file(...) or GraphSimulator.from_preset(...) for full graph configs (see examples/ and gwmock_pop.simulators.graph).

FilePopulationLoader also accepts http://, https://, s3://, and zenodo://<record>/<file> sources. Remote catalogues are cached under ${GWMOCK_POP_CACHE_DIR} or ${XDG_CACHE_HOME:-~/.cache}/gwmock-pop, and CBC catalogues are validated and rewritten to canonical gwmock-pop parameter names before sampling.

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 tests explicitly:

uv run pytest -m integration

Documentation

License

BSD 3-Clause, see LICENSE.