gwmock-pop

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

Floating-point precision

Importing gwmock_pop enables 64-bit JAX floats (jax_enable_x64). GPS-scale parameters such as coa_time (~1.6 × 10⁹ s) are unusable in JAX's 32-bit default, where the float32 spacing at that magnitude is 128 s. The flag is global JAX state, so it also affects arrays your own code creates after the import. To keep JAX's 32-bit default (e.g. for GPU-throughput studies that do not sample absolute times), set GWMOCK_POP_DISABLE_X64=1 in the environment before importing the package.

The flag is requested by setting JAX_ENABLE_X64=1 in os.environ, so that importing gwmock_pop does not have to import JAX (see below). Two consequences worth knowing: child processes started afterwards inherit the same precision, and GWMOCK_POP_DISABLE_X64 takes precedence over JAX_ENABLE_X64 whoever set it. Call jax.config.update("jax_enable_x64", True) yourself if you want 64-bit floats while opting out of this package's default.

Import cost

Importing gwmock_pop does not import JAX. The samplers, distributions and transforms are JAX code and import it when they are loaded, but reading a population catalogue, resolving a configuration or running gwmock-pop --help does not reach them — and so does not pay for JAX's import (about 240 ms) or start XLA's thread pools, which is also what keeps such a process safe to fork().

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:

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).

Sample from a packaged preset (run gwmock-pop list or list_presets() for the available names):

from gwmock_pop import GraphSimulator, list_presets

print(list_presets())                 # e.g. ["gwtc4", ...]
sim = GraphSimulator.from_preset("gwtc4")
catalogue = sim.simulate(1000)

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

• Site: https://leuven-gravity-institute.github.io/gwmock-pop/
• API index (tables + navigation): docs/api/index.md
• User guide: docs/user_guide/installation.md, docs/user_guide/quick_start.md

License

BSD 3-Clause, see LICENSE.