gw-remnant 0.2.0
Python package to extract remnant black hole properties from gravitational waveforms
License: MIT
Requires Python: >=3.8
Keywords: gravitational waves, black holes, numerical relativity, remnant properties

# gw_remnant

During binary-black-hole (BBH) mergers, energy and momenta are carried away from the binary system as gravitational radiation. Access to the radiated energy and momenta allows us to accurately predict the properties of the remnant black hole. 

```gw_remnant``` is an easy-to-use python package to efficiently extract the remnant mass, remnant spin, peak luminosity and the final kick imparted on the remnant black hole directly from the gravitational radiation.

Github repo for this project is : ```https://github.com/tousifislam/gw_remnant```

Currently it has the ability to generate waveforms from ```NRHybSur3dq8``` and ```BHPTNRSur1dq1e4```. However, it can take waveforms generated by other methods by the user too. 

## Repository Structure
```
gw_remnant/
├── gw_remnant/                        # Main package directory
│   ├── __init__.py                    # Package initialization
│   ├── gw_remnant_calculator.py       # Main calculator class
│   ├── gw_waveform_generator.py       # Waveform generation utilities
│   │
│   ├── gw_utils/                      # Utility functions
│   │   ├── __init__.py
│   │   ├── waveform_generator.py      # Waveform generation helpers
│   │   └── gw_plotter.py              # Plotting utilities
│   │
│   └── remnant_calculators/           # Remnant property calculators
│       ├── __init__.py
│       ├── remnant_mass_calculator.py
│       ├── remnant_spin_calculator.py
│       ├── kick_velocity_calculator.py
│       ├── peak_luminosity_calculator.py
│       └── initial_energy_momenta.py
│
├── tutorials/                         # Example notebooks and tutorials
├── tests/                             # Unit tests (if added)
├── setup.py                           # Package installation configuration
├── README.md                          # This file
├── LICENSE                            # License information
└── .gitignore                         # Git ignore rules
```

## Tutorials

Example notebook is provided in ```https://github.com/tousifislam/gw_remnant/tutorials``` directory.

You can find examples with deafult waveforms (BHPTNRSur1dq1e4 and NRHybSur3dq8) here : [https://github.com/tousifislam/gw_remnant/blob/main/tutorials/example_with_default_waveforms.ipynb](https://github.com/tousifislam/gw_remnant/blob/main/tutorials/example_with_default_waveforms.ipynb)

**If you do not already have gwsurrogate and BHPTNRSurrogate(s) installed, you can use the example with customed waveforms for now**

Examples with custom waveforms are given here : [https://github.com/tousifislam/gw_remnant/blob/main/tutorials/example_with_customized_waveform.ipynb](https://github.com/tousifislam/gw_remnant/blob/main/tutorials/example_with_customized_waveform.ipynb)


## BHPTNRremnant

```gw_remnant``` package has been used in developing NR-tuned perturbation based remnant model that can provide faithful estimates of the remnant properties for binaries with mass ratios ranging from ```q=3``` to ```q=1000```.

## Citation guideline

If you make use of any module from the Toolkit in your research please acknowledge using:

> This work makes use of the Black Hole Perturbation Toolkit.

If you make use of the ```gw_remnnat``` package or ```BHPTNRremnant``` surrogate models please cite the following paper:

```
@article{Islam:2022laz,
    author = "Islam, Tousif and Field, Scott E. and Khanna, Gaurav.",
    title = "{Remnant black hole properties from numerical-relativity-informed perturbation theory and implications for waveform modelling}",
    eprint = "https://arxiv.org/abs/2301.07215",
    archivePrefix = "arXiv",
    primaryClass = "gr-qc",
    month = "1",
    year = "2023"
}
```