Metadata-Version: 2.4
Name: gwmock
Version: 0.7.0
Summary: A Python package for simulating gravitational wave detector data for mock data challenges.
Project-URL: Documentation, https://leuven-gravity-institute.github.io/gwmock
Project-URL: Source, https://github.com/Leuven-Gravity-Institute/gwmock
Project-URL: Tracker, https://github.com/Leuven-Gravity-Institute/gwmock/issues
Author-email: "Isaac C. F. Wong" <chunfung.wong@kuleuven.be>
License: GPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
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
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: <3.14,>=3.12
Requires-Dist: filelock>=3.29.1
Requires-Dist: gwmock-noise>=0.5.0
Requires-Dist: gwmock-pop>=0.9.1
Requires-Dist: gwmock-signal>=0.8.0
Requires-Dist: h5py>=3.16.0
Requires-Dist: psutil>=7.2.2
Requires-Dist: pydantic>=2.13.4
Requires-Dist: pymap3d>=3.2.0
Requires-Dist: tqdm>=4.68.1
Requires-Dist: typer>=0.26.7
Provides-Extra: sgwb
Requires-Dist: gwmock-signal[sgwb]>=0.8.0; extra == 'sgwb'
Description-Content-Type: text/markdown

# gwmock

[![Python CI](https://github.com/Leuven-Gravity-Institute/gwmock/actions/workflows/ci.yml/badge.svg)](https://github.com/Leuven-Gravity-Institute/gwmock/actions/workflows/ci.yml)
[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/Leuven-Gravity-Institute/gwmock/main.svg)](https://results.pre-commit.ci/latest/github/Leuven-Gravity-Institute/gwmock/main)
[![Documentation Status](https://github.com/Leuven-Gravity-Institute/gwmock/actions/workflows/documentation.yml/badge.svg)](https://leuven-gravity-institute.github.io/gwmock)
[![codecov](https://codecov.io/gh/Leuven-Gravity-Institute/gwmock/graph/badge.svg?token=GLW2LEFKW7)](https://codecov.io/gh/Leuven-Gravity-Institute/gwmock)
[![PyPI Version](https://img.shields.io/pypi/v/gwmock)](https://pypi.org/project/gwmock/)
[![Python Versions](https://img.shields.io/pypi/pyversions/gwmock)](https://pypi.org/project/gwmock/)
[![License: GPL-3.0-or-later](https://img.shields.io/badge/License-GPL--3.0--or--later-blue.svg)](LICENSE)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![DOI](https://zenodo.org/badge/1115995501.svg)](https://doi.org/10.5281/zenodo.17925458)

A Python package for generating Mock Data Challenge (MDC) datasets for the
gravitational-wave (GW) community. It simulates strain data for detectors like
Einstein Telescope, providing a unified interface for reproducible GW data
generation.

## Features

- **Modular Design**: Uses mixins for flexible simulator composition
- **Detector Support**: Built-in support for various GW detectors with custom
  configuration options
- **Waveform Generation**: Integrates with PyCBC and LALSuite for accurate
  signal simulation
- **Noise Models**: Supports colored and correlated noise generation
  (In-Progress)
- **Population Models**: Handles injection populations for signals and glitches
- **Data Formats**: Outputs in standard GW formats (GWF frames)
- **CLI**: Command-line tools for easy simulation workflows

## Installation

We recommend using `uv` to manage virtual environments for installing gwmock.

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

**Note:** The package is built and tested against Python 3.12-3.13. When
creating a virtual environment with `uv`, specify the Python version to ensure
compatibility: `uv venv --python 3.12` (replace `3.12` with your preferred
version in the 3.12-3.13 range). This avoids potential issues with unsupported
Python versions.

### From PyPI

```bash
# 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
```

### From Source

```bash
git clone git@github.com:Leuven-Gravity-Institute/gwmock.git
cd gwmock
# Create a virtual environment (recommended with uv)
uv venv --python 3.13
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv sync
```

## Quick Start

### Command Line

```bash
# Generate simulated data
gwmock simulate config.yaml
```

## Configuration

gwmock uses YAML configuration files for reproducible simulations. New runs use
the adapter-backed `orchestration` surface, which keeps backend selection
explicit and lets third-party packages plug in through public protocols.

Key configuration sections:

| Section                    | Purpose                                                                                               |
| -------------------------- | ----------------------------------------------------------------------------------------------------- |
| `globals`                  | Shared orchestration parameters such as sampling rate, segment duration, start time, and output roots |
| `orchestration.population` | Public population backend, source type, sample count, and backend arguments                           |
| `orchestration.signal`     | Public signal backend, detector network, waveform model, and output settings                          |
| `orchestration.noise`      | Public noise backend, generation arguments, and output settings                                       |

Example:

```yaml
globals:
    working-directory: .
    output-directory: output
    metadata-directory: metadata
    simulator-arguments:
        sampling-frequency: 4096
        duration: 1024
        start-time: 1577491218
        total-duration: 5 hours

orchestration:
    population:
        backend: FilePopulationLoader
        source-type: bbh
        n-samples: 1
        arguments:
            path: https://raw.githubusercontent.com/Leuven-Gravity-Institute/gwmock/main/examples/signal/bbh_population.csv
    signal:
        detectors:
            - H1
        waveform-model: IMRPhenomXPHM
        minimum-frequency: 20
        output:
            output_directory: signal
            file_name: signal-{{ counter }}.gwf
            arguments:
                channel: H1:STRAIN
    noise:
        output:
            output_directory: noise
            file_name: noise-{{ counter }}.gwf
```

Third-party backends can be exposed through an entry point or referenced
directly as `module:Class`, as long as they satisfy the public protocol for the
relevant section. See `docs/user-guide/protocols.md`,
`docs/user-guide/orchestration.md`, and `docs/user-guide/extensibility.md` for
the protocol model and integration details.

## Documentation

Full documentation to be available at
[https://leuven-gravity-institute.github.io/gwmock](https://leuven-gravity-institute.github.io/gwmock).

## Contributing

Contributions are welcome!

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a merge 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/releases).

## Testing

Run the test suite:

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

## Support

For questions or issues, please open an issue on
[GitHub](https://github.com/Leuven-Gravity-Institute/gwmock/issues/new) or
contact the maintainers.
