gwmock-signal
A Python package for simulating gravitational wave signals.
Installation
We recommend using uv to manage virtual environments for installing
gwmock-signal.
If you don't have uv installed, you can install it with pip. See the project
pages for more details:
- Install via pip:
pip install --upgrade pip && pip install uv - Project pages: uv on PyPI | uv on GitHub
- Full documentation and usage guide: uv docs
Requirements
- Python 3.13-3.15 (We adopt the SPEC 0 policy for the Python support version)
- Operating System: Linux, or macOS
Note: The package is built and tested against Python 3.13-3.15
(requires-python is >=3.13). When creating a virtual environment with uv,
pin a supported interpreter, for example uv venv --python 3.13, so you do not
accidentally pick an unsupported version.
Install from PyPI
The recommended way to install gwmock-signal is from PyPI:
# Create a virtual environment (recommended with uv)
uv venv --python 3.13
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv pip install gwmock-signal
PyPI install scope
The PyPI wheel includes runtime dependencies only (see dependencies in
pyproject.toml). The published optional extras are gwmock-signal[pycbc] (the
PyCBC waveform backend) and gwmock-signal[jax] (the JAX/ripple waveform
backend and batched GPU simulation); development and documentation dependencies
remain uv dependency groups used when you work from a git clone (see
Development installation below).
Install from Source
For the latest development version:
git clone git@github.com:Leuven-Gravity-Institute/gwmock-signal.git
cd gwmock-signal
# Create a virtual environment (recommended with uv)
uv venv --python 3.13
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv sync
Development installation
To set up for development (tests, linters, pre-commit):
git clone git@github.com:Leuven-Gravity-Institute/gwmock-signal.git
cd gwmock-signal
# Create a virtual environment (recommended with uv)
uv venv --python 3.13
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv sync --group dev
# Install pre-commit hooks
uv run prek install
To build or serve the documentation site locally:
uv sync --group docs
uv run zensical serve
# or: uv run zensical build → static site under site/
Verify Installation
Check that the CLI and import path work (console script gwmock-signal,
Python package gwmock_signal):
gwmock-signal --help
gwmock-signal inject --help
python -c "import gwmock_signal; print(gwmock_signal.__version__)"
Backends
lal(default): ships with the core install vialalsuiteand supports the built-in CBC pipeline without installingpycbc.lalsuiteis not installed on Python 3.15 and later, which it publishes no wheel for yet.gwsignal: also ships with the core install — routes frequency-domain-native approximants through the LVK's forward-lookinglalsimulation.gwsignalinterface (GWSignalBackend) while sharing the LAL backend's conditioning, so outputs are bit-identical tolal; time-domain-native approximants fall back to the LAL path.pycbc(optional): install withpip install 'gwmock-signal[pycbc]'to usePyCBCBackend.ripple(optional): install withpip install 'gwmock-signal[jax]'to use the JAX/ripple backend (RippleBackend). Beyond the CLI/CPU path, it enables batched, on-device (GPU) catalogue simulation that assembles signals into fixed-duration data segments — see Batched GPU simulation. Its agreement with the LAL baseline and its speed across backends/hardware are tracked on the gwmock-benchmark site (Consistency, Performance).
Python API:
from gwmock_signal import CBCSimulator, LALSimulationBackend
sim = CBCSimulator("IMRPhenomD", waveform_backend=LALSimulationBackend())
# For a complete end-to-end example, see the
# Quick Start in the user guide:
# https://leuven-gravity-institute.github.io/gwmock-signal/user_guide/quick_start/
CLI:
gwmock-signal inject cbc --params examples/gw150914_like.json --network H1L1V1 --backend lal
# Same injection with the JAX/ripple backend (install with gwmock-signal[jax])
gwmock-signal inject cbc --params examples/gw150914_like.json --network H1L1V1 --backend ripple
Ready-to-run parameter files live in examples/.
Documentation
- Site: gwmock-signal documentation
- User guide: overview, Command-line interface (
inject cbc, JSON parameters,--network), Custom backends, and Examples (library walkthroughs) - API reference: signatures, types, and exceptions (mkdocstrings)
- Benchmarks: performance and ripple-vs-LAL consistency live on the
gwmock-benchmark
site — see
Performance
and
Consistency.
The underlying records are also published as a static JSON
Data API
(
.../data/v1/records.json) for programmatic retrieval
Public source-type backend lookup
gwmock-signal exposes a small public registry so downstream packages can
resolve the signal backend from a gwmock-pop source_type string instead of
hardcoding a concrete simulator class:
from gwmock_signal import resolve_simulator_backend
backend_cls = resolve_simulator_backend("bbh")
simulator = backend_cls(waveform_model="IMRPhenomD")
The built-in compact-binary backend is registered under bbh. Future source
families keep the same downstream lookup contract by registering a new
GWSimulator subclass inside gwmock-signal with
register_simulator_backend(source_type, backend_cls).
The stable backend boundary is
GWSimulator.simulate(...) -> DetectorStrainStack. For a minimal non-transient
backend example, see
User guide → Custom backends.
Build locally: uv sync --group docs && uv run zensical serve (or
uv run zensical build for static output in site/).
Contributing
Contributions are welcome!
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests
- Submit a pull request
Release Schedule
Releases follow a fixed schedule: every Tuesday at 00:00 UTC, unless an emergent bugfix is required. This ensures predictable updates while allowing flexibility for critical issues. Users can view upcoming changes in the draft release on the GitHub Releases page.
Testing
From a repository checkout with dev dependencies installed
(uv sync --group dev):
uv run pytest
License
This project is licensed under GPL-3.0-or-later. See the LICENSE file for the full license text.
gwmock-signal is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
gwmock-signal is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with gwmock-signal. If not, see https://www.gnu.org/licenses/.
Downstream dependency note
gwmock-signal should be treated as a GPL-3.0-or-later dependency by any
downstream package that distributes it, including gwmock. In practice, that
means gwmock may depend on gwmock-signal only if the resulting downstream
distribution is compatible with GPL-3.0-or-later.
Support
For questions or issues, please open an issue on GitHub or contact the maintainers.
2 maintainers
Metadata
2 maintainers
Release files for gwmock-signal 0.18.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| gwmock_signal-0.18.0.tar.gz | 588.1 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| gwmock_signal-0.18.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 787.4 kB
Release files / gwmock_signal-0.18.0.tar.gz
| Download URL | gwmock_signal-0.18.0.tar.gz |
|---|---|
| Size | 588.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5837f44c361b51f2da3f3f9c158f19fad23e5b8b2055aabe94688fb48d88432d
|
|
BLAKE2b-256 checksum How to use checksums |
8f786cf120479264ca0e7b02bbaecd783d534376b667a80fe084ab9f4fc76166
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / gwmock_signal-0.18.0-py3-none-any.whl
| Download URL | gwmock_signal-0.18.0-py3-none-any.whl |
|---|---|
| Size | 199.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cde71d789736573fc23f3d6ea255b7ab60a3a1b35a5d1a1285b17d95dbba47ad
|
|
BLAKE2b-256 checksum How to use checksums |
6d1067625443571207ed8357f2c119f0550a065ab6d08eac1a4aa64826511153
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for gwmock-signal 0.18.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
