Metadata-Version: 2.4
Name: gwmock-signal
Version: 0.6.3
Summary: A Python package for simulating gravitational wave signals
Project-URL: Documentation, https://leuven-gravity-institute.github.io/gwmock-signal
Project-URL: Source, https://github.com/Leuven-Gravity-Institute/gwmock-signal
Project-URL: Tracker, https://github.com/Leuven-Gravity-Institute/gwmock-signal/issues
Project-URL: Home, https://github.com/Leuven-Gravity-Institute/gwmock-signal
Project-URL: Release Notes, https://github.com/Leuven-Gravity-Institute/gwmock-signal/releases
Author: Isaac C. F. Wong
License: GPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: <3.14,>=3.12
Requires-Dist: gwpy>=4.0.1
Requires-Dist: lalsuite>=7.26.11
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: typer>=0.25.1
Provides-Extra: pycbc
Requires-Dist: pycbc>=2.11.0; extra == 'pycbc'
Description-Content-Type: text/markdown

# gwmock-signal

[![Python CI](https://github.com/Leuven-Gravity-Institute/gwmock-signal/actions/workflows/ci.yml/badge.svg)](https://github.com/Leuven-Gravity-Institute/gwmock-signal/actions/workflows/ci.yml)
[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/Leuven-Gravity-Institute/gwmock-signal/main.svg)](https://results.pre-commit.ci/latest/github/Leuven-Gravity-Institute/gwmock-signal/main)
[![Documentation Status](https://github.com/Leuven-Gravity-Institute/gwmock-signal/actions/workflows/documentation.yml/badge.svg)](https://leuven-gravity-institute.github.io/gwmock-signal/)
[![codecov](https://codecov.io/gh/Leuven-Gravity-Institute/gwmock-signal/graph/badge.svg?token=COF8341N60)](https://codecov.io/gh/Leuven-Gravity-Institute/gwmock-signal)
[![PyPI Version](https://img.shields.io/pypi/v/gwmock-signal)](https://pypi.org/project/gwmock-signal/)
[![Python Versions](https://img.shields.io/pypi/pyversions/gwmock-signal)](https://pypi.org/project/gwmock-signal/)
[![License: GPL-3.0-or-later](https://img.shields.io/badge/License-GPL--3.0--or--later-blue.svg)](LICENSE)
[![Security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
[![DOI](https://zenodo.org/badge/1180014442.svg)](https://doi.org/10.5281/zenodo.19202406)
[![SPEC 0 — Minimum Supported Dependencies](https://img.shields.io/badge/SPEC-0-green?labelColor=%23004811&color=%235CA038)](https://scientific-python.org/specs/spec-0000/)

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](https://pypi.org/project/uv/) |
  [uv on GitHub](https://github.com/astral-sh/uv)
- Full documentation and usage guide: [uv docs](https://docs.astral.sh/uv/)

### Requirements

- Python 3.12-3.13 (We adopt the SPEC 0 policy for the Python support version)
- We do not support Python 3.14 because `lalsuite` does not have a wheel for
  Python 3.14 yet ([#825](https://git.ligo.org/lscsoft/lalsuite/-/issues/825))
- Operating System: Linux, or macOS

**Note:** The package is built and tested against **Python 3.12 and 3.13**
(`requires-python` is `>=3.12,<3.14`). When creating a virtual environment with
`uv`, pin a supported interpreter, for example `uv venv --python 3.12`, so you
do not accidentally pick an unsupported version.

### Install from PyPI

The recommended way to install `gwmock-signal` is from PyPI:

```bash
# Create a virtual environment (recommended with uv)
uv venv --python 3.12
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 only published optional extra is `gwmock-signal[pycbc]`;
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:

```bash
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.12
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv sync
```

#### Development installation

To set up for development (tests, linters, pre-commit):

```bash
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.12
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:

```bash
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`**):

```bash
gwmock-signal --help
gwmock-signal inject --help
```

```bash
python -c "import gwmock_signal; print(gwmock_signal.__version__)"
```

## Backends

- `lal` (default): ships with the core install via `lalsuite` and supports the
  built-in CBC pipeline without installing `pycbc`.
- `pycbc` (optional): install with `pip install 'gwmock-signal[pycbc]'` to use
  `PyCBCBackend`.

Python API:

```python
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:

```bash
gwmock-signal inject cbc --params examples/gw150914_like.json --network H1L1V1 --backend lal
```

## Documentation

- **Site:**
  [gwmock-signal documentation](https://leuven-gravity-institute.github.io/gwmock-signal/)
- **User guide:** overview, **Command-line interface** (`inject cbc`, JSON
  parameters, `--network`), **Custom backends**, and **Examples** (library
  walkthroughs)
- **API reference:** signatures, types, and exceptions (mkdocstrings)

### 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:

```python
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](https://leuven-gravity-institute.github.io/gwmock-signal/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!

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. 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](https://github.com/Leuven-Gravity-Institute/gwmock-signal/releases).

## Testing

From a repository checkout with **dev** dependencies installed
(`uv sync --group dev`):

```bash
uv run pytest
```

## License

This project is licensed under **GPL-3.0-or-later**. See the [LICENSE](LICENSE)
file for the full license text.

### 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](https://github.com/Leuven-Gravity-Institute/gwmock-signal/issues/new/choose)
or contact the maintainers.
