Metadata-Version: 2.4
Name: burst-waveform
Version: 0.5.0
Summary: A Python package for gravitational wave burst waveform
Home-page: https://git.ligo.org/yumeng.xu/setup.py
Author: Yumeng Xu
Author-email: The PycWB team <yumeng.xu@ligo.org>
Keywords: ligo,sine-gaussian,white noise burst,gravitational waves,burst,waveform model
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: gwpy
Dynamic: author
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python

# Burst waveform

[![Build Status](https://git.ligo.org/yumeng.xu/burst_waveform/badges/main/pipeline.svg)](https://git.ligo.org/yumeng.xu/burst_waveform/-/pipelines)
[![PyPI version](https://badge.fury.io/py/burst-waveform.svg)](https://badge.fury.io/py/burst-waveform)
[![License](https://img.shields.io/badge/license-GPLv3-blue)](https://git.ligo.org/yumeng.xu/pycwb/-/blob/main/LICENSE)

This package hosts the python version of the burst waveform used in coherentWaveBurst(cWB) search.

## Installation

### Using pip

```bash
pip install burst-waveform
```

### from source

```bash
make install
```

## Usage

The `Burst-Waveform` package provides four burst waveform models: `SineGaussian`, `SineGaussianQ`, `WhiteNoiseBurst`,
and `Ringdown`. 

The waveforms can be generated by calling the instance of the waveform model after initializing it with the desired
parameters.

For example, to generate a `SineGaussianQ` waveform,

```python
from burst_waveform.models import SineGaussianQ
from matplotlib import pyplot as plt

params = {
    "amplitude": 1.0,
    "frequency": 300.0,
    "Q": 9
}

model = SineGaussianQ(params)
strain = model()

plt.plot(strain)
plt.show()
```

For `WhiteNoiseBurst` waveform,

```python
from burst_waveform.models import WhiteNoiseBurst
import matplotlib.pyplot as plt

params = {
    'frequency': 300,
    'bandwidth': 50,
    'duration': 0.005,
    'inj_length': 1,
    'mode': 1
}

WNB = WhiteNoiseBurst(params)
wnb_strain = WNB()

plt.plot(wnb_strain)
plt.xlim(0.5 - 10 * params['duration'], 0.5 + 10 * params['duration'])
plt.show()
```

For `Ringdown` waveform,

```python
import numpy as np
from burst_waveform.models import Ringdown
from matplotlib import pyplot as plt

params = {
    "tau": 0.3,
    "frequency": 10.0,
    "iota": np.pi / 2,  # inclination angle in radians (90 deg)
}

model = Ringdown(params)
hp, hc = model()

plt.plot(hp)
plt.plot(hc)
plt.show()
```

## cWB analytic burst conventions

`burst_waveform.interface.generate_waveform_pycwb.get_td_waveform` owns the
cWB-compatible `SG`, `SGE`, `GA`, and `WNB` implementations. PycWB no longer
provides a separate `burst_population` generator. The public interface returns
GWpy `hp` and `hc` series and accepts `delta_t` or `sample_rate` (16384 Hz by
default); supplying inconsistent values raises an error. The default buffer is
one second centered at epoch -0.5, configurable with `inj_length`.

- SGE uses sine for `hp`, cosine for `hc`, and cWB's positive-half component
  normalization. Source `hrss` is applied **before** inclination factors
  `(1 + cos(iota)**2)/2` and `cos(iota)`. `iota` is in radians;
  `ellipticity` remains an alias. This corrects the previous swapped phases
  and post-inclination normalization. SG has only the sine polarization.
- WNB has two independent, equally normalized polarizations, without inclination
  weighting (cWB `MDC_WNB`). `frequency` is the lower band edge; `duration` is
  the Gaussian amplitude standard deviation, correcting the former envelope's
  missing factor of 1/2. `mode=0` (the cWB default) selects a noise band;
  `mode=1` constructs the symmetric heterodyned band, including the corrected
  conjugation and cWB packed-FFT DC/Nyquist handling. To migrate the removed
  PycWB generator's WNBs, specify `mode=1` explicitly.
- GA uses cWB's `exp(-(t/duration)**2)` convention and has zero cross component.
- The interface defaults source `hrss` to `5e-23`; specify it explicitly for
  scientific runs. SG/CG direct classes share the same numerical kernels and
  now return the full padded buffer. The explicitly elliptical WNB class
  remains available as a separate model, but is not used for cWB `WNB`.

NumPy's RNG differs from ROOT's: equal integer seeds do not produce identical
WNB realizations. Tests against saved original cWB samples use the same Gaussian
inputs and require relative L2 error below `1e-12`. Reference fixtures and their
provenance live in `test/data/`.
